update roadmap and deploy docs

2026-05-25 20:01:50 +09:00 · 2026-05-25 20:01:50 +09:00 · 1a84420dac
commit 1a84420dac
parent 2c694bf2ec
5 changed files with 139 additions and 26 deletions
--- a/agent-ops/roadmap/ROADMAP.md
+++ b/agent-ops/roadmap/ROADMAP.md
@ -35,7 +35,7 @@ RAG, context 구성/압축, web search, MCP 정책, tool policy, output validati

 - [진행중] 서빙 라우팅과 최적화 기반
  - 경로: `agent-ops/roadmap/phase/serving-routing-optimization/PHASE.md`
-  - 요약: Edge OpenAI-compatible API에서 Node의 Ollama serving을 호출하는 한 사이클을 먼저 완성하고, 이후 로컬/클라우드 모델 profile, 부하 라우팅, 품질 평가 기준과 최적화 계층으로 확장하는 단계다.
+  - 요약: Edge OpenAI-compatible API에서 Node의 Ollama serving을 호출하는 E2E 한 사이클을 먼저 완성하고, 이후 로컬/클라우드 모델 profile, 부하 라우팅, 품질 평가 기준과 최적화 계층으로 확장하는 단계다.

 ## 로딩 정책

--- a/agent-ops/roadmap/current.md
+++ b/agent-ops/roadmap/current.md
@ -13,7 +13,7 @@

 ## 활성 Milestone

- [진행중] 모델 서빙과 부하 라우팅
+- [진행중] Ollama E2E 서빙 안정화
  - Phase: `agent-ops/roadmap/phase/serving-routing-optimization/PHASE.md`
  - 경로: `agent-ops/roadmap/phase/serving-routing-optimization/milestones/model-serving-load-routing.md`

--- a/agent-ops/roadmap/phase/serving-routing-optimization/PHASE.md
+++ b/agent-ops/roadmap/phase/serving-routing-optimization/PHASE.md
@ -13,9 +13,9 @@
 완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획 또는 보류 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다.
 완료, 검토중, 진행중, 계획 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다.

- [진행중] 모델 서빙과 부하 라우팅
+- [진행중] Ollama E2E 서빙 안정화
  - 경로: `agent-ops/roadmap/phase/serving-routing-optimization/milestones/model-serving-load-routing.md`
-  - 요약: Edge OpenAI-compatible API를 통해 Node에서 serving 중인 Ollama를 일반 OpenAI/Ollama client 경험에 가깝게 조회, 선택, 호출하는 한 사이클을 먼저 완성하고, 이후 Responses API와 로컬/클라우드 라우팅으로 확장한다.
+  - 요약: Edge OpenAI-compatible API를 통해 Node에서 serving 중인 Ollama를 일반 OpenAI/Ollama client 경험에 가깝게 조회, 선택, 호출하는 E2E 한 사이클을 먼저 완성하고, 자동 라우팅과 cloud fallback은 후속으로 미룬다.

 - [계획] 지식, 도구 정책, 검증 최적화
  - 경로: `agent-ops/roadmap/phase/serving-routing-optimization/milestones/knowledge-tool-validation-optimization.md`
--- a/agent-ops/roadmap/phase/serving-routing-optimization/milestones/model-serving-load-routing.md
+++ b/agent-ops/roadmap/phase/serving-routing-optimization/milestones/model-serving-load-routing.md
@ -1,4 +1,4 @@
-# Milestone: 모델 서빙과 부하 라우팅
+# Milestone: Ollama E2E 서빙 안정화

 ## 위치

@ -7,10 +7,9 @@

 ## 목표

