설정 가이드¶

# Continuum Router 설정
# 전체 주석이 달린 샘플은 continuum-router --generate-config로 생성하세요

# 서버 설정
server:
  # bind_address는 단일 문자열 또는 주소 배열을 허용합니다
  # TCP 형식: "host:port", Unix 소켓 형식: "unix:/path/to/socket"
  bind_address: "0.0.0.0:8080"          # 단일 주소
  # bind_address:                        # 또는 다중 주소:
  #   - "0.0.0.0:8080"                   #   모든 인터페이스의 TCP
  #   - "unix:/var/run/router.sock"      #   Unix 소켓 (Linux/macOS, Windows 10 1809+)
  # socket_mode: 0o660                   # 선택 사항: Unix 소켓 파일 권한
  workers: 4                             # 워커 스레드 수 (0 = 자동 감지)
  connection_pool_size: 100              # 백엔드당 최대 유휴 연결 수
  # max_concurrent_requests: 64          # 동시 처리 요청 상한 (재시작 필요)
  # max_stream_buffer_bytes: 4294967296  # 프로세스 전체 SSE/릴레이 버퍼 예산, 기본값 4 GiB (재시작 필요)
  # shutdown_drain_timeout: "20s"        # 계획된 종료 시 드레인 마감 시간 (재시작 필요)
  # explain_response_header: false       # API 응답에 x-continuum-route 헤더 포함 (재시작 필요)
  # 공유 아웃바운드 HTTP 클라이언트 튜닝. 선택 사항이며 각 필드의 기본값은
  # 아래와 같습니다. 클라이언트는 기동 시 한 번만 만들어지므로 모든 필드가
  # 재시작을 요구합니다.
  # http_client:
  #   pool_idle_timeout: "300s"          # 유휴 풀 연결 유지 시간
  #   pool_max_idle_per_host: 64         # 오리진당 유지할 유휴 연결 수
  #   tcp_keepalive: "30s"               # TCP keep-alive 프로브 간격
  #   http2_keep_alive_interval: "15s"   # HTTP/2 PING 간격
  #   http2_keep_alive_timeout: "5s"     # PING 무응답 허용 시간
  #   http2_keep_alive_while_idle: true  # 활성 스트림이 없는 연결에도 PING 유지

# 모델 메타데이터 설정 (선택 사항)
model_metadata_file: "model-metadata.yaml"  # 기본(0층) 메타데이터 파일 경로
model_metadata_dirs:                        # 추가 model-metadata.d 드롭인 디렉터리
  - "/etc/router/metadata"                  # 관례 위치 다음에, 적은 순서대로 적용

# 로드 밸런싱 전략: RoundRobin (기본값), WeightedRoundRobin,
# LeastLatency, Random, ConsistentHash, PrefixAwareHash, EngineLoad, LeastBusy,
# LeastCost
selection_strategy: RoundRobin

# 백엔드 설정
backends:
  # 내장 설정이 있는 네이티브 OpenAI API
  - name: "openai"
    type: openai                         # 네이티브 OpenAI 백엔드 사용
    api_key: "${CONTINUUM_OPENAI_API_KEY}"  # 환경 변수에서 로드
    org_id: "${CONTINUUM_OPENAI_ORG_ID}"    # 선택적 조직 ID
    weight: 3
    models:                              # 사용할 모델 지정
      - gpt-5.6-sol
      - gpt-5.6-terra
      - o3-mini
      - text-embedding-3-large
    retry_override:                      # 백엔드별 재시도 설정 (선택 사항)
      max_attempts: 5
      initial_delay: "200ms"
      max_delay: "30s"
      backoff_multiplier: 2.0
      jitter: true
      retryable_status_codes: [429, 502, 503, 504]
      retryable_errors: [ConnectionError, TimeoutError]
      timeout: "60s"

  # 사용자 정의 메타데이터가 있는 일반 OpenAI 호환 백엔드
  - name: "openai-compatible"
    url: "https://custom-llm.example.com"
    weight: 1
    models:
      - "gpt-5.6-sol"
      - "gpt-5.6-luna"
    model_configs:                       # 메타데이터가 포함된 향상된 모델 설정
      - id: "gpt-5.6-sol"
        aliases:                         # 이 메타데이터를 공유하는 대체 ID (선택 사항)
          - "gpt-5.6"
        metadata:
          display_name: "GPT-5.6 Sol"
          summary: "복잡한 전문 작업을 위한 프런티어 GPT-5.6 모델"
          capabilities: ["chat", "vision", "code", "reasoning", "tool"]
          knowledge_cutoff: "2026-02"
          pricing:                       # 1M 토큰당 USD
            input_tokens: 5.0
            output_tokens: 30.0
          limits:
            context_window: 1050000
            max_output: 128000

  # 자동 URL 감지가 있는 Ollama 로컬 서버
  - name: "local-ollama"
    type: ollama                         # 기본값 http://localhost:11434
    weight: 2
    models:
      - "llama2"
      - "mistral"
      - "codellama"

  # vLLM 서버
  - name: "vllm-server"
    type: vllm
    url: "http://localhost:8000"
    weight: 1
    # 지정하지 않으면 모델이 자동으로 검색됩니다
    # 네임스페이스 접두사가 있는 모델 (예: "custom/gpt-5.6-sol")은
    # 자동으로 기본 이름의 메타데이터와 일치합니다 (예: "gpt-5.6-sol")
    model_configs:
      - id: "qwen3.8-27b"
        metadata:
          artifact:                      # 이 백엔드가 서비스하는 가중치 (선택)
            digest: "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
            revision: "4c2e9a1"
            source: "hf://Qwen/Qwen3.8-27B-FP8"
          draft_model:                   # 추측 디코딩 드래프트 (선택)
            name: "qwen3.8-0.6b"

  # Google Gemini API (네이티브 백엔드)
  - name: "gemini"
    type: gemini                           # 네이티브 Gemini 백엔드 사용
    api_key: "${CONTINUUM_GEMINI_API_KEY}" # 환경 변수에서 로드
    weight: 2
    models:
      - gemini-3.1-pro-preview
      - gemini-3-flash-preview
      - gemini-2.5-pro
      - gemini-2.5-flash

