# 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 기준을 검증한다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 경로: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md`
- 잠금 해제 조건: 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`이며, 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에도 재사용한다.
- Ollama 경로에서 안정화된 기준을 흔들지 않도록 provider별 설정, target/model 매핑, adapter 책임 경계를 분리한다.

## 기능

### Epic: [vllm-provider] vLLM Provider Serving Path

- [x] [provider-boundary] vLLM provider를 독립 adapter로 둘지 OpenAI-compatible inference server 공통 adapter로 둘지 결정 근거가 정리되어 있다.
- [x] [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`가 응답한다.
- [x] [config-contract] vLLM endpoint, served model name, model alias, auth/header, timeout, option passthrough 설정 계약이 정리되어 있다.
- [x] [models-chat] Edge OpenAI-compatible `/v1/models`와 non-streaming `/v1/chat/completions`가 vLLM provider로 수렴하는 기준이 검증되어 있다.
- [x] [streaming] streaming `/v1/chat/completions`에서 SSE chunk, finish reason, 종료 신호가 vLLM provider 경로로 안정적으로 전달되는지 검증되어 있다.
- [x] [field-smoke] split-host field smoke에서 vLLM target/model을 선택해 모델 조회와 chat 왕복이 검증되어 있다.
- [x] [follow-up-scope] 코드 수정이 필요한 항목은 이 Milestone의 추가 Task 또는 같은 Milestone task group의 후속 plan으로 정리되어 있다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-06-18
- 완료 근거: `01_spark_container`, `02+01_config_contract`, `03+02_openai_vllm_smoke`, `04+03_field_smoke` complete.log가 모두 PASS이며 `Roadmap Completion`으로 `spark-container`, `config-contract`, `models-chat`, `streaming`, `field-smoke` 완료를 증명한다.
- 완료 근거: SDD `S01`~`S05`의 `Spec Completion` PASS 근거가 complete.log에 남아 있고, `provider-boundary`와 `follow-up-scope`는 이미 체크된 상태로 남은 기능 Task가 없다.
- 코드 레벨 리뷰: 2026-06-18 Edge OpenAI 응답 변환, Node `openai_compat`/vLLM adapter, routing/config, vLLM smoke script를 검토했고 완료 차단 이슈는 없다.
- 보완 완료: provider `finish_reason`을 Edge non-streaming/streaming 응답에 보존하도록 수정하고, vLLM smoke가 fake/real 모드 모두에서 `finish_reason`을 검증하도록 보강했다.
- 검증 완료: `go test -count=1 ./apps/edge/internal/openai ./apps/node/internal/adapters/openai_compat ./apps/edge/internal/service`, `go test ./packages/go/config ./apps/edge/internal/node ./apps/node/internal/adapters ./apps/node/internal/adapters/openai_compat ./apps/edge/internal/openai ./apps/edge/internal/service`, `bash scripts/e2e-openai-vllm.sh`, `git diff --check` PASS.
- 남은 차단 항목: 없음
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-18 사용자 승인에 따라 완료 처리 및 archive 이동.

## 범위 제외

- cloud fallback, 자동 부하 라우팅, 품질 평가 feedback의 본격 구현
- provider/device/model qualification report 저장/조회/비교 제품화
- 원격 provider 모델 lifecycle 관리 제품화
- 후속 최적화 계층 구현
- 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에도 그대로 적용한다.
- 표준선(선택): 이 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 base URL/port는 `http://<DGX_SPARK_HOST>:8000/v1`로 둔다. `<DGX_SPARK_HOST>`는 `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/archive/2026/06/m-vllm-provider-serving-validation/01_spark_container/complete.log`에서 `spark-container`와 SDD scenario `S01` PASS를 확인했다.
- 완료됨: `agent-task/archive/2026/06/m-vllm-provider-serving-validation/02+01_config_contract/complete.log`에서 `config-contract`와 SDD scenario `S02` PASS를 확인했다.
- 완료됨: `agent-task/archive/2026/06/m-vllm-provider-serving-validation/03+02_openai_vllm_smoke/complete.log`에서 `models-chat`, `streaming`과 SDD scenarios `S03`, `S04` PASS를 확인했다.
- 완료됨: `agent-task/archive/2026/06/m-vllm-provider-serving-validation/04+03_field_smoke/complete.log`에서 `field-smoke`와 SDD scenario `S05` PASS를 확인했다.
- 외부 근거: `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 경로 안정화 보완
- 확인 완료: DGX Spark vLLM container image/tag, model cache/volume, launch command, health check 실측은 `01_spark_container` 완료 로그에 기록되어 있다.
