iop/agent-ops/roadmap/phase/serving-routing-optimization/milestones/model-serving-load-routing.md

Milestone: Ollama E2E 서빙 안정화

위치

• Roadmap: agent-ops/roadmap/ROADMAP.md
• Phase: agent-ops/roadmap/phase/serving-routing-optimization/PHASE.md

목표

Edge에 OpenAI API 방식으로 접속한 외부 agent/client가 Edge-Node 소켓 경로를 의식하지 않고 Node에서 serving 중인 Ollama를 사용할 수 있게 한다. 현재 1차 우선순위는 /v1/models 조회, /v1/chat/completions non-streaming/streaming 호출, Ollama thinking/reasoning stream 보존, 수동 Node/model 선택, 실제 Ollama 사용자 흐름 검증까지 E2E 한 사이클을 자연스럽게 완성하는 것이다. 자동 라우팅, 부하 라우팅, cloud fallback, 품질 평가 feedback, Responses API 세부 호환은 이 E2E baseline 이후의 후속 작업으로 분리한다.

상태

[진행중]

구현 잠금

• 상태: 해제
• 결정 필요: 없음

범위

• 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 message.thinking은 기본적으로 숨기거나 think:false로 끄지 않고, OpenWebUI류 UX처럼 thinking 중임을 알 수 있는 별도 reasoning stream으로 보존한다.
• Ollama 관련 조회/상태/관리 command를 IOP OpenAI-compatible 표면에서 어디까지 pass-through할지에 대한 1차 기준과 unsupported 응답 정책
• 여러 Node와 여러 model은 자동 라우팅이 아니라 openai.node, openai.models, 요청 model, openai.target 조합을 수동으로 바꿔 검증한다.
• bin/edge.sh와 bin/node.sh를 실제로 연결해 사용자가 직접 재현 가능한 필드 테스트 환경을 문서화한다.
• IOP native protocol, A2A, routing 최적화 계층과 OpenAI-compatible 서빙 표면의 책임 경계를 충돌 없이 정리한다.

필수 기능

Epic: [e2e-serving-core] E2E Serving Core

• [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

• [models-list] Edge /v1/models가 Node/Ollama에서 사용 가능한 model 목록을 외부 client가 기대하는 OpenAI-compatible 형식으로 제공한다.
• [chat-cycle] Edge /v1/chat/completions 호출이 내부 adapter=ollama, target=<model> 실행으로 변환되어 Node Ollama adapter까지 왕복한다.
• [streaming-cycle] non-streaming 응답과 streaming SSE 응답이 일반 OpenAI-compatible client에서 사용할 수 있는 형태로 동작한다.
• [model-target-map] openai.target 고정 라우팅과 요청 model 기반 라우팅의 우선순위가 명확하며 Ollama model 선택 경험과 충돌하지 않는다.
• [option-pass-through] temperature, top_p, max_tokens, stop, stream 등 1차 지원 option의 매핑과 미지원 option 응답 정책이 정리되어 있다.
• [thinking-passthrough] Ollama message.thinking stream이 Edge-Node RunEvent에서 content delta와 구분되어 전달된다.
• [openai-reasoning-ux] Edge OpenAI-compatible streaming/non-streaming 응답이 thinking을 reasoning_content 계열 확장 필드로 노출하고, 답변 content stream과 섞지 않는다.
• [think-control] think:false는 기본값이 아니라 명시 옵션 또는 후속 client별 제어로만 다루며, 기본 UX는 thinking 보존으로 둔다.
• [ollama-command-pass-through] Ollama 관련 모델 조회, 상태, 관리 command를 Edge OpenAI-compatible 표면에서 어디까지 pass-through할지 1차 범위가 정의되어 있다.
• [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 기반 내부/운영 호출 기준으로 두고 OpenAI-compatible UX에 운영 제어 기능을 억지로 싣지 않는다.
• [optimization-later] RAG, MCP, web search, output validation은 기본 serving/load routing 이후 단계로 명시한다.

완료 기준

• Edge /v1/models와 /v1/chat/completions를 통해 Node의 Ollama serving을 조회하고 사용할 수 있다.
• 외부 agent/client가 Edge endpoint를 일반 OpenAI-compatible 또는 Ollama-backed endpoint처럼 설정해 한 차례 모델 조회와 chat completion을 완료할 수 있다.
• streaming/non-streaming 응답, thinking/reasoning passthrough, model-to-target 매핑, 1차 option pass-through, unsupported option 응답 정책이 검증되어 있다.
• gemma4:26b처럼 thinking을 먼저 내보내는 모델에서도 사용자는 thinking 중임을 볼 수 있고, content가 시작되면 답변 stream을 자연스럽게 받을 수 있다.
• 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의 역할이 충돌하지 않는다.
• 다음 단계인 model routing/fallback 최적화로 넘어갈 선행 조건이 정의된다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 모든 필수 Task와 완료 기준이 아직 모두 충족되지 않았다.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 없음

범위 제외

• RAG 검색, context 압축, web search, MCP/tool policy 구현
• 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으로 사용한다.
• 표준선(선택): Ollama thinking은 RunEvent.type=reasoning_delta 같은 별도 event type으로 content delta와 구분하고, OpenAI-compatible SSE에서는 delta.reasoning_content 확장 필드로 노출한다.
• 표준선(선택): non-streaming 응답은 최종 message.content에 답변만 담고, thinking은 message.reasoning_content 확장 필드로 분리한다.
• 표준선(선택): think:false는 테스트 우회 기본값으로 쓰지 않고, 명시 요청 또는 후속 설정 항목으로만 고려한다.
• 선행 작업: Edge 입력 표면, CLI Automation Runtime 안정화
• 후속 작업: 모델 라우팅/fallback 최적화, 지식/도구 정책/검증 최적화
• 확인 필요: cloud fallback 도입 시점, Responses API 세부 호환 범위, 모델 품질 평가와 routing feedback의 초기 신호