설정 가이드¶

# 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"  # 외부 모델 메타데이터 파일 경로

# 로드 밸런싱 전략: 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

  # 사용자 정의 메타데이터가 있는 일반 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"            # 가속 워밍업 모드 최대 지속 시간

# 요청 처리 및 타임아웃 설정
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]

# 로깅 설정
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                         # 서킷 브레이커 활성화
  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        # 회로를 닫는 데 필요한 성공 횟수

# 속도 제한 설정
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"

# 직접 오버라이드
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

# 설정 파일과 오버라이드 사용
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 --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