-로컬/클라우드 모델 runtime을 IOP의 `adapter + target` 실행 모델 안에서 운영할 수 있도록 Responses API를 포함한 OpenAI-compatible 모델 호출 표면, 모델 profile, 모델 선택, 부하 라우팅, 호출 로그와 품질 평가 기준을 정리한다.
-현재 1차 우선순위는 Edge에 OpenAI API 방식으로 접속한 외부 agent/client가 Node에서 serving 중인 Ollama를 호출해 모델 조회, 모델 선택, chat completion 호출, streaming 응답까지 한 사이클을 완료하는 것이다.
-로컬 모델을 우선 활용하되 cloud fallback과 품질 평가를 결합해 엔터프라이즈 모델 서비스에 가까운 운영 품질을 목표로 한다.
-RAG, MCP, web search, output validation 같은 최적화 계층으로 넘어가기 전에 기본 모델 서빙과 라우팅 기반을 먼저 만든다.
+Edge에 OpenAI API 방식으로 접속한 외부 agent/client가 Edge-Node 소켓 경로를 의식하지 않고 Node에서 serving 중인 Ollama를 사용할 수 있게 한다.
+현재 1차 우선순위는 `/v1/models` 조회, `/v1/chat/completions` non-streaming/streaming 호출, 수동 Node/model 선택, 실제 Ollama 사용자 흐름 검증까지 E2E 한 사이클을 자연스럽게 완성하는 것이다.
+자동 라우팅, 부하 라우팅, cloud fallback, 품질 평가 feedback, Responses API 세부 호환은 이 E2E baseline 이후의 후속 작업으로 분리한다.

 ## 상태

@ -23,23 +22,22 @@ RAG, MCP, web search, output validation 같은 최적화 계층으로 넘어가

 ## 범위

- 로컬/클라우드 모델 runtime profile 관리 기준
- 모델 선택, 부하 라우팅, fallback 후보 판단 기준
- OpenAI-compatible `/v1/chat/completions`와 `/v1/responses` 호출을 내부 `adapter + target` 실행으로 해석하는 경계
+- OpenAI-compatible `/v1/chat/completions` 호출을 내부 `adapter + target` 실행으로 해석하는 경계
 - OpenAI-compatible `/v1/models` 조회와 `/v1/chat/completions` non-streaming/streaming 호출을 Edge -> Node -> Ollama 경로로 완성하는 1차 full-cycle
 - 외부 agent/client가 일반 Ollama 또는 OpenAI-compatible endpoint를 쓰는 것과 유사하게 model을 조회하고, 요청 model을 내부 target으로 사용하고, 지원 가능한 generation option을 명확히 전달하는 경험
 - Ollama 관련 조회/상태/관리 command를 IOP OpenAI-compatible 표면에서 어디까지 pass-through할지에 대한 1차 기준과 unsupported 응답 정책
- IOP native protocol 기반 내부 모델 호출 인터페이스 후보
- 모델 호출 로그, usage, 품질 평가 신호의 책임 위치
- NomadCode direct model endpoint 또는 Ollama fallback 전환을 지원하기 위한 IOP 측 모델 호출 표면
+- 여러 Node와 여러 model은 자동 라우팅이 아니라 `openai.node`, `openai.models`, 요청 `model`, `openai.target` 조합을 수동으로 바꿔 검증한다.
+- `bin/edge.sh`와 `bin/node.sh`를 실제로 연결해 사용자가 직접 재현 가능한 필드 테스트 환경을 문서화한다.
+- IOP native protocol, A2A, routing 최적화 계층과 OpenAI-compatible 서빙 표면의 책임 경계를 충돌 없이 정리한다.

 ## 필수 기능

-### Epic: [model-routing-core] Model Routing Core
+### Epic: [e2e-serving-core] E2E Serving Core

- [ ] [model-routing] 모델 선택과 local/cloud routing은 IOP 책임으로 정의한다.
- [ ] [cloud-fallback] 로컬 모델 우선 활용과 cloud fallback 기준을 함께 정의한다.
- [ ] [responses-api] OpenAI-compatible API는 chat completions와 Responses API를 포함하는 외부 모델 기반 호출 표면으로 정의한다.
+- [ ] [edge-node-ollama-path] Edge OpenAI-compatible API 요청이 Edge-Node 소켓을 통해 Node Ollama adapter로 전달되는 E2E 경로가 검증되어 있다.
+- [ ] [manual-node-select] Node 선택은 자동 라우팅이 아니라 `openai.node` 또는 단일 Node fallback 같은 수동 설정 기준으로 동작한다.
+- [ ] [manual-model-select] model 선택은 요청 `model` 또는 `openai.target` 고정값을 통해 수동으로 검증할 수 있다.
+- [ ] [routing-later] 자동 라우팅, 부하 라우팅, cloud fallback, 품질 평가 feedback은 후속 마일스톤으로 분리되어 있다.

 ### Epic: [ollama-openai-cycle] Ollama OpenAI-Compatible Full Cycle