# 헬스 모니터링 설정
health_checks:
  interval: "30s"                        # 백엔드 상태 확인 주기
  timeout: "5s"                          # 헬스 체크 요청 타임아웃
  unhealthy_threshold: 3                 # 비정상으로 표시되기 전 실패 횟수
  healthy_threshold: 2                   # 정상으로 표시되기 전 성공 횟수
  endpoint: "/health"                    # 헬스 체크에 사용되는 엔드포인트
  warmup_check_interval: "1s"            # 백엔드 워밍업(HTTP 503) 중 가속 체크 간격
  max_warmup_duration: "300s"            # 가속 워밍업 모드 최대 지속 시간
  block_startup: true                    # 프리워밍과 첫 헬스 체크가 끝날 때까지 리스너 바인딩을 대기
  prewarm_timeout: "10s"                 # 기동 시 프리워밍 프로브 요청 하나의 제한 시간 (변경하려면 재시작)

# 요청 처리 및 타임아웃 설정
timeouts:
  connection: "10s"                      # TCP 연결 설정 타임아웃
  request:
    standard:                            # 비스트리밍 요청
      first_byte: "30s"                  # 폐기 예정이며 동작하지 않음. 실제 예산은 `total`
      total: "180s"                      # 전체 요청 타임아웃 (3분)
    streaming:                           # 스트리밍 (SSE) 요청
      first_byte: "120s"                 # 첫 SSE 청크에 적용되는 실제 기한
      chunk_interval: "30s"              # 두 번째 청크부터의 최대 간격
      total: "600s"                      # 전체 스트리밍 타임아웃 (10분)
    image_generation:                    # 이미지 생성 요청 (DALL-E 등)
      first_byte: "60s"                  # standard.first_byte와 마찬가지로 폐기 예정이며 동작하지 않음
      total: "180s"                      # 전체 타임아웃 (기본 3분, 상한 600s)
    model_overrides:                     # 모델별 타임아웃 오버라이드
      gpt-5-latest:
        streaming:
          total: "1200s"                 # GPT-5용 20분
      gpt-5.6-sol:
        streaming:
          total: "900s"                  # GPT-4o용 15분
  # 이 섹션 전체의 검증 상한. 기동 시 고정되므로 핫 리로드, Admin API,
  # 설정 동기화는 이 값을 바꾸는 후보 설정을 거부합니다.
  # limits:
  #   max_standard_timeout: "900s"       # 기본값 540s, 절대 상한 1080s
  #   max_retry_timeout: "90s"           # 기본값 30s, 절대 상한 120s

# 전역 재시도 및 복원력 설정
retry:
  max_attempts: 3                        # 최대 재시도 횟수
  initial_delay: "100ms"                 # 재시도 간 초기 지연
  max_delay: "10s"                       # 재시도 간 최대 지연
  backoff_multiplier: 2.0                # 지수 백오프 배수
  jitter: true                           # 지연에 무작위 지터 추가
  retryable_status_codes: [429, 502, 503, 504]
  retryable_errors: [ConnectionError, TimeoutError]
  timeout: "30s"                        # 전체 재시도 예산
  prefer_untried_backends: false        # 이 요청이 아직 연결하지 않은 백엔드로 재시도

