설정 가이드¶

# 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              # 백엔드당 최대 유휴 연결 수

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

# 로드 밸런싱 전략: RoundRobin (기본값), WeightedRoundRobin,
# LeastLatency, Random, ConsistentHash, PrefixAwareHash
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-4o
      - gpt-4o-mini
      - 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-4"
      - "gpt-3.5-turbo"
    model_configs:                       # 메타데이터가 포함된 향상된 모델 설정
      - id: "gpt-4"
        aliases:                         # 이 메타데이터를 공유하는 대체 ID (선택 사항)
          - "gpt-4-0125-preview"
          - "gpt-4-turbo-preview"
        metadata:
          display_name: "GPT-4"
          summary: "복잡한 작업을 위한 가장 유능한 GPT-4 모델"
          capabilities: ["text", "image", "function_calling"]
          knowledge_cutoff: "2024-04"
          pricing:
            input_tokens: 0.03
            output_tokens: 0.06
          limits:
            context_window: 128000
            max_output: 4096

  # 자동 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-4")은
    # 자동으로 기본 이름의 메타데이터와 일치합니다 (예: "gpt-4")

  # 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                    # 프리워밍과 첫 헬스 체크가 끝날 때까지 리스너 바인딩을 대기

# 요청 처리 및 타임아웃 설정
timeouts:
  connection: "10s"                      # TCP 연결 설정 타임아웃
  request:
    standard:                            # 비스트리밍 요청
      first_byte: "30s"                  # 첫 바이트 수신까지의 시간
      total: "180s"                      # 전체 요청 타임아웃 (3분)
    streaming:                           # 스트리밍 (SSE) 요청
      first_byte: "60s"                  # 첫 SSE 청크까지의 시간
      chunk_interval: "30s"              # 청크 간 최대 시간
      total: "600s"                      # 전체 스트리밍 타임아웃 (10분)
    image_generation:                    # 이미지 생성 요청 (DALL-E 등)
      first_byte: "60s"                  # 첫 바이트 수신까지의 시간
      total: "180s"                      # 전체 타임아웃 (기본 3분)
    model_overrides:                     # 모델별 타임아웃 오버라이드
      gpt-5-latest:
        streaming:
          total: "1200s"                 # GPT-5용 20분
      gpt-4o:
        streaming:
          total: "900s"                  # GPT-4o용 15분
  health_check:
    timeout: "5s"                        # 헬스 체크 타임아웃
    interval: "30s"                      # 헬스 체크 간격

# 전역 재시도 및 복원력 설정
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"                        # 전체 재시도 예산

# 로깅 설정
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 스코프는 모든 파일 접근 가능

# 분산 추적 설정
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:
  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                          # 시작 시 이보다 오래된 스냅샷은 폐기

# 메트릭 및 모니터링 설정
metrics:
  enabled: true                         # Prometheus 메트릭 수집 활성화
  path: "/metrics"                      # 메트릭 엔드포인트 경로

# 최소 설정 - 나머지 설정은 기본값 사용
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

/etc/continuum-router/model-metadata.yaml        # 벤더 기준 파일, 덮어써도 안전
/etc/continuum-router/model-metadata.d/
    10-private-models.yaml                       # 우리가 직접 호스팅하는 모델
    50-negotiated-pricing.yaml                   # gpt-5 계약 단가
    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 }

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