@ -49,25 +47,27 @@ RAG, MCP, web search, output validation 같은 최적화 계층으로 넘어가
 - [ ] [model-target-map] `openai.target` 고정 라우팅과 요청 `model` 기반 라우팅의 우선순위가 명확하며 Ollama model 선택 경험과 충돌하지 않는다.
 - [ ] [option-pass-through] temperature, top_p, max_tokens, stop, stream 등 1차 지원 option의 매핑과 미지원 option 응답 정책이 정리되어 있다.
 - [ ] [ollama-command-pass-through] Ollama 관련 모델 조회, 상태, 관리 command를 Edge OpenAI-compatible 표면에서 어디까지 pass-through할지 1차 범위가 정의되어 있다.
- [ ] [openai-ollama-smoke] Edge -> Node -> Ollama full-cycle smoke가 fake Ollama와 실제 Ollama 사용자 흐름 기준으로 검증된다.
+- [ ] [openai-ollama-aux-smoke] fake Ollama 기반 보조 smoke가 OpenAI-compatible 입력 표면과 edge-node relay의 최소 생존을 확인한다.
+- [ ] [toki-labs-field-flow] 공통 필드 테스트 환경에서 `toki-labs` Ollama `gemma4:26b` 모델을 사용해 사용자가 직접 재현 가능한 bin edge-node 흐름이 문서화되고 검증된다.

 ### Epic: [protocol-boundary] Protocol Boundary

 - [ ] [a2a-boundary] A2A API는 외부 agent의 작업 위임 표면으로 제한한다.
 - [ ] [nomadcode-a2a] NomadCode의 A2A 도입 시점은 이 Milestone에서 강제하지 않고 별도 판단으로 남긴다.
- [ ] [native-protocol] IOP native protocol은 proto-socket 기반 내부/운영 호출 기준으로 둔다.
+- [ ] [native-protocol] IOP native protocol은 proto-socket 기반 내부/운영 호출 기준으로 두고 OpenAI-compatible UX에 운영 제어 기능을 억지로 싣지 않는다.
 - [ ] [optimization-later] RAG, MCP, web search, output validation은 기본 serving/load routing 이후 단계로 명시한다.

 ## 완료 기준

- [ ] Responses API 호환 지원 범위와 chat completions baseline의 차이가 문서화된다.
 - [ ] Edge `/v1/models`와 `/v1/chat/completions`를 통해 Node의 Ollama serving을 조회하고 사용할 수 있다.
 - [ ] 외부 agent/client가 Edge endpoint를 일반 OpenAI-compatible 또는 Ollama-backed endpoint처럼 설정해 한 차례 모델 조회와 chat completion을 완료할 수 있다.
 - [ ] streaming/non-streaming 응답, model-to-target 매핑, 1차 option pass-through, unsupported option 응답 정책이 검증되어 있다.
- [ ] 모델 profile, routing 입력값, routing 결과, fallback 책임 경계가 문서화된다.
+- [ ] `bin/edge.sh`와 `bin/node.sh`를 실제로 연결해 Edge -> Node -> Ollama 흐름을 재현할 수 있다.
+- [ ] 최종 완료 검증은 fake Ollama smoke가 아니라 사용자가 직접 테스트하는 방식과 같은 `toki-labs` 실제 Ollama 필드 흐름으로 수행된다.
+- [ ] 공통 필드 테스트 환경의 Node host, Ollama endpoint, model, edge/node 임시 config 기준이 문서화되어 있다.
+- [ ] Node/model 선택은 수동 설정으로 검증하고, 자동 라우팅과 부하 라우팅은 후속 작업으로 분리되어 있다.
 - [ ] 외부 API 표면과 IOP native protocol의 역할이 충돌하지 않는다.