# 로깅 설정
logging:
  level: "info"                         # 로그 레벨: trace, debug, info, warn, error
  format: "json"                        # 로그 형식: json, pretty

# Files API 설정
files:
  enabled: true                         # Files API 엔드포인트 활성화/비활성화
  max_file_size: 536870912              # 최대 파일 크기 (바이트, 기본: 512MB)
  storage_path: "./data/files"          # 업로드된 파일 저장 경로 (~지원)
  retention_days: 0                     # 시작 시 보존 기간 초과 파일 정리 (일, 0 = 영구 보존)
  metadata_storage: persistent          # 메타데이터 백엔드: "memory" 또는 "persistent" (기본)
  cleanup_orphans_on_startup: false     # 시작 시 고아 파일 자동 정리

  # 인증 및 권한
  auth:
    method: api_key                     # "none" 또는 "api_key" (기본)
    required_scope: files               # 접근에 필요한 API 키 스코프
    enforce_ownership: true             # 사용자가 자신의 파일만 접근 가능
    admin_can_access_all: true          # admin 스코프는 모든 파일 접근 가능

  # OpenAI 백엔드 파일 처리 전략
  openai:
    strategy: base64                    # "base64" (기본) 또는 "upload"
    fallback_to_base64: true            # 업로드 실패 시 base64로 폴백
    cache_capacity: 1000                # 최대 캐시 파일 ID 매핑 수
    cache_ttl_secs: 86400               # 캐시 TTL (초, 기본: 24시간)

  # 파일 작업 엔드포인트별 속도 제한
  rate_limiting:
    enabled: false                      # Files API 속도 제한 활성화
    uploads_per_minute: 10              # 분당 최대 파일 업로드 수
    downloads_per_minute: 100           # 분당 최대 파일 다운로드 수
    operations_per_minute: 1000         # 분당 최대 목록/조회/삭제 작업 수

# 분산 추적 설정
tracing:
  enabled: true                         # 분산 추적 활성화/비활성화
  w3c_trace_context: true               # W3C Trace Context 지원 (traceparent 헤더)
  headers:
    trace_id: "X-Trace-ID"              # 추적 ID 헤더 이름
    request_id: "X-Request-ID"          # 요청 ID 헤더 이름
    correlation_id: "X-Correlation-ID"  # 상관 ID 헤더 이름

# 서킷 브레이커 설정
circuit_breaker:
  enabled: true                         # 프록시 데이터 경로 상태 머신/Admin 제어 활성화
  failure_threshold: 5                  # 회로 개방까지의 연속 실패 횟수
  failure_rate_threshold: 0.5           # 회로 개방 실패율 (0.0-1.0)
  minimum_requests: 10                  # 실패율 평가 전 최소 요청 수
  timeout: "60s"                        # 복구 시도(반개방)까지의 시간
  half_open_max_requests: 3             # 반개방 상태에서 허용되는 시험 요청 수
  half_open_success_threshold: 2        # 회로를 닫는 데 필요한 성공 횟수

# 일반 LLM 프록시 경로가 이 상태를 기록하고 조회합니다. 열린 서킷은 선택에서
# 제외되며, 상태 확인·재시도·폴백과 함께 추론 라우팅을 보호합니다.

# 속도 제한 설정
rate_limiting:
  enabled: true                         # 속도 제한 활성화
  storage: memory                       # "memory" 또는 "redis"
  limits:
    per_client:
      requests_per_second: 10
      burst_capacity: 20
    global:
      requests_per_second: 1000
      burst_capacity: 2000

# Admin API 설정
admin:
  max_backend_name_length: 64             # 백엔드 이름 최대 길이 (1-256, 기본값: 64)
  auth:
    method: bearer                         # 인증 방법: none, bearer, basic, ip_whitelist, api_key
    bearer_token: "${ADMIN_TOKEN}"         # Admin 인증 토큰
  stats:
    enabled: true                          # 통계 수집 활성화/비활성화
    retention_window: 24h                  # 윈도우 쿼리용 링 버퍼 보존 기간
    token_tracking: true                   # 응답 본문에서 토큰 사용량 파싱
    persistence:
      enabled: true                        # 재시작 시 통계 영속 활성화
      path: ./data/stats.json              # 스냅샷 파일 경로
      snapshot_interval: 5m                # 주기적 스냅샷 간격
      max_age: 7d                          # 시작 시 이보다 오래된 스냅샷은 폐기
    # GET /admin/usage/export용 레코드 단위 사용량 내보내기 (기본값: 꺼짐).
    # persistence가 켜져 있으면 레코드 하나가 스냅샷에 약 300바이트를 더하므로
    # (1,000,000개면 약 300 MB) max_records는 감사 기간에 맞춰 정하세요.
    usage_export:
      enabled: false                       # stats.enabled도 필요; 끄면 레코드를 비움
      retention: 7d                        # 해석할 수 없거나 0이면 로드 오류
      max_records: 1000000                 # 1,000에서 10,000,000; 가장 오래된 것부터 제거

