From 1a84420dac8850af4ef1f818cae6794775a596b4 Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 25 May 2026 20:01:50 +0900 Subject: [PATCH] update roadmap and deploy docs --- agent-ops/roadmap/ROADMAP.md | 2 +- agent-ops/roadmap/current.md | 2 +- .../serving-routing-optimization/PHASE.md | 4 +- .../milestones/model-serving-load-routing.md | 47 ++++---- docs/deploy-dev.md | 110 ++++++++++++++++++ 5 files changed, 139 insertions(+), 26 deletions(-) diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md index c96f54b..0b3918b 100644 --- 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, 부하 라우팅, 품질 평가 기준과 최적화 계층으로 확장하는 단계다. ## 로딩 정책 diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md index 810b31e..7fb07aa 100644 --- 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` diff --git a/agent-ops/roadmap/phase/serving-routing-optimization/PHASE.md b/agent-ops/roadmap/phase/serving-routing-optimization/PHASE.md index 018df90..4cce7b7 100644 --- 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` diff --git 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 index 1fd6c29..e69859e 100644 --- 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의 초기 신호 diff --git a/docs/deploy-dev.md b/docs/deploy-dev.md index fd79350..b4df13a 100644 --- a/docs/deploy-dev.md +++ b/docs/deploy-dev.md @@ -117,6 +117,116 @@ repo root에서 수동으로 검증할 때는 기존 helper를 사용할 수 있 IOP_EDGE_ADDR=: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`과 ``는 테스트 시점의 값으로 바꾼다. +`openai.target`은 비워 두면 요청의 `model`을 내부 target으로 사용하고, `gemma4:26b`로 고정하면 외부 요청 model과 무관하게 해당 model로만 호출한다. +Node는 Edge로 outbound 연결하므로 `ssh toki@toki-labs.com` 환경에서 `: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: ":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`에서 관리한다.