iop/agent-roadmap/archive/phase/inference-provider-extension/milestones/model-route-queue-policy-alignment.md

Milestone: Model route Queue 정책 정합화

위치

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

목표

Edge-owned model group queue의 정책 원천을 OpenAI-compatible model_routes의 model alias로 정리한다. max_queue와 queue_timeout_ms는 model alias queue 정책으로 두고, Node/provider instance의 capacity는 per-node 동시 실행 slot 기준으로 남긴다. 기존 adapter instance queue 설정은 호환 fallback으로만 유지해, 다중 Node/다중 provider pool에서 queue owner와 설정 위치가 어긋나지 않게 만든다.

상태

[완료]

승격 조건

• 없음

구현 잠금

• 상태: 해제
• SDD: 필요
• SDD 문서: agent-roadmap/archive/sdd/inference-provider-extension/model-route-queue-policy-alignment/SDD.md
• SDD 사유: OpenAI route config schema와 Edge queue dispatch 계약을 바꾸는 작업이다.
• 잠금 해제 조건:
  • SDD 잠금이 해제되어 있다
  • SDD 사용자 리뷰가 없거나 승인/해결되었다
  • Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  • Evidence Map이 plan의 Spec Targets와 완료 시 Spec Completion으로 검증 가능하게 연결되어 있다
• 결정 필요: 없음

범위

• openai.model_routes[]에 Edge-owned model group queue 정책 필드를 추가한다.
• route-level max_queue와 queue_timeout_ms가 있으면 Edge queue group policy에서 우선 사용한다.
• route-level queue policy가 없으면 기존 Node/provider adapter instance의 queue 설정을 호환 fallback으로 유지한다.
• Node/provider instance의 capacity는 각 Node가 해당 adapter instance로 동시에 받을 수 있는 요청 slot으로 유지한다.
• /v1/chat/completions와 /v1/responses 모두 같은 route-level queue policy 전달 경로를 사용한다.
• 설정 예시와 테스트에서 model alias queue policy와 per-node capacity의 책임 경계를 명확히 한다.

기능

Epic: [route-policy] Model Route Queue Policy

OpenAI-compatible model alias가 Edge queue group의 정책 원천이 되도록 config, dispatch DTO, queue admission 경로를 정리한다.

• [config-schema] openai.model_routes[]가 max_queue, queue_timeout_ms를 받을 수 있고 validation/default/fallback 문서가 정리되어 있다. 검증: go test -count=1 ./packages/go/config ./apps/edge/internal/openai
• [dispatch-contract] OpenAI Chat Completions와 Responses route resolution이 route-level queue policy를 SubmitRunRequest로 전달한다. 검증: go test -count=1 ./apps/edge/internal/openai
• [queue-policy] Edge queue admission이 route-level queue policy를 adapter instance fallback보다 우선하고, route policy가 없을 때 기존 fallback을 유지한다. 검증: go test -count=1 ./apps/edge/internal/service
• [docs-example] configs/edge.yaml 예시가 model alias queue policy와 Node/provider capacity의 책임 경계를 보여준다.

완료 리뷰

• 상태: 승인됨
• 요청일: 2026-06-17
• 완료 근거:
  • agent-task/archive/2026/06/m-model-route-queue-policy-alignment/01_config_route_policy/complete.log가 config-schema, dispatch-contract, docs-example과 SDD S01, S02, S04 PASS를 기록했다.
  • agent-task/archive/2026/06/m-model-route-queue-policy-alignment/02+01_service_queue_policy/complete.log가 queue-policy와 SDD S03 PASS를 기록했다.
  • 최종 검증으로 go test -count=1 ./packages/go/config ./apps/edge/internal/openai, go test -count=1 ./apps/edge/internal/service, git diff --check가 PASS로 기록되어 있다.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 2026-06-17 코드 레벨 검토와 관련 테스트 재검증 후 종료 승인에 따라 완료 처리했다.

범위 제외

• GPU/CPU/VRAM 실측 기반 자동 capacity 조정
• cross-Edge 부하 라우팅, cloud fallback, 품질/비용 기반 모델 선택
• model_routes 하나에서 provider별로 서로 다른 target을 선언하는 route 후보 목록
• vLLM/Lemonade/Ollama provider 자체의 실서비스 smoke 완료 판정
• Node bootstrap, Control Plane, Client UI 변경

작업 컨텍스트

• 관련 경로: packages/go/config, configs/edge.yaml, apps/edge/internal/openai, apps/edge/internal/service, agent-test/local/edge-smoke.md, agent-test/local/platform-common-smoke.md
• 표준선(선택): queue owner는 Edge이며, OpenAI-compatible model 값은 model group key다.
• 표준선(선택): model_routes는 외부 model alias와 Edge queue policy를 소유하고, Node/provider instance는 adapter endpoint와 per-node capacity를 소유한다.
• 표준선(선택): 기존 adapter instance max_queue/queue_timeout_ms는 route-level queue policy가 없는 설정의 호환 fallback으로 유지한다.
• 선행 작업: Edge 모델 그룹 Queue 스케줄링 전환
• 후속 작업: vLLM provider 서빙 경로 추가, SGLang provider 서빙 경로 추가, provider catalog/device status에서 queue policy 표시 확장
• 확인 필요: 없음