# 메트릭 및 모니터링 설정
metrics:
  enabled: true                         # Prometheus 메트릭 수집 활성화
  path: "/metrics"                      # 메트릭 엔드포인트 경로
  port: 9090                            # 메트릭 전용 리스너 (0이면 끔), 변경하려면 재시작
  # bind_address: "0.0.0.0"             # 그 호스트, 기본값: 첫 번째 TCP server.bind_address 호스트
  auth:
    method: bearer
    bearer_token: "${METRICS_TOKEN}"    # auth를 생략하면 엔드포인트가 401을 반환

# 읽기 전용 NVIDIA Dynamo 워커 탐색 (빌드 기능 `dynamo`, 공식 릴리스
# 바이너리에 포함). 라우터는 Dynamo가 등록한 워커를 etcd에서, 한
# 네임스페이스의 DynamoWorkerMetadata 리소스와 EndpointSlice에서, 또는 그
# operator 라벨이 붙은 Pod에서 관찰만 하며, 쓰기·삭제·lease를 전혀 하지
# 않습니다. 재시작이 필요한 필드는 없습니다. `load.*`, `shim.*`, `kv.*`는
# 즉시 반영되고, 나머지(`source`·`endpoints`·`tls`·`auth`·모든 `kubernetes.*`
# 필드)는 watcher를 교체해 다시 접속하고 전체 재동기화합니다
# (`kubernetes.model`과 `kubernetes.models`는 `source: kubernetes`에서
# 무시되며 고쳐도 아무 변화가 없습니다). `event_bus`는 클러스터 내부 이벤트 브로커
# 리스너를 자체 수퍼바이저로 실행합니다(아래 "Dynamo 이벤트 브로커 리스너" 참고).
# architecture/dynamo-integration.md 참고.
dynamo:
  enabled: false                        # 마스터 스위치; `dynamo` 빌드 기능 없이는 비활성
  discovery:
    source: etcd                        # `etcd`(기본값), `kubernetes`(DynamoWorkerMetadata + EndpointSlice; etcd처럼 부하·용량 제공), 또는 `kubernetes_pods`(Pod만; 부하·용량 정보 없음: 라운드로빈 디스패치)
    etcd:
      endpoints: ["http://etcd:2379"]   # http(s) URL 또는 host:port; 즉시 반영
      namespace: "dynamo"               # 워커의 DYN_NAMESPACE와 일치해야 함
      # namespaces: ["prod", "canary"]  # 또는 여러 그래프(최대 16개), 각각 자기 `shim.pools` 항목에 묶임; 하나를 더하거나 빼도 다른 그래프의 워커는 유지
      watch_reconnect_backoff:
        initial: "500ms"                # watch 끊김 후 첫 재연결 지연
        max: "30s"                      # 지연이 2배씩 늘어나는 상한
    # kubernetes:                       # `source: kubernetes` 또는 `kubernetes_pods`일 때 필수; 블록이 있으면 항상 검증
    #   namespace: "dynamo"             # 플릿의 Kubernetes 네임스페이스 (dynamoworkermetadatas + endpointslices, 또는 pods에 get/list/watch)
    #   dynamo_namespace: "dynamo"      # 워커의 DYN_NAMESPACE (nvidia.com/dynamo-namespace 라벨 값이자 레코드의 네임스페이스)
    #   dynamo_namespaces: ["prod", "canary"]  # 또는 이 Kubernetes 네임스페이스 안의 여러 Dynamo 네임스페이스; `dynamo_namespace`와 배타적; `models` 항목은 각자 `dynamo_namespace`를 지정
    #   model: "Qwen/Qwen3-32B"         # 서빙 모델 이름; `kubernetes_pods`는 이것 또는 `models`가 필요(Pod에는 카드가 없음), `kubernetes`는 둘 다 무시. 또는 이것 대신:
    #   models:                         # nvidia.com/dynamo-component마다 한 항목; 목록에 없는 컴포넌트는 건너뜀
    #     - {component: "VllmWorker-decodeheavy", model: "solar-pro4"}
    #     - {component: "VllmWorker-prefillheavy", model: "solar-pro4-longcontext"}
    #   watch_reconnect_backoff: {initial: "500ms", max: "30s"}
  load:
    max_staleness: "3s"                 # 워커의 마지막 kv_metrics 샘플을 신선하다고 볼 창 (100ms-5m)
    transport: direct                   # direct | broker: kv_metrics·kv-events 구독이 퍼블리셔에 닿는 방식
  shim:
    backends: []                        # `dynamo.frontend --router-mode direct` 복제본(backends[].name); disaggregated_serving.enabled 필요
    # pools:                            # 네임스페이스가 여럿이면 `backends` 대신 네임스페이스마다 풀 하나; 고정된 요청은 자기 네임스페이스의 frontend에만 닿음
    #   - {namespace: "prod", backends: [dynamo-frontend-prod]}
    #   - {namespace: "canary", backends: [dynamo-frontend-canary]}
    model_map: {}                       # 후보 매칭용 클라이언트 모델 id -> Dynamo display_name (요청 본문은 그대로 전달됨)
  kv:                                   # KV 오버랩 인지 prefill 선택(빌드 기능 `dynamo-kv`); 모든 필드 즉시 반영
    enabled: false                      # kv-events 구독, 블록 인덱스 유지, 플릿의 아티팩트로 토큰화, 프리픽스 오버랩 크레딧 적용
    # artifact_cache_dir: /var/cache/continuum-router/dynamo-kv-artifacts  # 기본값: <사용자 캐시 디렉터리>/continuum-router/dynamo-kv-artifacts; blake3 검증
    allow_http_artifacts: true          # 카드의 http(s):// 아티팩트(워커 자체 메타데이터 엔드포인트) 가져오기 허용
    allow_hf_artifacts: false           # 카드의 hf:// 아티팩트를 Hub에서 가져오기(공개 인터넷 egress; HF_ENDPOINT / HF_TOKEN 존중)
    pinned_artifacts: []                # 라우터가 로드해도 되는 파일의 blake3 체크섬; 핀 전에는 아무것도 로드·컴파일·렌더링하지 않음(비어 있으면 validate가 경고)
    # pinned_artifacts: ["blake3:<64 hex>", ...]  # 검토한 tokenizer.json / tokenizer_config.json / chat_template.jinja에 `b3sum`을 돌린 값
    overlap_score_credit: 1.0           # 프리픽스 오버랩 블록당 크레딧 블록(유한, >= 0)
    prefill_load_scale: 1.0             # 조정된 prefill 항의 배율(유한, >= 0)
    router_temperature: 0.0             # 0 = 최저 비용 선택; > 0이면 비용에 대한 softmax 샘플링(<= 100)
    send_token_data: false              # 렌더링한 토큰 id를 nvext.token_data로 전송(라우터의 토크나이저 버전을 플릿과 결합)
    conditional_disaggregation:         # 유효 ISL이 짧으면 원격 prefill 생략; Dynamo 1.5.x direct 모드 frontend는 거부
      enabled: false
      policy: isl_bounding              # isl_bounding | prefill_load | isl_or_load
      eff_isl_threshold: 2048           # 유효 ISL이 이 토큰 수 미만이어야 함
      eff_isl_ratio_threshold: 0.7      # 유효/원래 ISL 비율이 이 값 미만이어야 함(0-1)
      # prefill_busy_threshold: 0.8     # prefill_load / isl_or_load: max_num_batched_tokens의 이 비율 초과 시 busy
      # decode_busy_threshold: 0.9      # busy한(또는 신호 없는) decode 워커로의 우회 거부
  event_bus:                            # 클러스터 내부 이벤트 브로커 리스너(빌드 기능 `dynamo-event-bus`); `enabled`와 독립적
    enabled: false                      # continuum-event-broker가 접속하는 TLS 리스너 시작; 끄면 모든 세션을 드레인
    listen: "0.0.0.0:7443"              # enabled일 때 필수; 전용 포트이며 server.bind_address 포트와 겹칠 수 없음
    tls:                                # enabled일 때 필수; TLS 1.3, ALPN h2, 평문 거부
      cert: "/etc/continuum-router/event-bus/tls.crt"
      key: "/etc/continuum-router/event-bus/tls.key"
      # client_ca: "/etc/continuum-router/event-bus/client-ca.crt"  # mTLS: DNS SAN이 브로커 id인 인증서가 그 브로커로 인증
    brokers:
      - id: "broker-a.dynamo"           # 소문자 [a-z0-9.-], 63바이트 이하; 브로커의 hello.client_id와 같아야 함
        token_hash: "sha256:0000000000000000000000000000000000000000000000000000000000000001"  # 자리표시자: printf %s "$TOKEN" | sha256sum; 토큰 자체는 금지
        namespaces: ["dynamo"]          # 이 브로커가 선언할 수 있는 Dynamo 네임스페이스; 비우면 모두 허용(validate가 경고)
      # - id: "kv-listener-a"           # 푸시 모드의 continuum-kv-listener
      #   role: kv_listener             # broker(기본값) | kv_listener
      #   token_hash: "sha256:0000000000000000000000000000000000000000000000000000000000000003"  # 플레이스홀더
      #   backends: ["vllm-1"]          # 이 리스너가 알릴 수 있는 kv_cache_index event_sources backend_name 값
    max_sessions: 64                    # 라우터 전체의 welcome된 세션 수(1-1024)
    max_streams_per_session: 1024       # 세션당 구독 수(1-1024)
    max_session_buffer_bytes: 67108864  # 세션당 바이트 예산; 이 기본값에서 스트림·방향당 16 KiB
    heartbeat_interval: "10s"           # 1s-30s
    idle_timeout: "30s"                 # heartbeat_interval의 2배 이상, 300s 이하