- [ ] NomadCode direct model endpoint/Ollama fallback 전환에 필요한 IOP 측 계약이 정리된다.
- [ ] 다음 Milestone인 지식/도구/검증 최적화로 넘어갈 선행 조건이 정의된다.
+- [ ] 다음 단계인 model routing/fallback 최적화로 넘어갈 선행 조건이 정의된다.

 ## 완료 리뷰

@ -85,14 +85,17 @@ RAG, MCP, web search, output validation 같은 최적화 계층으로 넘어가
 - output validation, retry/fallback loop의 세부 알고리즘 구현
 - NomadCode 전용 task metadata 계약 확정
 - 외부 Agent CLI adapter 추가 구현
+- 자동 Node 라우팅, 부하 라우팅, cloud fallback, 품질 평가 feedback 구현
+- Responses API 세부 호환 구현

 ## 작업 컨텍스트

 - 관련 경로: `apps/edge`, `apps/node`, `packages/config`, `packages/observability`, `proto/iop`, `docs/architecture.md`, `apps/edge/README.md`
 - 1차 우선순위: OTO/bootstrap 연동보다 Edge OpenAI-compatible API -> Node -> Ollama serving full-cycle을 먼저 완성한다.
+- 공통 필드 테스트 환경: `docs/deploy-dev.md`의 `공통 Ollama 필드 테스트 환경`을 따른다.
 - 표준선(선택): 내부 실행 계약은 `adapter + target`을 유지하고, OpenAI-compatible API는 외부 호환 입력 표면으로 둔다.
 - 표준선(선택): 1차 구현은 local Ollama를 기준으로 하며 cloud fallback, 품질 평가 feedback, Responses API 세부 호환은 chat completions baseline 이후 확장한다.
 - 표준선(선택): Edge `/v1/models`는 설정된 model 목록과 Node capability/Ollama 조회 결과 중 사용 가능한 근거를 우선해 반환하고, 요청 `model`은 `openai.target`이 비어 있을 때 내부 target으로 사용한다.
 - 선행 작업: Edge 입력 표면, CLI Automation Runtime 안정화
- 후속 작업: 지식, 도구 정책, 검증 최적화
+- 후속 작업: 모델 라우팅/fallback 최적화, 지식/도구 정책/검증 최적화
 - 확인 필요: cloud fallback 도입 시점, Responses API 세부 호환 범위, 모델 품질 평가와 routing feedback의 초기 신호
