# Milestone: SGLang provider 서빙 경로 추가

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/inference-provider-extension/PHASE.md`

## 목표

Ollama 경로가 안정화된 뒤, 추가 추론 서버 provider로 SGLang provider를 붙인다.
Ollama 실테스트에서 안정화한 모델 조회, non-streaming/streaming chat, reasoning/content 분리, option/API passthrough, split-host smoke 기준을 기준선으로 삼아 SGLang provider 경로를 검증한다.

## 상태

[폐기]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 문서: `agent-roadmap/archive/sdd/inference-provider-extension/sglang-provider-serving-validation/SDD.md`
- 잠금 해제 조건:
  - [x] SDD 잠금이 해제되어 있다
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  - [x] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다
- 결정 필요: 없음

## 범위

- SGLang provider를 Ollama 이후의 추가 추론 서버 provider 후보로 로드맵에 추가한다.
- Edge OpenAI-compatible API의 `/v1/models`, `/v1/chat/completions` non-streaming/streaming 요청이 SGLang provider 경로로 수렴하는 기준을 정한다.
- SGLang provider의 모델 조회, chat completion, streaming chunk, reasoning/content 분리, option/API passthrough 기대 동작을 실제 endpoint 기준으로 검증한다.
- split-host field smoke 기준을 SGLang provider에도 재사용한다.
- Ollama 경로에서 안정화된 기준을 흔들지 않도록 provider별 설정, target/model 매핑, adapter 책임 경계를 분리한다.

## 기능

### Epic: [sglang-provider] SGLang Provider Serving Path

- [ ] [provider-boundary] SGLang provider를 독립 adapter로 둘지 OpenAI-compatible inference server 공통 adapter로 둘지 결정 근거가 정리되어 있다.
- [ ] [config-contract] SGLang endpoint, model, auth/header, timeout, option passthrough 설정 계약이 정리되어 있다.
- [ ] [models-chat] Edge OpenAI-compatible `/v1/models`와 non-streaming `/v1/chat/completions`가 SGLang provider로 수렴하는 기준이 검증되어 있다.
- [ ] [streaming] streaming `/v1/chat/completions`에서 SSE chunk와 종료 신호가 SGLang provider 경로로 안정적으로 전달되는지 검증되어 있다.
- [ ] [follow-up-scope] 코드 수정이 필요한 항목은 이 Milestone의 추가 Task 또는 같은 Milestone task group의 후속 plan으로 정리되어 있다.

## 완료 리뷰

- 상태: 폐기
- 요청일: 2026-06-19
- 완료 근거: SGLang field serving은 가능했지만, 현재 GX10/Qwen3.6 조건에서는 vLLM 대비 호환성과 성능 이점이 없어 provider 채택을 진행하지 않기로 했다.
- 리뷰 필요:
  - [x] 사용자가 field validation 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 미채택 종료. 이 Milestone은 SGLang provider 구현 완료가 아니라, 현 환경에서 SGLang 채택 ROI가 낮다는 negative validation 결과로 닫는다.

## 종료 결정

- 결론: SGLang은 현 GX10 + Qwen3.6 35B NVFP4 조건에서 vLLM 대비 채택할 만한 ROI가 낮아 provider 구현을 진행하지 않는다.
- SGLang field 결과:
  - `lmsysorg/sglang:latest-cu130` image와 `unsloth/Qwen3.6-35B-A3B-NVFP4` served model로 OpenAI-compatible `/v1/models`와 `/v1/chat/completions` smoke를 통과했다.
  - 기존 `nvidia/Qwen3.6-35B-A3B-NVFP4` checkpoint는 현재 SGLang image에서 quantization/block shape 오류로 로딩 실패했다.
  - vLLM과 같은 의도로 `--context-length 262144`, `--mem-fraction-static 0.30`을 사용했지만 관측 KV pool은 `270101` tokens 수준이었다.
- vLLM 비교 결과:
  - vLLM은 기존 `nvidia/Qwen3.6-35B-A3B-NVFP4` checkpoint를 직접 로드했다.
  - vLLM 관측 KV cache는 `561737` tokens, 262K 요청 기준 maximum concurrency `2.14x`였다.
  - 동일 256 completion-token, thinking-off, concurrency sweep에서 vLLM이 전 구간 우세했다.

| 동시 호출 수 | SGLang 요청당 tok/s | vLLM 요청당 tok/s | vLLM 우위 | SGLang 전체 tok/s | vLLM 전체 tok/s | vLLM 우위 |
|---:|---:|---:|---:|---:|---:|---:|
| 1 | 40.95 | 77.42 | +89.1% | 40.94 | 77.38 | +89.0% |
| 2 | 42.34 | 67.29 | +58.9% | 84.66 | 134.54 | +58.9% |
| 3 | 36.61 | 55.41 | +51.4% | 109.82 | 166.20 | +51.3% |
| 4 | 38.98 | 60.41 | +55.0% | 155.90 | 241.57 | +55.0% |
| 5 | 34.09 | 42.04 | +23.3% | 170.42 | 210.15 | +23.3% |

- 재검토 조건:
  - SGLang이 `nvidia/Qwen3.6-35B-A3B-NVFP4`를 직접 안정 로드한다.
  - shared-prefix/RAG cache reuse가 핵심 workload가 된다.
  - vLLM 운영상 blocker가 생기거나, SGLang 특화 기능(speculative decoding, prefix reuse, structured output 등)이 제품 요구가 된다.

## 범위 제외

- cloud fallback, 자동 부하 라우팅, 품질 평가 feedback의 본격 구현
- provider/device/model qualification report 저장/조회/비교 제품화
- 원격 provider 모델 lifecycle 관리 제품화
- 후속 최적화 계층 구현
- Responses API 세부 호환 구현
- 진행중인 Ollama 실테스트와 후속 안정화 범위 변경
- Ollama 경로 완료 기록 재작성

## 작업 컨텍스트

- 관련 경로: `apps/edge`, `apps/node`, `packages/go/config`, `proto/iop`, `configs`, `bin/edge.sh`, `bin/node.sh`, `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 기준을 SGLang provider에도 그대로 적용한다.
- 표준선(선택): 이 Milestone은 SGLang serving path와 adapter/config/target 매핑 검증에 집중하고, provider/device/model 리포트 제품화는 `운영 관측과 Provider 관리` Phase 후반부에서 다룬다.
- 선행 작업: Ollama 실테스트와 후속 안정화, Node 단일 통로 멀티 타겟 서빙 기반
- 후속 작업: SGLang provider 실테스트에서 확인된 serving 경로 안정화 보완
- 확인 필요: SGLang adapter 경계, 실테스트 endpoint/model, 인증/헤더 필요 여부, streaming 기대 동작