# Continuum Hub control-plane 에이전트 (`control-plane` 빌드 기능 필요)
control_plane:
  enabled: false                        # 마스터 스위치
  hub_url: "https://hub.example.com"    # enabled일 때 필수
  enrollment_token: "${CONTINUUM_HUB_ENROLLMENT_TOKEN}"
  state_file: "./data/control-plane/state.json"
  heartbeat_interval_secs: 30           # 하트비트 주기(초, 기본값: 30)
  usage_push_interval_secs: 10          # 사용량 푸시 주기(초, 기본값: 10)
  usage_batch_max_records: 500          # 사용량 푸시 배치당 최대 레코드 수(기본값: 500)
  request_timeout_secs: 10              # 아웃바운드 Hub 요청별 타임아웃(초, 기본값: 10)
  config_sync:
    enabled: false
    poll_interval_secs: 5
    state_file: "./data/control-plane/config-sync.json"
    backends:
      mode: disabled                    # disabled | overlay | authoritative
      state_file: "./data/control-plane/backend-sync.json"
      tasks: true                       # 아웃바운드 후보 프로브 및 마스킹 내보내기 작업 채널
      max_concurrent_tasks: 2           # 동시 실행할 Hub 백엔드 작업 수(1-8, 기본값: 2)

# 클라이언트용 System One 결정 엔드포인트: POST /v1/decisions (별칭 /v1/systemone).
# `targets`에 있는 이름은 해당 System One 서버로 그대로 전달하고 그 외 이름은
# 같은 이름의 채팅 모델에서 에뮬레이션합니다(강제 `emit_decision` 도구 호출 1회,
# 응답에 `emulated: true` 표시). 즉시 반영됩니다. api.md의 Decisions 절 참고.
decisions:
  enabled: true                         # false면 404 decisions_disabled 응답
  targets:
    - name: jev                         # 클라이언트가 보내는 `model`; 폴백 체인에서도 사용 가능
      protocol: typesafe                # generic (기본값) | typesafe | foundry | llama_cpp
      auth: auto                        # auto (기본값) | bearer | api_key | entra
      endpoint: "https://api.typesafe.ai/v1/systemone"
      api_key_env: TYPESAFE_API_KEY     # 또는 `backend: <자체 호스팅 backends[] 이름>`
      model: jev-1.14.0                 # 업스트림 모델 또는 Foundry 배포 이름
      typesafe_images: false            # TypeSafe JSON assets 및 Box 질문 옵트인
      typesafe_long_context: false      # TypeSafe 262k 롱 컨텍스트 헤더 옵트인
      max_questions: 64                 # 1-256 (기본값: 64)
      max_state_bytes: 16384            # 256-1048576 (기본값: 16384)
      max_media_bytes: 4194304          # 디코딩된 미디어 바이트 1-16777216 (기본값: 4 MiB)
      timeout_ms: 1500                  # 100-60000 (기본값: 1500)
      max_concurrent: 32                # 1-1024 (기본값: 32)
  emulation:
    enabled: true                       # false면 타깃이 아닌 이름은 404
    max_state_bytes: 16384              # 256-1048576
    max_tokens: 1024                    # 16-32768

