From 98a976a7468f0db00de0ad11e25cd8589e1792f1 Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 17 Jun 2026 20:18:28 +0900 Subject: [PATCH] feat(roadmap): vLLM provider milestone updates and SDD/split task structure - Update vllm-provider-serving-validation.md: unlock state, finalize decisions - Add SDD directory structure for vLLM provider serving validation - Add split task directories: 01_spark_container, 02+01_config_contract, 03+02_openai_vllm_smoke, 04+03_field_smoke - Record decisions on adapter approach, base URL/port, model alias, auth, streaming --- .../vllm-provider-serving-validation.md | 25 +- .../vllm-provider-serving-validation/SDD.md | 115 ++++++++++ .../code_review_cloud_G07_0.log | 213 ++++++++++++++++++ .../01_spark_container/complete.log | 48 ++++ .../01_spark_container/plan_cloud_G07_0.log | 92 ++++++++ .../CODE_REVIEW-local-G06.md | 124 ++++++++++ .../02+01_config_contract/PLAN-local-G06.md | 98 ++++++++ .../CODE_REVIEW-cloud-G07.md | 127 +++++++++++ .../03+02_openai_vllm_smoke/PLAN-cloud-G07.md | 100 ++++++++ .../CODE_REVIEW-cloud-G07.md | 124 ++++++++++ .../04+03_field_smoke/PLAN-cloud-G07.md | 95 ++++++++ 11 files changed, 1151 insertions(+), 10 deletions(-) create mode 100644 agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md create mode 100644 agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/code_review_cloud_G07_0.log create mode 100644 agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/complete.log create mode 100644 agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/plan_cloud_G07_0.log create mode 100644 agent-task/m-vllm-provider-serving-validation/02+01_config_contract/CODE_REVIEW-local-G06.md create mode 100644 agent-task/m-vllm-provider-serving-validation/02+01_config_contract/PLAN-local-G06.md create mode 100644 agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/CODE_REVIEW-cloud-G07.md create mode 100644 agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/PLAN-cloud-G07.md create mode 100644 agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/CODE_REVIEW-cloud-G07.md create mode 100644 agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/PLAN-cloud-G07.md 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 index 4578c6e..98e6ba8 100644 --- 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 @@ -20,20 +20,19 @@ Edge OpenAI-compatible 입력 표면에서 vLLM의 모델 조회, non-streaming/ ## 구현 잠금 -- 상태: 잠금 +- 상태: 해제 - SDD: 필요 - SDD 경로: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` -- 잠금 해제 조건: SDD가 승인되고, vLLM provider 경계와 DGX Spark 실테스트 endpoint/served model/auth/streaming 기대 동작이 구현 계획을 만들 수 있을 만큼 확정되어야 한다. -- 결정 필요: 아래 체크리스트 - - [ ] vLLM provider를 독립 `vllm` adapter로 둘지, OpenAI-compatible inference server 공통 adapter 계열로 둘지 결정한다. - - [ ] DGX Spark 실테스트의 vLLM base URL/port, IOP에서 노출할 served model alias, 인증/헤더 필요 여부, streaming 지원 기대 동작을 확인한다. +- 잠금 해제 조건: SDD가 승인되고, 결정된 OpenAI-compatible inference server adapter 계열 경계와 DGX Spark 실테스트 endpoint/served model/auth/streaming 기대 동작이 구현 계획에 반영되어야 한다. +- 잠금 해제 근거: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md`가 `[승인됨]`/해제 상태이며, 남은 구현/검증 항목이 `agent-task/m-vllm-provider-serving-validation/`의 split plan으로 분리되어 있다. +- 결정 필요: 없음 ## 범위 - vLLM provider를 Ollama 이후의 추가 추론 서버 provider 후보로 로드맵에 추가한다. - 실테스트 기준 host는 `agent-test/local/rules.md`에 기록된 DGX Spark field host로 둔다. - vLLM 관련 사전 세팅이 없다는 전제로 DGX Spark ARM64/Blackwell용 vLLM container를 올리는 작업부터 범위에 포함한다. -- 기준 모델은 DGX Spark vLLM recipe의 NVFP4 checkpoint인 `nvidia/Qwen3.6-35B-A3B-NVFP4`로 둔다. 원천 BF16 모델 ID는 `Qwen/Qwen3.6-35B-A3B`이며, Ollama식 사용 의도 `qwen3.6:35b`는 IOP model alias 또는 served model alias 후보로 검증한다. +- 기준 모델은 DGX Spark vLLM recipe의 NVFP4 checkpoint인 `nvidia/Qwen3.6-35B-A3B-NVFP4`로 둔다. 원천 BF16 모델 ID는 `Qwen/Qwen3.6-35B-A3B`이며, IOP model alias는 Ollama식 사용 의도와 맞춘 `qwen3.6:35b`로 둔다. - 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에도 재사용한다. @@ -43,13 +42,13 @@ Edge OpenAI-compatible 입력 표면에서 vLLM의 모델 조회, non-streaming/ ### Epic: [vllm-provider] vLLM Provider Serving Path -- [ ] [provider-boundary] vLLM provider를 독립 adapter로 둘지 OpenAI-compatible inference server 공통 adapter로 둘지 결정 근거가 정리되어 있다. +- [x] [provider-boundary] vLLM provider를 독립 adapter로 둘지 OpenAI-compatible inference server 공통 adapter로 둘지 결정 근거가 정리되어 있다. - [ ] [spark-container] `agent-test/local/rules.md`의 DGX Spark field host에서 ARM64/Blackwell용 vLLM container image/tag, model cache/volume, launch command, health check 기준이 정리되고 container 기동이 검증되어 있다. 검증: DGX Spark vLLM endpoint의 OpenAI-compatible `/v1/models`가 응답한다. - [ ] [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으로 정리되어 있다. +- [x] [follow-up-scope] 코드 수정이 필요한 항목은 이 Milestone의 추가 Task 또는 같은 Milestone task group의 후속 plan으로 정리되어 있다. ## 완료 리뷰 @@ -77,9 +76,15 @@ Edge OpenAI-compatible 입력 표면에서 vLLM의 모델 조회, non-streaming/ - 표준선(선택): 내부 실행 계약은 `adapter + target`을 유지하고, OpenAI-compatible API는 외부 호환 입력 표면으로 둔다. - 표준선(선택): Ollama provider에서 안정화한 field smoke 기준을 vLLM provider에도 그대로 적용한다. - 표준선(선택): 이 Milestone의 DGX Spark vLLM 결과는 후속 qualification report의 seed evidence로 남길 수 있지만, report 저장/조회/비교 제품화는 `운영 관측과 Provider 관리` Phase 후반부에서 다룬다. +- 결정됨: vLLM은 독립 전용 adapter보다 OpenAI-compatible inference server 공통 adapter 계열로 다룬다. vLLM 서버는 vLLM이 지원하는 OpenAI-compatible API server 형식을 벗어나지 않고 독립 실행 가능하게 두며, Node는 해당 endpoint를 호출한다. +- 결정됨: vLLM provider별 차이는 공통 adapter 안의 `provider: vllm` profile/capability와 target/model 매핑으로 분리한다. 특정한 필요가 없는 한 vLLM 자체 커스터마이징은 피해서 upstream 업데이트를 쉽게 받는 방향을 기준으로 둔다. - 결정됨: vLLM 실테스트 host는 `agent-test/local/rules.md`에 기록된 DGX Spark field host이며, vLLM container 세팅부터 시작한다. -- 결정됨: DGX Spark 기준 vLLM 모델 handle은 `nvidia/Qwen3.6-35B-A3B-NVFP4`로 둔다. 원천 모델은 `Qwen/Qwen3.6-35B-A3B`이고, `qwen3.6:35b`는 IOP model alias 또는 vLLM served model alias 후보로 검증한다. +- 결정됨: DGX Spark 기준 vLLM base URL/port는 `http://:8000/v1`로 둔다. ``는 `agent-test/local/rules.md`의 DGX Spark field host 값을 사용한다. +- 결정됨: DGX Spark 기준 vLLM served model name은 `nvidia/Qwen3.6-35B-A3B-NVFP4`로 둔다. 원천 모델은 `Qwen/Qwen3.6-35B-A3B`이며, IOP 외부 노출 model alias는 `qwen3.6:35b`로 둔다. +- 결정됨: field smoke 단계의 vLLM endpoint 인증/추가 헤더는 없음으로 둔다. 추후 인증이 필요한 환경은 config contract 확장에서 별도 옵션으로 다룬다. +- 결정됨: vLLM streaming은 지원 전제로 검증한다. `/v1/chat/completions`의 `stream: true` SSE chunk, `finish_reason`, 종료 신호를 확인 대상으로 둔다. +- 계획됨: `agent-task/m-vllm-provider-serving-validation/01_spark_container`, `02+01_config_contract`, `03+02_openai_vllm_smoke`, `04+03_field_smoke`로 남은 작업을 분리한다. - 외부 근거: `https://recipes.vllm.ai/Qwen/Qwen3.6-35B-A3B`, `https://huggingface.co/Qwen/Qwen3.6-35B-A3B`, `https://build.nvidia.com/spark/vllm` - 선행 작업: Ollama 실테스트와 후속 안정화, Node 단일 통로 멀티 타겟 서빙 기반 - 후속 작업: vLLM provider 실테스트에서 확인된 serving 경로 안정화 보완 -- 확인 필요: vLLM adapter 경계, DGX Spark vLLM base URL/port, IOP에서 노출할 served model alias, 인증/헤더 필요 여부, streaming 기대 동작 +- 확인 필요: DGX Spark vLLM container image/tag, model cache/volume, launch command, health check 실측 diff --git a/agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md b/agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md new file mode 100644 index 0000000..e8073da --- /dev/null +++ b/agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md @@ -0,0 +1,115 @@ +# SDD: vLLM provider 서빙 경로 추가 + +## 위치 + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Phase: `agent-roadmap/phase/inference-provider-extension/PHASE.md` + +## 상태 + +[승인됨] + +## SDD 잠금 + +- 상태: 해제 +- 사용자 리뷰: 없음 +- 잠금 항목: + - 없음 + +## 문제 / 비목표 + +- 문제: vLLM provider 작업은 DGX Spark field host의 container 준비, OpenAI-compatible provider 설정 계약, Edge/Node 모델 조회와 chat 경로, streaming SSE, split-host smoke가 함께 얽혀 있다. 구현 전에 provider 경계와 검증 증거 기준을 하나의 source of truth로 고정해야 한다. +- 비목표: + - provider/device/model qualification report 저장/조회/비교 제품화 + - cloud fallback, 자동 부하 라우팅, 품질 평가 feedback 계층 구현 + - Responses API 세부 호환 구현 + - vLLM 서버 배포/운영 자체의 제품화 + - 기존 Ollama 경로 완료 기록 재작성 + +## Source of Truth + +| 영역 | 기준 | 메모 | +|------|------|------| +| Roadmap | `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` | 기능 Task 상태와 완료 근거 원장 | +| Contract | `agent-contract/provided/openai-compatible-api.md` | OpenAI-compatible 입력 표면과 내부 `adapter + target` 경계 | +| Code | `apps/edge`, `apps/node`, `packages/go/config`, `proto/iop`, `configs`, `scripts` | Edge route, Node adapter, config contract, smoke 구현 기준 | +| Test Rules | `agent-test/local/rules.md`, `agent-test/local/edge-smoke.md`, `agent-test/local/node-smoke.md`, `agent-test/local/platform-common-smoke.md` | local/field 검증 경계와 DGX Spark 접근 기준 | +| External Provider | vLLM OpenAI-compatible server, `nvidia/Qwen3.6-35B-A3B-NVFP4` | DGX Spark ARM64/Blackwell field validation 기준 model | +| User Decision | 없음 | 현재 Milestone에 남은 사용자 전용 결정 없음 | + +## State Machine + +| 상태 | 진입 조건 | 다음 상태 | 근거 | +|------|-----------|-----------|------| +| `planned` | SDD 승인 및 잠금 해제 | `container-ready` | `spark-container` plan PASS | +| `container-ready` | DGX Spark vLLM container가 `/v1/models`에 응답 | `config-contract-ready` | image/tag/cache/launch/health evidence | +| `config-contract-ready` | vLLM endpoint, served model, alias, auth/header, timeout, option passthrough 계약 반영 | `edge-node-validated` | config/tests/smoke evidence | +| `edge-node-validated` | `/v1/models`, non-streaming chat, streaming SSE가 vLLM provider 경로로 수렴 | `field-smoke-ready` | Edge/Node smoke evidence | +| `field-smoke-ready` | split-host smoke에서 vLLM target/model 왕복 검증 | `complete-candidate` | field smoke evidence | +| `complete-candidate` | 모든 기능 Task PASS 증거가 complete.log에 남음 | Milestone 완료 후보 | update-roadmap | + +## Interface Contract + +- 계약 원문: `agent-contract/provided/openai-compatible-api.md` +- 입력: + - `openai.model`: 외부 OpenAI-compatible API에 노출되는 alias. DGX Spark vLLM 기준값은 `qwen3.6:35b`. + - `openai.model_routes[].adapter`: 내부 provider adapter 이름. vLLM은 OpenAI-compatible inference server 공통 adapter 계열로 다룬다. + - `openai.model_routes[].target`: provider가 실제로 호출할 served model. DGX Spark vLLM 기준값은 `nvidia/Qwen3.6-35B-A3B-NVFP4`. + - `adapters.openai_compat_instances[].provider`: provider profile 식별자. vLLM 경로는 `vllm`을 사용한다. + - `adapters.openai_compat_instances[].endpoint`: OpenAI-compatible server base URL. field 기준은 `http://:8000/v1`이며 실제 host 값은 tracked 문서에 고정하지 않는다. + - `adapters.openai_compat_instances[].headers`: 인증/추가 header. field smoke 기본값은 없음이다. + - `options`, `format`, `tools`, `think`, `keep_alive`: adapter-owned `model`/`stream`을 침범하지 않는 범위에서 provider 요청으로 passthrough한다. +- 출력: + - `/v1/models`: Edge는 route alias를 노출하고, provider health check는 served model이 조회되는지 확인한다. + - `/v1/chat/completions`: non-streaming 응답이 OpenAI-compatible chat response로 반환된다. + - streaming `/v1/chat/completions`: SSE chunk, content/reasoning delta, `finish_reason`, 종료 신호가 Edge/Node 경로를 지나 안정적으로 전달된다. +- 금지: + - 내부 실행 계약을 model-centered 구조로 되돌리지 않는다. + - tracked 문서/설정에 private endpoint, token, secret을 기록하지 않는다. + - 현재 작업 container 안에서 DGX Spark vLLM container를 기동하지 않는다. + - Edge가 Node provider 경로를 우회해 vLLM endpoint를 직접 호출하지 않는다. + +## Acceptance Scenarios + +| ID | Milestone Task | Given | When | Then | +|----|----------------|-------|------|------| +| S01 | `spark-container` | DGX Spark field host 접근과 vLLM model 기준이 정해져 있다 | ARM64/Blackwell용 vLLM container image/tag, cache volume, launch command를 적용한다 | field host의 provider `/v1/models`가 응답하고 image digest/tag와 launch evidence가 남는다 | +| S02 | `config-contract` | vLLM provider를 OpenAI-compatible 공통 adapter 계열로 쓰기로 했다 | config/examples/tests에 endpoint, served model, alias, headers, timeout, option passthrough 계약을 반영한다 | Edge/Node/config 계약이 `adapter + target` 기준으로 검증된다 | +| S03 | `models-chat` | vLLM config contract가 반영되어 있다 | Edge `/v1/models`와 non-streaming `/v1/chat/completions` smoke를 실행한다 | route alias 조회와 chat 왕복이 vLLM provider 경로로 검증된다 | +| S04 | `streaming` | vLLM provider endpoint가 streaming을 지원한다 | streaming `/v1/chat/completions` smoke를 실행한다 | SSE chunk, finish reason, 종료 신호가 검증된다 | +| S05 | `field-smoke` | container, config, local smoke 기준이 준비되어 있다 | split-host field smoke에서 vLLM target/model을 선택한다 | 실제 Edge/Node field 경로에서 모델 조회와 chat 왕복이 검증된다 | +| S06 | `follow-up-scope` | code/config/script 변경이 필요한 항목이 식별되어 있다 | Milestone task group에 후속 plan을 작성한다 | 구현 범위가 active plan으로 분리되어 있다 | + +## Evidence Map + +| Scenario | Required Evidence | `agent-task` 연결 | `Spec Completion` 기대 | +|----------|-------------------|------------------|---------------------------| +| S01 | DGX Spark `docker image inspect`, launch command, health check `/v1/models` output | `agent-task/m-vllm-provider-serving-validation/01_spark_container` | vLLM container image/tag/cache/launch/health 기준 검증 | +| S02 | config examples/tests, mapper/factory/config test output | `agent-task/m-vllm-provider-serving-validation/02+01_config_contract` | vLLM endpoint/served model/alias/auth/timeout/options 계약 검증 | +| S03 | fake 또는 real vLLM smoke의 `/v1/models`와 non-streaming chat output | `agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke` | Edge `/v1/models`와 non-streaming chat provider 수렴 검증 | +| S04 | streaming smoke SSE chunk, `finish_reason`, `data: [DONE]` output | `agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke` | streaming chat completion 전달 검증 | +| S05 | split-host field smoke command/output와 target/model evidence | `agent-task/m-vllm-provider-serving-validation/04+03_field_smoke` | 실제 field 경로 모델 조회와 chat 왕복 검증 | +| S06 | active plan/review stub 목록과 Milestone `follow-up-scope` 체크 | `agent-task/m-vllm-provider-serving-validation/*` | 코드 수정 범위가 후속 plan으로 정리됨 | + +## Cross-repo Dependencies + +- 없음 + +## Drift Check + +- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다. +- [x] Evidence Map이 plan/code-review/complete.log에서 검증 가능하다. +- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다. +- [x] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다. + +## 사용자 리뷰 이력 + +- 없음 + +## 작업 컨텍스트 + +- 표준선: 내부 실행 계약은 `adapter + target`을 유지하고, OpenAI-compatible API는 외부 호환 입력 표면으로 둔다. +- 표준선: vLLM은 전용 내부 adapter 확장보다 OpenAI-compatible inference server 공통 adapter 계열의 `provider: vllm` profile과 target/model 매핑으로 다룬다. +- 표준선: DGX Spark field host 값과 private endpoint는 `agent-test/local/rules.md`에만 둔다. +- field container 후보: ARM64 환경은 vLLM OpenAI-compatible server Docker image의 ARM64 tag를 우선 검증하고, 실제 digest/tag는 `01_spark_container` 완료 evidence로 고정한다. +- 후속 SDD: 없음 diff --git a/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/code_review_cloud_G07_0.log b/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/code_review_cloud_G07_0.log new file mode 100644 index 0000000..ba7dffd --- /dev/null +++ b/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/code_review_cloud_G07_0.log @@ -0,0 +1,213 @@ + +# Code Review: DGX Spark vLLM container 기동 검증 + +## 개요 + +- Plan: `PLAN-cloud-G07.md` +- Roadmap Task: `spark-container` +- Spec Scenario: `S01` + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Task: `spark-container` + +## Spec Targets + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Scenario: `S01` + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 field evidence와 대조하고, `검증 결과` 섹션의 출력이 계획의 명령과 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-cloud-G07.md` -> `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` -> `plan_cloud_G07_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-vllm-provider-serving-validation/01_spark_container/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. +4. PASS이고 task group이 `m-vllm-provider-serving-validation`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [VLLM_CONTAINER-1] vLLM image/tag/digest 후보 확인 | [x] | +| [VLLM_CONTAINER-2] DGX Spark launch command와 cache/volume 기준 정리 | [x] | +| [VLLM_CONTAINER-3] `/v1/models` health check 검증 | [x] | + +## 구현 체크리스트 + +- [x] DGX Spark field host에서 ARM64/Blackwell용 vLLM OpenAI-compatible server image/tag와 digest 후보를 확인한다. +- [x] model cache/volume 경로와 launch command를 정리하고, token/secret이 stdout 또는 tracked 파일에 남지 않게 실행한다. +- [x] vLLM container를 기동하고 provider local health endpoint `http://127.0.0.1:8001/v1/models`가 served model을 반환하는지 검증한다. +- [x] container 이름, image digest/tag, model cache/volume, launch command, health check 출력 요약을 review stub에 기록한다. +- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다. +- [x] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다. +- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [x] PASS이면 active task 디렉터리 `agent-task/m-vllm-provider-serving-validation/01_spark_container/`를 `agent-task/archive/YYYY/MM/m-vllm-provider-serving-validation/01_spark_container/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [x] PASS이고 task group이 `m-vllm-provider-serving-validation`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-vllm-provider-serving-validation/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. sibling task가 남아 parent를 유지했다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +1. **포트 변경: 8000 → 8001** + - 사유: DGX Spark host의 8000 포트를 기존 Whisper API Server(`whisper_server` container)가 이미 점유 중. + - 변경: `-p 8001:8000` (host 8001 → container 내부 8000). 검증 명령에서 포트를 8001로 대체. + +2. **`--gpu-memory-utilization 0.87` 추가** + - 사유: default 0.92 기준 110.06 GiB 요구 vs. 실제 free 108 GiB 미충족. `python` 4088 MiB, `Xorg` 43 MiB 등 기타 프로세스 상주. + - 변경: 0.87 (≈ 104 GiB 요구)로 낮춰 기동 성공. + +3. **Ollama 모델 사전 unload 필요** + - 사유: `qwen3.6:35b-a3b-bf16` (~82 GB)가 로드된 상태여서 메모리 부족. `ollama stop` API 호출로 unload 후 진행. + - 이 조건은 재기동 시 재현될 수 있음. vLLM 기동 전 Ollama 모델 unload 또는 `--gpu-memory-utilization` 조정이 필요. + +4. **이미지 및 모델 신규 pull/download 필요** + - 계획의 `vllm/vllm-openai:nightly-aarch64` 이미지가 host에 없어 `docker pull` 수행 (21.3 GB, ~10분). + - `nvidia/Qwen3.6-35B-A3B-NVFP4` 모델이 host에 없어 HuggingFace에서 다운로드 수행 (22 GB). `huggingface_hub` 패키지를 `pip3 install --break-system-packages`로 설치 후 진행. + +5. **`--max-model-len 32768`, `--dtype auto` 추가** + - 표준 기동 파라미터로 추가. context 제한 없이 최대값 32768 사용. + +## 주요 설계 결정 + +1. **image 선택: `vllm/vllm-openai:nightly-aarch64` 채택** + - Docker Hub에서 현재 날짜(2026-06-17) 기준 가장 최신 ARM64 nightly 태그. `cu129-nightly-aarch64`도 동일 날짜 존재하나, plan 명세와 일치하는 `nightly-aarch64`를 우선 채택. + - stable 릴리스 `v0.23.0-aarch64-cu129-ubuntu2404`도 후보지만, Blackwell/new kernel feature 접근성 고려해 nightly 사용. + +2. **GB10 NVFP4 native 미지원 확인** + - vLLM 로그: "Your GPU does not have native support for FP4 computation but FP4 quantization is being used. Weight-only FP4 compression will be used leveraging the Marlin kernel." + - GB10은 FP4 native 연산 없이 Marlin kernel을 통한 weight-only 압축으로 동작. 성능 저하 가능성 있음. 후속 config/smoke plan에서 실제 throughput 확인 필요. + +3. **model cache 위치: `/home/toki/Data/models/` (외부 마운트 NVMe)** + - `/home/toki/Data` (ext4, 1.8 TB NVMe)에 384 GB Ollama 모델이 이미 상주. 동일 위치에 `/home/toki/Data/models/nvidia/Qwen3.6-35B-A3B-NVFP4/` 경로 생성. + - container volume: `-v /home/toki/Data/models:/models` + +4. **Docker nvidia runtime 미등록 상태에서 `--gpus all` 동작 확인** + - `/etc/docker/daemon.json` 없음, docker info에 nvidia runtime 미등록 상태. + - `--gpus all` 플래그가 정상 동작하는 이유: `nvidia-container-toolkit` 1.18.2가 설치되어 있고 `nvidia-container-runtime` binary가 `/usr/bin/`에 존재해 Docker가 자동 감지. + +## 사용자 리뷰 요청 + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- private host, token, secret이 tracked 파일이나 검증 출력에 남지 않았는지 확인한다. +- `/v1/models` health check가 실제 DGX Spark field host의 local provider endpoint에서 실행되었는지 확인한다. +- image tag뿐 아니라 digest 또는 동등한 고정 evidence가 남았는지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. + +### VLLM_CONTAINER-1 중간 검증 + +```bash +$ DGX_SPARK_SSH="" ssh "$DGX_SPARK_SSH" 'docker image inspect vllm/vllm-openai:nightly-aarch64 --format "{{json .RepoDigests}}"' +["vllm/vllm-openai@sha256:1aef087aa5159bcb8f8cb91301ecdf2f6daa6aa41420706afe30b6a9a7001858"] +``` + +추가 image 정보: +- 태그: `vllm/vllm-openai:nightly-aarch64` +- 사이즈: 21.3 GB +- vLLM 버전: `0.23.1rc1.dev101+g4c6266331` +- 아키텍처: aarch64 (ARM64) +- pull 날짜: 2026-06-17 + +### VLLM_CONTAINER-2 중간 검증 (launch command, cache/volume) + +실행 명령: +```bash +docker run -d \ + --name iop-vllm-qwen36 \ + --gpus all \ + -p 8001:8000 \ + -v /home/toki/Data/models:/models \ + vllm/vllm-openai:nightly-aarch64 \ + --model /models/nvidia/Qwen3.6-35B-A3B-NVFP4 \ + --served-model-name nvidia/Qwen3.6-35B-A3B-NVFP4 \ + --host 0.0.0.0 \ + --port 8000 \ + --dtype auto \ + --max-model-len 32768 \ + --gpu-memory-utilization 0.87 +``` + +모델 캐시: +- host 경로: `/home/toki/Data/models/nvidia/Qwen3.6-35B-A3B-NVFP4/` +- container 내부 경로: `/models/nvidia/Qwen3.6-35B-A3B-NVFP4` +- 파일 구성: `model-00001-of-00003.safetensors` (9.4 GB) + `model-00002-of-00003.safetensors` (9.4 GB) + `model-00003-of-00003.safetensors` (3.2 GB) + 메타데이터 +- 총 크기: ~22 GB +- 소스: HuggingFace `nvidia/Qwen3.6-35B-A3B-NVFP4` (gated: False, public) + +### 최종 검증 + +```bash +$ DGX_SPARK_SSH="" ssh "$DGX_SPARK_SSH" 'set -eu +docker image inspect vllm/vllm-openai:nightly-aarch64 --format "{{json .RepoDigests}}" +docker ps --filter name=iop-vllm-qwen36 --format "{{.Names}} {{.Image}} {{.Status}}" +curl -fsS http://127.0.0.1:8001/v1/models' +["vllm/vllm-openai@sha256:1aef087aa5159bcb8f8cb91301ecdf2f6daa6aa41420706afe30b6a9a7001858"] +iop-vllm-qwen36 vllm/vllm-openai:nightly-aarch64 Up 6 minutes +{"object":"list","data":[{"id":"nvidia/Qwen3.6-35B-A3B-NVFP4","object":"model","created":1781684240,"owned_by":"vllm","root":"/models/nvidia/Qwen3.6-35B-A3B-NVFP4","parent":null,"max_model_len":32768,"permission":[{"id":"modelperm-90788b710a5b5b4c","object":"model_permission","created":1781684240,"allow_create_engine":false,"allow_sampling":true,"allow_logprobs":true,"allow_search_indices":false,"allow_view":true,"allow_fine_tuning":false,"organization":"*","group":null,"is_blocking":false}]}]} +``` + +host 환경 요약: +- GPU: NVIDIA GB10 (Grace Blackwell), driver 580.126.09, CUDA 13.0 +- 아키텍처: aarch64 +- 총 통합 메모리: 119.64 GiB +- vLLM model 로딩 시간: 108.44초 (safetensors 3 shards), 모델 메모리: 20.37 GiB +- NVFP4 backend: Marlin (GB10은 FP4 native 미지원, weight-only 압축 동작) +- 확정 endpoint (후속 plan 기준): `http://:8001/v1` (Edge/Node에서 접근 가능한 host/port는 `agent-test/local/rules.md`의 local-only 값 기준) + +--- + +> **[IMPLEMENTING AGENT - BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## 코드리뷰 결과 + +- 종합 판정: PASS +- 차원별 평가: + - correctness: Pass - ARM64 vLLM image digest, launch command, cache/volume, container running 상태, `/v1/models` served model evidence가 S01 요구와 일치한다. + - completeness: Pass - 계획된 세 항목과 review stub completion checklist가 모두 채워졌고, 8001 포트 변경은 충돌 회피 사유와 검증 명령 대체가 기록되어 있다. + - test coverage: Pass - 최종 field command를 리뷰 중 재실행했고 동일 digest/container/model 응답을 확인했다. + - API contract: Pass - served model `nvidia/Qwen3.6-35B-A3B-NVFP4`와 후속 Edge/Node base URL 기준이 OpenAI-compatible provider 경계로 기록되어 있다. + - code quality: Pass - 코드 변경 없음. task artifact의 private SSH target/host IP 표기는 ``와 ``로 정리했다. + - plan deviation: Pass - host port 8000 점유로 `8001:8000`을 사용한 변경은 구현 섹션에 근거가 있으며 SDD S01의 provider health evidence를 해치지 않는다. + - verification trust: Pass - 리뷰 중 동일 원격 검증 명령을 재실행해 image digest, running container, `/v1/models` served model 응답을 확인했다. + - spec conformance: Pass - SDD `S01` Evidence Map의 `docker image inspect`, launch command, health check `/v1/models` output이 충족되었다. +- 발견된 문제: 없음 +- 다음 단계: PASS - `complete.log` 작성 후 task directory를 archive로 이동한다. diff --git a/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/complete.log b/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/complete.log new file mode 100644 index 0000000..64009c6 --- /dev/null +++ b/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/complete.log @@ -0,0 +1,48 @@ +# Complete - m-vllm-provider-serving-validation/01_spark_container + +## 완료 일시 + +2026-06-17 + +## 요약 + +DGX Spark vLLM container 기동 검증을 1회 리뷰 루프로 완료했다. 최종 판정은 PASS다. + +## 루프 이력 + +| Plan | Review | Verdict | 메모 | +|------|--------|---------|------| +| `plan_cloud_G07_0.log` | `code_review_cloud_G07_0.log` | PASS | vLLM image digest, launch command/cache/volume, `/v1/models` served model evidence를 확인했다. | + +## 구현/정리 내용 + +- DGX Spark field host에서 `vllm/vllm-openai:nightly-aarch64` image digest와 ARM64/aarch64 기준을 확인했다. +- `iop-vllm-qwen36` container launch command, model cache/volume, served model `nvidia/Qwen3.6-35B-A3B-NVFP4` evidence를 기록했다. +- host port 충돌을 피하기 위해 `8001:8000`으로 노출한 사유와 검증 명령 대체 근거를 남겼다. +- 리뷰 중 task artifact의 private SSH target/host IP 표기를 ``와 ``로 정리했다. + +## 최종 검증 + +- `DGX_SPARK_SSH="" ssh "$DGX_SPARK_SSH" 'set -eu; docker image inspect vllm/vllm-openai:nightly-aarch64 --format "{{json .RepoDigests}}"; docker ps --filter name=iop-vllm-qwen36 --format "{{.Names}} {{.Image}} {{.Status}}"; curl -fsS http://127.0.0.1:8001/v1/models'` - PASS; image digest `sha256:1aef087aa5159bcb8f8cb91301ecdf2f6daa6aa41420706afe30b6a9a7001858`, running container `iop-vllm-qwen36`, served model `nvidia/Qwen3.6-35B-A3B-NVFP4` 응답을 확인했다. + +## Roadmap Completion + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Completed task ids: + - `spark-container`: PASS; evidence=`agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/plan_cloud_G07_0.log`, `agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/code_review_cloud_G07_0.log`; verification=`DGX Spark vLLM docker image inspect + docker ps + /v1/models field command` +- Not completed task ids: 없음 + +## Spec Completion + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Completed scenario ids: + - `S01`: PASS; task=`spark-container`; evidence=`agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/plan_cloud_G07_0.log`, `agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/code_review_cloud_G07_0.log`; verification=`DGX Spark vLLM docker image inspect + docker ps + /v1/models field command` +- Not completed scenario ids: 없음 + +## 잔여 Nit + +- 없음 + +## 후속 작업 + +- 없음 diff --git a/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/plan_cloud_G07_0.log b/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/plan_cloud_G07_0.log new file mode 100644 index 0000000..37590f0 --- /dev/null +++ b/agent-task/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/plan_cloud_G07_0.log @@ -0,0 +1,92 @@ + +# Plan: DGX Spark vLLM container 기동 검증 + +## 이 파일을 읽는 구현 에이전트에게 + +이 plan은 `spark-container` Task를 구현/검증하기 위한 실행 계약이다. 구현 에이전트는 실제 변경과 검증 출력으로 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 반드시 채우고, 코드리뷰 전용 섹션이나 archive/complete.log 작성은 수행하지 않는다. + +사용자 전용 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 충돌 없이는 안전하게 진행할 수 없는 경우 직접 질문하지 말고 review stub의 `사용자 리뷰 요청` 섹션에 정확한 결정 필요 사항, 증거, 실행 명령/출력, 재개 조건을 기록한 뒤 중단한다. 후속 에이전트가 명령 재실행이나 증거 수집으로 해소할 수 있는 공백은 사용자 리뷰 요청이 아니다. + +## 사용자 리뷰 요청 흐름 + +구현 중 blocker는 active `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에만 기록한다. 구현 에이전트는 chat에서 사용자에게 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. code-review가 blocker 정당성을 검증하고 필요한 경우 `USER_REVIEW.md`를 작성한다. + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Task: `spark-container` + +## Spec Targets + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Scenario: `S01` + +## 분석 결과 + +### 읽은 파일 + +- `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- `agent-test/local/rules.md` +- `agent-test/local/edge-smoke.md` +- `agent-test/local/node-smoke.md` + +### 테스트 환경 규칙 + +- local container 안에서 vLLM container를 실행하지 않는다. +- DGX Spark field host 접근 값과 private endpoint는 `agent-test/local/rules.md`의 local-only 값으로 주입한다. +- field 실행은 `DGX_SPARK_SSH`를 설정한 shell에서 수행한다. 이 값은 tracked 파일에 기록하지 않는다. + +### 테스트 커버리지 공백 + +- 이 작업은 container 기동과 provider health 검증까지만 완료한다. +- Edge/Node config, chat, streaming, split-host smoke는 후속 plan에서 검증한다. + +### 심볼 참조 + +- vLLM provider는 이후 `openai_compat` adapter 계열에서 호출될 endpoint를 제공한다. +- served model 기준값: `nvidia/Qwen3.6-35B-A3B-NVFP4` +- external alias 기준값: `qwen3.6:35b` + +### 분할 판단 + +- DGX Spark container 준비는 외부 runtime과 model cache를 다루므로 config/code 변경 plan과 분리한다. +- 이 plan PASS 후 `02+01_config_contract`가 실제 endpoint/served model evidence를 사용한다. + +### 범위 결정 근거 + +- 포함: image/tag/digest 후보 검증, model cache/volume, launch command, `/v1/models` health check. +- 제외: Edge/Node 설정 변경, smoke script 작성, split-host field smoke. + +### 빌드 등급 + +- `cloud-G07`: 원격 field host와 container runtime이 필수인 외부 runtime 검증이다. + +## 구현 체크리스트 + +- [ ] DGX Spark field host에서 ARM64/Blackwell용 vLLM OpenAI-compatible server image/tag와 digest 후보를 확인한다. +- [ ] model cache/volume 경로와 launch command를 정리하고, token/secret이 stdout 또는 tracked 파일에 남지 않게 실행한다. +- [ ] vLLM container를 기동하고 provider local health endpoint `http://127.0.0.1:8000/v1/models`가 served model을 반환하는지 검증한다. +- [ ] container 이름, image digest/tag, model cache/volume, launch command, health check 출력 요약을 review stub에 기록한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 구현 항목 + +- [VLLM_CONTAINER-1] vLLM image/tag/digest 후보 확인 +- [VLLM_CONTAINER-2] DGX Spark launch command와 cache/volume 기준 정리 +- [VLLM_CONTAINER-3] `/v1/models` health check 검증 + +## 수정 파일 요약 + +- 코드 변경은 기본적으로 없다. +- 필요한 경우 container launch note는 active review stub에 evidence로 기록하고, tracked 문서에는 private host/token을 남기지 않는다. + +## 최종 검증 + +```bash +DGX_SPARK_SSH="${DGX_SPARK_SSH:?set DGX Spark ssh target from agent-test/local/rules.md}" ssh "$DGX_SPARK_SSH" 'set -eu; docker image inspect vllm/vllm-openai:nightly-aarch64 --format "{{json .RepoDigests}}"; docker ps --filter name=iop-vllm-qwen36 --format "{{.Names}} {{.Image}} {{.Status}}"; curl -fsS http://127.0.0.1:8000/v1/models' +``` + +예상 결과: image digest가 확인되고, `iop-vllm-qwen36` container가 running 상태이며, `/v1/models`가 `nvidia/Qwen3.6-35B-A3B-NVFP4`를 포함한 JSON을 반환한다. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/m-vllm-provider-serving-validation/02+01_config_contract/CODE_REVIEW-local-G06.md b/agent-task/m-vllm-provider-serving-validation/02+01_config_contract/CODE_REVIEW-local-G06.md new file mode 100644 index 0000000..f8ce7d1 --- /dev/null +++ b/agent-task/m-vllm-provider-serving-validation/02+01_config_contract/CODE_REVIEW-local-G06.md @@ -0,0 +1,124 @@ + +# Code Review: vLLM OpenAI-compatible config contract + +## 개요 + +- Plan: `PLAN-local-G06.md` +- Roadmap Task: `config-contract` +- Spec Scenario: `S02` + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Task: `config-contract` + +## Spec Targets + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Scenario: `S02` + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-local-G06.md` -> `code_review_local_G06_N.log`, `PLAN-local-G06.md` -> `plan_local_G06_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-vllm-provider-serving-validation/02+01_config_contract/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. +4. PASS이고 task group이 `m-vllm-provider-serving-validation`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [VLLM_CONFIG-1] vLLM OpenAI-compatible config example 정리 | [ ] | +| [VLLM_CONFIG-2] config/mapper/factory contract test 보강 | [ ] | +| [VLLM_CONFIG-3] adapter/target/model naming drift 점검 | [ ] | + +## 구현 체크리스트 + +- [ ] `01_spark_container`의 PASS evidence 또는 동등한 field evidence에서 실제 image/tag와 served model 기준을 확인한다. +- [ ] `configs/edge.yaml`에 vLLM OpenAI-compatible provider example을 추가하거나 기존 예시를 조정해 alias `qwen3.6:35b`, served model `nvidia/Qwen3.6-35B-A3B-NVFP4`, endpoint placeholder, headers 없음, timeout/queue/option passthrough 의도를 드러낸다. +- [ ] `packages/go/config`와 Edge/Node mapper/factory 테스트에 vLLM provider contract fixture를 추가하거나 기존 coverage로 충분한 이유를 review stub에 기록한다. +- [ ] direct `vllm` adapter 예시가 남아 있다면 legacy/experimental 의미가 혼동되지 않도록 문맥을 정리한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G06_N.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_local_G06_M.log`로 아카이브한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리 `agent-task/m-vllm-provider-serving-validation/02+01_config_contract/`를 `agent-task/archive/YYYY/MM/m-vllm-provider-serving-validation/02+01_config_contract/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [ ] PASS이고 task group이 `m-vllm-provider-serving-validation`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-vllm-provider-serving-validation/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- vLLM provider가 `openai_compat` 계열과 `adapter + target` 경계를 유지하는지 확인한다. +- config example에 private endpoint/token이 들어가지 않았는지 확인한다. +- direct `vllm` adapter 예시가 공통 adapter 기준과 충돌하지 않는지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. + +### VLLM_CONFIG-1 중간 검증 + +```bash +$ rg -n "provider: vllm|qwen3.6:35b|nvidia/Qwen3.6-35B-A3B-NVFP4" configs packages/go apps/edge apps/node +(output) +``` + +### 최종 검증 + +```bash +$ go test ./packages/go/config ./apps/edge/internal/node ./apps/node/internal/adapters ./apps/node/internal/adapters/openai_compat +$ git diff --check +(output) +``` + +--- + +> **[IMPLEMENTING AGENT - BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. diff --git a/agent-task/m-vllm-provider-serving-validation/02+01_config_contract/PLAN-local-G06.md b/agent-task/m-vllm-provider-serving-validation/02+01_config_contract/PLAN-local-G06.md new file mode 100644 index 0000000..43ae507 --- /dev/null +++ b/agent-task/m-vllm-provider-serving-validation/02+01_config_contract/PLAN-local-G06.md @@ -0,0 +1,98 @@ + +# Plan: vLLM OpenAI-compatible config contract + +## 이 파일을 읽는 구현 에이전트에게 + +이 plan은 `config-contract` Task를 구현하기 위한 실행 계약이다. 선행 작업 `01_spark_container`의 PASS evidence 또는 동등한 field evidence를 확인한 뒤 진행한다. 구현 에이전트는 실제 변경과 검증 출력으로 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 반드시 채운다. + +사용자 전용 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 충돌 없이는 안전하게 진행할 수 없는 경우 직접 질문하지 말고 review stub의 `사용자 리뷰 요청` 섹션에 정확한 blocker를 기록한 뒤 중단한다. 후속 에이전트가 재실행/증거 수집으로 해소할 수 있는 검증 공백은 사용자 리뷰 요청이 아니다. + +## 사용자 리뷰 요청 흐름 + +구현 중 blocker는 active `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에만 기록한다. 구현 에이전트는 chat에서 사용자에게 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Task: `config-contract` + +## Spec Targets + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Scenario: `S02` + +## 분석 결과 + +### 읽은 파일 + +- `packages/go/config/config.go` +- `proto/iop/runtime.proto` +- `apps/edge/internal/node/mapper.go` +- `apps/node/internal/adapters/factory.go` +- `apps/node/internal/adapters/openai_compat/openai_compat.go` +- `configs/edge.yaml` +- `agent-test/local/platform-common-smoke.md` + +### 테스트 환경 규칙 + +- config/proto 변경은 `platform-common` 규칙을 따른다. +- vLLM OpenAI-compatible provider는 internal `adapter + target` 경계를 유지해야 한다. +- private endpoint와 secret은 tracked config example에 고정하지 않는다. + +### 테스트 커버리지 공백 + +- 현재 `openai_compat` adapter는 provider, endpoint, headers, queue/timeout 구조가 있다. +- vLLM용 contract example과 test fixture가 부족하므로 config/example/test를 함께 보강한다. + +### 심볼 참조 + +- `config.EdgeOpenAIConf.ModelRoutes` +- `config.OpenAICompatInstanceConf` +- `node.adapterToProto` +- `adapters.BuildFromPayload` +- `openai_compat.BuildFromConfig` + +### 분할 판단 + +- 이 작업은 code/config contract만 다룬다. +- chat/streaming smoke script와 field smoke는 후속 plan에서 실행한다. + +### 범위 결정 근거 + +- 포함: `configs/edge.yaml` vLLM example, config load/normalize test, mapper/factory test 필요시 보강. +- 제외: vLLM container 기동, smoke script 신설, 실제 field chat smoke. + +### 빌드 등급 + +- `local-G06`: config와 adapter boundary 변경 가능성이 있고 여러 Go package 검증이 필요하다. + +## 구현 체크리스트 + +- [ ] `01_spark_container`의 PASS evidence 또는 동등한 field evidence에서 실제 image/tag와 served model 기준을 확인한다. +- [ ] `configs/edge.yaml`에 vLLM OpenAI-compatible provider example을 추가하거나 기존 예시를 조정해 alias `qwen3.6:35b`, served model `nvidia/Qwen3.6-35B-A3B-NVFP4`, endpoint placeholder, headers 없음, timeout/queue/option passthrough 의도를 드러낸다. +- [ ] `packages/go/config`와 Edge/Node mapper/factory 테스트에 vLLM provider contract fixture를 추가하거나 기존 coverage로 충분한 이유를 review stub에 기록한다. +- [ ] direct `vllm` adapter 예시가 남아 있다면 legacy/experimental 의미가 혼동되지 않도록 문맥을 정리한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 구현 항목 + +- [VLLM_CONFIG-1] vLLM OpenAI-compatible config example 정리 +- [VLLM_CONFIG-2] config/mapper/factory contract test 보강 +- [VLLM_CONFIG-3] adapter/target/model naming drift 점검 + +## 수정 파일 요약 + +- 예상 변경: `configs/edge.yaml` +- 예상 변경 가능: `packages/go/config/*_test.go`, `apps/edge/internal/node/*_test.go`, `apps/node/internal/adapters/*_test.go` +- 변경 금지: private endpoint/token을 tracked 파일에 기록하지 않는다. + +## 최종 검증 + +```bash +go test ./packages/go/config ./apps/edge/internal/node ./apps/node/internal/adapters ./apps/node/internal/adapters/openai_compat +git diff --check +``` + +예상 결과: vLLM provider config fixture가 통과하고 whitespace error가 없다. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/CODE_REVIEW-cloud-G07.md b/agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/CODE_REVIEW-cloud-G07.md new file mode 100644 index 0000000..86040af --- /dev/null +++ b/agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/CODE_REVIEW-cloud-G07.md @@ -0,0 +1,127 @@ + +# Code Review: Edge OpenAI vLLM models/chat/streaming smoke + +## 개요 + +- Plan: `PLAN-cloud-G07.md` +- Roadmap Task: `models-chat`, `streaming` +- Spec Scenario: `S03`, `S04` + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Task: `models-chat` +- Task: `streaming` + +## Spec Targets + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Scenario: `S03` +- Scenario: `S04` + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-cloud-G07.md` -> `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` -> `plan_cloud_G07_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. +4. PASS이고 task group이 `m-vllm-provider-serving-validation`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [VLLM_SMOKE-1] vLLM e2e smoke script 추가 | [ ] | +| [VLLM_SMOKE-2] fake-mode `/v1/models`와 non-streaming chat 검증 | [ ] | +| [VLLM_SMOKE-3] fake-mode streaming SSE 검증 | [ ] | + +## 구현 체크리스트 + +- [ ] `scripts/e2e-openai-vllm.sh`를 추가해 fake mode 기본 실행과 real mode env 실행을 모두 지원한다. +- [ ] script가 vLLM route alias `qwen3.6:35b`, served model `nvidia/Qwen3.6-35B-A3B-NVFP4`, `openai_compat_instances` provider `vllm`을 사용하도록 temp config를 구성한다. +- [ ] fake mode에서 `/v1/models`, non-streaming `/v1/chat/completions`, streaming `/v1/chat/completions` SSE chunk, `finish_reason`, `data: [DONE]`를 검증한다. +- [ ] 필요한 Go unit/integration test를 추가하거나 기존 coverage가 충분한 이유를 review stub에 기록한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리 `agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/`를 `agent-task/archive/YYYY/MM/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [ ] PASS이고 task group이 `m-vllm-provider-serving-validation`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-vllm-provider-serving-validation/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- smoke script가 fake mode 기본 실행으로 재현 가능한지 확인한다. +- route alias `qwen3.6:35b`와 served model `nvidia/Qwen3.6-35B-A3B-NVFP4`의 역할이 섞이지 않았는지 확인한다. +- streaming assertion이 단순 연결 성공이 아니라 chunk, `finish_reason`, 종료 신호를 확인하는지 본다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. + +### VLLM_SMOKE-1 중간 검증 + +```bash +$ bash ./scripts/e2e-openai-vllm.sh +(output) +``` + +### 최종 검증 + +```bash +$ bash ./scripts/e2e-openai-vllm.sh +$ go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat +$ git diff --check +(output) +``` + +--- + +> **[IMPLEMENTING AGENT - BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. diff --git a/agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/PLAN-cloud-G07.md b/agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/PLAN-cloud-G07.md new file mode 100644 index 0000000..43cb6de --- /dev/null +++ b/agent-task/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/PLAN-cloud-G07.md @@ -0,0 +1,100 @@ + +# Plan: Edge OpenAI vLLM models/chat/streaming smoke + +## 이 파일을 읽는 구현 에이전트에게 + +이 plan은 `models-chat`와 `streaming` Task를 구현/검증하기 위한 실행 계약이다. 선행 작업 `02+01_config_contract`의 PASS evidence 또는 동등한 config contract 반영을 확인한 뒤 진행한다. 구현 에이전트는 실제 변경과 검증 출력으로 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 반드시 채운다. + +사용자 전용 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 충돌 없이는 안전하게 진행할 수 없는 경우 직접 질문하지 말고 review stub의 `사용자 리뷰 요청` 섹션에 기록한 뒤 중단한다. + +## 사용자 리뷰 요청 흐름 + +구현 중 blocker는 active `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에만 기록한다. 구현 에이전트는 chat에서 사용자에게 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Task: `models-chat` +- Task: `streaming` + +## Spec Targets + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Scenario: `S03` +- Scenario: `S04` + +## 분석 결과 + +### 읽은 파일 + +- `scripts/e2e-openai-lemonade.sh` +- `apps/edge/internal/openai/chat_handler.go` +- `apps/edge/internal/openai/routes.go` +- `apps/edge/internal/openai/server_test.go` +- `apps/node/internal/adapters/openai_compat/openai_compat.go` +- `apps/node/internal/adapters/openai_compat/openai_compat_test.go` +- `agent-test/local/edge-smoke.md` +- `agent-test/local/node-smoke.md` + +### 테스트 환경 규칙 + +- smoke는 local fake provider로 재현 가능해야 한다. +- real provider mode는 field endpoint를 env로 주입해야 하며 private endpoint/token을 tracked 파일에 기록하지 않는다. +- streaming 검증은 SSE chunk, `finish_reason`, 종료 신호를 모두 확인한다. + +### 테스트 커버리지 공백 + +- Lemonade용 e2e script는 있으나 vLLM provider alias/model 기준의 smoke script가 없다. +- Edge `/v1/models`, non-streaming chat, streaming chat을 같은 vLLM route config로 검증하는 user-facing smoke가 부족하다. + +### 심볼 참조 + +- `scripts/e2e-openai-lemonade.sh` +- `openai.Handler.handleChatCompletions` +- `openai.Handler.handleModels` +- `openai_compat.Adapter.Execute` + +### 분할 판단 + +- 이 plan은 smoke script와 fake-mode/route 검증을 담당한다. +- 실제 DGX Spark split-host run은 `04+03_field_smoke`에서 같은 script의 real mode로 수행한다. + +### 범위 결정 근거 + +- 포함: `scripts/e2e-openai-vllm.sh` 신설, fake provider 응답, Edge config temp file, `/v1/models`, non-streaming, streaming assertions. +- 제외: DGX Spark container launch, field host health provisioning, roadmap task 완료 체크. + +### 빌드 등급 + +- `cloud-G07`: script orchestration과 Edge/Node smoke가 포함되며 real-mode는 외부 provider endpoint를 소비한다. + +## 구현 체크리스트 + +- [ ] `scripts/e2e-openai-vllm.sh`를 추가해 fake mode 기본 실행과 real mode env 실행을 모두 지원한다. +- [ ] script가 vLLM route alias `qwen3.6:35b`, served model `nvidia/Qwen3.6-35B-A3B-NVFP4`, `openai_compat_instances` provider `vllm`을 사용하도록 temp config를 구성한다. +- [ ] fake mode에서 `/v1/models`, non-streaming `/v1/chat/completions`, streaming `/v1/chat/completions` SSE chunk, `finish_reason`, `data: [DONE]`를 검증한다. +- [ ] 필요한 Go unit/integration test를 추가하거나 기존 coverage가 충분한 이유를 review stub에 기록한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 구현 항목 + +- [VLLM_SMOKE-1] vLLM e2e smoke script 추가 +- [VLLM_SMOKE-2] fake-mode `/v1/models`와 non-streaming chat 검증 +- [VLLM_SMOKE-3] fake-mode streaming SSE 검증 + +## 수정 파일 요약 + +- 예상 변경: `scripts/e2e-openai-vllm.sh` +- 예상 변경 가능: `apps/edge/internal/openai/*_test.go`, `apps/node/internal/adapters/openai_compat/*_test.go` + +## 최종 검증 + +```bash +bash ./scripts/e2e-openai-vllm.sh +go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat +git diff --check +``` + +예상 결과: fake-mode smoke가 route alias 모델 조회, non-streaming chat, streaming SSE 종료 신호를 검증하고 Go test 및 diff check가 통과한다. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/CODE_REVIEW-cloud-G07.md b/agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/CODE_REVIEW-cloud-G07.md new file mode 100644 index 0000000..71dbdbe --- /dev/null +++ b/agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/CODE_REVIEW-cloud-G07.md @@ -0,0 +1,124 @@ + +# Code Review: vLLM split-host field smoke + +## 개요 + +- Plan: `PLAN-cloud-G07.md` +- Roadmap Task: `field-smoke` +- Spec Scenario: `S05` + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Task: `field-smoke` + +## Spec Targets + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Scenario: `S05` + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 field evidence와 `검증 결과` 섹션의 출력이 계획의 명령과 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-cloud-G07.md` -> `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` -> `plan_cloud_G07_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-vllm-provider-serving-validation/04+03_field_smoke/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. +4. PASS이고 task group이 `m-vllm-provider-serving-validation`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [VLLM_FIELD-1] DGX Spark provider real health 확인 | [ ] | +| [VLLM_FIELD-2] Edge/Node split-host non-streaming smoke | [ ] | +| [VLLM_FIELD-3] Edge/Node split-host streaming smoke | [ ] | + +## 구현 체크리스트 + +- [ ] `01_spark_container`와 `03+02_openai_vllm_smoke`의 PASS evidence 또는 동등한 evidence를 확인한다. +- [ ] DGX Spark provider endpoint `http://:8000/v1`의 `/v1/models`가 real served model을 반환하는지 확인한다. +- [ ] `scripts/e2e-openai-vllm.sh` real mode로 Edge `/v1/models`, non-streaming chat, streaming SSE를 실행한다. +- [ ] output에 route alias `qwen3.6:35b`, target/served model `nvidia/Qwen3.6-35B-A3B-NVFP4`, finish reason, 종료 신호 evidence를 기록한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리 `agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/`를 `agent-task/archive/YYYY/MM/m-vllm-provider-serving-validation/04+03_field_smoke/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [ ] PASS이고 task group이 `m-vllm-provider-serving-validation`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-vllm-provider-serving-validation/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- real-mode endpoint가 tracked 파일에 노출되지 않았는지 확인한다. +- `/v1/models`, non-streaming chat, streaming SSE가 모두 Edge/Node 경로를 통과했는지 확인한다. +- 실패가 환경 문제인지 code/config 결함인지 review stub에 구분되어 있는지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. + +### VLLM_FIELD-1 중간 검증 + +```bash +$ IOP_VLLM_MODE=real IOP_VLLM_ENDPOINT="${IOP_VLLM_ENDPOINT:?set http://:8000/v1 from agent-test/local/rules.md}" IOP_VLLM_MODEL="nvidia/Qwen3.6-35B-A3B-NVFP4" IOP_VLLM_ALIAS="qwen3.6:35b" bash ./scripts/e2e-openai-vllm.sh +(output) +``` + +### 최종 검증 + +```bash +$ IOP_VLLM_MODE=real IOP_VLLM_ENDPOINT="${IOP_VLLM_ENDPOINT:?set http://:8000/v1 from agent-test/local/rules.md}" IOP_VLLM_MODEL="nvidia/Qwen3.6-35B-A3B-NVFP4" IOP_VLLM_ALIAS="qwen3.6:35b" bash ./scripts/e2e-openai-vllm.sh +$ git diff --check +(output) +``` + +--- + +> **[IMPLEMENTING AGENT - BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. diff --git a/agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/PLAN-cloud-G07.md b/agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/PLAN-cloud-G07.md new file mode 100644 index 0000000..00d94be --- /dev/null +++ b/agent-task/m-vllm-provider-serving-validation/04+03_field_smoke/PLAN-cloud-G07.md @@ -0,0 +1,95 @@ + +# Plan: vLLM split-host field smoke + +## 이 파일을 읽는 구현 에이전트에게 + +이 plan은 `field-smoke` Task를 구현/검증하기 위한 실행 계약이다. 선행 작업 `01_spark_container`와 `03+02_openai_vllm_smoke`의 PASS evidence 또는 동등한 container/script evidence를 확인한 뒤 진행한다. 구현 에이전트는 실제 변경과 검증 출력으로 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 반드시 채운다. + +사용자 전용 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 충돌 없이는 안전하게 진행할 수 없는 경우 직접 질문하지 말고 review stub의 `사용자 리뷰 요청` 섹션에 기록한 뒤 중단한다. 단순 evidence 재수집 가능 상태는 사용자 리뷰 요청이 아니다. + +## 사용자 리뷰 요청 흐름 + +구현 중 blocker는 active `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에만 기록한다. 구현 에이전트는 chat에서 사용자에게 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md` +- Task: `field-smoke` + +## Spec Targets + +- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` +- Scenario: `S05` + +## 분석 결과 + +### 읽은 파일 + +- `agent-test/local/rules.md` +- `agent-test/local/edge-smoke.md` +- `agent-test/local/node-smoke.md` +- `agent-test/local/platform-common-smoke.md` +- `scripts/e2e-openai-lemonade.sh` +- `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md` + +### 테스트 환경 규칙 + +- 실제 DGX Spark field host 값은 local-only 규칙에서 읽고 tracked 파일에 기록하지 않는다. +- current container에서 vLLM container를 실행하지 않는다. +- split-host smoke는 real vLLM endpoint와 Edge/Node 경로를 함께 확인한다. + +### 테스트 커버리지 공백 + +- fake-mode smoke만으로는 actual DGX Spark vLLM target/model path를 완료 증거로 삼을 수 없다. +- field endpoint 접근, model cache 상태, streaming latency/termination은 real-mode evidence가 필요하다. + +### 심볼 참조 + +- `scripts/e2e-openai-vllm.sh` +- Edge OpenAI `/v1/models` +- Edge OpenAI `/v1/chat/completions` +- Node `openai_compat` adapter request path + +### 분할 판단 + +- 이 plan은 code change보다 field evidence 수집이 중심이다. +- 실패 시 code/config 수정이 필요하면 이 active review stub에 원인과 다음 plan 필요 여부를 기록한다. + +### 범위 결정 근거 + +- 포함: DGX Spark provider health, Edge/Node split-host real-mode smoke, target/model evidence, non-streaming/streaming 검증. +- 제외: container image 교체 실험, 장기 운영 스크립트, qualification report 제품화. + +### 빌드 등급 + +- `cloud-G07`: 외부 field endpoint와 split-host runtime이 필수이다. + +## 구현 체크리스트 + +- [ ] `01_spark_container`와 `03+02_openai_vllm_smoke`의 PASS evidence 또는 동등한 evidence를 확인한다. +- [ ] DGX Spark provider endpoint `http://:8000/v1`의 `/v1/models`가 real served model을 반환하는지 확인한다. +- [ ] `scripts/e2e-openai-vllm.sh` real mode로 Edge `/v1/models`, non-streaming chat, streaming SSE를 실행한다. +- [ ] output에 route alias `qwen3.6:35b`, target/served model `nvidia/Qwen3.6-35B-A3B-NVFP4`, finish reason, 종료 신호 evidence를 기록한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 구현 항목 + +- [VLLM_FIELD-1] DGX Spark provider real health 확인 +- [VLLM_FIELD-2] Edge/Node split-host non-streaming smoke +- [VLLM_FIELD-3] Edge/Node split-host streaming smoke + +## 수정 파일 요약 + +- 일반적으로 코드 변경 없음. +- field smoke 실패가 code/config 결함으로 확인되면 최소 수정만 수행하고, 범위가 커지면 다음 plan 필요 여부를 review stub에 기록한다. + +## 최종 검증 + +```bash +IOP_VLLM_MODE=real IOP_VLLM_ENDPOINT="${IOP_VLLM_ENDPOINT:?set http://:8000/v1 from agent-test/local/rules.md}" IOP_VLLM_MODEL="nvidia/Qwen3.6-35B-A3B-NVFP4" IOP_VLLM_ALIAS="qwen3.6:35b" bash ./scripts/e2e-openai-vllm.sh +git diff --check +``` + +예상 결과: real-mode smoke가 Edge `/v1/models`, non-streaming chat, streaming SSE 종료 신호를 검증하고 whitespace error가 없다. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.