diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index 0ee8b90..0957fbd 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -40,7 +40,7 @@ RAG, context 구성/압축, web search, MCP 정책, tool policy, output validati - [진행중] 추론 서버 provider 확장 - 경로: `agent-roadmap/phase/inference-provider-extension/PHASE.md` - - 요약: Ollama 경로 안정화 결과를 기준선으로 삼아 Node 단일 통로 멀티 타겟 서빙 기반을 완료했고, 이후 SGLang 같은 추가 provider의 adapter/config/target/model 매핑 표준선을 정리하는 단계다. + - 요약: Ollama 경로 안정화 결과와 Node 단일 통로 멀티 타겟 서빙 기반을 기준선으로 삼아, provider 공통 상태 확인과 capacity queue 기반을 먼저 정리한 뒤 Lemonade를 우선 provider로 올리고 이후 vLLM/SGLang 같은 추가 provider의 adapter/config/target/model 매핑 표준선을 정리하는 단계다. - [계획] 지식과 도구 최적화 확장 - 경로: `agent-roadmap/phase/knowledge-tool-optimization-extension/PHASE.md` diff --git a/agent-roadmap/phase/automation-runtime-bridge/milestones/codex-app-server-streaming-migration.md b/agent-roadmap/archive/phase/automation-runtime-bridge/milestones/codex-app-server-streaming-migration.md similarity index 94% rename from agent-roadmap/phase/automation-runtime-bridge/milestones/codex-app-server-streaming-migration.md rename to agent-roadmap/archive/phase/automation-runtime-bridge/milestones/codex-app-server-streaming-migration.md index 5dcd040..3ee386f 100644 --- a/agent-roadmap/phase/automation-runtime-bridge/milestones/codex-app-server-streaming-migration.md +++ b/agent-roadmap/archive/phase/automation-runtime-bridge/milestones/codex-app-server-streaming-migration.md @@ -12,7 +12,7 @@ Codex CLI adapter의 기본 `codex` target/profile을 `codex app-server` 기반 ## 상태 -[검토중] +[완료] ## 구현 잠금 @@ -45,16 +45,16 @@ Codex app-server를 장기 JSON-RPC 실행기로 붙여 IOP CLI adapter의 세 ## 완료 리뷰 -- 상태: 요청됨 +- 상태: 승인됨 - 요청일: 2026-06-12 - 완료 근거: - `01_appserver_rpc_client`, `02+01_session_events`, `03+02_default_profile`, `04+03_stream_smoke`의 `complete.log`가 모두 Roadmap Completion을 포함하며, 기능 Task id 7개가 모두 PASS로 매칭되었다. - 실제 `codex` profile smoke에서 foreground 2회, background 1회, `mode=codex-app-server` session list, `/terminate-session`, `/status`가 통과했다. - 최종 검증은 `go test ./apps/node/... ./apps/edge/... -count=1`, `./scripts/e2e-smoke.sh`, `IOP_E2E_PROFILE=codex IOP_E2E_RUN_TIMEOUT=120 IOP_E2E_STATUS_TIMEOUT=120 ./scripts/e2e-smoke.sh`로 확인되었다. - 리뷰 필요: - - [ ] 사용자가 완료 결과를 확인했다 - - [ ] archive 이동을 승인했다 -- 리뷰 코멘트: 모든 기능 Task가 충족된 완료 후보 상태다. 사용자 확인 후 `[완료]` 전환과 archive 이동을 진행한다. + - [x] 사용자가 완료 결과를 확인했다 + - [x] archive 이동을 승인했다 +- 리뷰 코멘트: 2026-06-13 사용자 요청으로 완료 승인 및 archive 이동을 수행했다. ## 범위 제외 diff --git a/agent-roadmap/phase/automation-runtime-bridge/PHASE.md b/agent-roadmap/phase/automation-runtime-bridge/PHASE.md index 2ba6ea2..85d2d0e 100644 --- a/agent-roadmap/phase/automation-runtime-bridge/PHASE.md +++ b/agent-roadmap/phase/automation-runtime-bridge/PHASE.md @@ -66,9 +66,13 @@ CLI 실행, specialized agent 등록, bootstrap/enrollment, 원격 터미널 브 - 경로: `agent-roadmap/archive/phase/automation-runtime-bridge/milestones/bridge-boundary-hardening.md` - 요약: 원격 터미널 브리지 POC 전에 남은 호환성/소유권 리스크를 Client HTTP lifecycle, Edge run surface, Node terminal core, typed adapter config 계약으로 고정한다. -- [검토중] Codex App Server 스트리밍 전환 - - 경로: `agent-roadmap/phase/automation-runtime-bridge/milestones/codex-app-server-streaming-migration.md` - - 요약: Codex CLI target의 기본 `codex` profile을 app-server 기반으로 전환하고 실제 `codex` smoke까지 통과해 사용자 완료 확인과 archive 승인을 기다린다. +- [완료] Codex App Server 스트리밍 전환 + - 경로: `agent-roadmap/archive/phase/automation-runtime-bridge/milestones/codex-app-server-streaming-migration.md` + - 요약: Codex CLI target의 기본 `codex` profile을 app-server 기반으로 전환하고 실제 `codex` foreground/background smoke와 app-server session lifecycle 검증을 완료했다. + +- [계획] OpenAI Workspace Agent Execution Contract + - 경로: `agent-roadmap/phase/automation-runtime-bridge/milestones/openai-workspace-agent-execution-contract.md` + - 요약: NomadCode가 IOP CLI를 직접 실행하지 않고 IOP Edge OpenAI-compatible HTTP 호출의 `metadata.workspace`만으로 내부 workspace-bound agent target이 해당 checkout에서 산출물을 만들 수 있게 한다. - [계획] 원격 터미널 브리지 POC - 경로: `agent-roadmap/phase/automation-runtime-bridge/milestones/remote-terminal-bridge-poc.md` diff --git a/agent-roadmap/phase/automation-runtime-bridge/milestones/openai-workspace-agent-execution-contract.md b/agent-roadmap/phase/automation-runtime-bridge/milestones/openai-workspace-agent-execution-contract.md new file mode 100644 index 0000000..6a8e521 --- /dev/null +++ b/agent-roadmap/phase/automation-runtime-bridge/milestones/openai-workspace-agent-execution-contract.md @@ -0,0 +1,84 @@ +# Milestone: OpenAI Workspace Agent Execution Contract + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/automation-runtime-bridge/PHASE.md` + +## 목표 + +외부 소비자, 특히 NomadCode는 IOP와 CLI로 통신하지 않고 IOP Edge의 OpenAI-compatible HTTP 표면(`/v1/responses`, `/v1/chat/completions`)으로 요청한다. +이 마일스톤은 그 HTTP 요청의 `metadata.workspace`가 IOP 내부 `adapter + target` 실행 경로를 지나 실제 workspace agent process의 작업 디렉터리까지 전달되도록 만든다. +완료 지점은 NomadCode가 workspace slot path를 `metadata.workspace`로 넘겨 IOP Edge HTTP 호출 한 번으로 Codex 같은 내부 agent target이 해당 checkout 안에 roadmap Milestone 산출물을 만들 수 있는 상태다. + +## 상태 + +[계획] + +## 구현 잠금 + +- 상태: 해제 +- 결정 필요: 없음 + +## 범위 + +- OpenAI-compatible 요청의 `metadata.workspace` 파싱과 검증 +- OpenAI-compatible `model` route를 IOP 내부 `adapter + target` 실행으로 해석하는 기준 +- Edge service가 workspace를 명시 실행 필드로 받아 Node `RunRequest.Workspace`로 전달하는 흐름 +- Node CLI adapter 계열이 `ExecutionSpec.Workspace`를 process working directory로 적용하는 흐름 +- target/session 재사용 시 workspace가 섞이지 않도록 하는 logical session 기준 +- NomadCode workspace slot 기반 authoring run을 검증할 수 있는 HTTP smoke/test 기준 + +## 기능 + +### Epic: [metadata-workspace] OpenAI Metadata Workspace Ingress + +OpenAI-compatible 입력 표면에서 workspace agent 실행 문맥을 별도 wrapper 없이 `metadata.workspace`로 받는 계약을 구현한다. + +- [ ] [metadata-schema] `/v1/responses`와 `/v1/chat/completions`가 flat `metadata.workspace`를 파싱해 run workspace로 전달한다. 검증: 기존 `metadata.request_id`, `metadata.nomadcode.*`, `metadata.inference.target`은 유지되고 `metadata.cli`는 계속 거부된다. +- [ ] [workspace-required] 내부 실행 route가 workspace-bound agent target이면 workspace가 비어 있거나 상대 경로일 때 OpenAI-compatible error로 거부한다. 검증: workspace가 필요 없는 inference route는 기존 동작을 유지하고, workspace-bound route만 필수 조건을 적용한다. +- [ ] [route-catalog] 외부 `model` route가 내부 `adapter + target`으로 해석되는 기준을 config와 smoke fixture에 남긴다. 검증: `model: "codex"` 같은 route가 명시적으로 workspace-bound agent target으로 수렴한다. + +### Epic: [edge-node-workspace] Edge-Node Workspace Propagation + +Edge service와 Node runtime 사이에서 workspace가 metadata 문자열로만 남지 않고 실행 spec의 작업 디렉터리로 이어지게 한다. + +- [ ] [run-workspace] `SubmitRunRequest`와 `BuildRunRequest`가 workspace를 명시 필드로 갖고 proto `RunRequest.Workspace`에 채운다. 검증: service unit test가 metadata와 workspace를 별도 필드로 보존하는지 확인한다. +- [ ] [node-spec] Node router가 `RunRequest.Workspace`를 `ExecutionSpec.Workspace`로 유지한다. 검증: router/node test에서 workspace 값이 adapter execution spec까지 보존된다. +- [ ] [agent-cwd] workspace-bound agent process 실행기가 `ExecutionSpec.Workspace`를 process working directory로 적용한다. 검증: 이 마일스톤에서 지원하는 agent target profile의 cwd 적용 test가 통과한다. +- [ ] [session-workspace] logical session이 다른 workspace를 같은 target/session으로 재사용하지 않는다. 검증: 같은 target/session이라도 workspace가 다르면 별도 session을 만들거나 명시 오류를 반환한다. + +### Epic: [nomad-http-smoke] NomadCode Todo Authoring Readiness + +NomadCode가 Plane `Todo` projection 전 단계에서 IOP Edge HTTP 호출로 workspace agent 산출물을 만들 수 있는 최소 실행 증거를 확보한다. + +- [ ] [workspace-authoring-smoke] `metadata.workspace`가 가리키는 임시 checkout에서 workspace-bound agent target이 파일을 생성/수정할 수 있음을 검증한다. 검증: OpenAI-compatible `/v1/responses` smoke가 workspace 안 marker 또는 git diff를 남기고, 프로세스 cwd가 workspace 밖으로 벗어나지 않는다. +- [ ] [nomad-handoff-contract] NomadCode authoring 호출 shape를 계약 문서와 운영 문서에 연결한다. 검증: 외부 호출은 `model`, `input`, `metadata.workspace`만으로 충분하며 `metadata.cli`, root-level `iop` wrapper, IOP CLI 직접 실행을 요구하지 않는다. +- [ ] [failure-surface] workspace 누락, 존재하지 않는 경로, 권한 오류, agent process exit failure가 호출자에게 구분 가능한 실패로 드러난다. 검증: 잘못된 workspace 요청이 조용히 기본 cwd에서 실행되지 않는다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 모든 기능 Task와 Task 안에 명시된 검증이 아직 충족되지 않았다. +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- NomadCode가 IOP CLI를 직접 실행하는 통신 경로 +- NomadCode의 Plane `Todo` projection, Plane 댓글/본문/상태 갱신 구현 +- NomadCode의 `develop` push 성공 판정, milestone/work item identity map, 재시도 정책 +- OpenAI-compatible API에 terminal 제어 기능을 싣는 일 +- IOP native remote terminal bridge 구현 +- MCP/tool policy, approval flow, artifact store, RAG/context compression 구현 + +## 작업 컨텍스트 + +- 관련 경로: `agent-contract/provided/openai-compatible-api.md`, `apps/edge/internal/openai/`, `apps/edge/internal/service/`, `apps/node/internal/router/`, `apps/node/internal/node/`, `apps/node/internal/adapters/cli/`, `proto/iop/runtime.proto`, `configs/edge.yaml`, `agent-test/local/` +- 표준선(선택): 외부 통신은 IOP Edge OpenAI-compatible HTTP 표면을 사용한다. 내부 실행은 `adapter + target`과 `RunRequest.Workspace`로 변환한다. workspace agent process의 작업 디렉터리는 prompt 본문, `metadata.cli` wrapper, IOP CLI 직접 실행이 아니라 `metadata.workspace`에서 온다. +- 선행 작업: `OpenAI Responses Input Surface`, `Codex App Server 스트리밍 전환` +- 후속 작업: NomadCode `Milestone Work Item Creation Sync`, `원격 터미널 브리지 POC` +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/inference-provider-extension/PHASE.md b/agent-roadmap/phase/inference-provider-extension/PHASE.md index 305eccb..b3db6fe 100644 --- a/agent-roadmap/phase/inference-provider-extension/PHASE.md +++ b/agent-roadmap/phase/inference-provider-extension/PHASE.md @@ -6,8 +6,9 @@ ## 목표 -Ollama 경로가 안정화된 뒤, 그 결과를 기준선으로 삼아 SGLang 같은 추가 추론 서버 provider를 붙인다. +Ollama 경로가 안정화된 뒤, 그 결과를 기준선으로 삼아 Lemonade를 우선 provider로 올리고 이후 vLLM, SGLang 같은 추가 추론 서버 provider를 붙인다. 이 Phase는 하나의 Node transport 위에서 여러 CLI profile, terminal gateway, 추론 엔진, model target을 함께 쓰는 구조를 기준선으로 삼고, provider별 adapter/config/target/model 매핑을 단계적으로 검증한다. +추가 provider를 붙이기 전에 Node가 Ollama/Lemonade/vLLM/SGLang 같은 provider의 최소 가용 상태와 IOP-owned capacity/queue 상태를 공통 형태로 Edge에 제공하는 기반을 선행한다. ## Milestone 흐름 @@ -18,6 +19,18 @@ Ollama 경로가 안정화된 뒤, 그 결과를 기준선으로 삼아 SGLang - 경로: `agent-roadmap/archive/phase/inference-provider-extension/milestones/node-multi-target-serving-foundation.md` - 요약: 하나의 Node 연결이 여러 CLI profile, terminal gateway, Ollama/vLLM/SGLang 같은 추론 엔진 연결, 여러 model target을 동시에 제공할 수 있도록 config/proto/routing/runtime 기준선을 정리했고, 최종 코드 리뷰와 검증까지 통과해 archive했다. +- [계획] Node provider 상태와 Capacity Queue 기반 + - 경로: `agent-roadmap/phase/inference-provider-extension/milestones/provider-availability-capacity-queue-foundation.md` + - 요약: provider별 health/model probe 차이를 Node adapter 내부로 숨기고, Edge가 공통으로 볼 수 있는 최소 상태와 capacity/in-flight/queued snapshot, FIFO admission queue 기준선을 만든다. + +- [계획] Lemonade provider 서빙 경로 추가 + - 경로: `agent-roadmap/phase/inference-provider-extension/milestones/lemonade-provider-serving-validation.md` + - 요약: Node provider 상태와 capacity queue 기반 위에서 Lemonade provider의 adapter/config/target/model 매핑과 모델 조회, non-streaming/streaming chat 경로를 검증한다. + +- [계획] vLLM provider 서빙 경로 추가 + - 경로: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` + - 요약: Ollama 경로와 Node 단일 통로 멀티 타겟 기준선을 바탕으로 vLLM OpenAI-compatible provider를 붙이고, 모델 조회와 non-streaming/streaming chat을 검증한다. + - [계획] SGLang provider 서빙 경로 추가 - 경로: `agent-roadmap/phase/inference-provider-extension/milestones/sglang-provider-serving-validation.md` - 요약: Ollama 경로가 안정화된 뒤 추가 추론 서버 provider로 SGLang을 붙이고, 같은 Edge OpenAI-compatible 입력 표면에서 모델 조회와 non-streaming/streaming chat을 검증한다. @@ -26,5 +39,7 @@ Ollama 경로가 안정화된 뒤, 그 결과를 기준선으로 삼아 SGLang - 이 Phase는 Ollama 경로 안정화가 선행된 뒤 시작한다. - 진행중인 Ollama 실테스트와 후속 안정화 작업을 이 Phase로 흡수하지 않는다. +- provider 작업 우선순위는 Ollama 기준선 다음 Lemonade를 우선하고, vLLM/SGLang은 그 뒤 후보로 둔다. - 여러 추론 서버 provider 표준화는 Ollama 경로가 안정화된 결과와 Node 단일 통로 멀티 타겟 기준선을 함께 기준으로 삼아 진행한다. -- cloud fallback, 자동 부하 라우팅, 품질 평가 feedback과 후속 최적화 계층은 이 Phase에서 다루지 않는다. +- provider 공통 상태 확인과 Node-owned capacity/FIFO queue는 추가 provider 검증 전에 필요한 기반으로 이 Phase에서 다룬다. +- model group alias, 여러 Node/Edge 후보 간 자동 부하 라우팅, cloud fallback, 품질 평가 feedback과 후속 최적화 계층은 이 Phase에서 다루지 않는다. diff --git a/agent-roadmap/phase/inference-provider-extension/milestones/lemonade-provider-serving-validation.md b/agent-roadmap/phase/inference-provider-extension/milestones/lemonade-provider-serving-validation.md new file mode 100644 index 0000000..2c2a9ed --- /dev/null +++ b/agent-roadmap/phase/inference-provider-extension/milestones/lemonade-provider-serving-validation.md @@ -0,0 +1,76 @@ +# Milestone: Lemonade provider 서빙 경로 추가 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/inference-provider-extension/PHASE.md` + +## 목표 + +Node provider 상태와 capacity queue 기반을 전제로 Lemonade provider를 Ollama 다음 우선 provider 후보로 검증한다. +Edge OpenAI-compatible 입력 표면에서 Lemonade target/model의 모델 조회, non-streaming/streaming chat, option/API passthrough, split-host smoke 기준을 검증한다. + +## 상태 + +[계획] + +## 승격 조건 + +- 없음 + +## 구현 잠금 + +- 상태: 잠금 +- 결정 필요: 아래 체크리스트 + - [ ] Lemonade provider를 독립 `lemonade` adapter로 둘지, OpenAI-compatible inference server 공통 adapter 계열로 둘지 결정한다. + - [ ] 실테스트에 사용할 Lemonade endpoint, served model name 또는 기준 model, 인증/헤더 필요 여부, streaming 지원 기대 동작을 확인한다. + +## 범위 + +- Lemonade provider를 Ollama 이후의 우선 추론 서버 provider 후보로 둔다. +- Edge OpenAI-compatible API의 `/v1/models`, `/v1/chat/completions` non-streaming/streaming 요청이 Lemonade provider 경로로 수렴하는 기준을 정한다. +- Lemonade provider의 모델 조회, chat completion, streaming chunk, usage/finish reason, option/API passthrough 기대 동작을 실제 endpoint 기준으로 검증한다. +- Node provider 상태와 capacity queue snapshot에 Lemonade target/model이 같은 방식으로 노출되는지 검증한다. +- split-host field smoke 기준을 Lemonade provider에도 재사용한다. +- Ollama 경로에서 정리한 provider별 설정, target/model 매핑, adapter 책임 경계를 Lemonade에도 유지한다. + +## 기능 + +### Epic: [lemonade-provider] Lemonade Provider Serving Path + +- [ ] [provider-boundary] Lemonade provider를 독립 adapter로 둘지 OpenAI-compatible inference server 공통 adapter로 둘지 결정 근거가 정리되어 있다. +- [ ] [config-contract] Lemonade endpoint, served model name 또는 model, auth/header, timeout, option passthrough 설정 계약이 정리되어 있다. +- [ ] [availability] Lemonade provider의 endpoint/model probe 결과가 Node 공통 상태 모델 `unknown`, `available`, `unavailable`로 노출되는 기준이 검증되어 있다. +- [ ] [models-chat] Edge OpenAI-compatible `/v1/models`와 non-streaming `/v1/chat/completions`가 Lemonade provider로 수렴하는 기준이 검증되어 있다. +- [ ] [streaming] streaming `/v1/chat/completions`에서 SSE chunk, finish reason, 종료 신호가 Lemonade provider 경로로 안정적으로 전달되는지 검증되어 있다. +- [ ] [field-smoke] split-host field smoke에서 Lemonade target/model을 선택해 모델 조회와 chat 왕복이 검증되어 있다. +- [ ] [follow-up-scope] 코드 수정이 필요한 항목은 이 Milestone의 추가 Task 또는 같은 Milestone task group의 후속 plan으로 정리되어 있다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 모든 기능 Task가 아직 충족되지 않았다. +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- Lemonade 서버 배포/운영 자체의 제품화 +- cloud fallback, 자동 부하 라우팅, 품질 평가 feedback의 본격 구현 +- 후속 최적화 계층 구현 +- Responses API 세부 호환 구현 +- 진행중인 Ollama/vLLM/SGLang provider Milestone 범위 변경 +- Ollama 경로 완료 기록 재작성 + +## 작업 컨텍스트 + +- 관련 경로: `apps/edge`, `apps/node`, `packages/go/config`, `proto/iop`, `configs`, `agent-test/local/edge-smoke.md`, `agent-test/local/node-smoke.md`, `agent-test/local/platform-common-smoke.md` +- 표준선(선택): 내부 실행 계약은 `adapter + target`을 유지하고, OpenAI-compatible API는 외부 호환 입력 표면으로 둔다. +- 표준선(선택): Node provider 상태와 capacity queue 기반을 Lemonade provider에도 동일하게 적용한다. +- 표준선(선택): 실제 provider가 보장하지 않는 확장 상태는 추가하지 않고, 초기 상태는 `unknown`, `available`, `unavailable`만 사용한다. +- 선행 작업: Node provider 상태와 Capacity Queue 기반 +- 후속 작업: Lemonade provider 실테스트에서 확인된 serving 경로 안정화 보완 +- 확인 필요: Lemonade adapter 경계, 실테스트 endpoint/served model name 또는 model, 인증/헤더 필요 여부, streaming 기대 동작 diff --git a/agent-roadmap/phase/inference-provider-extension/milestones/provider-availability-capacity-queue-foundation.md b/agent-roadmap/phase/inference-provider-extension/milestones/provider-availability-capacity-queue-foundation.md new file mode 100644 index 0000000..da6849d --- /dev/null +++ b/agent-roadmap/phase/inference-provider-extension/milestones/provider-availability-capacity-queue-foundation.md @@ -0,0 +1,81 @@ +# Milestone: Node provider 상태와 Capacity Queue 기반 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/inference-provider-extension/PHASE.md` + +## 목표 + +Ollama, Lemonade, vLLM, SGLang 같은 provider별 상태 확인 방식 차이를 Node adapter 내부로 숨기고, Edge가 동일한 형태로 provider 가용성과 부하 상태를 확인할 수 있게 만든다. +초기 상태 모델은 `unknown`, `available`, `unavailable`만 사용하고, provider별 capacity를 넘는 요청은 Node가 소유한 FIFO queue에서 대기시키는 기준선을 만든다. + +## 상태 + +[계획] + +## 승격 조건 + +- 없음 + +## 구현 잠금 + +- 상태: 해제 +- 결정 필요: 없음 + +## 범위 + +- Node provider adapter가 provider별 endpoint probe를 구현하되, Edge-visible 상태 결과는 동일한 최소 형태로 제공한다. +- 공통 provider 상태는 `unknown`, `available`, `unavailable`만 먼저 사용한다. +- provider별 configured capacity, current in-flight count, queued count, max queue, queue timeout을 Node가 소유하고 추적한다. +- capacity를 초과한 요청은 provider별 FIFO queue에 넣고, 실행 중 요청이 완료, 실패, 취소되면 가장 먼저 들어온 대기 요청을 실행 슬롯으로 올린다. +- Edge는 provider-specific endpoint를 알지 않고 Node가 제공하는 provider availability/load snapshot만 읽을 수 있게 한다. + +## 기능 + +### Epic: [provider-state] Provider Availability Snapshot + +Provider별 probe 차이를 Node 내부로 감추고 Edge가 라우팅 입력으로 사용할 수 있는 최소 상태 snapshot을 정의한다. + +- [ ] [status-model] Node가 Edge에 노출하는 provider 상태 모델은 `unknown`, `available`, `unavailable`로 제한하고, provider가 직접 보장하지 않는 `degraded`, `starting`, `draining` 같은 상태는 넣지 않는다. +- [ ] [probe-contract] Ollama, Lemonade, vLLM, SGLang 등 provider adapter가 endpoint 생존 여부와 target/model 사용 가능 여부를 확인하는 공통 probe 인터페이스를 구현한다. +- [ ] [edge-snapshot] Edge가 provider별 구현 세부를 모르고 Node의 provider 상태, capacity, in-flight, queued 값을 조회하거나 이벤트로 받을 수 있는 계약을 정리한다. + +### Epic: [capacity-queue] Capacity Gate and FIFO Queue + +Provider별 동시 처리 한도를 IOP가 소유하고, 한도를 넘는 요청을 예측 가능한 FIFO queue로 관리한다. + +- [ ] [capacity-config] provider target별 `capacity`, `max_queue`, `queue_timeout`, `request_timeout` 설정 기준을 정리하고 기본 config 예시에 반영한다. +- [ ] [admission-gate] Node provider executor가 `in_flight < capacity`일 때만 provider 호출을 시작하고, capacity가 찬 요청은 provider별 FIFO queue에 넣는다. +- [ ] [queue-release] 실행 중 요청이 응답, 실패, 취소, timeout으로 종료되면 `in_flight`를 줄이고 queue의 첫 요청을 실행 슬롯으로 승격한다. +- [ ] [queue-reject] `max_queue` 초과 또는 `queue_timeout` 초과 요청은 명확한 error/rejection reason으로 종료한다. +- [ ] [queue-observe] Edge가 보는 snapshot에 `capacity`, `in_flight`, `queued`가 포함되어 이후 capacity-aware routing의 입력으로 사용할 수 있다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 모든 기능 Task가 아직 충족되지 않았다. +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- 같은 로컬 모델을 묶는 model group alias 설계와 구현 +- 여러 Node/Edge 후보 중 여유 자원으로 자동 분산하는 본격 capacity-aware routing +- cloud fallback, 품질 평가 feedback, 비용/속도/품질 기반 모델 선택 +- `degraded`, `starting`, `draining` 같은 확장 상태 모델 +- provider 내부 metric을 해석해 capacity를 자동 조정하는 기능 +- 우선순위 queue, weighted queue, preemption 같은 고급 scheduling 정책 + +## 작업 컨텍스트 + +- 관련 경로: `apps/node`, `apps/edge`, `packages/go/config`, `proto/iop`, `configs` +- 표준선(선택): provider가 직접 제공하지 않는 상태를 IOP 공통 상태로 만들지 않고, 초기 상태는 `unknown`, `available`, `unavailable`만 사용한다. +- 표준선(선택): capacity와 queue는 provider 기능이 아니라 Node의 공통 provider execution wrapper 책임으로 둔다. +- 표준선(선택): Edge routing은 provider별 endpoint가 아니라 Node가 제공하는 availability/load snapshot을 입력으로 삼는다. +- 선행 작업: Node 단일 통로 멀티 타겟 서빙 기반 +- 후속 작업: Lemonade provider 서빙 경로 추가, vLLM provider 서빙 경로 추가, SGLang provider 서빙 경로 추가, model group alias와 capacity-aware routing Milestone +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md b/agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md new file mode 100644 index 0000000..cf84ffc --- /dev/null +++ b/agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md @@ -0,0 +1,72 @@ +# Milestone: vLLM provider 서빙 경로 추가 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/inference-provider-extension/PHASE.md` + +## 목표 + +Ollama 경로와 Node 단일 통로 멀티 타겟 기준선을 바탕으로 vLLM OpenAI-compatible provider를 붙인다. +Edge OpenAI-compatible 입력 표면에서 vLLM의 모델 조회, non-streaming/streaming chat, option/API passthrough, split-host smoke 기준을 검증한다. + +## 상태 + +[계획] + +## 승격 조건 + +- 없음 + +## 구현 잠금 + +- 상태: 잠금 +- 결정 필요: 아래 체크리스트 + - [ ] vLLM provider를 독립 `vllm` adapter로 둘지, OpenAI-compatible inference server 공통 adapter 계열로 둘지 결정한다. + - [ ] 실테스트에 사용할 vLLM endpoint, served model name, 기준 model, 인증/헤더 필요 여부, streaming 지원 기대 동작을 확인한다. + +## 범위 + +- vLLM provider를 Ollama 이후의 추가 추론 서버 provider 후보로 로드맵에 추가한다. +- Edge OpenAI-compatible API의 `/v1/models`, `/v1/chat/completions` non-streaming/streaming 요청이 vLLM provider 경로로 수렴하는 기준을 정한다. +- vLLM provider의 모델 조회, chat completion, streaming chunk, usage/finish reason, option/API passthrough 기대 동작을 실제 endpoint 기준으로 검증한다. +- split-host field smoke 기준을 vLLM provider에도 재사용한다. +- Ollama 경로에서 안정화된 기준을 흔들지 않도록 provider별 설정, target/model 매핑, adapter 책임 경계를 분리한다. + +## 기능 + +### Epic: [vllm-provider] vLLM Provider Serving Path + +- [ ] [provider-boundary] vLLM provider를 독립 adapter로 둘지 OpenAI-compatible inference server 공통 adapter로 둘지 결정 근거가 정리되어 있다. +- [ ] [config-contract] vLLM endpoint, served model name, model alias, auth/header, timeout, option passthrough 설정 계약이 정리되어 있다. +- [ ] [models-chat] Edge OpenAI-compatible `/v1/models`와 non-streaming `/v1/chat/completions`가 vLLM provider로 수렴하는 기준이 검증되어 있다. +- [ ] [streaming] streaming `/v1/chat/completions`에서 SSE chunk, finish reason, 종료 신호가 vLLM provider 경로로 안정적으로 전달되는지 검증되어 있다. +- [ ] [field-smoke] split-host field smoke에서 vLLM target/model을 선택해 모델 조회와 chat 왕복이 검증되어 있다. +- [ ] [follow-up-scope] 코드 수정이 필요한 항목은 이 Milestone의 추가 Task 또는 같은 Milestone task group의 후속 plan으로 정리되어 있다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 모든 기능 Task가 아직 충족되지 않았다. +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- cloud fallback, 자동 부하 라우팅, 품질 평가 feedback의 본격 구현 +- 후속 최적화 계층 구현 +- Responses API 세부 호환 구현 +- vLLM 서버 배포/운영 자체의 제품화 +- Ollama 경로 완료 기록 재작성 + +## 작업 컨텍스트 + +- 관련 경로: `apps/edge`, `apps/node`, `packages/go/config`, `proto/iop`, `configs`, `agent-test/local/edge-smoke.md`, `agent-test/local/node-smoke.md`, `agent-test/local/platform-common-smoke.md` +- 표준선(선택): 내부 실행 계약은 `adapter + target`을 유지하고, OpenAI-compatible API는 외부 호환 입력 표면으로 둔다. +- 표준선(선택): Ollama provider에서 안정화한 field smoke 기준을 vLLM provider에도 그대로 적용한다. +- 선행 작업: Ollama 실테스트와 후속 안정화, Node 단일 통로 멀티 타겟 서빙 기반 +- 후속 작업: vLLM provider 실테스트에서 확인된 serving 경로 안정화 보완 +- 확인 필요: vLLM adapter 경계, 실테스트 endpoint/served model name, 인증/헤더 필요 여부, streaming 기대 동작