# control-plane 사용량 레코드의 요청별 품질 판정 (control-plane 빌드와
# control_plane.enabled 필요). /v1/chat/completions 응답이 버퍼링되었든
# 스트리밍되었든 모든 가드레일 단계를 통과하고 나면 System One 결정 모델이
# 판정하고 확률은 해석된 판정 모델 id와 함께 basis point로 사용량 레코드에
# 실립니다. 응답, 레코드의 회계, 푸시는 판정을 기다리지 않습니다.
# 즉시 반영됩니다.
usage:
  quality_judgment:
    target:                             # 공유 System One 타깃 블록
      endpoint: "http://laya.internal:8000/v1/systemone"
    sample_rate: 1.0                    # 판정할 요청 비율
    models: []                          # 제공된 모델 id; 비어 있으면 모든 모델
    include_tool_results: false         # true면 현재 턴의 도구 결과를 보냄 (`grounded`용)
    max_request_bytes: 512              # 앞뒤를 남기는 상한, Laya 다국어 기준
    max_reply_bytes: 1536
    max_tool_results_bytes: 1024
    max_in_flight: 32                   # 라우터별 동시 판정 수; 초과분은 버림
  # 스트림 종료 후 엔진 /tokenize 보정(기본값 꺼짐): 라우터가 직접 센 델타 수로
  # 기록되는 스트림을 클라이언트 스트림이 끝난 뒤 서빙 엔진의 토크나이저 경로
  # (vllm, sglang, llamacpp, mlxcel, continuumrouter)로 다시 세어 최대
  # timeout_ms 뒤에 `engine_tokenize`로 기록합니다. 스트림이 끝날 때마다 읽습니다.
  tokenize_correction:
    enabled: true                       # 기본값 false
    timeout_ms: 2000                    # 100-30000
    max_concurrent: 4                   # 라우터별 1-256; 초과분은 대기 없이 버림
  # control-plane 에이전트가 만드는 모든 사용량 배치를 SHA-256 체인 해시와 함께
  # 추가 전용 로컬 파일에 기록. 파일 검증은
  # `python3 -I scripts/verify-usage-ledger.py <file>`. 다음 푸시 주기에 반영됩니다.
  ledger_export:
    path: "/var/lib/continuum-router/usage-ledger.jsonl"  # 설정하지 않으면 내보내지 않음
    max_bytes: 1073741824               # 1 GiB를 넘으면 회전 (최소 1 MiB)
    rotate: true                        # false면 max_bytes에서 내보내기를 멈춤
    max_files: 30                       # 회전 파일 보관 개수(최소 1). 생략하면 모두 보관
  # 백엔드별, 윈도별로 원장 출력 토큰을 엔진 생성 카운터와 비교.
  # engine_stats.enabled: true가 필요하며 즉시 리로드됩니다.
  reconciliation:
    window: "5m"                        # 10s-24h, engine_stats.interval의 두 배 이상 권장
    max_drift: 0.05                     # (0, 1]
    history: 24                         # 백엔드별로 보관할 닫힌 윈도 수(1-1000)

