Milestone: Model Alias Provider Pool과 Provider Catalog

위치

Roadmap: agent-roadmap/ROADMAP.md
Phase: agent-roadmap/phase/operational-observability-provider-management/PHASE.md

목표

qwen3.6:35b 같은 외부 OpenAI-compatible model key를 models[] catalog 항목으로 정의하고, 각 model이 사용할 provider id와 provider별 실제 served model name을 Edge config에서 연결하는 MVP를 만든다. provider 정의는 Node 아래에 두고, 같은 Node 안의 여러 provider와 provider별 models[] list를 기준으로 Edge가 provider 선택, load-ratio routing, target rewrite를 소유한다. API provider, CLI provider, local inference provider catalog는 이 provider pool을 운영자가 읽기 전용으로 관찰하기 위한 health/capacity/in-flight/model/lifecycle 상태 모델로 연결한다. provider/device/model별 qualification report와 benchmark/품질 비교는 이 Milestone의 직접 구현 범위가 아니라 후속 심화 Milestone으로 분리한다.

상태

[완료]

승격 조건

충족: agent-roadmap/sdd/operational-observability-provider-management/provider-catalog-device-status/SDD.md에서 D01-D06 사용자 결정이 해결되었고, user_review_0.log에 결정 이력이 남아 있다.
충족: models[], nodes[].providers[], provider별 served model list, Edge-owned target rewrite, in_flight / capacity load-ratio 선택, read-only catalog 경계가 구현 계획을 만들 수 있을 만큼 정리되었다.
충족: runtime control, resource telemetry, detailed lifecycle/qualification report는 후속 Milestone 범위로 분리되었다.

구현 잠금

상태: 해제
SDD: 필요
SDD 문서: agent-roadmap/sdd/operational-observability-provider-management/provider-catalog-device-status/SDD.md
잠금 해제 조건:
- SDD 잠금이 해제되어 있다
- SDD 사용자 리뷰가 없거나 승인/해결되었다
- Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
- Evidence Map이 plan의 Spec Targets와 완료 시 Spec Completion으로 검증 가능하게 연결되어 있다
- models[] provider pool의 config/API 계약, provider candidate 선택 기준, target rewrite 책임, catalog 상태 필드, 운영 표면 책임 경계가 구현 계획을 만들 수 있을 만큼 확정되어 있다
결정 필요: 없음

범위

models[] 기반 model catalog와 provider id -> served model name 매핑 계약
nodes[].providers[] 기반 provider 정의, provider type/category, provider별 served model list 계약
Edge-owned provider 선택, in_flight / capacity load-ratio routing, target rewrite 책임 경계
API, CLI, local inference provider category와 read-only catalog 표시 기준
health, capacity, in-flight, derived load ratio, models, queued 상태 추적 기준
provider별 coarse lifecycle capability flags 표시 기준
vLLM, vLLM-MLX, Lemonade, SGLang 같은 provider의 운영 표시 후보
provider validation과 운영 catalog의 책임 분리

기능

Epic: [model-pool] Model Alias Provider Pool

models[] catalog model을 중심으로 provider 후보를 묶고 Edge가 실행 후보를 고르는 최소 산출물을 구현한다.

[alias-contract] models[].id가 OpenAI-compatible model key이자 provider pool의 canonical routing key가 되며, models[].providers가 provider id -> served model name map으로 검증된다.
[candidate-schema] nodes[].providers[]가 provider id, type, category, served models[], health, capacity, in-flight, queued, coarse lifecycle capability를 표현한다.
[target-rewrite] Edge가 선택한 provider id의 models[].providers[provider_id] 값을 concrete target으로 rewrite해 Node에 전달하고, Node/provider adapter는 rewrite하지 않는다.
[selection-policy] Edge가 available provider 중 in_flight / capacity load ratio가 가장 낮은 후보를 우선 선택하고, 동률은 deterministic tie-break로 처리하며, queue timeout을 적용한다.
[pool-compat] 기존 openai.model_routes, adapter + target, Node provider instance 설정과 새 models[]/provider catalog 계약의 호환/마이그레이션 방향이 정리되어 있다.

Epic: [provider-catalog] Provider Operations Catalog

운영자가 model provider pool과 provider 상태를 같은 기준으로 비교하기 위한 read-only catalog 산출물을 묶는다.

[category-map] MVP provider category가 api, cli, local_inference로 정리되고 read-only catalog 표시 필드에 반영된다.
[device-status] provider health, capacity, in-flight, derived load ratio, served models, queued 상태가 catalog/status 표면에 정리된다.
[lifecycle-cap] Ollama, Lemonade, vLLM, SGLang 등의 lifecycle 차이가 coarse capability flags로 표시되고 상세 qualification report는 후속 범위로 분리된다.
[boundary] provider adapter 구현, Edge-owned provider pool routing, read-only operations catalog, 후속 runtime control의 책임 경계가 정리되어 있다.
[ops-review] Edge config와 Edge-owned read-only catalog/status를 기준으로 iop-edge CLI, Control Plane, Client가 어떤 정보를 소비하는지 확인할 수 있다.