--- a/docs/deploy-dev.md
+++ b/docs/deploy-dev.md
@ -117,6 +117,116 @@ repo root에서 수동으로 검증할 때는 기존 helper를 사용할 수 있
 IOP_EDGE_ADDR=<edge-host>:9090 ./bin/node.sh
 ```

+## 공통 Ollama 필드 테스트 환경
+
+OpenAI-compatible Ollama E2E 서빙 검증은 아래 필드 환경을 공통 기준으로 사용한다.
+이 환경은 특정 마일스톤에만 두지 않고, 이후 모델 서빙, routing, fallback, client 통합 검증에서도 재사용한다.
+`scripts/e2e-openai-ollama.sh` 같은 fake Ollama smoke는 보조 확인이다.
+완료 판정은 사용자가 직접 테스트하는 방식과 동일하게 `bin/edge.sh`, `bin/node.sh`, 실제 Ollama endpoint를 연결한 full-cycle 흐름으로 한다.
+
+| 항목 | 값 |
+|---|---|
+| Node host | `ssh toki@toki-labs.com` |
+| Ollama base URL | `http://192.168.0.97:11434` |
+| 기준 model | `gemma4:26b` |
+| 권장 node id | `node-toki-labs-ollama` |
+| 권장 node alias | `toki-labs-ollama` |
+
+기본 `configs/*.yaml`은 필드 테스트 값으로 덮어쓰지 않는다.
+edge와 node는 임시 config 또는 `/etc/iop/*.yaml` 필드 설정을 사용한다.
+Node가 사용할 Ollama endpoint는 node config가 아니라 edge config의 `nodes[].adapters.ollama.base_url`에 둔다.
+Node는 registration 이후 Edge가 내려주는 adapter config로 Ollama를 호출한다.
+
+edge host에서 임시 config를 만들 때의 기준은 다음과 같다.
+`CHANGE_ME_FIELD_TOKEN`과 `<edge-host>`는 테스트 시점의 값으로 바꾼다.
+`openai.target`은 비워 두면 요청의 `model`을 내부 target으로 사용하고, `gemma4:26b`로 고정하면 외부 요청 model과 무관하게 해당 model로만 호출한다.
+Node는 Edge로 outbound 연결하므로 `ssh toki@toki-labs.com` 환경에서 `<edge-host>:9090`에 접근할 수 있어야 한다.
+로컬 개발 머신이 원격 host에서 직접 보이지 않으면 Edge를 접근 가능한 host에서 실행하거나 터널을 구성한다.
+
+```yaml
+edge:
+  id: "edge-toki-labs-field"
+  name: "Toki Labs Field Edge"
+
+server:
+  listen: "0.0.0.0:9090"
+
+openai:
+  enabled: true
+  listen: "0.0.0.0:8080"
+  node: "node-toki-labs-ollama"
+  adapter: "ollama"
+  target: ""
+  models:
+    - "gemma4:26b"
+  session_id: "openai-field"
+  timeout_sec: 300
+
+nodes:
+  - id: "node-toki-labs-ollama"
+    alias: "toki-labs-ollama"
+    token: "CHANGE_ME_FIELD_TOKEN"
+    adapters:
+      ollama:
+        enabled: true
+        base_url: "http://192.168.0.97:11434"
+        context_size: 262144
+```
+
+edge 실행:
+
+```bash
+IOP_EDGE_CONFIG=/tmp/iop-edge-toki-labs.yaml ./bin/edge.sh
+```
+
+node host에 접속한 뒤 node 임시 config를 만든다.
+
+```bash
+ssh toki@toki-labs.com
+```
+
+```yaml
+transport:
+  edge_addr: "<edge-host>:9090"
+  token: "CHANGE_ME_FIELD_TOKEN"
+
+logging:
+  level: "info"
+  pretty: true
+
+metrics:
+  port: 9091
+```
+
+node 실행:
+
+```bash
+IOP_NODE_CONFIG=/tmp/iop-node-toki-labs.yaml ./bin/node.sh
+```
+
+edge host에서 OpenAI-compatible API를 호출해 검증한다.
+
+```bash
+curl -fsS http://127.0.0.1:8080/v1/models
+```
+
+```bash
+curl -fsS http://127.0.0.1:8080/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"gemma4:26b","messages":[{"role":"user","content":"Reply with IOP_OLLAMA_E2E_OK only."}]}'
+```
+
+streaming 검증:
+
+```bash
+curl -fsS -N http://127.0.0.1:8080/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"gemma4:26b","stream":true,"messages":[{"role":"user","content":"Reply with IOP_OLLAMA_STREAM_OK only."}]}'
+```
+
+완료 기준은 사용자가 재현하는 실제 절차에서 node registration, `/v1/models` 응답, non-streaming chat completion, streaming SSE chunk와 `data: [DONE]` 확인이다.
+Edge/Node 뒤의 소켓 relay가 사용자 UX에 드러나지 않아야 하며, 실패 시 edge와 node 양쪽 로그를 함께 확인한다.
+
 ## Agent Bootstrap / Bridge References

 OTO 같은 specialized domain agent의 bootstrap/enrollment 상세 계획은 `agent-ops/roadmap/milestones/agent-bootstrap-oto-enrollment.md`에서 관리한다.