proxy:
  internal_streaming: true   # 즉시 재로드

backends:
  - name: vllm-a
    type: vllm
    url: http://vllm-a:8000
    internal_streaming: false   # 이 백엔드는 버퍼링 유지

proxy:
  response_cost_headers: true   # 즉시 재로드

proxy:
  hedge_delay_ms: 500   # 즉시 재로드, 미설정이면 비활성

proxy:
  variant_suffixes:
    enabled: true   # 기본값 false, 즉시 재로드

proxy:
  middle_out:
    enabled: false                 # 즉시 재로드, 기본값은 꺼짐
    default_output_reserve: 1024   # 0~1000000, 요청에 출력 한도가 없을 때 사용

backends:
  - name: "self-hosted-embeddings"
    type: vllm
    url: "http://embeddings:8000"
    record_usage_missing: true   # 기본값 false; 즉시 리로드

# 최소 설정 - 나머지 설정은 기본값 사용
server:
  bind_address: "0.0.0.0:8080"

backends:
  - name: "ollama"
    url: "http://localhost:11434"
  - name: "lm-studio"
    url: "http://localhost:1234"

health_checks:
  interval: "30s"
  timeout: "5s"
  unhealthy_threshold: 3
  healthy_threshold: 2
  endpoint: "/health"

logging:
  level: "info"
  format: "json"

# 직접 오버라이드
export CONTINUUM_BIND_ADDRESS="0.0.0.0:9000"
export CONTINUUM_BACKEND_URLS="http://localhost:11434,http://localhost:1234"
export CONTINUUM_LOG_LEVEL="debug"

# config.yaml의 ${...} 치환에서 참조
export CONTINUUM_OPENAI_API_KEY="sk-..."
export ADMIN_TOKEN="my-admin-token"

# 라우터 시작
continuum-router

continuum-router --help

export CONTINUUM_GITHUB_TOKEN="$(gh auth token)"    # 저장소가 비공개인 동안 필수