완료 리뷰

상태: 통과
요청일: 2026-06-21
완료 근거: agent-task/archive/2026/06/m-provider-catalog-device-status/01_pool_schema/complete.log, 02+01_edge_dispatch/complete.log, 03_catalog_status_http/complete.log, 04+03_client_catalog_view/complete.log의 Roadmap Completion과 Spec Completion 기준으로 모든 기능 Task와 S01-S10 Acceptance Scenario가 PASS 근거를 갖는다.
완료 근거: device-status는 Control Plane /edges/{id}/status의 provider_snapshots JSON과 load_ratio=0 보존 regression test, ops-review는 Client Nodes panel provider catalog/status 렌더링과 health color mapping widget test를 근거로 완료 반영했다.
완료 근거: 2026-06-21 종료 전 코드레벨 검토에서 config validation, provider-pool dispatch/target rewrite, Control Plane status JSON, Client provider catalog 렌더링 경로를 재확인했고 go test ./..., flutter test, flutter analyze --no-fatal-infos, git diff --check가 통과했다.
남은 차단 항목: 없음
리뷰 필요:
- 사용자가 완료 결과 코드레벨 검토 후 종료를 요청했다
- archive 이동을 승인했다
리뷰 코멘트: 종료 가능으로 판정하고 다음 후보를 사용량, 토큰, 로그 운영 추적 MVP로 지정한다.

범위 제외

vLLM, vLLM-MLX, Lemonade, SGLang provider adapter 구현 자체
provider pool scheduler 코드 구현과 config migration 실행
provider/device/model qualification report 저장/조회/비교
자동 benchmark, 품질 평가, provider marketplace, cross-Edge provider balancing
cloud fallback과 품질 평가 feedback 구현
provider runtime enable/disable, drain, fallback 우선순위 변경, capacity override
runtime process/container detail과 CPU/GPU/RAM/VRAM resource telemetry

작업 컨텍스트

관련 경로: apps/edge, apps/node, apps/control-plane, apps/client, packages/go/config, proto/iop/runtime.proto
기존 구조: 현재 OpenAI route는 외부 model을 단일 adapter + target으로 resolve하고, Edge queue는 ModelGroupKey를 쓰지만 후보 필터링은 같은 adapter + target 기준으로 동작한다.
새 표준선(선택): provider 실행 구현의 외부 계약은 models[].id를 canonical key로 두고, 내부 dispatch 직전에 Edge가 provider id별 served model name으로 target을 rewrite한다.
MVP 표면: Edge config와 Edge-owned read-only catalog/status API를 기준으로 두고, iop-edge CLI는 읽기 전용 확인 표면, Control Plane/Client는 Edge 상태 소비자로 둔다.
선행 작업: Node provider 상태와 Capacity Queue 기반, Edge 모델 그룹 Queue 스케줄링 전환
후속 작업: provider pool scheduler 구현, Provider-Device-Model Qualification 리포트와 Lifecycle 관리, provider enable/disable, benchmark/품질 평가
작업 메모: [pool-compat] apps/edge/README.md와 configs/edge.yaml에 기존 openai.model_routes/adapter + target/Node provider instance 설정을 새 models[] provider pool의 1:1 migration 입력 및 fallback/compat 경로로 유지하는 방향을 정리했다. SDD 대상 Milestone의 공식 Task 체크는 complete.log의 Roadmap/Spec Completion 근거로 처리한다.
작업 메모: [sync] 01_pool_schema 완료 로그로 alias-contract, candidate-schema를, 02+01_edge_dispatch 완료 로그로 target-rewrite, selection-policy를 Roadmap/Spec Completion 기준 완료 처리했다.
작업 메모: [sync-correction] pool-compat는 01_pool_schema의 공식 Roadmap/Spec Targets에는 빠졌지만, SDD S05 Evidence Map이 요구한 migration/compat note와 기존 model_routes regression evidence가 apps/edge/README.md, configs/edge.yaml, packages/go/config/config_test.go, apps/edge/internal/openai/server_test.go에 남아 있어 완료로 보정했다.
작업 메모: [provider-catalog-small] api, cli, local_inference category는 config.Category*와 ProviderSnapshot.category에 반영되어 있고, coarse lifecycle capability는 nodes[].providers[].lifecycle_capabilities와 ProviderSnapshot.lifecycle_capabilities 및 iop-edge nodes list configured provider 요약으로 확인 가능하다. 상세 lifecycle/qualification과 runtime control은 SDD/범위 제외 기준에 따라 후속 Milestone으로 분리한다.
작업 메모: [sync-complete] 03_catalog_status_http 완료 로그로 device-status를, 04+03_client_catalog_view 완료 로그로 ops-review를 Roadmap/Spec Completion 기준 완료 처리했다.
확인 필요: 없음

9.7 KiB Raw Blame History