continuum-router metadata download                  # main을 받아 해석된 경로에 설치
continuum-router metadata download --check          # 최신 여부만 확인하고 쓰지 않음
continuum-router metadata download --ref v1.15.5    # 릴리스 태그로 고정
continuum-router metadata download --output ./model-metadata.yaml
continuum-router metadata update --all               # 기본 파일과 설정된 드롭인 경로
continuum-router metadata update --dir ./model-metadata.d

/etc/continuum-router/model-metadata.yaml        # 벤더 기준 파일, 덮어써도 안전
/etc/continuum-router/model-metadata.d/
    10-alibaba.yaml                              # 배포 파일, source_url 있음
    23-openai.yaml                               # 배포 파일, source_url 있음
    50-negotiated-pricing.yaml                   # 로컬 파일, source_url 없음
    90-local-overrides.yaml

models:
  - id: gpt-5
    aliases: [gpt-5-latest]
    metadata:
      display_name: GPT-5
      capabilities: [chat, reasoning, vision]
      pricing: { input_tokens: 1.25, output_tokens: 10.0 }

models:
  - id: gpt-5
    metadata:
      pricing: { input_tokens: 0.90, output_tokens: 7.20 }

# model-metadata.d/10-private-models.yaml
models:
  - id: qwen3.8-27b
    metadata:
      artifact:
        digest: sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
        registry_version: v2.1-fp8
        revision: 4c2e9a1
        source: hf://Qwen/Qwen3.8-27B-FP8
      draft_model:
        name: qwen3.8-0.6b
        artifact:
          digest: blake3:5e2b0a9c1f7d3e8b4a6c0d2f9e1b7a3c5d8f0e2a4c6b8d0f1e3a5c7b9d0f2e4a

continuum-router metadata show              # 원본 병합 결과와 레이어 보고서
continuum-router metadata show --resolved   # 라우터가 실제로 쓰는 타입 문서
continuum-router metadata show --json       # 같은 보고서를 기계가 읽는 객체로

# 설정 파일과 오버라이드 사용
continuum-router --config config.yaml --bind "0.0.0.0:9000"

# 백엔드 임시 오버라이드
continuum-router --config config.yaml --backends "http://localhost:11434"

# 사용자 정의 모델 메타데이터 파일 사용
continuum-router --config config.yaml --model-metadata /path/to/custom-metadata.yaml

# 틸드 확장과 함께 모델 메타데이터 사용
continuum-router --model-metadata ~/configs/model-metadata.yaml

# 테스트용 헬스 체크 설정 조정
continuum-router --config config.yaml --health-check-interval 10

# 샘플 설정 생성
continuum-router --generate-config > my-config.yaml

# 검증하고 목적별 템플릿 생성
continuum-router config validate my-config.yaml
continuum-router config generate --template production-ha --output production.yaml

# 설정 조회 또는 비교 (`--resolved` 출력에는 비밀 값이 포함될 수 있음)
continuum-router config show my-config.yaml
continuum-router config diff my-config.yaml production.yaml

# 구버전 설정 파일 마이그레이션 (미리보기 후 적용)
continuum-router --migrate-config-file config.yaml --dry-run
continuum-router --migrate-config-file config.yaml

# Docker HEALTHCHECK 프로브
continuum-router --health-check --health-check-url http://localhost:8080/health

# ChatGPT/Codex 백엔드용 OAuth 디바이스 플로 로그인
continuum-router --config config.yaml auth login --backend chatgpt

# MCP 클라이언트에 설정 도우미 등록
claude mcp add continuum-router-config -- continuum-router mcp-serve

# 모델 메타데이터 갱신, 또는 로컬 사본이 오래됐는지 확인 (종료 코드 2 = 업데이트 있음)
export CONTINUUM_GITHUB_TOKEN="$(gh auth token)"
continuum-router metadata download
continuum-router metadata download --check --json

# 이 라우터 인스턴스가 읽는 경로에 설치
continuum-router --model-metadata /etc/continuum-router/model-metadata.yaml metadata download

# model-metadata.d 계층까지 반영된 실제 적용 메타데이터 확인
continuum-router metadata show --resolved
continuum-router metadata show --json

# 실행 중인 라우터의 대시보드. 관리 토큰이 프로세스 목록에 노출되지 않게 환경 변수로 전달
export CONTINUUM_ADMIN_TOKEN="<admin-scoped API key>"
continuum-router status --url http://router.internal:8080
continuum-router status --watch --interval 2 --window 1h
continuum-router usage --by api-keys --top 20
continuum-router usage --window 24h --series --series-days 14