아키텍처 가이드¶

이 문서는 Continuum Router의 아키텍처, 설계 결정, 확장 지점을 다룹니다.

목차¶

• 개요
• 4계층 아키텍처
• 라이브러리 진입점 (src/server/)
• 핵심 컴포넌트
• 데이터 흐름
• 의존성 주입
• 오류 처리 전략
• 확장 지점
• 설계 결정
• 성능 고려 사항
• 속도 제한 → 설정
• 모델 폴백 시스템 → 오류 처리
• 서킷 브레이커 → 오류 처리
• 파일 저장소 → 아키텍처 상세
• 실시간 WebSocket 프록시 → 설정
• Dynamo 워커 탐색 → 아키텍처 상세
• Agent Communication Protocol (ACP)
• 백엔드 패스스루 계약

개요¶

Continuum Router는 깔끔한 4계층 아키텍처를 사용하여 명확한 관심사 분리, 테스트 가능성, 유지보수성을 제공하는 고성능, 프로덕션 레디 LLM API 라우터로 설계되었습니다. 이 아키텍처는 도메인 주도 설계 원칙과 의존성 역전을 따라 견고하고 확장 가능한 시스템을 만듭니다.

아키텍처 목표¶

1. 관심사 분리: 각 계층은 단일의 명확하게 정의된 책임을 가집니다
2. 의존성 역전: 상위 계층은 구체적인 구현이 아닌 추상화에 의존합니다
3. 테스트 가능성: 각 컴포넌트를 독립적으로 단위 테스트할 수 있습니다
4. 확장성: 기존 코드를 수정하지 않고 새로운 기능을 추가할 수 있습니다
5. 성능: 깔끔한 아키텍처를 유지하면서 최소한의 오버헤드
6. 안정성: 다층 오류 처리를 갖춘 빠른 실패 설계

4계층 아키텍처 { #4-layer-architecture }¶

계층 설명¶

1. HTTP Layer (src/http/)¶

책임: HTTP 요청, 응답 및 웹 관련 관심사 처리

구성 요소¶

• Routes (routes.rs): HTTP 엔드포인트 및 라우트 처리 정의
• Middleware (middleware/): 횡단 관심사 (인증, 로깅, 메트릭, 속도 제한)
• DTOs (dto/): HTTP 직렬화/역직렬화를 위한 데이터 전송 객체
• Streaming (streaming/): Server-Sent Events (SSE) 처리

주요 파일¶

src/http/
├── mod.rs              # HTTP 계층 내보내기
├── routes.rs           # 라우트 정의 및 핸들러
├── dto.rs              # 요청/응답 DTO
├── handlers/           # 요청 핸들러
│   ├── mod.rs
│   └── responses.rs    # Responses API 핸들러
├── middleware/         # HTTP 미들웨어 컴포넌트
│   ├── mod.rs
│   ├── auth.rs         # API 키 인증 미들웨어
│   ├── admin_auth.rs   # Admin API 인증 미들웨어
│   ├── files_auth.rs   # Files API 인증 미들웨어
│   ├── admin_audit.rs  # Admin 작업 감사 로깅
│   ├── cors.rs         # CORS (Cross-Origin Resource Sharing) 미들웨어
│   ├── logging.rs      # 요청/응답 로깅
│   ├── metrics.rs      # 메트릭 수집
│   ├── metrics_auth.rs # 메트릭 엔드포인트 인증
│   ├── model_extractor.rs # 요청에서 모델 추출
│   ├── prometheus.rs   # Prometheus 메트릭 통합
│   ├── rate_limit.rs   # 속도 제한 미들웨어 (레거시)
│   └── rate_limit_v2/  # 향상된 속도 제한 (모듈화)
│       ├── mod.rs      # 모듈 내보내기
│       ├── middleware.rs # 속도 제한 미들웨어
│       ├── store.rs    # 속도 제한 저장소 및 추적
│       └── token_bucket.rs # 토큰 버킷 알고리즘
└── streaming/          # SSE 스트리밍 핸들러
    ├── mod.rs
    └── handler.rs      # 스트리밍 응답 처리

미들웨어 구성 요소¶

HTTP 계층에는 횡단 관심사를 제공하는 여러 미들웨어 구성 요소가 포함됩니다:

• auth.rs: 메인 엔드포인트 (/v1/chat/completions, /v1/models, /anthropic/* 등)에 대한 API 키 인증

  • Authorization: Bearer <key> 또는 Anthropic 고유의 x-api-key: <key> 헤더로 전달된 API 키 검증. 둘 다 있으면 Authorization: Bearer를 우선
  • config.yaml에 구성된 다중 API 키 지원
  • 유효하지 않거나 누락된 키에 대해 401 Unauthorized 반환

• admin_auth.rs: admin 엔드포인트 (/admin/*)에 대한 별도 인증

  • 명시적 none, 베어러 토큰, HTTP Basic, IP 허용 목록, 공유 저장소 API 키 모드 지원
  • 민감한 작업 보호(설정 리로드, 서킷 브레이커 제어, 헬스 관리)
  • admin.auth로 설정. 블록이 없으면 실패 시 차단하고 method가 없는 블록은 기본적으로 api_key를 사용

• files_auth.rs: Files API (/v1/files/*)에 대한 인증 미들웨어

  • 파일 업로드/다운로드/삭제 작업에 특화된 API 키 검증
  • 무단 파일 접근 및 조작 방지
  • 권한 확인을 위해 파일 저장소 서비스와 통합

• admin_audit.rs: admin 작업에 대한 감사 로깅 미들웨어

  • 타임스탬프 및 호출자 식별과 함께 모든 admin API 호출 기록
  • 민감한 작업의 매개변수와 결과 로깅
  • 규정 준수 및 보안 모니터링을 위한 감사 추적 제공
  • 설정 가능한 로그 레벨 및 보존 정책

• cors.rs: CORS (Cross-Origin Resource Sharing) 미들웨어

  • 웹 애플리케이션, Tauri 앱, Electron 앱에 라우터 임베딩 가능
  • 와일드카드 출처 (*), 정확한 출처, 포트 와일드카드 (http://localhost:*) 지원
  • 데스크톱 앱용 사용자 정의 스킴 지원 (예: tauri://localhost)
  • 메서드, 헤더, 자격 증명, 프리플라이트 캐시 기간 설정 가능
  • 적절한 프리플라이트 처리를 위해 미들웨어 스택 초기에 적용

• rate_limit_v2/: 향상된 속도 제한 시스템 (속도 제한 섹션 참조)

  • 클라이언트별 추적이 있는 토큰 버킷 알고리즘
  • 지속적인 속도 및 버스트 보호를 위한 별도 제한
  • 만료된 클라이언트 항목의 자동 정리
  • 모니터링을 위한 상세 메트릭

2. Services Layer (src/services/)¶

책임: 비즈니스 로직 조율 및 인프라 구성 요소 간 조정

구성 요소¶

• Backend Service (backend_service.rs): 백엔드 풀 관리, 로드 밸런싱, 헬스 체크
• Model Service (model_service.rs): 백엔드에서 모델 집계, 캐싱 처리, 메타데이터로 보강
• Proxy Service (proxy_service.rs): 요청 라우팅, 재시도 처리, 스트리밍 관리
• Health Service (health_service.rs): 서비스 헬스 모니터링, 상태 추적
• Web Search Service (search/): 자체 호스팅 백엔드를 위해 라우터가 관리하는 web_search 도구입니다. Serper, Exa, Brave, SearXNG 구현체를 갖춘 플러그형 프로바이더 트레이트와 반복 횟수, 경과 시간, 바이트 예산 상한이 있는 도구 실행 루프를 제공합니다(웹 검색 참조)
• System One Client (systemone/): generic, typesafe, foundry, llama_cpp 프로바이더 프로필(호스팅 TypeSafe Jev, Foundry의 Microsoft-Decision-1, 자체 호스팅 Laya / Kev / Nimble / VLLM Decision 2/D3)을 아우르는 공유 System One 결정 모델 클라이언트입니다(의사 결정 모델 참조).
  • 핵심 기능: state에 대한 타입 지정 noul / choice / score / box 질의, 429 / 529 / 연결 실패 시 1회 제한 재시도, 크기 제한 오류 본문 처리, 고정 백엔드 계약에 따른 backend: 참조 해석을 제공합니다.
  • 캐시 무효화 및 공유: cache_target_identity()는 라이브 Config 스냅샷이 리로드될 때마다 단조 증가하는 CacheTopologyGeneration 카운터를 사용해 자격 증명을 해시하지 않고 하위 캐시를 무효화합니다. 가드레일 프로바이더, 스마트 라우팅 분류기, 액션 안전 평가기, 응답 품질 폴백 검사, 공개 /v1/decisions 네이티브 패스스루가 모두 이 클라이언트와 SystemOneTargetConfig(src/core/config/models/systemone.rs)를 공유합니다. ClientCache(systemone/cache.rs)는 소비자와 라우터마다(/v1/decisions는 get_or_build_keyed로 소비자, 라우터, 타깃 이름마다) 타깃 블록을 키로 삼아 클라이언트를 하나씩 유지하며, 타깃이 리로드되면 다음 요청에서 재생성합니다.
• Answer Quality (answer_quality/): 소비자 중립적인 응답 품질 질문 묶음입니다.
  • 질문 및 상태 생성: 세 가지 noul 질문(answered, refusal, truncated, questions 설정으로 부분 집합 선택), 임계값에 따라 판정을 내리는 AnswerJudgment::worst_problem, 마지막 사용자 메시지와 응답만 읽어 각각 앞뒤 일부만 남기는 {user_message, ai_response} 상태 생성기를 제공합니다.
  • 품질 기반 폴백: fallback.quality_check(src/proxy/quality_fallback.rs)는 비스트리밍 채팅 응답에 대해 가드레일 출력 게이트 직후에 이 검사를 실행하며, 체인 실행기와 동일한 홉 경로(src/proxy/request.rs의 execute_quality_hop)로 폴백 체인을 진행합니다(max_extra_hops, max_fallback_attempts, 비스트리밍 체인 예산 적용).
• Usage Quality Judgment (src/control_plane/usage_quality/, control-plane 기능): usage.quality_judgment는 질문 묶음에 grounded와 language_match를 추가하여 가드레일 출력 게이트를 통과한 버퍼링 및 스트리밍 응답을 평가합니다.
  • 샘플링 및 비동기 봉인: UsageQualityPlan은 디스패치 전에 요청을 샘플링해 길이 제한이 적용된 텍스트를 보관하며, 비스트리밍 통계 탭이 그 QualityTicket을 요청의 UsageEvent에 첨부합니다. 응답이 확정되면 finish_text_with(OpenAI용 finish / finish_with 래퍼 뒤의 와이어 중립 코어)가 라우터별 동시 실행 상한 안에서 별도 평가 태스크를 띄우거나, fallback.quality_check와 호출을 공유하는 경우 이미 수행된 판정을 그대로 전달합니다. 사용량 루프는 판정을 기다리지 않고 레코드를 즉시 변환, 시퀀싱, 차감, 버퍼링한 뒤 푸시 배치를 구성할 때 티켓을 봉인합니다(그 시점까지 완료된 판정만 레코드에 실리고 지연된 판정은 late로 집계되며, 허브는 idempotency_key로 중복을 제거합니다).
  • 스트리밍 채팅 경로: 채팅 인그레스가 입력 게이트 직후에 요청을 샘플링해 StreamQualityHandle(단일 소비 공유 핸들)로 스트리밍 핸들러에 전달하며, 캐시 재생이 아님이 확인되면 StreamObservabilityContext::usage_quality에 장착됩니다. record_stream_usage가 티켓을 스트림 종료 UsageEvent에 싣고, OpenAI 와이어 릴레이(변환기, thinking 변환기, mid-stream 폴백 릴레이)는 StreamReplyAccumulator(src/services/answer_quality/stream.rs, 전체 응답의 cap_middle과 동일한 결과를 내는 앞뒤 버퍼링 판독기)에 청크를 누적한 뒤 게이트의 finalize 이후 한 번 평가합니다. 정상 종료된 스트림만 평가하며, 게이트 차단·변환, mid-stream 홉 이어붙이기, 오류, 클라이언트 연결 종료, 또는 어떤 릴레이도 꺼내지 않은 계획은 모두 skipped로 집계됩니다(모든 결과에 stream 레이블 부여).
  • Anthropic Messages 인그레스: QualityRequest 트레이트(src/services/answer_quality/state.rs)를 통해 요청을 샘플링하고(판정 대상 턴은 액션 안전 평가기와 공유하는 src/http/handlers/anthropic/user_turn.rs의 judged_user_turn이 선택하며, tool_result와 하네스 <system-reminder> 블록을 제외한 마지막 사용자 메시지를 사용), anthropic_reply_text와 StreamReplyAccumulator::observe_anthropic_event(src/services/answer_quality/anthropic.rs)로 응답을 추출합니다. 버퍼링 요청은 with_request_plan(src/control_plane/usage_quality/scope.rs) 범위 안에서 실행되어 응답 경로의 탭이 claim_current_ticket으로 티켓을 가져가고 build_gated_anthropic_response가 take_request_plan으로 본문을 평가합니다. 스트리밍 요청은 AnthropicStreamOutput(src/http/handlers/anthropic/stream_output.rs)을 통해 스트림 전 시도들이 StreamQualityHandle을 공유합니다.
  • /v1/responses 및 responses_only 브리지: /v1/responses는 ResponsesRequest에 QualityRequest를 구현하고 responses_reply_text(src/services/answer_quality/responses.rs, previous_response_id 연쇄 요청에서도 현재 요청의 input 내 마지막 사용자 메시지만 평가)와 src/http/handlers/responses_quality.rs를 통해 연결됩니다. 스트리밍 변환 경로의 CompletedResponsePersister와 패스스루 릴레이는 종료 이벤트(response.completed / response.incomplete)의 응답 객체를 게이트 검사 뒤에 정산합니다. 채팅 인그레스의 responses_only 브리지(src/proxy/responses_only/bridge_usage.rs)도 입력 게이트 직후 자체 계획을 샘플링해 버퍼링 응답은 출력 게이트 뒤에, 스트리밍 응답은 BridgeStreamEnd::record에서 정산합니다. 모델 실험 요청의 모든 사용량 레코드에는 experiment_id와 experiment_variant_id(ExperimentArm)가 함께 기록됩니다.
• System One Classifier (smart_routing/system_one_classifier.rs): 스마트 라우팅 method: system_one / hybrid_system_one 분류기입니다.
  • 분류 및 신뢰도 게이트: 캐시되지 않은 요청마다 공유 클라이언트를 통해 복잡도 수준(score)과 도메인(choice)을 단일 결정 호출로 질의하고, 점수를 가장 가까운 수준으로 반올림한 뒤 두 응답 신뢰도의 최솟값과 함께 ClassificationResult를 구성합니다. SmartRouter는 min_confidence로 결과를 게이트하며(미달 시 규칙 기반 폴백 또는 hybrid_system_one의 LLM 에스컬레이션 실행), 기능(capabilities)과 언어는 규칙 분류기에서 가져옵니다. shadow 모드에서는 라우팅 결정을 바꾸지 않고 주 분류기와 나란히 실행해 일치율을 기록합니다.
  • 캐싱 및 후보 사전 필터링: 캐시 키는 cache_namespace({version, target, questions}), SystemOneClient::cache_target_identity(), 가드레일 통과 후 길이 제한된 state로 구분됩니다. 분류 및 정책 선택 전에 collect_smart_routing_candidates_for_request(src/proxy/smart_routing_candidates.rs)가 호출자 API 키의 allowed_models 및 allowed_backends, 백엔드 헬스 상태, 서킷 브레이커 허용 여부, 채팅 출력 적격성(결정 전용 모델은 excluded_incompatible로 제외)을 교차 검증합니다.

주요 파일¶

src/services/
├── mod.rs              # 모듈 내보내기
├── model_service.rs    # 모델 집계 서비스
├── proxy_service.rs    # 요청 프록시 및 라우팅
├── health_service.rs   # 헬스 모니터링 서비스
├── deduplication.rs    # 요청 중복 제거 서비스
├── responses/          # Responses API 지원
│   ├── mod.rs
│   ├── converter.rs    # 응답 형식 변환
│   ├── router.rs       # 라우팅 전략 결정 (패스스루 vs 변환)
│   ├── passthrough.rs  # OpenAI/Azure 및 `responses_api: native` 백엔드용 직접 패스스루
│   ├── passthrough_lifecycle.rs # 응답을 처리한 백엔드로 GET/DELETE/cancel 전달
│   ├── passthrough_routes.rs    # 라우터별로 제한된 (소유자, 응답 ID) -> 백엔드 바인딩
│   ├── session.rs      # 세션 관리
│   ├── stream_service.rs # 스트리밍 서비스 오케스트레이션
│   └── streaming.rs    # 스트리밍 응답 처리
├── answer_quality/     # 응답 품질 질문 묶음과 결정 상태
│   ├── battery.rs      # QualityQuestion, AnswerJudgment, judge()
│   └── state.rs        # {user_message, ai_response[, tool_results]} 상태 생성기와 상한
├── search/             # 라우터 관리형 웹 검색 서비스
│   ├── mod.rs          # SearchProvider 트레이트, SearchError, SearchResult, build_provider
│   ├── executor.rs     # WebSearchExecutor: 도구 주입, 도구 실행 루프
│   └── providers.rs    # 프로바이더 구현체 (Serper, Exa, Brave, SearXNG)
├── streaming/          # 스트리밍 유틸리티
│   ├── mod.rs
│   ├── parser.rs       # 스트림 파싱 로직
│   └── transformer.rs  # 스트림 변환 (OpenAI/Anthropic)
├── tokenize/           # 엔진 토크나이저 접근, 항상 컴파일
│   ├── wire.rs         # 백엔드 타입별 지원 여부, 경로, 페이로드. count_tokens와 공유
│   ├── response.rs     # 크기 제한된 바이트에서 JSON 트리 없이 엔진 응답을 읽는 리더
│   ├── lenient.rs      # 타입이 다른 필드를 없는 것으로 읽는 비지터
│   ├── token_strs.rs   # 버퍼 하나와 u32 오프셋으로 담는 토큰 문자열 목록
│   ├── upstream.rs     # 시간 예산과 크기 제한 본문 읽기. count_tokens와 공유
│   ├── validate.rs     # /tokenize와 /detokenize의 클라이언트 계약
│   ├── dispatch.rs     # 정확한 모델 해석 (재시도와 폴백 없음)
│   ├── call.rs         # 업스트림 호출, 또는 /apply-template과 /tokenize 두 호출
│   ├── chat_render.rs  # llama-server 엔진별로 반영되는 messages 옵션과 두 호출의 본문
│   └── handlers.rs     # build_api_routes가 마운트하는 두 핸들러
└── systemone/          # 공유 System One 결정 모델 클라이언트
    ├── mod.rs          # 모듈 문서와 재수출
    ├── cache.rs        # ClientCache: 소비자, 라우터, 타깃 키당 클라이언트 하나
    ├── client.rs       # SystemOneClient: 대상 해석, 제한된 재시도, 디코딩
    ├── metering.rs     # SystemOneConsumer별 시도 단위 사용량 기록
    └── types.rs        # Question / Answer / Usage 와이어 타입과 질문 검증

3. Infrastructure Layer (src/infrastructure/)¶

책임: 외부 시스템 및 기술적 기능의 구체적인 구현 제공

구성 요소¶

• Backends (backends/): 특정 백엔드 구현 (OpenAI, Anthropic, Gemini, vLLM, SGLang, Ollama, llama.cpp, LM Studio, Continuum Router)
• Cache (cache/): 캐싱 구현 (LRU, TTL 기반)
• Configuration (config/): 설정 로딩, 감시, 검증
• HTTP Client (common/http_client.rs): 모든 백엔드 클라이언트에 쓰이는 HttpClientFactory 프리셋(유일한 클라이언트 팩토리)
• Backend HTTP Protocol (backend_http/): 백엔드별 http_version 선택. auto 백엔드는 공유 프록시 클라이언트를 쓰고 http1과 http2 백엔드는 같은 ProxyClientTuning(타임아웃과 server.http_client)으로 만든 형제 클라이언트를 씁니다. 형제 클라이언트는 이 튜닝과 버전을 키로 프로세스 전역에 캐시됩니다. AppState::backend_client는 요청이 라우팅된 설정에 있는 백엔드 항목으로 클라이언트를 고르므로 리로드는 다음 디스패치부터 적용되고 BackendClients는 이 선택을 mid-stream 릴레이 태스크로 전달합니다. 디스패치 관측성(디스패치마다 debug 로그, HTTP/2를 협상할 수 있는 백엔드가 in-flight 100에 이르면 빈도 제한된 경고, 버려진 대기를 cancelled로 기록하는 ResponseWait를 통한 continuum_backend_response_wait_seconds)도 여기서 나옵니다. 형제 클라이언트 빌드 실패는 캐시되어 한 번만 로그되고 해당 백엔드는 공유 클라이언트로 대체됩니다. 호스트당 두 번째 HTTP/2 연결은 구현하지 않았습니다. reqwest 풀은 오리진마다 HTTP/2 연결 하나를 재사용하며 스트림 수를 고려하는 훅이 없기 때문입니다.
• Auth (auth/): OAuth 2.0 디바이스 인가 그랜트(RFC 8628) 서브시스템. AuthStrategyRegistry는 시작 시 채워지고 핫 리로드 중에 갱신되며 모든 프록시 핫 패스 핸들러(chat completions, responses, image generation)가 이걸 조회해 outbound 요청에 서명하고 401이 오면 강제 갱신을 트리거합니다. 스트리밍 요청 빌더(초기 디스패치, 홉 단위 스트림 중간 폴백, 자동 백엔드 선택, Unix 소켓 전송)도 같은 레지스트리를 조회합니다. 공유 프록시 인증 헬퍼는 src/proxy/oauth_helper.rs에 있습니다.

주요 파일¶

src/infrastructure/
├── mod.rs              # 인프라 내보내기 및 유틸리티
├── backends/           # 백엔드 구현
│   ├── mod.rs
│   ├── anthropic/      # 네이티브 Anthropic Claude 백엔드
│   │   ├── mod.rs      # 백엔드 구현 및 요청 변환
│   │   └── stream.rs   # SSE 스트림 변환기 (Anthropic → OpenAI)
│   ├── gemini/         # 네이티브 Google Gemini 백엔드
│   │   ├── mod.rs      # TTFB 최적화가 있는 백엔드 구현
│   │   └── stream.rs   # SSE 스트림 변환기 (Gemini → OpenAI)
│   ├── openai/         # OpenAI 호환 백엔드
│   │   ├── mod.rs
│   │   ├── backend.rs  # OpenAI 백엔드 구현
│   │   └── models/     # OpenAI 특화 모델 정의
│   ├── factory/        # 백엔드 팩토리 패턴
│   │   ├── mod.rs
│   │   └── backend_factory.rs  # 설정에서 백엔드 생성
│   ├── pool/           # 백엔드 풀링 및 관리
│   │   ├── mod.rs
│   │   ├── backend_pool.rs     # 연결 풀 관리
│   │   └── backend_manager.rs  # 백엔드 라이프사이클 관리
│   ├── generic/        # 제네릭 백엔드 구현
│   │   └── mod.rs
│   ├── llamacpp/       # llama.cpp / llama-server 백엔드
│   │   ├── mod.rs
│   │   ├── backend.rs     # LlamaCppBackend 구현
│   │   ├── model_parser.rs # 하이브리드 응답 형식 파싱
│   │   └── props.rs       # 도구 호출 감지를 위한 /props 엔드포인트
│   ├── continuum_router/  # Continuum Router / Backend.AI GO 백엔드
│   │   ├── mod.rs
│   │   └── backend.rs     # ContinuumRouterBackend 구현
│   └── vllm.rs         # vLLM/SGLang/Ollama/LM Studio 백엔드 구현
├── common/             # 공유 인프라 유틸리티
│   ├── mod.rs
│   ├── executor.rs     # 재시도/메트릭이 있는 요청 실행
│   ├── headers.rs      # HTTP 헤더 유틸리티
│   ├── http_client.rs  # 풀링이 있는 HTTP 클라이언트 팩토리
│   ├── statistics.rs   # 백엔드 통계 수집
│   └── url_validator.rs # URL 검증 및 보안
├── transport/          # 전송 추상화 레이어
│   ├── mod.rs          # Transport 열거형 (HTTP, UnixSocket)
│   └── unix_socket.rs  # Unix Domain Socket 클라이언트
├── auth/               # OAuth 2.0 디바이스 인가 그랜트 (RFC 8628)
│   ├── mod.rs
│   ├── device_flow.rs  # 표준 RFC 8628 디바이스 플로우 클라이언트
│   ├── openai_codex_flow.rs # OpenAI Codex 헤드리스 디바이스 코드 플로우 (PKCE 포함)
│   ├── strategy.rs     # AsyncAuthStrategy 트레이트 + OAuthAuthStrategy (proactive refresh)
│   ├── token_store.rs  # 0600 권한, 원자적 쓰기, ~ 확장
│   ├── registry.rs     # 백엔드 이름 키 기반 AuthStrategyRegistry
│   └── error.rs        # 공유 AuthError 타입
├── cache/              # 캐싱 구현
│   ├── mod.rs
│   ├── lru_cache.rs    # LRU 캐시 구현
│   └── retry_cache.rs  # 재시도 인식 캐시
├── config/             # 설정 관리
│   ├── mod.rs
│   ├── loader.rs       # 설정 로딩
│   ├── validator.rs    # 설정 검증
│   ├── timeout_validator.rs # 타임아웃 설정 검증
│   ├── watcher.rs      # 핫 리로드를 위한 파일 감시
│   ├── migrator.rs     # 설정 마이그레이션 오케스트레이터
│   ├── migration.rs    # 마이그레이션 타입 및 트레이트
│   ├── migrations.rs   # 특정 마이그레이션 구현
│   ├── fixer.rs        # 자동 수정 로직
│   ├── backup.rs       # 백업 관리
│   └── secrets.rs      # 시크릿/API 키 관리
└── lock_optimization.rs # 락 및 동시성 최적화

4. Core Layer (src/core/)¶

책임: 도메인 모델, 비즈니스 규칙, 기본 추상화 정의

구성 요소¶

• Models (models/): 핵심 도메인 엔티티 (Backend, Model, Request, Response)
• Traits (traits.rs): 핵심 인터페이스 및 계약
• Errors (errors.rs): 도메인 특화 오류 타입 및 처리
• Retry (retry/): 재시도 정책 및 전략
• Scoring (scoring.rs): 백엔드 선택 스코어링 파이프라인 (BackendScorer)

주요 파일¶

src/core/
├── mod.rs              # 코어 내보내기 및 유틸리티
├── models/             # 도메인 모델
│   ├── mod.rs
│   ├── backend.rs      # 백엔드 도메인 모델
│   ├── model.rs        # LLM 모델 표현
│   ├── request.rs      # 요청 모델
│   └── responses.rs    # 응답 모델 (Responses API)
├── traits.rs           # 핵심 트레이트 및 인터페이스
├── errors.rs           # 오류 타입 및 처리
├── container.rs        # 미사용 레거시 (런타임에 배선되지 않음)
├── async_utils.rs      # 비동기 유틸리티 함수
├── duration_utils.rs   # Duration 파싱 유틸리티
├── streaming/          # 스트리밍 모델
│   ├── mod.rs
│   └── models.rs       # 스트리밍 특화 모델
├── retry/              # 재시도 메커니즘
│   ├── mod.rs
│   ├── policy.rs       # 재시도 정책
│   └── strategy.rs     # 재시도 전략
├── circuit_breaker/    # 서킷 브레이커 패턴
│   ├── mod.rs          # 모듈 내보내기
│   ├── config.rs       # 설정 모델
│   ├── state.rs        # 상태 머신 및 브레이커 로직
│   ├── error.rs        # 서킷 브레이커 오류
│   ├── metrics.rs      # Prometheus 메트릭
│   └── tests.rs        # 단위 테스트
├── files/              # 파일 처리 유틸리티
│   ├── mod.rs          # 모듈 내보내기
│   ├── resolver.rs     # 채팅 요청에서 파일 참조 해석
│   ├── transformer.rs  # 파일 콘텐츠가 있는 메시지 변환
│   └── transformer_utils.rs # 변환 유틸리티 함수
├── tool_calling/       # 도구 호출 변환
│   ├── mod.rs          # 모듈 내보내기
│   ├── definitions.rs  # 도구/함수 타입 정의
│   └── transform.rs    # 백엔드별 변환
└── config/             # 설정 모델
    ├── mod.rs
    ├── models/            # 설정 데이터 모델 (모듈화 구조)
    │   ├── mod.rs         # 공개 모듈 재내보내기
    │   ├── config.rs      # 메인 Config 구조체, ServerConfig, BackendConfig
    │   ├── backend_type.rs # BackendType 열거형 정의
    │   ├── model_metadata.rs # ModelMetadata, PricingInfo, CapabilityInfo
    │   ├── global_prompts.rs # GlobalPrompts 설정
    │   ├── samples.rs     # 샘플 생성 설정
    │   ├── validation.rs  # 설정 검증 로직
    │   └── error.rs       # 설정 특화 오류
    ├── timeout_models.rs # 타임아웃 설정 모델
    ├── cached_timeout.rs # 캐시된 타임아웃 해석
    ├── optimized_retry.rs # 최적화된 재시도 설정
    ├── metrics.rs      # 메트릭 설정
    └── rate_limit.rs   # 속도 제한 설정

라이브러리 진입점 (src/server/)¶

역할: ContinuumRouter 빌더 API를 통해 Continuum Router를 임베딩 가능한 Rust 라이브러리 크레이트로 노출

src/server/ 모듈은 모든 초기화 로직을 바이너리 진입점(main.rs)에서 분리하여, 하위 Rust 프로젝트에서 서브프로세스를 생성하지 않고 라우터를 직접 임베딩할 수 있게 합니다. 바이너리 main.rs는 이 모듈에 위임하는 씬 CLI 래퍼(약 220줄)가 됩니다.

주요 파일:

src/server/
├── mod.rs      # ContinuumRouter 구조체, 플루언트 API를 가진 ContinuumRouterBuilder
├── init.rs     # 개별 서비스 초기화 함수 (HTTP 클라이언트, 헬스 체커,
│               # 서킷 브레이커, 파일 서비스, API 키 스토어, 속도 제한)
├── state.rs    # initialize_services() - 모든 서비스를 AppState로 조합
├── routes.rs   # API, 관리자, 파일, WebUI, 메트릭, CORS용 라우트 빌더
└── serve.rs    # 서버 라이프사이클: 리스너 바인딩, 핫 리로드, 그레이스풀 셧다운

빌더 API:

use continuum_router::{ContinuumRouter, Config};

// 설정 파일에서 (핫 리로드 활성화)
let router = ContinuumRouter::from_config_file("config.yaml")
    .await?
    .enable_hot_reload(true)
    .build()
    .await?;
router.serve("0.0.0.0:8080").await?;

// 프로그래밍 방식 Config 구조체에서 (파일 의존성 없음)
let router = ContinuumRouter::from_config(Config::default())
    .enable_health_checks(false)
    .with_config_dir("/etc/continuum")
    .build()
    .await?;

// 기존 Axum 애플리케이션에 임베딩
let app = axum::Router::new()
    .nest("/llm", router.into_router());

자세한 사용법은 라이브러리 사용법 가이드를 참조하세요.

핵심 컴포넌트¶

백엔드 풀¶

위치: src/infrastructure/backends/pool/ (backend_pool.rs + lifecycle.rs)

목적: 백엔드 멤버십, 선택, 라이프사이클에 대한 단일 진실 공급원입니다. 이 풀은 Arc<dyn Backend> 실행 객체를 보유하고 헬스 상태를 고려한 선택(라운드 로빈 / 가중치 / 최소 지연 시간 / 일관 해시 / 프리픽스 인식, 인플라이트 카운팅과 백엔드별 통계를 포함한 조합 가능한 스코어러 파이프라인)을 실행하며 그레이스풀 드레인과 핫 리로드 라이프사이클을 관리합니다.

모든 라이브 HTTP 요청 경로(채팅 컴플리션, 스트리밍 채팅, Responses, Anthropic Messages와 count_tokens, 이미지 생성)는 최종 백엔드 선택을 이 풀을 통해 수행합니다:

• 후보 필터링 및 스코어러 파이프라인: 각 경로는 먼저 자체 후보 집합(모델 조회, 내부 백엔드 필터, 키별 허용 목록, 재시도 상태 제외)을 해석하고 사전 필터링한 뒤, 공유 선택 지점(proxy::selection::select_pooled_backend)으로 전달합니다. 이 지점은 헬스 상태로 후보를 걸러내고 BackendPool::select_from_candidates를 호출하므로, 후보 목록의 순서가 아니라 설정된 selection_strategy와 등록된 스코어러(예: prefix_routing.enabled와 KV 인덱스가 활성화된 경우의 KvOverlapScorer)가 트래픽 분산을 결정합니다.
• 일관 해시 링 캐시: 참여 백엔드 이름 벡터(순서 포함)를 키로 사용하는 크기 제한 LRU 캐시이므로, 모델별 후보 부분집합이 번갈아 사용되어도 각 링을 무제한 증가 없이 재사용합니다. 각 선택 호출은 링 순회 전에 Arc 스냅샷을 복제하므로 캐시 잠금을 유지하지 않습니다.
• 타입 안전한 라우팅 가시성(proxy::selection::UserRoutableCandidates): 후보 목록은 단순 Vec<String>이 아니라 UserRoutableCandidates 타입으로 전달됩니다.
  • 사용자 라우팅 가시성 필터는 키별 허용 목록보다 먼저 실행되어야 internal: true 또는 enabled: false 백엔드만 서빙하는 모델이 잘못된 403 대신 모델 없음(404)으로 보고됩니다.
  • 일반 생성자는 filter_user_routing_candidates(이름 목록)와 filter_user_routing_backends(BackendConfig 항목)뿐이며, 나머지 메서드는 모두 집합을 좁히기만 하므로 필터를 빠뜨린 디스패치 경로는 컴파일 시점에 차단됩니다.
  • 필터를 거치지 않는 유일한 생성자는 UserRoutableCandidates::bypass_for_management이며(현재 호출자 없음), 숨김 백엔드를 정당하게 다루는 내부 소비자(관리 프로브, 헬스 모니터링, 관리자 카탈로그, 허브 인벤토리, 모델 디스커버리)는 이 선택 지점을 거치지 않고 백엔드를 직접 해석합니다.

pub struct BackendPool {
    backends: Arc<RwLock<Vec<Arc<dyn Backend>>>>,
    counter: Arc<AtomicUsize>,
    selection_strategy: SelectionStrategy,
    stats: Arc<RwLock<HashMap<String, BackendStats>>>,
    scorers: Arc<RwLock<Vec<Arc<dyn BackendScorer>>>>,
    // 라이프사이클 사이드 테이블(백엔드 이름을 키로 사용), lifecycle.rs 참조:
    backend_states: Arc<RwLock<HashMap<String, BackendState>>>, // Active/Draining/Removed
    draining: Arc<RwLock<Vec<DrainingEntry>>>,                  // + 드레인 타임스탬프
    // ... 해시 링 캐시, 엡실론, 스코어러 임계값 ...
}

impl BackendPool {
    // 라이브 백엔드에 대한 헬스/스코어러 인식 선택.
    pub async fn select_backend(&self, model: Option<&str>) -> CoreResult<Arc<dyn Backend>> { /* ... */ }

    // 모든 라이브 HTTP 경로에서 사용하는 후보 제한 선택:
    // 호출자가 사전 필터링한 후보 이름과 풀 멤버십을 이름만으로 교집합하고
    // (순서 유지), 정확히 그 부분집합에 스코어러 파이프라인과 설정된 전략을 실행합니다.
    pub async fn select_from_candidates(
        &self,
        candidates: &[String],
        model: Option<&str>,
        context: &ScoringContext,
    ) -> CoreResult<Arc<dyn Backend>> { /* ... */ }

    // 그레이스풀 드레인(로테이션에서 제외하고 인플라이트 요청은 완료) + 정리.
    pub async fn drain_backend(&self, name: &str) -> Option<Arc<dyn Backend>> { /* ... */ }
    pub async fn cleanup_draining(&self) -> usize { /* ... */ }

    // 제자리 핫 리로드: 새 설정에서 백엔드를 추가/드레인/재생성합니다.
    pub async fn update_from_config(&self, configs: &[BackendConfig], factory: &BackendFactory) { /* ... */ }
}

변경 가능한 라이프사이클 상태는 풀의 기존 이름 기반 stats 맵과 마찬가지로 백엔드 이름을 키로 사용하는 사이드 테이블(backend_states, draining)에 저장되므로, 핫 선택 경로는 단순한 Vec<Arc<dyn Backend>> 레이아웃을 유지합니다. AppState는 정확히 하나의 backend_pool을 보유하며 프록시/패스스루 계층은 선택 경계에서 선택된 Arc<dyn Backend>를 경량 PooledBackend { name, url } 핸들로 투영합니다.

이 풀은 백엔드별 엔진 통계 저장소(src/infrastructure/backends/engine_stats/)도 소유합니다. 항상 컴파일되는 이 모듈은 백그라운드 폴러가 각 자체 호스팅 엔진 자체의 부하 또는 메트릭 엔드포인트(vLLM /metrics, SGLang /v1/loads, llama.cpp /slots·/metrics, Ollama /api/ps, LM Studio /api/v0/models)를 읽어 백엔드당 하나의 EngineStatsSnapshot으로 정규화하고 인플라이트 트래커 옆에 TTL로 유지합니다. Prometheus 스크레이프 갱신(backend_engine_*{backend} 패밀리), GET /admin/backends/{name}/engine-stats, WebUI 대시보드 카드, Backend::get_current_load()(풀이 add_backend에서 붙이는 EngineLoadProbe 핸들 경유), KV 오버랩 스코어러의 엔진 부하 항과 선택 지점의 포화 어드미션 힌트(둘 다 routing.engine_load로 게이트)가 모두 이 저장소 하나를 읽습니다. 자세한 내용은 engine_stats/snapshot.rs의 모듈 문서와 docs/ko/metrics.md의 엔진 통계 메트릭 절을 참고하세요.

헬스 체커¶

위치: src/health.rs → src/services/health_service.rs

목적: 설정 가능한 임계값, 자동 복구, 가속화된 워밍업 감지로 백엔드 헬스 모니터링

pub struct HealthChecker {
    backends: Arc<RwLock<Vec<Backend>>>,
    config: HealthConfig,
    status_map: Arc<RwLock<HashMap<String, HealthStatus>>>,
}

pub struct HealthConfig {
    pub interval: Duration,
    pub timeout: Duration,
    pub unhealthy_threshold: u32,     // 비정상으로 표시하기 전 실패 횟수
    pub healthy_threshold: u32,       // 정상으로 표시하기 전 성공 횟수
    pub warmup_check_interval: Duration, // 워밍업 중 가속화된 간격 (기본값: 1초)
    pub max_warmup_duration: Duration,   // 워밍업 모드 최대 시간 (기본값: 300초)
}

pub enum HealthStatus {
    Healthy,      // 백엔드가 HTTP 200으로 응답
    Unhealthy,    // 연결 실패 또는 오류
    WarmingUp,    // HTTP 503 - 백엔드 로딩 중 (가속화된 체크)
    Unknown,      // 초기 상태
}

가속화된 워밍업 헬스 체크¶

백엔드가 HTTP 503 (Service Unavailable)을 반환하면 WarmingUp 상태로 진입합니다. 이 상태에서는:

• 헬스 체크가 일반 간격 대신 warmup_check_interval (기본값: 1초)로 실행됩니다
• 모델 가용성 감지 시간이 ~30초에서 ~1초로 단축됩니다
• max_warmup_duration 이후에는 백엔드가 Unhealthy로 표시됩니다
• 모델 로딩 중 HTTP 503을 반환하는 llama.cpp 백엔드에 특히 유용합니다

Transport 레이어¶

위치: src/infrastructure/transport/

목적: HTTP/HTTPS 또는 Unix Domain Socket을 통한 백엔드 통신을 위한 통합 전송 추상화 제공

Transport 레이어는 TCP 포트 노출 없이 Unix 소켓을 통한 안전한 로컬 LLM 통신을 가능하게 합니다.

URL 스킴¶

Transport 열거형¶

pub enum Transport {
    Http { url: String },
    UnixSocket { socket_path: PathBuf },
}

impl Transport {
    pub fn from_url(url: &str) -> Result<Self, TransportError>;
    pub fn is_unix_socket(&self) -> bool;
    pub fn is_http(&self) -> bool;
}

Unix Socket 클라이언트¶

UnixSocketClient는 HTTP-over-Unix-socket 통신을 제공합니다:

pub struct UnixSocketClient {
    socket_path: PathBuf,
    config: UnixSocketClientConfig,
}

impl UnixSocketClient {
    pub async fn get(&self, endpoint: &str, headers: Option<Vec<(String, String)>>)
        -> Result<UnixSocketResponse, UnixSocketError>;
    pub async fn post(&self, endpoint: &str, headers: Option<Vec<(String, String)>>, body: Bytes)
        -> Result<UnixSocketResponse, UnixSocketError>;
    pub async fn health_check(&self) -> Result<bool, UnixSocketError>;
}

보안 기능¶

• 경로 순회 보호: 디렉토리 순회 공격을 방지하기 위한 소켓 경로 검증
• CRLF 인젝션 보호: HTTP 헤더 인젝션을 위한 엔드포인트 및 헤더 검증
• 응답 크기 제한: 설정 가능한 최대 응답 크기 (기본값: 100MB)

플랫폼 지원¶

모델 집계 서비스¶

위치: src/models/ (모듈화 구조)

목적: 모든 백엔드에서 모델 정보를 집계하고 캐시하며 메타데이터로 보강하고 캐시 스탬피드 방지

모듈 구조:

src/models/
├── mod.rs             # 공개 모듈 재내보내기
├── types.rs           # Model, AggregatedModel, ModelList, SingleModelResponse 타입
├── metrics.rs         # ModelMetrics 추적 (스탬피드 메트릭 포함)
├── cache.rs           # stale-while-revalidate 및 singleflight를 갖춘 ModelCache
├── config.rs          # ModelAggregationConfig
├── fetcher.rs         # 백엔드에서 모델 가져오기
├── handlers.rs        # /v1/models 및 /v1/models/{model} 엔드포인트용 HTTP 핸들러
├── background_refresh.rs  # 백그라운드 주기적 캐시 갱신 서비스
├── pattern_matching.rs    # 6단계 모델 ID 조회 파이프라인 (날짜 / 형식 접미사 정규화, HuggingFace 리포지토리 접두사 제거, 와일드카드)
├── utils.rs           # 유틸리티 함수 (normalize_model_id 등)
└── aggregation/       # 핵심 집계 로직
    ├── mod.rs         # ModelAggregationService 구현
    └── tests.rs       # 단위 테스트

메타데이터 보강 중 사용되는 모델 ID 결정 파이프라인은 설정 가이드의 메타데이터 우선순위 및 별칭 해석을 참조하세요. 새 매핑을 명시적 YAML 별칭으로 추가할지 peel 허용 목록의 확장이나 HuggingFace 접두사 제거 레이어로 추가할지에 대한 정책 지침은 별칭과 접미사 정규화: 선택 기준을 참조하세요. 접두사 제거 레이어는 접미사 peel과 조합됩니다. 단일 조회에서 vendor/repo 접두사를 제거한 뒤 허용 목록의 접미사 토큰을 peel할 수 있어서 unsloth/Qwen3.6-35B-A3B-GGUF는 수동으로 등록된 별칭 없이 qwen3.6-35b-a3b 메타데이터로 라우팅됩니다.

캐시 스탬피드 방지¶

모델 집계 서비스는 캐시 스탬피드(썬더링 허드 문제)를 방지하기 위해 네 가지 전략을 구현합니다:

1. 싱글플라이트 패턴: 한 번에 하나의 집계 요청만 실행됩니다. 동시 요청은 진행 중인 집계가 완료될 때까지 기다린 후 결과를 공유합니다.

2. Stale-While-Revalidate: 캐시가 오래된 경우(소프트 TTL과 하드 TTL 사이), 백그라운드에서 갱신을 트리거하면서 즉시 오래된 데이터를 반환합니다. 클라이언트는 약간 오래된 데이터로 빠른 응답을 받습니다.

3. 백그라운드 주기적 갱신: 백그라운드 태스크가 만료 전에 사전에 캐시를 갱신합니다. 요청은 콜드 스타트를 제외하고 캐시 갱신을 기다리지 않습니다.

4. 대체 스탬프(Supersession Stamps): 모든 집계는 풀을 스냅샷하기 직전에 풀의 membership_generation과 캐시의 invalidation_epoch을 기록하고 저장 시점에 두 값을 다시 비교합니다.

   • 만료 상태 저장: 팬아웃이 실행되는 동안 스탬프가 바뀐 결과(핫 리로드, Admin API, AppProxy가 백엔드를 추가·제거·드레인한 경우, 또는 멤버십 변경 없이 clear_cache()를 호출한 설정 변경)는 Fresh가 아니라 이미 만료된 항목으로 저장됩니다. 덕분에 stale-serve 범위 안의 읽기는 이전 목록을 계속 제공받고 후속 갱신은 즉시 시작됩니다(백그라운드 재검증은 최대 3회까지 제자리에서 재집계하고, 요청 경로는 백그라운드 재검증 태스크를 하나 띄웁니다).
   • 스냅샷 이전 읽기 및 사후 검증: 스탬프는 경쟁 조건을 막기 위해 반드시 풀 스냅샷 이전에 읽습니다. 멤버십 비교는 삽입 잠금과 하나로 묶여 있지 않으므로, 저장 직후 세대를 다시 읽어 변경되었으면 항목을 즉시 만료시킵니다. 핫 리로드는 헬스 체크 왕복보다 먼저 캐시를 무효화하여 두 스탬프를 연달아 올리므로 진행 중인 팬아웃에 단일 이벤트로 도달합니다.
   • 잠금 해제 백오프 및 재가동 간격: 제자리 재시도는 패스 사이에 집계 잠금을 풀고 지터가 섞인 백오프를 두므로 대기 중인 POST /v1/models/refresh가 체인 전체를 기다리지 않습니다. 모든 패스가 대체된 체인은 항목을 만료 상태로 남기고 다음 재검증을 2초 동안 유예하며, 어느 경로에서든 Fresh 저장이 성공하면 이 유예 간격은 즉시 해제됩니다.

pub struct ModelAggregationService {
    cache: ModelCache,  // 싱글플라이트 잠금 및 백그라운드 갱신 추적 포함
    config: ModelAggregationConfig,
    fetcher: ModelFetcher,
}

impl ModelAggregationService {
    // 싱글플라이트 보호가 있는 모델 집계
    pub async fn aggregate_models_with_singleflight(&self, state: &Arc<AppState>)
        -> Result<AggregatedModelsResponse, StatusCode> { /* ... */ }

    // stale-while-revalidate 지원이 있는 백엔드 찾기
    pub async fn find_backends_for_model(&self, state: &Arc<AppState>, model_id: &str)
        -> Vec<String> { /* ... */ }

    // 캐시 지우기 (핫 리로드 시 사용)
    pub fn clear_cache(&self) { /* ... */ }
}

캐시 TTL 설정¶

캐시는 듀얼 TTL 방식을 사용합니다:

메트릭¶

캐시 스탬피드 모니터링을 위한 새 메트릭:

• stale_while_revalidate: 갱신 중 오래된 데이터를 반환한 요청
• coalesced_requests: 진행 중인 집계를 기다린 요청
• background_refreshes: 시작된 백그라운드 갱신 작업
• background_refresh_successes/failures: 백그라운드 갱신 결과
• singleflight_lock_acquired: 집계 잠금이 획득된 횟수

프록시 모듈¶

위치: src/proxy/ (모듈화 구조)

목적: 요청 프록시, 백엔드 선택, 파일 해석, 이미지 생성/편집 처리

모듈 구조:

src/proxy/
├── mod.rs             # 공개 모듈 재내보내기
├── backend.rs         # 백엔드 선택 및 라우팅 로직
├── request.rs         # 재시도 로직이 있는 요청 실행
├── files.rs           # 요청에서 파일 참조 해석
├── image_gen.rs       # 이미지 생성 처리 (DALL-E, Gemini, GPT Image)
├── image_edit.rs      # 이미지 편집 지원 (/v1/images/edits)
├── image_utils.rs     # 이미지 처리 유틸리티 (멀티파트, 검증)
├── handlers.rs        # 프록시 엔드포인트용 HTTP 핸들러
├── utils.rs           # 유틸리티 함수 (오류 응답 등)
└── tests.rs           # 단위 테스트

주요 책임¶

• 백엔드 선택: 사용 가능한 백엔드로 지능형 라우팅
• 파일 해석: 채팅 요청에서 파일 참조 해석
• 이미지 생성: OpenAI (DALL-E, GPT Image) 및 Gemini (Nano Banana) 이미지 모델 지원
• 이미지 편집: 이미지 편집 및 변형 엔드포인트
• 요청 재시도: 지수 백오프가 있는 자동 재시도
• 오류 처리: OpenAI 형식의 표준화된 오류 응답
• 내부 스트리밍: 조건을 만족하는 버퍼링 chat 및 completions 요청을 백엔드에서 스트리밍으로 받아 클라이언트 취소를 계량(proxy.internal_streaming)

버퍼링 요청의 내부 스트리밍¶

proxy.internal_streaming(src/proxy/internal_streaming.rs와 internal_streaming_read.rs)은 make_http_request 안에서 모든 페이로드 변환을 마친 뒤, 조건을 만족하는 버퍼링 디스패치를 업스트림에는 stream: true와 공용 apply_router_stream_options가 생성한 stream_options(include_usage: true, vllm 백엔드에는 continuous_usage_stats: true 추가, 클라이언트가 보낸 stream_options는 제거)로 전송합니다.

• 적용 범위 및 적격 조건:
  • 대상 라우트: chat completions와 completions 핸들러가 정책 적용 이후 작업을 태스크 로컬 범위(client_route) 안에서 실행하므로, 재시도, 폴백 홉, 중복 제거, 웹 검색 턴, 품질 홉, 분리형 서빙 및 shim 디스패치가 모두 대상이 됩니다. 반면 /v1/decisions 에뮬레이션 홉, Anthropic Messages와 Responses 인그레스, 임베딩, 리랭크, 이미지, 파일, 합성 프로브, 라우터 자체 호출은 대상이 아닙니다.
  • 백엔드 및 요청 조건: 백엔드의 유효 플래그가 켜져 있고, 타입이 azure가 아닌 OpenAI 와이어이며, 전송 방식이 HTTP(S)이고, 요청 형태가 n == 1, 로그 확률 없음, response_format이 text 또는 json_object이며 functions, function_call, audio, 오디오 modalities, web_search_options를 포함하지 않을 때만 활성화됩니다.
• 응답 조립 및 정산: 2xx가 아닌 응답은 읽어서 오류로 분류하고, 2xx application/json 응답은 그대로 전달합니다. 2xx 스트림은 디스패치 타임아웃 아래에서 단일 릴레이 루프가 읽어 표준 모드 SseParser로 파싱한 뒤 StreamUsageFinalizer에 전달하고, services::streaming::assemble(스트리밍 캐시 재생과 공유)이 버퍼링 본문으로 조립합니다(tests/stream_early_exit_audit_test.rs가 단일 종료 경로를 검증).
  • 출력 생성 전 실패: 데이터 이벤트 없음, 오류 이벤트, 역할만 담은 청크 뒤의 전송 오류나 타임아웃, 또는 [DONE]과 finish_reason 없이 잘린 본문은 여기서 기록하지 않고 일반 버퍼링 읽기와 동일하게 재시도합니다(출력은 라우터 델타 수, 엔진 완성 토큰 수, 또는 role 외에 비어 있지 않은 채팅 델타 필드로 판별하므로 모델 거부 응답도 출력으로 인정되어 재시도를 막습니다).
  • 완료된 스트림: 확정된 사용량을 시도별 키로 요청 원장에 남기고, 해당 시도를 기록하는 버퍼링 행(응답 행, 대체된 웹 검색 턴, 품질 홉)이 이를 가져갑니다. 토큰 수, 결과(엔진 사용량이 없으면 usage_missing), 토큰 출처는 스트림에서 가져오고 TTFT는 응답 헤더 관측값으로, stream은 false로 기록합니다.
  • 출력 생성 후 실패: [DONE]이나 finish_reason 없이 끊긴 본문을 포함해 출력 이후 발생한 실패는 확정된 부분 사용량(partial)을 담은 BackendRequestFailure를 반환합니다. 재시도 지점은 이를 upstream_error 또는 timeout_mid_stream으로 기록하고 replay: disabled와 동일하게 최종 실패(TriggerReason::PartialOutput)로 처리하여 재시도 루프, 폴백 체인, 분리형 서빙 폴백이 재전송하지 않도록 막습니다.
  • 클라이언트 연결 종료: 첫 이벤트 이후 클라이언트가 연결을 끊어 핸들러 퓨처가 드롭되면 Drop에서 동기적으로 client_cancelled 시도 하나를 기록하고 업스트림 본문을 즉시 닫습니다. 서킷 브레이커는 조립된 본문에는 settle_success, 실패에는 settle_error를 기록합니다.

재시도 핸들러¶

위치: src/services/deduplication.rs

목적: 지터가 있는 지수 백오프 및 요청 중복 제거 구현

EnhancedRetryHandler는 코어 재시도 엔진(src/core/retry/strategy.rs)과 DeduplicationManager를 조합합니다. 설정은 공개 문자열 기간 RetryConfig(max_attempts, initial_delay, max_delay, backoff_multiplier, jitter, 재시도 가능 상태/오류 목록, 전체 timeout)를 사용합니다.

백엔드별 재전송 정책과 시도 추적¶

• 재전송 정책(backends[].replay): 모든 재시도 시도가 거치는 단일 지점인 src/proxy/request.rs의 execute_single_retry_attempt_observed에서 적용됩니다.
  • replay: disabled 백엔드로의 디스패치가 실패했고 미전송임이 증명되지 않으면(BackendRequestFailure::not_sent는 연결 실패나 전송 전 라우터 측 거절에만 설정됨) 재시도 루프가 즉시 종료되고, 요청 단위 차단 플래그가 폴백 체인 트리거를 TriggerReason::ReplayDisabled로 고정해 추가 홉을 막습니다.
  • 스트리밍 연결 단계, mid-stream 릴레이, 프로바이더 인그레스 체인(src/http/ingress_fallback.rs::seal_replay_barrier), 품질 홉 드라이버, 분리형 서빙 통합 폴백도 모두 동일한 규칙을 따르며, replay: disabled 백엔드가 후보에 포함된 요청은 중복 제거(deduplication)를 건너뜁니다. (RetryState::backend_attempted는 사용 중단되었으며 선택 과정에서 참조하지 않습니다.)
• 시도(Attempt) 수명주기:
  • 백엔드 선택, 홉 다이얼 제한, 서킷 승인이 모두 성공한 뒤 요청이 나가기 직전에 요청 원장에 시도를 등록합니다(src/services/stats/request_ledger_attempts.rs의 begin_attempt). 따라서 디스패치 이전 거절은 시도로 집계되지 않습니다.
  • 각 시도는 클라이언트 요청의 다음 attempt_seq를 할당받고 직전 시도를 parent_attempt로 가리킵니다.
  • 실패 시에는 재시도 대기나 체인 홉보다 먼저 record_attempt_usage(src/services/stats/attempts.rs)가 실패한 시도를 즉시 기록합니다(업스트림 상태는 BackendRequestFailure::upstream_status에서, 토큰은 사용량이 포함된 오류 본문에서 추출).
  • 최종 응답 시도는 요청 단위 기록기가 요청 원장의 현재 시도로 기록합니다. connect_with_pre_stream_fallback의 스트림 전 다이얼, Anthropic 웹 검색 호출기, 웹 검색 루프의 대체된 턴 훅도 동일한 인터페이스를 사용합니다.

요청 중복 제거 (In-Flight Coalescing)¶

replay: disabled 백엔드가 처리할 수 없고 may_coalesce(src/services/deduplication/eligibility.rs)가 허용하는 10KB 미만의 비스트리밍 POST 요청은 execute_with_deduplication_attributed를 통해 설정 스냅샷, 엔드포인트, 디스패치 본문, 인바운드 헤더 허용 목록, 유효 백엔드 허용 목록을 키로 삼아 하나로 합쳐집니다.

• 엔드포인트 및 요청 적격성(may_coalesce):
  • /v1/chat/completions와 /v1/completions는 요청 본문에 temperature: 0이 명시된 경우에만 합칩니다(OpenAI 기본값이 1이므로 생략된 temperature는 합치지 않으며, 응답 캐시의 규칙과는 독립적입니다). 적격성 판단은 디스패치 전에 수행되므로 백엔드별 request_extensions.body.overrides.temperature는 영향을 주지 않습니다.
  • 결정론적 엔드포인트인 /v1/embeddings, /v1/rerank, /embed_sparse, /v1/models는 항상 허용하며, /v1/images/generations와 그 밖의 엔드포인트는 제외됩니다.
  • /v1/decisions 에뮬레이션 홉은 temperature: 0을 보내므로 대상이 되지만, 웹 검색 도구 루프와 답변 품질 폴백은 턴이나 홉마다 개별 시도를 기록해야 하므로 without_coalescing 범위 안에서 실행됩니다.
• 리더 선출, 대기자 수명주기, 타임아웃 예산:
  • 동일한 키로 처음 승인된 요청이 단일 DashMap::entry 연산(DeduplicationManager::admit)을 통해 리더가 되어 진행 중 마커를 소유합니다.
  • 마커가 유지되는 동안 도착한 동일 요청은 대기자(src/services/deduplication/waiters.rs)로서 마커의 tokio::sync::watch 채널을 구독하며, 리더가 완료되면 성공 응답뿐 아니라 503이나 Retry-After가 포함된 429 오류까지 그대로 공유받습니다.
  • 리더는 완료 시 마커를 먼저 제거한 뒤 채널에 결과를 게시하므로, 이후 도착하는 요청은 완료된 결과를 재사용하지 않고 새 리더로 실행됩니다(완료된 응답의 재사용은 응답 캐시가 담당).
  • 대기 시간과 마커 수명은 리더의 최대 실행 예산(시도당 전체 타임아웃 + max_retry_timeout으로 제한된 retry.timeout + 폴백 홉의 경우 timeouts.connection 다이얼 대기 시간)으로 제한되며, 예산 소진 시 대기자는 408 timeout을 받습니다.
  • 리더가 완료 전에 드롭(클라이언트 연결 종료)되면 드롭 가드가 마커를 제거하고 채널을 닫아 대기자 중 하나가 새 리더로 승격되며, 두 번째 리더마저 드롭되면 남은 대기자는 중복 제거 없이 각자 재시도 루프를 실행합니다.
• 대기자 통계 및 사용량 집계(src/services/stats/coalesced.rs):
  • 중복 제거 지점이 요청 원장에 note_coalesced_result를 표시하면, 공용 통계 탭은 대기자 요청을 백엔드 미전송(not_dispatched), attempt_seq: 0(허브 매핑 시 최소 1로 보정하고 parent_attempt 제거), 프롬프트 토큰은 리더의 값, 출력 토큰은 0으로 기록합니다.
  • 또한 로컬 캐시 재생과 동일한 사용량 내보내기 레코드(cache_hit_type: exact)와 컨트롤 플레인 record_local_cache_hit 이벤트(토큰 윈도우 및 예산 미차감)를 방출합니다. 미들웨어의 요청 수 기반 속도 제한(RPM)은 대기자에게도 정상 적용됩니다.
• 중복 제거 키 헤더 허용 목록(src/services/deduplication/key_headers.rs):
  • 키 해시는 닫힌 허용 목록에 포함된 헤더만 대소문자 구분 없이 정규화하여 반영합니다: 자격 증명 헤더(is_credential_header: authorization, x-api-key, x-goog-api-key 등), 프로바이더 동작 변경 헤더(anthropic-version, anthropic-beta, openai-organization, openai-project, openai-beta, x-vllm-priority), 라우터 제어 헤더(x-backend, x-continuum-router-hops, x-smart-route-bypass, 허브 x-continuum-substitution/-arbitrage/-budget-fallback/-compression/-batch), 라우터가 기록한 Dynamo shim 워커 고정 헤더(x-dynamo-prefill-instance-id, x-dynamo-prefill-dp-rank, x-dynamo-worker-instance-id, x-dynamo-dp-rank), 활성 설정의 smart_routing.routing_policies[].when.header 및 model_experiments[].sticky_key: header:<name> 헤더.
  • X-Trace-ID, traceparent, x-request-id, user-agent, x-stainless-* 등 그 밖의 모든 헤더는 무시됩니다. 같은 API 키를 공유하는 호출자(또는 무인증 라우터의 모든 호출자)가 동일한 적격 요청을 동시에 보내면 결과를 공유하므로, 격리가 필요하면 별도의 API 키를 발급해야 합니다.

pub struct EnhancedRetryHandler {
    pub retry_handler: RetryHandler,
    deduplication: DeduplicationManager,
    enable_deduplication: bool,
}

서킷 브레이커¶

위치: src/core/circuit_breaker/

목적: 백엔드별 독립 3상태 서킷 브레이커 상태 머신 유지

pub struct CircuitBreaker {
    states: Arc<DashMap<String, BackendCircuitState>>,
    config: CircuitBreakerConfig,
    metrics: Option<CircuitBreakerMetrics>,
}

pub struct CircuitBreakerConfig {
    pub enabled: bool,
    pub failure_threshold: u32,           // 열리기 전 실패 횟수 (기본값: 5)
    pub failure_rate_threshold: f64,      // 실패율 임계값 (기본값: 0.5)
    pub minimum_requests: u32,            // 비율 계산 전 최소 요청 수
    pub timeout: Duration,                // 열린 상태 대기 시간 (기본값: 60초)
    pub half_open_max_requests: u32,      // half-open 상태에서 최대 요청 수
    pub half_open_success_threshold: u32, // 닫히는 데 필요한 성공 횟수
}

pub enum CircuitState {
    Closed,    // 정상 작동 - 요청 통과
    Open,      // 빠른 실패 - 요청 즉시 거부
    HalfOpen,  // 복구 테스트 - 제한된 요청 허용
}

주요 기능¶

• 독립적인 상태를 가진 백엔드별 서킷 브레이커
• 핫 패스에서 락 프리 상태 확인을 위한 원자적 연산
• 성공/실패 패턴에 기반한 자동 상태 전환
• 실패율 계산을 위한 슬라이딩 윈도우
• 메인 메트릭 레지스트리에 등록되어 프록시 경로가 값을 채우는 메트릭 수집기
• 조회 및 수동 제어를 위한 Admin 엔드포인트

표준 LLM 프록시 경로는 후보를 선택하는 동안과 요청을 보내기 직전에 브레이커를 조회하고 백엔드 결과를 기록합니다. 열린 서킷은 일반 추론 트래픽에서 제외되고, half-open 상태의 프로브는 용량이 제한되며, 기본 메트릭 레지스트리가 브레이커 카운터를 그대로 노출합니다. 능동 상태 필터, 재시도, 폴백은 이를 보완하는 계층입니다.

컨테이너 (배선되지 않은 레거시)¶

위치: src/core/container.rs

Container(src/core/container.rs)는 예전 설계에서 남은 코드로, 런타임에 배선되지 않았습니다. 자기 단위 테스트 안에서만 생성되고 어떤 서비스도 등록하지 않습니다.

라우터는 런타임 DI 컨테이너를 사용하지 않습니다. 서비스는 평범한 생성자 인자로 전달되며, 자세한 내용은 의존성 주입을 참고하세요.

데이터 흐름¶

요청 처리 흐름¶

sequenceDiagram
    participant Client
    participant HTTPLayer as HTTP Layer
    participant ProxyService as Proxy Service
    participant BackendService as Backend Service
    participant ModelService as Model Service
    participant Backend as LLM Backend

    Client->>HTTPLayer: POST /v1/chat/completions
    HTTPLayer->>HTTPLayer: 미들웨어 적용 (인증, 로깅, 메트릭)
    HTTPLayer->>ProxyService: 요청 전달

    ProxyService->>ModelService: 모델 정보 가져오기
    ModelService->>ModelService: 캐시 확인
    alt 캐시 미스
        ModelService->>BackendService: 모델용 백엔드 가져오기
        BackendService->>Backend: 모델 쿼리
        Backend-->>BackendService: 모델 목록
        BackendService-->>ModelService: 필터링된 백엔드
        ModelService->>ModelService: 캐시 업데이트
    end
    ModelService-->>ProxyService: 백엔드에서 모델 사용 가능

    ProxyService->>BackendService: 정상 백엔드 선택
    BackendService->>BackendService: 로드 밸런싱 적용
    BackendService-->>ProxyService: 선택된 백엔드

    ProxyService->>Backend: 요청 전달
    Backend-->>ProxyService: 응답 (스트리밍 또는 비스트리밍)

    ProxyService->>ProxyService: 응답 처리 적용
    ProxyService-->>HTTPLayer: 처리된 응답
    HTTPLayer-->>Client: HTTP 응답

모델 이름 해석과 모델 실험¶

백엔드를 선택하기 전에, 모델을 기준으로 라우팅하는 모든 인그레스는 src/proxy/alias_dispatch.rs의 dispatch_model_for_request라는 단일 지점에서 디스패치할 모델 이름을 해석합니다(이 지점은 클라이언트가 보낸 이름을 기준으로 판단하는 model_aliases, 스마트 라우팅, 요청 파라미터 정책 스냅샷, 키별 모델 게이트 이후에 실행됩니다):

• 실험 변형 배정 및 메타데이터 별칭 해석:
  • 먼저 모델 실험(src/proxy/model_experiments/)을 해석합니다. 클라이언트 모델 이름은 SHA-256 고정 키에 대한 랑데부 해싱으로 가중치가 부여된 변형 하나에 배정되며, 요청은 그 변형의 업스트림 모델로 진행되고 변형의 백엔드 고정이 요청의 백엔드 허용 목록을 좁힙니다.
  • 그다음 그 결과 이름에 대해 메타데이터 별칭 디스패치를 실행합니다.
  • 반환되는 DispatchModel 쌍에는 클라이언트 모델 이름, 디스패치 이름, 실험 배정이 함께 담기므로, 선택 오류와 폴백 귀속은 클라이언트가 보낸 이름을 그대로 표시하고 fallback: within_variant 실험은 모델 간 폴백 체인을 막을 수 있습니다.
• 요청 범위 태스크 로컬 귀속: API 라우트 그룹을 감싸는 model_experiment_middleware가 설치하는 tokio::task_local! 셀을 사용합니다. 디스패치 지점이 배정을 기록하고 응답 캐시 경로 식별자가 이를 exact, prefix, semantic 캐시 네임스페이스에 반영하며, 핸들러가 반환된 뒤 미들웨어가 model_experiment_* 메트릭을 기록하고 선택적 귀속 헤더를 출력하며 response_model: client를 적용합니다.

가드레일 레이어¶

가드레일이 설정되면(guardrails.enabled: true) 콘텐츠 안전 레이어가 추론 요청 경로에서 백엔드 호출을 감쌉니다. 대상은 OpenAI chat completions(업스트림 /v1/responses로 가는 responses_only 브리지 포함), /v1/responses 엔드포인트, 레거시 /v1/completions, 네이티브 Anthropic Messages입니다(라우트별 단계 적용 범위는 가드레일: 라우트별 적용 범위 참조).

• 단일 게이팅 지점, 와이어별 뷰, 입력 마스킹:
  • 서비스 레이어의 GuardrailService(src/services/guardrail/)와 단일 게이팅 지점(src/services/guardrail/gate.rs)을 통해 구동됩니다. 각 와이어(Wire::OpenAi, Wire::Responses, Wire::Completions, Wire::Anthropic)는 전용 요청/응답 뷰(responses_input_view.rs, responses_view.rs, completions_view.rs, anthropic_input_view.rs)와 차단 형태를 가집니다.
  • 입력 마스킹(masking.rs)은 와이어에 독립적입니다: 각 와이어가 검사 가능한 문자열과 JSON 위치를 나열하면, 마스킹 판정을 반환한 프로바이더로 문자열마다 다시 도출해 제자리(도구 호출 arguments는 masking_args.rs에서 토큰 단위)에 덮어쓰고 기한 안에 재검사합니다(적용 불가 시 또는 재검사 프로바이더 실패 시 fail-closed). 범위를 좁힌 단계는 GuardrailService::run_input_pass(service_pass.rs)를 거칩니다.
  • 모든 와이어의 차단은 response::block_into_response가 프로세스 내부 GuardrailBlocked 마커를 붙여 HTTP 응답으로 변환하며, 인그레스 폴백 드라이버와 /v1/decisions 체인(TriggerReason::GuardrailBlocked)은 마커가 붙은 응답을 최종 확정 시도로 취급해 폴백 모델로 넘어가지 않게 막습니다. 가드레일이 비활성화되면 핸들러는 이 지점에 진입하지 않아 오버헤드가 없습니다.
• 락 프리 동적 초기화 (GuardrailServiceHandle):
  • 서비스는 시작 시 고정되는 Option이 아니라 arc-swap 기반 락 프리 슬롯인 GuardrailServiceHandle(src/services/guardrail/handle.rs) 뒤에 놓입니다. 요청 경로는 요청당 한 번 원자적 로드로 핸들을 읽어 모든 게이트에서 재사용합니다.
  • 가드레일이 비활성 상태로 시작한 라우터도 로컬 enabled: true 핫 리로드 시 가드레일 설정 감시자가, 집행 가능한 허브 정책 도착 시 컨트롤 플레인 가드레일 정책 reconciler가 시작 시점과 동일한 팩토리 경로(src/server/state.rs의 guardrail_service_factory, backend: 프로바이더 참조용 백엔드 리졸버 포함)를 통해 서비스를 동적으로 생성합니다.
  • 라우터가 실행할 수 없는 집행을 요구하는 허브 정책은 guardrails_unavailable 코드로 전체 거부되어 컨트롤 플레인 정책 스토어에 기록되며 로컬 설정은 그대로 유지됩니다.

이 레이어는 요청 라이프사이클의 두 지점에 훅합니다:

• 입력 pre-call: 백엔드 디스패치 전에 요청당 한 번 모든 입력 프로바이더를 실행합니다. Block 판정은 백엔드를 호출하지 않고 요청을 중단하며 Transform은 디스패치 전에 프롬프트를 다시 씁니다. OpenAI chat completions에서는 스트리밍과 비스트리밍 경로 모두에 대해 응답 캐시 조회, 전역 프롬프트 주입, 분리형 디스패치보다 먼저 한 번 실행되므로(src/proxy/chat_input_gate.rs), 차단된 스트리밍 요청도 SSE 시작 전에 동일한 차단 응답을 받습니다(GuardrailService::run_input_during_call은 라이브러리 호출자를 위해 유지).
• 출력 post-call: 백엔드가 반환한 후 응답이 전달되거나 캐시되기 전에 생성된 텍스트를 검사합니다. 스트리밍 응답에서는 롤링 윈도우 검사(buffer_full / chunked / passthrough)로 동작합니다.

GuardrailService는 모든 정책(monitor 대 enforce 모드, 우회 허용 목록, 라우트별 프로바이더 부분집합, 카테고리별 임계값, 허용/차단 리스트, 프로바이더별 타임아웃, fail-open/fail-closed 결정)을 소유하며, 설정된 프로바이더(OpenAI Moderation, 자체 호스팅 분류기, PII, AWS Bedrock, Azure Content Safety)의 판정을 가장 심각한 판정 우선 규칙으로 집계하고 모든 결정에 대해 Prometheus 메트릭과 감사 로그를 내보냅니다.

sequenceDiagram
    participant Client
    participant Gate as Guardrail Gate
    participant Service as GuardrailService
    participant Backend as LLM Backend

    Client->>Gate: 요청 (prompt / messages)
    Gate->>Service: 입력 pre-call
    alt Block (enforce)
        Service-->>Client: 차단 응답 (content_filter / refusal / error)
    else Allow or Transform
        Service-->>Gate: 판정
        Gate->>Backend: (변환된) 요청 전달
        Backend-->>Gate: 응답
        Gate->>Service: 출력 post-call
        alt Block (enforce)
            Service-->>Client: 차단 응답
        else Allow or Transform
            Service-->>Client: 응답 (정제될 수 있음)
        end
    end

운영자 대상 가이드(개념, 프로바이더 설정, 설정, 임계값 튜닝, 관리자 제어, 메트릭)는 가드레일을 참고하세요.

Claude Code 세이프가드 레이어¶

운영자가 safeguards.action_safety.enabled: true를 명시적으로 설정하면, 액션 세이프가드 어댑터(src/services/action_safety.rs의 ActionSafetyEvaluator)가 변환 백엔드 응답이 제안한 도구 액션을 클라이언트가 실행하기 전에 평가합니다:

• 도구 액션 추출 및 평가:
  • Anthropic Messages 핸들러와 /v1/responses 변환 계열에서 구동됩니다. tool_use 블록(또는 /v1/responses의 tool_calls)을 제안하는 응답에서 액션을 와이어 순서대로 추출해 고정된 평가기 백엔드로 액션당 한 번 디스패치합니다.
  • 판정 결과는 action_safety::wire가 생성하는 safeguard_results(도구 사용 ID를 키로 하는 dangerous_tool_use 검사, not_flagged/flagged, 그리고 하나라도 indeterminate이면 unavailable 검사)로 첨부되며, 스트리밍 /v1/responses는 결과 이벤트를 [DONE] 센티널 직전에 방출하고, 스트리밍 Anthropic Messages는 평가가 끝날 때까지 마지막 message_delta와 message_stop을 보류했다가 판정 결과를 그 message_delta의 delta.safeguard_results에 담아 보냅니다(#2682). 도구 사용을 제안하지 않은 응답에는 tool_uses 맵이 빈 available 검사를 싣습니다. 설정 섹션이 없으면 네이티브 경로는 변경 없이 전달하고 변환 경로는 아무것도 합성하지 않습니다.
• System One 평가기 모드(safeguards.action_safety.evaluator: systemone):
  • 공유 SystemOneClient 위에 구축된 SystemOneEvaluator(src/services/action_safety/systemone.rs, 라우터당 클라이언트 1개 캐시)를 통해 각 액션을 {tool, arguments, user_request, recent_tool_results}에 대한 단일 결정 호출로 평가합니다.
  • advisory 모드에서는 채팅 모델 평가기와 동시에 실행되어 진단 및 safeguards_action_safety_advisory_total 메트릭에만 쓰이고, enforce 모드에서는 fail-closed 매핑이 실제 방출 판정이 됩니다.
• 공개 POST /v1/decisions 엔드포인트(별칭 /v1/systemone):
  • 핸들러(src/proxy/decisions/)는 디스패치 전에 공유 질문 규칙으로 본문을 검증하고 키별 모델 게이트를 적용한 뒤 FallbackService::execute_with_fallback_snapshot으로 fallback.fallback_chains를 순회합니다.
  • 패스스루 타깃: 공유 ClientCache에 캐시된 SystemOneClient(src/services/decisions/targets.rs)를 통해 decisions.targets[] 항목으로 전달합니다(allowed_backends가 설정된 키에는 인라인 엔드포인트 타깃을 거부하며, 체인 홉에서는 이를 사용 불가 백엔드로 처리해 건너뜁니다).
  • 채팅 모델 에뮬레이션: 질문 맵을 강제 emit_decision 도구 호출 하나로 변환하고, 채팅 request_params 정책과 입력 가드레일 사전 게이트(src/proxy/decisions/emulation_gate.rs)를 거친 뒤 일반 채팅 재시도 루프(proxy::request::execute_decision_chat_hop)로 전송해 도구 인자를 emulated: true가 표시된 one-hot 응답으로 복원합니다(src/services/decisions/emulation.rs). 모델 이름은 dispatch_model_for_request로 해석하며 사용량은 실제 응답한 모델 이름으로 호출자 키에 기록됩니다.
• 구조적 fail-closed 불변성: 평가기 사용 불가, 타임아웃, 잘못되었거나 알 수 없는 판정, 거부, 예산 소진은 모두 합성된 allow가 아닌 non-allow 결과로 귀결됩니다. 스트리밍 경로는 평가가 진행되는 동안 요청당 액션 예산 범위 안에서 마지막 message_delta와 message_stop을 보류하여 판정 결과가 턴 종료 전에 도달하도록 보장하며, 진단 로그에는 페이로드, 도구 인자, 자격 증명을 절대 기록하지 않습니다.

운영자 대상 가이드(네이티브 패스스루, 어댑터 설정, 클라이언트 측 우회 방법, 프로토콜 기록)는 Integrating with Claude Code를 참고하세요.

responses_only 모델용 Responses-API 라우팅¶

일부 OpenAI Pro 모델(현재 gpt-5-pro, gpt-5.2-pro, gpt-5.4-pro, gpt-5.5-pro)은 /v1/responses로만 노출되며 /v1/chat/completions에서는 404 not_found가 돌아옵니다. model-metadata.yaml(과 내장 OpenAI 레지스트리)의 responses_only: true capability 플래그가 이런 모델을 표시하면, 라우터는 클라이언트가 어느 surface로 요청했는지에 관계없이 Responses API 쪽으로 투명하게 dispatch합니다.

플래그는 모델 조회 직후, 백엔드 dispatch 직전인 프록시 계층에서 검사합니다. capability 정보를 해석하는 모델 메타데이터 파이프라인이 그대로 responses_only도 해석하므로, 백엔드별 오버라이드, 외부 메타데이터 파일, 내장 기본값이 표준 우선순위 순서로 그대로 작동합니다(메타데이터 우선순위 및 별칭 해석 참조).

sequenceDiagram
    participant Client
    participant ChatHandler as POST /v1/chat/completions
    participant AnthropicHandler as POST /anthropic/v1/messages
    participant Lookup as is_responses_only_model()
    participant Converter as Request Converter
    participant Backend as OpenAI / Azure OpenAI

    alt OpenAI surface
        Client->>ChatHandler: chat.completion 요청
        ChatHandler->>Lookup: (backend, model)
    else Anthropic surface
        Client->>AnthropicHandler: messages 요청
        AnthropicHandler->>Lookup: (backend, model)
    end

    alt responses_only = true
        alt 백엔드가 OpenAI / Azure OpenAI
            Lookup-->>Converter: /v1/responses payload으로 변환
            Converter->>Backend: POST /v1/responses
            Backend-->>Converter: Responses API 응답 (또는 SSE)
            Converter-->>Client: 원래 surface 모양으로 다시 변환
        else 백엔드가 OpenAI / Azure OpenAI 아님
            Lookup-->>Client: 400 invalid_request_error
        end
    else responses_only = false
        Lookup-->>Backend: 표준 /v1/chat/completions dispatch
        Backend-->>Client: chat.completion / Anthropic Messages
    end

주요 속성:

• 두 surface 모두에서 dispatch가 투명합니다. 클라이언트는 /v1/chat/completions나 /anthropic/v1/messages를 그대로 쓰면서 매칭되는 모양의 응답을 받습니다.
• /v1/responses는 OpenAI와 Azure OpenAI 백엔드만 제공합니다. 다른 유형의 백엔드는 업스트림 호출 전에 400 invalid_request_error로 거절됩니다.
• (backend, model) 쌍별 첫 dispatch는 info 레벨로 로깅되어, 디버그 로그를 켜지 않고도 운영자가 Responses-API 라우팅 여부를 확인할 수 있습니다.
• 스트리밍 요청은 이벤트 단위로 브리지됩니다. Responses API SSE 이벤트는 전체 응답을 버퍼링하지 않고 chat.completion.chunk(OpenAI surface)나 Anthropic Messages SSE 이벤트(Anthropic surface)로 변환됩니다.

설정 문법, 현재 모델 목록, 새 모델을 표시하는 방법은 설정 가이드의 Responses-API 전용 모델을 참조하세요.

헬스 체크 흐름¶

sequenceDiagram
    participant HealthService as Health Service
    participant BackendPool as Backend Pool
    participant Backend as LLM Backend
    participant Cache as Health Cache

    loop 매 간격마다
        HealthService->>BackendPool: 모든 백엔드 가져오기
        BackendPool-->>HealthService: 백엔드 목록

        par 각 백엔드에 대해
            HealthService->>Backend: GET /v1/models (또는 /health)
            alt 성공
                Backend-->>HealthService: 200 OK + 모델 목록
                HealthService->>Cache: 업데이트: consecutive_successes++
                HealthService->>HealthService: 임계값 충족 시 정상으로 표시
            else 실패
                Backend-->>HealthService: 오류/타임아웃
                HealthService->>Cache: 업데이트: consecutive_failures++
                HealthService->>HealthService: 임계값 충족 시 비정상으로 표시
            end
        end

        HealthService->>BackendPool: 백엔드 헬스 상태 업데이트
    end

핫 리로드 서비스¶

위치: src/infrastructure/config/hot_reload.rs, src/infrastructure/config/hot_reload_service.rs

목적: 서버 재시작 없이 런타임 설정 업데이트 제공

핫 리로드 시스템은 자동 파일 감시와 지능형 컴포넌트 업데이트를 통해 무중단 설정 변경을 가능하게 합니다.

주요 아키텍처 컴포넌트¶

• ConfigManager: notify 크레이트를 사용한 파일 시스템 감시, tokio::sync::watch 채널을 통해 업데이트 게시
• HotReloadService: 설정 차이점 계산, 변경 사항 분류 (즉시/점진적/재시작)
• 컴포넌트 업데이트: HealthChecker, CircuitBreaker, RateLimitStore, BackendPool에 대한 원자적 업데이트를 위한 내부 가변성 패턴 (RwLock)

백엔드 풀 핫 리로드¶

BackendPool은 서비스 중단 없이 런타임 백엔드 추가 및 제거를 지원하기 위해 내부 가변성(Arc<RwLock<Vec<Arc<Backend>>>>)을 사용합니다.

백엔드 상태:

• Active: 정상 운영, 새 요청 수락
• Draining: 설정에서 제거됨, 기존 요청은 계속, 새 요청 없음
• Removed: 모든 참조 해제 후 완전히 정리됨

우아한 드레이닝 프로세스:

1. 백엔드가 설정에서 제거되면 Draining으로 표시됩니다
2. 새 요청은 드레이닝 백엔드를 건너뜁니다
3. 기존 진행 중인 요청/스트림은 중단 없이 계속됩니다 (Arc 참조 카운팅)
4. 백그라운드 정리 태스크가 10초마다 실행됩니다
5. 백엔드는 다음 경우에 제거됩니다: 참조가 없거나 5분 타임아웃 초과 시

설정 변경 중에도 진행 중인 연결에 영향을 주지 않습니다.

변경 분류¶

• 즉시 업데이트: 활성 속도 제한과 서킷 브레이커 정책, 전역 프롬프트, 요청 매개변수, 스트리밍/스마트 라우팅 스냅샷, 선택 전략, prefix 라우팅, 재시도 정책, 요청별 타임아웃 예산, 문서화된 동적 필드
• 점진적 업데이트: 백엔드와 상태 확인
• 재시작 필요: 서버/CORS, 로깅과 추적, HTTP 클라이언트의 연결 및 전체 타임아웃, 캐시 구성 및 시작 시 생성되는 서비스

Admin API: 핫 리로드 기능 검사를 위한 /admin/config/hot-reload-status

핫 리로드 설정, 프로세스 흐름, 사용 예제에 대한 자세한 내용은 핫 리로드 섹션을 참조하세요.

설정 마이그레이션 시스템¶

위치: src/infrastructure/config/{migrator,migration,migrations,fixer,backup}.rs

목적: 설정 문제를 자동으로 감지 및 수정하고 스키마를 마이그레이션하며 설정 유효성을 보장

설정 마이그레이션 시스템은 설정 진화와 유지보수를 처리하며 자동으로 다음 작업을 수행합니다.

• 오래된 스키마 버전 감지 및 마이그레이션
• YAML/TOML 파일의 일반적인 구문 오류 수정
• 설정 값 검증 및 수정
• 변경 전 백업 생성
• 변경 사항 미리보기를 위한 dry-run 기능 제공

아키텍처 컴포넌트¶

1. 마이그레이션 오케스트레이터 (migrator.rs) - 마이그레이션 작업의 메인 진입점 - 전체 마이그레이션 워크플로우 조율 - 백업 생성 및 복원 관리 - 보안 검증 구현 (경로 탐색, 파일 크기 제한)

2. 마이그레이션 프레임워크 (migration.rs) - 마이그레이션을 위한 핵심 타입 및 트레이트 정의 - 버전 업그레이드 구현을 위한 Migration 트레이트 - 문제 분류를 위한 ConfigIssue 열거형 - 변경 사항 추적을 위한 MigrationResult

3. 스키마 마이그레이션 (migrations.rs) - 구체적인 마이그레이션 구현 (예: V1ToV2Migration) - 버전 간 설정 구조 변환 - 예시: backend_url을 backends 배열로 변환

4. 자동 수정 엔진 (fixer.rs) - 일반적인 설정 오류 감지 및 수정 - Duration 형식 수정 (예: '10 seconds' → '10s') - URL 검증 및 프로토콜 추가 - 필드 비권장화 처리

5. 백업 관리자 (backup.rs) - 수정 전 타임스탬프가 있는 백업 생성 - 리소스 제한 구현 (파일당 10MB, 총 100MB, 최대 50개 백업) - 오래된 백업의 자동 정리 - 파일 권한 보존

마이그레이션 워크플로우¶

graph TD
    A[설정 파일 읽기] --> B[경로 및 크기 검증]
    B --> C[백업 생성]
    C --> D[설정 파싱]
    D --> E{파싱 성공?}
    E -->|아니오| F[구문 오류 수정]
    F --> D
    E -->|예| G[스키마 버전 감지]
    G --> H{마이그레이션 필요?}
    H -->|예| I[마이그레이션 적용]
    H -->|아니오| J[값 검증]
    I --> J
    J --> K{문제 발견?}
    K -->|예| L[자동 수정 적용]
    K -->|아니오| M[설정 반환]
    L --> N[업데이트된 설정 쓰기]
    N --> M

보안 기능¶

1. 경로 탐색 보호: 디렉토리 탐색 공격 방지를 위한 경로 검증
2. 파일 크기 제한: DoS 방지를 위한 최대 10MB 설정 파일
3. 형식 검증: .yaml, .yml, .toml 파일만 처리
4. 시스템 디렉토리 보호: 민감한 시스템 경로 접근 차단
5. 테스트 모드 완화: 테스트 친화적 검증을 위한 조건부 컴파일 사용

예시 마이그레이션: v1.0에서 v2.0으로¶

// V1ToV2Migration 구현
fn migrate(&self, config: &mut Value) -> Result<(), MigrationError> {
    // 단일 backend_url을 backends 배열로 변환
    if let Some(backend_url) = config.get("backend_url") {
        let mut backends = Vec::new();
        let mut backend = Map::new();
        backend.insert("url".to_string(), backend_url.clone());

        // 모델을 백엔드로 이동
        if let Some(model) = config.get("model") {
            backend.insert("models".to_string(),
                Value::Sequence(vec![model.clone()]));
        }

        backends.push(Value::Mapping(backend));
        config["backends"] = Value::Sequence(backends);

        // 이전 필드 제거
        config.remove("backend_url");
        config.remove("model");
    }
    Ok(())
}

설정 로딩 흐름¶

graph TD
    A[애플리케이션 시작] --> B[Config Manager 초기화]
    B --> C{설정 파일 지정됨?}
    C -->|예| D[지정된 파일 로드]
    C -->|아니오| E[표준 위치 검색]

    E --> F{설정 파일 발견?}
    F -->|예| G[설정 파일 로드]
    F -->|아니오| H[CLI 인자 + 환경 변수 + 기본값 사용]

    D --> I[YAML 파싱]
    G --> I
    H --> J[인자에서 설정 생성]

    I --> K[환경 변수 오버라이드 적용]
    J --> K

    K --> L[CLI 인자 오버라이드 적용]
    L --> M[설정 검증]
    M --> N{유효함?}
    N -->|예| O[설정 반환]
    N -->|아니오| P[오류와 함께 종료]

    O --> Q[핫 리로드를 위한 파일 감시 시작]
    Q --> R[애플리케이션 실행 중]

    Q --> S[설정 파일 변경됨]
    S --> T[리로드 및 검증]
    T --> U{유효함?}
    U -->|예| V[새 설정 적용]
    U -->|아니오| W[오류 로깅, 이전 설정 유지]

    V --> R
    W --> R

의존성 주입¶

런타임에 서비스 컨테이너에서 무언가를 꺼내 쓰는 구조는 없습니다. 서비스는 평범한 생성자 인자입니다. src/server/state.rs가 시작 시점에 서비스를 만들고 AppState(src/lib.rs)가 이를 보관하며 각 컴포넌트는 필요한 핸들을 넘겨받습니다. 소비자가 특정 구현 하나에 묶이면 안 되는 자리에서는 구체 타입 대신 트레이트 객체를 넘깁니다.

그 이음매가 바로 BackendService(src/core/traits.rs)입니다. 라우터의 백엔드에 대해 get_backend, list_backends, get_healthy_backends, get_stats를 노출하며 프로덕션 구현체는 BackendManager(src/infrastructure/backends/pool/backend_manager.rs) 하나뿐입니다. BackendManager는 BackendPool과 선택적인 Arc<dyn HealthChecker>에 작업을 위임합니다. BackendPool이 Arc 기반이라 BackendManager::from_pool은 실행 중인 풀을 복사하지 않고 감쌉니다.

src/core/container.rs에는 예전 설계에서 남은 Container가 아직 있지만 끝내 배선되지 않았습니다. 자기 단위 테스트 안에서만 생성되고 어떤 서비스도 등록하지 않습니다.

서비스 구성¶

src/server/state.rs의 두 곳에서 공유 풀을 BackendService로 감싸 소비자에게 넘깁니다.

// src/server/state.rs: 가드레일 서비스 팩토리.
pub(crate) fn guardrail_service_factory(
    client: reqwest::Client,
    backend_pool: BackendPool,
    topology: LiveBackendTopology,
) -> GuardrailServiceFactory {
    Arc::new(move |g_cfg| {
        // 프로덕션 BackendService 구현체는 BackendManager 하나뿐이다.
        // from_pool은 라우터의 살아 있는 풀을 다시 만들지 않고 공유한다.
        let backend_resolver: Arc<dyn BackendService> =
            Arc::new(BackendManager::from_pool(backend_pool.clone()));

        // 리졸버는 설정된 백엔드 토폴로지의 실시간 뷰와 함께 전달되므로
        // `backend:` 가드 모델 참조는 가드 호출마다 가시성 계약으로 검사된다.
        let guardrail_service = GuardrailService::from_config(
            g_cfg,
            client.clone(),
            Some(GuardBackendAccess::new(backend_resolver, topology.clone())),
        );
        Arc::new(guardrail_service)
    })
}

// src/server/state.rs: 스마트 라우팅 LLM 분류기도 같은 종류의 리졸버를 받아
// 분류 요청을 프로덕션 백엔드로 흘려보낸다. 여기에 각 백엔드의
// `request_extensions`를 읽는 살아 있는 뷰를 함께 받아, 분류 호출도 사용자
// 트래픽과 같은 확장 헤더를 싣는다.
if let Some(llm_classifier) = LlmClassifier::from_runtime_config(
    config,
    classifier_config,
    Arc::new(BackendManager::from_pool(backend_pool.clone())),
    backend_topology.extensions_source(),
) {
    router = router.with_llm_classifier(llm_classifier, classifier_config.clone());
}

서비스 의존성¶

소비자는 넘겨받은 트레이트 객체를 그대로 들고 트레이트 메서드를 호출합니다. 따로 조회하는 과정은 없습니다.

// src/services/smart_routing/llm_classifier.rs
pub struct LlmClassifier {
    backend_resolver: Arc<dyn BackendService>,
    extensions_source: BackendExtensionsSource,
    backend_name: String,
    // ... 프롬프트, 스키마, 캐시, 설정 필드
}

impl LlmClassifier {
    async fn send_request(&self, request_payload: &Value) -> Result<Value, String> {
        // 백엔드의 현재 확장 헤더를 먼저 깔고, 그 위에 재귀 방지 헤더를 넣는다.
        // 설정으로 들어온 어떤 표기의 재귀 방지 헤더든 이 값이 대체한다.
        let headers = self.dispatch_headers();

        let backend = self
            .backend_resolver
            .get_backend(&self.backend_name)
            .await
            .map_err(|e| {
                format!(
                    "classifier backend '{}' is not available in the live backend pool: {e}",
                    self.backend_name
                )
            })?;

        // 해석된 백엔드로 디스패치하면 사용자 트래픽과 동일한 요청 변환,
        // 인증, 복원력 처리를 그대로 쓴다.
        let response = backend
            .execute_chat_completion(request_payload, Some(headers))
            .await;
        // ...
    }
}

이점¶

• 테스트 가능성: 소비자가 Arc<dyn BackendService>를 받으므로 테스트는 라우터를 띄우지 않고 직접 만든 풀 위의 BackendManager를 넘기면 됩니다.
• 살아 있는 상태 공유: from_pool은 실행 중인 풀의 백엔드와 통계, 수명 주기 상태를 그대로 공유하므로 하위 시스템은 사본이 아니라 프로덕션 트래픽이 보는 것과 같은 상태를 봅니다.
• 구현 교체 가능: 소비자는 BackendManager가 아니라 트레이트에 의존하므로 소비자를 건드리지 않고 구성 지점에서 다른 리졸버로 바꿔 끼울 수 있습니다.

오류 처리 전략¶

라우터는 타입화된 오류, 지능형 복구, 사용자 친화적 응답을 갖춘 다층 오류 처리 전략을 구현합니다.

오류 타입 계층¶

• CoreError: 도메인 레벨 오류 (검증, 서비스 실패, 타임아웃, 설정)
• RouterError: Core, HTTP, Backend, Model 오류를 결합하는 애플리케이션 레벨 오류
• HttpError: HTTP 특화 오류 (400 BadRequest, 401 Unauthorized, 404 NotFound, 500 InternalServerError 등)

오류 처리 원칙¶

1. 빠른 실패: 명확한 오류 메시지와 함께 입력을 조기에 검증
2. 오류 컨텍스트: 관련 컨텍스트 포함 (필드 이름, 작업 세부 정보)
3. 재시도 가능 분류: 재시도 가능(타임아웃, 503)과 불가능(400, 401) 오류 구분
4. 사용자 친화적 응답: 내부 오류를 OpenAI 호환 오류 형식으로 변환
5. 구조화된 로깅: 적절한 심각도와 컨텍스트로 오류 로깅

오류 복구 메커니즘¶

• 지수 백오프가 있는 재시도: 일시적 장애 자동 재시도
• 모델 폴백: 기본 모델을 사용할 수 없을 때 대체 모델로 라우팅 (모델 폴백 시스템 참조)
• 우아한 성능 저하: 컴포넌트 실패 시 감소된 기능으로 계속 작동

오류 처리, 복구 전략, 모니터링, 문제 해결에 대한 자세한 내용은 error-handling.md를 참조하세요.

확장 지점¶

백엔드 타입 아키텍처¶

라우터는 다른 API 형식을 가진 여러 백엔드 타입을 지원합니다. 각 백엔드 타입은 요청/응답 변환을 자동으로 처리합니다.

지원되는 백엔드 타입¶

Anthropic 백엔드 아키텍처¶

Anthropic 백엔드는 자동 형식 변환과 함께 Claude 모델에 대한 네이티브 지원을 제공합니다:

┌─────────────────────────────────────────────────────────────────┐
│                   OpenAI 형식 요청                                │
│  POST /v1/chat/completions                                       │
│  { "model": "claude-haiku-4-5", "messages": [...] }             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              요청 변환 레이어                                     │
│  transform_openai_to_anthropic_request()                        │
│  • 시스템 메시지 추출 → 별도의 `system` 매개변수                   │
│  • image_url 변환 → Anthropic 이미지 형식                        │
│  • max_tokens / max_completion_tokens 매핑                       │
│  • reasoning_effort 변환 → thinking 매개변수                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Anthropic Messages API                          │
│  POST https://api.anthropic.com/v1/messages                     │
│  Headers: x-api-key, anthropic-version (backend setting)        │
│  { "model": "...", "system": "...", "messages": [...] }         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              AnthropicStreamTransformer                          │
│  SSE 이벤트 변환 (Anthropic → OpenAI 형식)                        │
│  • message_start → role이 있는 초기 청크                          │
│  • content_block_delta → 콘텐츠 청크                              │
│  • thinking_delta → reasoning_content (확장된 사고)               │
│  • message_delta → finish_reason 매핑                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   OpenAI 형식 응답                                │
│  data: {"choices":[{"delta":{"content":"..."}}]}                │
└─────────────────────────────────────────────────────────────────┘

주요 변환¶

요청 형식 차이:

확장된 사고 지원:

// OpenAI reasoning_effort → Anthropic thinking
{
  "reasoning_effort": "high"  // OpenAI 형식
}
// 다음으로 변환:
{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 32768   // effort 레벨에서 매핑
  }
}

도구 호출 변환 (Tool Calling Transformation)¶

라우터는 OpenAI 형식의 도구 정의를 백엔드 네이티브 형식으로 자동 변환하여 크로스 프로바이더 도구 호출을 지원합니다.

위치: src/core/tool_calling/

모듈 구조:

src/core/tool_calling/
├── mod.rs           # 모듈 익스포트
├── definitions.rs   # 타입 정의 (ToolDefinition, FunctionDefinition 등)
├── transform.rs     # 각 백엔드별 변환 함수
├── tool_choice.rs   # 각 백엔드별 도구 선택 변환
├── response.rs      # 백엔드로부터 도구 호출 응답 추출
├── streaming.rs     # 스트리밍 도구 호출 변환
└── messages.rs      # 멀티턴 대화 메시지 변환

지원 백엔드¶

OpenAI 도구 형식 (입력)¶

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "위치의 현재 날씨를 가져옵니다",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          },
          "required": ["location"]
        }
      }
    }
  ]
}

Anthropic 변환¶

// transform_tools_to_anthropic()
// 입력:  `function.parameters`를 포함한 OpenAI 형식
// 출력: `input_schema`를 포함한 Anthropic 형식
{
  "tools": [
    {
      "name": "get_weather",
      "description": "위치의 현재 날씨를 가져옵니다",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    }
  ]
}

Gemini 변환¶

// transform_tools_to_gemini()
// 입력:  OpenAI 형식
// 출력: Gemini 중첩 functionDeclarations 형식
{
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "위치의 현재 날씨를 가져옵니다",
          "parameters": {
            "type": "object",
            "properties": {
              "location": { "type": "string" }
            },
            "required": ["location"]
          }
        }
      ]
    }
  ]
}

검증 규칙¶

• 도구 이름: ^[a-zA-Z0-9_-]+$ 패턴과 일치해야 함 (영숫자, 밑줄, 하이픈만 허용)
• 빈 이름: 검증 오류로 거부됨
• 누락된 필드: 경고로 로깅되고 도구는 건너뜀 (무음 데이터 손실 없음)
• Type 필드: 표준 도구 정의의 경우 "function"이어야 함

폴백 시스템과의 통합¶

도구 호출 변환은 ParameterTranslator를 통해 모델 폴백 시스템과 통합됩니다:

// src/core/fallback/translation.rs에서
impl ParameterTranslator {
    pub fn translate_tools(
        &self,
        tools: &Value,
        from_backend_type: BackendType,
        to_backend_type: BackendType,
    ) -> CoreResult<Value> {
        match (from_backend_type, to_backend_type) {
            (_, BackendType::Anthropic) => transform_tools_to_anthropic(tools),
            (_, BackendType::Gemini) => transform_tools_to_gemini(tools),
            (_, BackendType::LlamaCpp) => transform_tools_for_llamacpp(tools),
            _ => Ok(tools.clone()),
        }
    }
}

그래서 도구 정의를 보존하면서 한 프로바이더에서 다른 프로바이더로 매끄럽게 폴백할 수 있습니다.

도구 선택 변환 (Tool Choice Transformation)¶

도구 정의 외에도 라우터는 모델의 도구 호출 동작을 제어하는 tool_choice 파라미터도 변환합니다.

지원 값:

엣지 케이스:

• Anthropic none 처리: Anthropic API는 tool_choice=none을 지원하지 않습니다. 이 값이 감지되면 라우터가 요청에서 tools와 tool_choice를 모두 제거합니다.
• llama.cpp: 병렬 함수 호출 지원을 위해 parallel_tool_calls 파라미터를 유지합니다.

구현:

// src/core/tool_calling/tool_choice.rs에서
pub enum ToolChoiceValue {
    Auto,
    None,
    Required,
    Function(String),
}

impl ToolChoiceValue {
    pub fn from_openai(value: &Value) -> CoreResult<Self>;
    pub fn to_anthropic(&self) -> Option<Value>;  // "none"의 경우 None 반환
    pub fn to_gemini(&self) -> Value;
}

스트리밍 도구 호출 변환¶

스트리밍이 활성화된 경우, 도구 호출은 완전한 객체가 아닌 델타 이벤트로 점진적으로 반환됩니다. 각 프로바이더는 서로 다른 스트리밍 형식을 사용하므로 OpenAI API 호환성을 유지하기 위해 실시간 변환이 필요합니다.

위치: src/core/tool_calling/streaming.rs

주요 컴포넌트:

스트리밍 형식 비교:

상태 머신 (Anthropic):

IDLE → message_start → READY
READY → content_block_start (tool_use) → TOOL_STARTED
TOOL_STARTED → content_block_delta → ACCUMULATING
ACCUMULATING → content_block_delta → ACCUMULATING (루프)
ACCUMULATING → content_block_stop → TOOL_COMPLETE
TOOL_COMPLETE → message_delta → FINISHED

안전 제한:

잘못된 형식의 스트림으로 인한 메모리 고갈을 방지하기 위해:

• MAX_TOOL_CALLS = 64: 메시지당 최대 병렬 도구 호출 수
• MAX_ARGUMENTS_SIZE = 1MB: 도구 호출당 최대 누적 인자 크기

예시 변환 (Anthropic → OpenAI):

// Anthropic 입력: content_block_start
{"type": "content_block_start", "index": 0,
 "content_block": {"type": "tool_use", "id": "toolu_123", "name": "get_weather"}}

// OpenAI 출력: 델타 청크
{"id": "chatcmpl-...", "choices": [{"delta": {"tool_calls": [
  {"index": 0, "id": "toolu_123", "type": "function",
   "function": {"name": "get_weather", "arguments": ""}}
]}}]}

종료 사유 매핑:

멀티턴 대화 메시지 변환¶

멀티턴 대화에서 도구를 사용할 때, 메시지 히스토리에는 어시스턴트의 도구 호출과 클라이언트의 도구 결과가 포함됩니다. 이러한 메시지들은 다른 백엔드로 라우팅할 때 형식 변환이 필요합니다.

위치: src/core/tool_calling/messages.rs

주요 함수:

메시지 형식 차이점:

OpenAI 형식 (입력):

{
  "messages": [
    {"role": "user", "content": "NYC 날씨가 어때?"},
    {
      "role": "assistant",
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"location\": \"NYC\"}"}
      }]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": 72, \"condition\": \"sunny\"}"
    }
  ]
}

Anthropic 변환:

{
  "messages": [
    {"role": "user", "content": "NYC 날씨가 어때?"},
    {
      "role": "assistant",
      "content": [{
        "type": "tool_use",
        "id": "call_abc123",
        "name": "get_weather",
        "input": {"location": "NYC"}
      }]
    },
    {
      "role": "user",
      "content": [{
        "type": "tool_result",
        "tool_use_id": "call_abc123",
        "content": "{\"temperature\": 72, \"condition\": \"sunny\"}"
      }]
    }
  ]
}

Gemini 변환:

{
  "contents": [
    {"role": "user", "parts": [{"text": "NYC 날씨가 어때?"}]},
    {
      "role": "model",
      "parts": [{
        "functionCall": {"name": "get_weather", "args": {"location": "NYC"}}
      }]
    },
    {
      "role": "function",
      "parts": [{
        "functionResponse": {
          "name": "get_weather",
          "response": {"temperature": 72, "condition": "sunny"}
        }
      }]
    }
  ]
}

다중 도구 결과:

여러 도구가 병렬로 호출된 경우, 연속된 도구 결과 메시지는 Anthropic에서 단일 사용자 메시지로 결합됩니다:

// 여러 OpenAI 도구 결과:
{"role": "tool", "tool_call_id": "call_1", "content": "72F, 맑음"}
{"role": "tool", "tool_call_id": "call_2", "content": "오후 3:00 EST"}

// 결합된 Anthropic 형식:
{
  "role": "user",
  "content": [
    {"type": "tool_result", "tool_use_id": "call_1", "content": "72F, 맑음"},
    {"type": "tool_result", "tool_use_id": "call_2", "content": "오후 3:00 EST"}
  ]
}

오류 처리:

• tool_call_id 누락: 유효성 검사 오류 반환
• 잘못된 형식의 도구 호출: 경고로 로깅되고 전체 요청 실패 없이 건너뜀
• Gemini에서 알 수 없는 함수 이름: 경고 로그와 함께 "unknown"으로 대체
• 잘못된 JSON 인수: 빈 객체 {}로 대체
• is_error 표시자: Anthropic 형식으로 변환 시 보존

Gemini 3 thoughtSignature 지원¶

Gemini 3 모델은 함수 호출에 새로운 thoughtSignature 필드를 도입했으며 이 필드는 멀티턴 대화에서 보존되어 다시 전달되어야 합니다. 라우터는 변환 파이프라인을 통해 이를 자동으로 처리합니다.

thoughtSignature란?

Gemini 3+ 모델이 함수 호출을 반환할 때, 모델의 내부 추론 컨텍스트를 캡슐화하는 암호화된 thoughtSignature 필드가 포함됩니다. 이 서명은 대화를 올바르게 계속하기 위해 함수 결과를 다시 보낼 때 포함되어야 합니다.

응답 추출 (Gemini -> 클라이언트):

라우터는 Gemini 응답에서 thoughtSignature를 추출하여 OpenAI 호환 형식에 포함합니다:

// Gemini 네이티브 응답 (thoughtSignature 포함)
{
  "candidates": [{
    "content": {
      "parts": [{
        "functionCall": {"name": "get_weather", "args": {"location": "NYC"}},
        "thoughtSignature": "encrypted_signature_abc123"
      }]
    }
  }]
}

// 라우터의 OpenAI 호환 응답
{
  "choices": [{
    "message": {
      "tool_calls": [{
        "id": "call_xyz789",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"location\":\"NYC\"}"},
        "extra_content": {
          "google": {
            "thought_signature": "encrypted_signature_abc123"
          }
        }
      }]
    }
  }]
}

요청 주입 (클라이언트 -> Gemini):

클라이언트가 도구 결과를 다시 보낼 때, 라우터는 extra_content.google에서 thought_signature를 추출하여 Gemini 요청에 thoughtSignature로 주입합니다:

// 클라이언트의 OpenAI 형식 요청
{
  "messages": [{
    "role": "assistant",
    "tool_calls": [{
      "id": "call_xyz789",
      "function": {"name": "get_weather", "arguments": "{}"},
      "extra_content": {
        "google": {"thought_signature": "encrypted_signature_abc123"}
      }
    }]
  }]
}

// 변환된 Gemini 요청
{
  "contents": [{
    "role": "model",
    "parts": [{
      "functionCall": {"name": "get_weather", "args": {}},
      "thoughtSignature": "encrypted_signature_abc123"
    }]
  }]
}

스트리밍 지원:

스트리밍 변환기도 thoughtSignature 추출을 처리하며 도구 호출 delta 청크에 포함합니다.

호환 동작:

• Gemini 2.x 모델은 thoughtSignature를 반환하지 않습니다 - 라우터는 이를 우아하게 처리합니다
• extra_content.google.thought_signature를 보존하지 않는 클라이언트도 함수 호출이 가능합니다 (다만 Gemini 3+에서 대화 연속성이 저하될 수 있음)
• extra_content 필드는 Gemini가 아닌 백엔드에서는 무시됩니다

구현 위치:

새 백엔드 타입 추가하기¶

1. 타입 선언: src/core/config/models/backend_type.rs의 BackendTypeConfig에 변형을 추가합니다. backends[] 항목의 type: 필드가 이 열거형으로 역직렬화됩니다. 새 변형을 추가하면 AGENTS.md의 "Configuration Assistant Sync"에 나열된 설정 어시스턴트 갱신도 함께 해야 합니다.

2. Backend 트레이트 구현: 트레이트는 src/core/traits.rs에 정의되어 있으며, 팩토리는 이를 BackendTrait로 임포트합니다.

   // src/infrastructure/backends/custom_backend.rs에서
   use std::collections::HashMap;
   use std::sync::Arc;
   use std::time::Duration;
   
   use async_trait::async_trait;
   use serde_json::Value;
   
   use crate::core::CoreError;
   use crate::core::traits::{
       Backend, BackendCapabilities, BackendResponse, BackendType, HealthStatus,
   };
   
   pub struct CustomBackend {
       client: Arc<HttpClient>,
       config: CustomBackendConfig,
   }
   
   #[async_trait]
   impl Backend for CustomBackend {
       fn name(&self) -> &str { /* ... */ }
       fn url(&self) -> &str { /* ... */ }
       fn weight(&self) -> u32 { /* ... */ }
       fn supported_models(&self) -> &[String] { /* ... */ }
       fn supports_model(&self, model: &str) -> bool { /* ... */ }
       fn backend_type(&self) -> BackendType { BackendType::Custom("custom".to_string()) }
       fn capabilities(&self) -> BackendCapabilities { /* ... */ }
       fn metadata(&self) -> &HashMap<String, Value> { /* ... */ }
       fn request_timeout(&self) -> Duration { /* ... */ }
   
       async fn health_check(&self) -> Result<HealthStatus, CoreError> { /* ... */ }
       async fn execute_chat_completion(
           &self,
           request: &Value,
           headers: Option<HashMap<String, String>>,
       ) -> Result<BackendResponse, CoreError> { /* ... */ }
   
       // 그 밖에 execute_completion, execute_streaming_request,
       // get_models, get_model_details, get_statistics, get_current_load,
       // validate_config, transform_request, transform_response도 필수입니다.
   }
   

3. 백엔드 팩토리에 등록: src/infrastructure/backends/factory/backend_factory.rs의 BackendFactory::create_backend_from_typed_config에 분기를 추가합니다.

   match config.backend_type {
       // ... 기존 분기 ...
       BackendTypeConfig::Custom => {
           let backend = CustomBackend::from_config(config).await?;
           Ok(Arc::new(backend))
       }
   }
   

새 미들웨어 추가하기¶

1. 미들웨어 트레이트 구현:

   // src/http/middleware/custom_middleware.rs에서
   pub struct CustomMiddleware {
       config: CustomConfig,
   }
   
   impl<S> tower::Layer<S> for CustomMiddleware {
       type Service = CustomMiddlewareService<S>;
   
       fn layer(&self, inner: S) -> Self::Service {
           CustomMiddlewareService { inner, config: self.config.clone() }
       }
   }
   

2. HTTP 라우터에 등록:

   // src/main.rs에서
   let app = Router::new()
       .route("/v1/models", get(list_models))
       .layer(CustomMiddleware::new(config.custom))
       .layer(LoggingMiddleware::new())
       .with_state(state);
   

새 캐시 타입 추가하기¶

1. CacheStore 트레이트 구현:

   // src/infrastructure/cache/your_store.rs에서
   pub struct YourCacheStore { /* ... */ }
   
   #[async_trait]
   impl CacheStore for YourCacheStore {
       async fn get(&self, key: &str) -> CacheStoreResult<Option<Vec<u8>>> { /* ... */ }
       async fn set(&self, key: &str, value: &[u8], ttl: Duration) -> CacheStoreResult<()> { /* ... */ }
       async fn delete(&self, key: &str) -> CacheStoreResult<()> { /* ... */ }
       async fn clear(&self) -> CacheStoreResult<()> { /* ... */ }
       async fn stats(&self) -> CacheStoreStats { /* ... */ }
   }
   

RedisCacheStore(src/infrastructure/cache/redis_store.rs)는 기본으로 제공되는 공유 상태 구현체이며 redis-cache Cargo 기능으로 게이트됩니다. 이 기능은 default/full에 포함되지 않지만 공식 릴리스 바이너리와 컨테이너 이미지는 이를 컴파일하므로, 다중 복제본 배포에서 사용자 정의 빌드 없이 캐시와 속도 제한 카운터를 공유할 수 있습니다. 지원되는 엔드포인트 토폴로지(관리형 엔드포인트 하나, Sentinel 및 Cluster는 계약 범위 밖)는 src/core/config/redis_endpoint.rs에서 정의하고 강제하며 응답 캐시와 분산 속도 제한기는 모두 구성 로드 시 이를 기준으로 검증합니다.

1. ResponseCacheStore에 주입:

   let store: Arc<dyn CacheStore> = Arc::new(YourCacheStore::new(/* ... */));
   let cache = ResponseCacheStore::with_store(store, capacity, ttl, max_response_size, max_stream_buffer_size);
   

새 로드 밸런싱 전략 추가하기¶

선택 전략은 SelectionStrategy(src/core/models/backend.rs) enum으로 선언되고, 실제 선택은 BackendPool의 스코어러 파이프라인(BackendScorer, src/core/scoring.rs)에서 실행됩니다.

1. BackendScorer 구현:

// src/core/scoring.rs (또는 새 스코어러 모듈)
pub struct LeastBusyScorer;

#[async_trait]
impl BackendScorer for LeastBusyScorer {
    fn name(&self) -> &'static str { "least_busy" }

    async fn prepare(&self, _context: &ScoringContext) {
        // score()가 동기로 읽을 데이터를 미리 캐시 (기본 구현은 no-op)
    }

    fn score(&self, context: &ScoringContext, backend: &dyn Backend) -> f64 {
        // 값이 높을수록 선호. f64::NEG_INFINITY를 반환하면 해당 백엔드는 제외됨
        /* ... */
    }
}

1. 풀에 스코어러 등록:

pool.register_scorer(Arc::new(LeastBusyScorer)).await;

기본 전략(RoundRobin, WeightedRoundRobin, LeastLatency, Random, ConsistentHash 등)은 SelectionStrategy(src/core/models/backend.rs)에서 설정하며, 구성 방법은 로드 밸런싱 가이드에 정리되어 있습니다.

설계 결정¶

왜 4계층 아키텍처인가?¶

결정: 4계층 아키텍처 사용 (HTTP → Services → Infrastructure → Core)

이유¶

• 명확한 분리: 각 계층이 구별되는 책임을 가짐
• 테스트 가능성: 계층을 독립적으로 테스트 가능
• 유지보수성: 한 계층의 변경이 다른 계층에 영향을 미치지 않음
• 유연성: 구현을 쉽게 교체 가능 (예: 다른 캐시 백엔드)

트레이드오프¶

• ✅ 장점: 깔끔하고 유지보수 가능하고 테스트 가능하고 확장 가능
• ❌ 단점: 더 많은 복잡성, 약간의 성능 오버헤드
• 결론: 프로덕션 시스템에서는 이점이 비용을 초과함

왜 DI 컨테이너 대신 생성자 주입인가?¶

결정: 서비스를 평범한 생성자 인자로 전달하며, 런타임 서비스 컨테이너를 사용하지 않음

이유¶

• 컴파일 타임 배선: 서비스 그래프가 src/server/state.rs에 드러나고 빌드 시점에 검증됨
• 런타임 해석 실패 모드 없음: 누락된 등록은 시작 실패가 아니라 컴파일 오류
• 테스트: 각 컴포넌트를 필요한 목과 테스트 더블로 직접 생성

고려된 대안¶

• 런타임 DI 컨테이너 (src/core/container.rs): 초기에 구현되었으나 끝내 배선되지 않았고, 미사용 코드로 남아 있음

왜 Arc<RwLock>를 공유 상태에 사용하는가?¶

결정: 공유 가변 상태에 Arc<RwLock<T>> 사용

이유¶

• 읽기-쓰기 시맨틱스: 다중 리더, 배타적 쓰기
• 성능: 읽기가 많은 워크로드에서 Arc<Mutex<T>>보다 좋음
• 안전성: 컴파일 타임에 데이터 레이스 방지

고려된 대안¶

• Arc<Mutex<T>>: 더 간단하지만 읽기 성능이 나쁨
• 채널: 단순한 공유 상태에는 너무 복잡함
• 원자 타입: 복잡한 데이터 구조에 적합하지 않음

왜 전체적으로 async/await인가?¶

결정: 모든 I/O 작업에 async/await 사용

이유¶

• 성능: 논블로킹 I/O가 높은 동시성 허용
• 리소스 효율성: 요청당 스레드보다 낮은 메모리 사용
• 에코시스템: Rust 비동기 에코시스템 (Tokio, reqwest, axum)이 성숙함

트레이드오프¶

• ✅ 장점: 높은 성능, 낮은 리소스 사용, 좋은 에코시스템
• ❌ 단점: 복잡성, 학습 곡선, 디버깅 어려움
• 결론: 고성능 네트워크 서비스에 필수적

왜 설정 핫 리로드인가?¶

결정: 파일 감시를 사용한 설정 핫 리로드 지원

이유¶

• 제로 다운타임: 재시작 없이 설정 업데이트
• 운영 친화적: 프로덕션에서 설정 조정이 쉬움
• 개발: 개발 중 빠른 반복

구현¶

• 파일 시스템 감시자가 변경 감지
• 적용 전 새 설정 검증
• 일관성 없는 상태를 피하기 위한 원자적 업데이트
• 검증 오류 시 이전 설정으로 폴백

성능 고려 사항¶

메모리 관리¶

1. 연결 풀링: HTTP 연결을 재사용하여 할당 오버헤드 감소
2. 스마트 캐싱: LRU 제거로 무한 메모리 증가 방지
3. Arc 복제: 딥 복제 대신 저렴한 참조 카운팅
4. 스트리밍: 큰 응답을 메모리에 로드하지 않도록 청크 단위로 응답 처리

동시성¶

1. 읽기 중심 워크로드를 위한 RwLock: 백엔드 풀과 모델 캐시에 대한 다중 동시 리더
2. 가능한 경우 락 프리: 카운터와 간단한 상태에 원자 사용
3. 비동기 태스크 스폰: 헬스 체크와 캐시 업데이트를 위한 백그라운드 태스크
4. 바운드된 채널: 태스크의 무제한 큐잉 방지
5. 스트리밍 릴레이 채널: 클라이언트로 나가는 SSE 릴레이는 예외입니다. 모든 릴레이는 클라이언트를 기다리지 않는 하나의 공유 릴레이 채널(services::streaming::sse_relay_channel)로 전송하므로, 릴레이 태스크는 업스트림 속도로 업스트림을 읽고 클라이언트가 얼마나 느리게 읽든 마지막 사용량을 관찰합니다. 연결이 끊기면 다음 전송이 실패하며 이는 릴레이를 멈추고 업스트림을 끊습니다. 스트림별 버퍼는 업스트림 응답(출력 토큰 상한과 timeouts.streaming.total)으로 제한됩니다. tests/streaming_relay_pacing_audit_test.rs는 SSE 이벤트를 담는 유한 채널이나 이 채널을 쓰지 않는 Sse 본문을 빌드 실패로 잡습니다.

I/O 최적화¶

1. 연결 Keep-Alive: TCP 연결이 재사용을 위해 열린 상태 유지
2. 스트리밍 응답: 버퍼링 없이 SSE 청크 전달
3. 타임아웃: 느린 백엔드에서 행잉 방지
4. 백오프가 있는 재시도: 실패하는 백엔드에 과부하 방지

메모리 레이아웃¶

// 캐시 효율성을 위해 최적화된 데이터 구조
pub struct Backend {
    pub name: String,          // 작은 이름을 위한 인라인 문자열
    pub url: Arc<str>,         // URL을 위한 공유 문자열
    pub weight: u32,           // 컴팩트한 정수
    pub is_healthy: AtomicBool, // 락 프리 헬스 상태
}

// 캐시 친화적 모델 저장소
pub struct ModelCache {
    models: HashMap<String, Arc<ModelInfo>>, // 공유된 모델 정보
    last_updated: AtomicU64,                 // 락 프리 타임스탬프
    ttl: Duration,
}

벤치마킹 결과¶

벤치마크 기준 (benches/performance_benchmarks.rs 참조):

• 요청 지연 시간: 라우팅 결정에 < 5ms 오버헤드
• 메모리 사용량: ~50MB 기본 메모리, 백엔드에 따라 선형 확장
• 처리량: 보통 하드웨어에서 1000+ 요청/초
• 연결 효율성: 최소 메모리 오버헤드로 백엔드당 100+ 동시 연결

속도 제한¶

라우터는 남용으로부터 보호하고 클라이언트 간 공정한 리소스 할당을 보장하기 위해 다층 속도 제한을 구현합니다.

주요 기능: - 이중 윈도우 접근 방식: 지속 제한 (100 req/min) + 버스트 보호 (20 req/5s) - API 키 (선호) 또는 IP 주소 (폴백)로 클라이언트 식별 - 자동 캐시 정리가 있는 클라이언트별 격리 - 빈 응답에 대한 짧은 TTL로 DoS 방지

속도 제한 V2 아키텍처¶

향상된 속도 제한 시스템 (rate_limit_v2/)은 모듈화된 고성능 구현을 제공합니다:

모듈 구조¶

src/http/middleware/rate_limit_v2/
├── mod.rs              # 공개 API 및 모듈 내보내기
├── middleware.rs       # Axum 미들웨어 통합
├── store.rs            # 속도 제한 저장소 및 클라이언트 추적
└── token_bucket.rs     # 토큰 버킷 알고리즘 구현

구성 요소¶

1. 토큰 버킷 알고리즘 (token_bucket.rs)
2. 설정 가능한 버킷 용량 및 리필 속도
3. 락 프리 토큰 소비를 위한 원자적 연산
4. 경과 시간에 기반한 자동 토큰 보충

5. 지속 및 버스트 제한을 위한 별도 버킷

6. 속도 제한 저장소 (store.rs)

7. 동시 접근을 위한 DashMap을 사용한 클라이언트별 상태 추적
8. 만료된 클라이언트 항목의 자동 정리
9. 비활성 클라이언트에 대한 설정 가능한 TTL (기본값: 1시간)

10. 바운드된 저장소로 메모리 효율적

11. 미들웨어 통합 (middleware.rs)

12. 클라이언트 식별자 추출 (API 키 → IP 주소 폴백)
13. 처리 전 지속 및 버스트 제한 모두 확인
14. Retry-After 헤더와 함께 HTTP 429 (Too Many Requests) 반환
15. 속도 제한 히트 모니터링을 위한 Prometheus 메트릭

설정 예시¶

rate_limiting:
  enabled: true
  sustained:
    max_requests: 100
    window_seconds: 60
  burst:
    max_requests: 20
    window_seconds: 5
  cleanup_interval_seconds: 300

결정 흐름¶

요청 도착
    ↓
클라이언트 ID 추출 (API 키 또는 IP)
    ↓
지속 제한 확인 (100 req/min)
    ↓ OK
버스트 제한 확인 (20 req/5s)
    ↓ OK
요청 처리

속도 제한 설정에 대한 자세한 내용은 속도 제한 섹션을 참조하세요.

모델 폴백 시스템¶

라우터는 기본 모델을 사용할 수 없을 때 자동으로 대체 모델로 요청을 라우팅하는 설정 가능한 모델 폴백 시스템을 구현합니다.

주요 기능: - 자동 폴백 체인 실행 (예: gpt-5.6-sol → gpt-5.6-terra → gpt-5.6-luna) - 모든 홉에서 표준 요청 페이로드를 유지하는 크로스 프로바이더 폴백 지원 - 설정된 HTTP 오류, 타임아웃, 연결 실패, 모델 조회 실패, 백엔드 상태 기반 트리거 - 폴백 사용 모니터링을 위한 Prometheus 메트릭

자세한 설정 및 구현은 error-handling.md 모델 폴백 섹션을 참조하세요.

서킷 브레이커¶

라우터에는 Admin 조회와 강제 제어를 제공하는 백엔드별 서킷 브레이커 상태 머신이 있습니다. 일반 LLM 프록시 경로는 요청 결과를 이 상태 머신에 기록하고 선택 시 조회합니다. 열린 백엔드 서킷은 제외되어 트래픽이 우회하며 호환되는 모든 서킷이 열리면 라우터는 표준 service-unavailable 오류를 반환하고 설정된 폴백에 참여합니다. 이는 해당 경로의 능동 상태 확인, 재시도, 모델 폴백을 보완합니다.

3-상태 머신:

주요 기능: - 독립적인 상태를 가진 백엔드별 격리 - 핫 패스 오버헤드를 최소화하기 위한 락 프리 원자적 연산 - 수동 제어를 위한 admin 엔드포인트 (/admin/circuit/*) - 메인 메트릭 레지스트리에 등록되어 프록시 경로가 값을 채우는 메트릭 수집기

자세한 설정 및 구현은 error-handling.md 서킷 브레이커 섹션을 참조하세요.

파일 저장소¶

라우터는 영구 메타데이터가 있는 OpenAI Files API 호환 파일 저장소를 제공합니다.

주요 기능: - 사이드카 JSON 파일이 있는 영구 메타데이터 저장소 - 서버 재시작 시 자동 복구 - 고아 파일 감지 및 정리 - 플러그 가능한 백엔드 (메모리/영구)

자세한 아키텍처 및 구현은 파일 저장소 가이드를 참조하세요.

이미지 생성 아키텍처¶

라우터는 자동 매개변수 변환과 함께 여러 백엔드 (OpenAI GPT Image, DALL-E, Google Gemini/Nano Banana)에 걸친 이미지 생성을 위한 통합 인터페이스를 제공합니다.

다중 백엔드 이미지 생성¶

┌─────────────────────────────────────────────────────────────────┐
│                   OpenAI 호환 요청                                │
│  POST /v1/images/generations                                     │
│  { "model": "...", "prompt": "...", "size": "1536x1024" }       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    모델 라우터 (image_gen.rs)                     │
│  • 모델 타입 감지 (GPT Image, DALL-E, Nano Banana)                │
│  • 적절한 핸들러로 라우팅                                          │
│  • 스트리밍 vs 비스트리밍 처리                                     │
└─────────────────────────────────────────────────────────────────┘
                   │                              │
        ┌──────────┘                              └──────────┐
        ▼                                                     ▼
┌───────────────────────────┐           ┌───────────────────────────┐
│    OpenAI 백엔드           │           │    Gemini 백엔드           │
│    (GPT Image, DALL-E)    │           │    (Nano Banana)           │
│                           │           │                            │
│  • 요청 패스스루          │           │  • Gemini API로 변환       │
│  • SSE 스트리밍 지원      │           │  • size → aspectRatio 매핑  │
│  • output_format 지원     │           │  • imageConfig 생성        │
└───────────────────────────┘           └───────────────────────────┘

OpenAI → Gemini 매개변수 변환¶

Nano Banana (Gemini) 모델을 사용할 때, OpenAI 스타일 매개변수가 자동으로 Gemini 네이티브 형식으로 변환됩니다:

크기에서 종횡비 매핑¶

요청 변환¶

OpenAI 형식 (입력):

{
  "model": "nano-banana",
  "prompt": "고요한 일본 정원",
  "size": "1536x1024",
  "n": 1
}

Gemini 형식 (변환됨):

{
  "contents": [
    {
      "parts": [{"text": "고요한 일본 정원"}]
    }
  ],
  "generationConfig": {
    "imageConfig": {
      "aspectRatio": "3:2",
      "imageSize": "1K"
    }
  }
}

변환 구현¶

변환은 src/infrastructure/backends/gemini/image_generation.rs에서 처리됩니다:

pub fn convert_openai_to_gemini(request: &OpenAIImageRequest)
    -> CoreResult<(String, GeminiImageRequest)>
{
    // 1. 모델 이름 매핑
    let gemini_model = map_model_to_gemini(&request.model);

    // 2. 크기를 종횡비 및 크기 카테고리로 파싱
    let parsed_size = parse_openai_size(&request.size, &request.model)?;

    // 3. imageConfig가 있는 Gemini 요청 빌드
    let gemini_request = GeminiImageRequest {
        contents: vec![GeminiContent { parts: vec![...] }],
        generation_config: Some(GeminiGenerationConfig {
            image_config: Some(GeminiImageConfig {
                aspect_ratio: Some(parsed_size.aspect_ratio.to_gemini_string()),
                image_size: Some(parsed_size.size_category.to_gemini_image_size()),
            }),
        }),
    };

    Ok((gemini_model, gemini_request))
}

스트리밍 이미지 생성 (SSE)¶

GPT Image 모델의 경우, 라우터는 스트리밍 이미지 생성을 위한 진정한 SSE 패스스루를 지원합니다:

┌─────────────┐                ┌─────────────┐                ┌─────────────┐
│   클라이언트 │────stream:true─▶│   라우터    │────stream:true─▶│   OpenAI    │
│             │                │             │                │             │
│             │◀───SSE 이벤트──│  패스스루   │◀───SSE 이벤트──│             │
└─────────────┘                └─────────────┘                └─────────────┘

SSE 이벤트 타입:

구현 (src/proxy/image_gen.rs):

async fn handle_streaming_image_generation(...) -> Result<Response, StatusCode> {
    // 1. 백엔드 요청에서 stream: true 유지
    // 2. bytes_stream()을 통해 스트리밍 요청 수행
    // 3. tokio 채널을 통해 SSE 이벤트 전달

    let (tx, rx) = tokio::sync::mpsc::unbounded_channel();

    tokio::spawn(async move {
        let mut stream = backend_response.bytes_stream();
        while let Some(chunk) = stream.next().await {
            // SSE 형식 파싱 (event:/data: 라인)
            // 클라이언트에 이벤트 전달
            for line in chunk_str.lines() {
                if let Some(event_type) = line.strip_prefix("event:") { ... }
                if let Some(data) = line.strip_prefix("data:") {
                    let event = Event::default().event(event_type).data(data);
                    tx.send(Ok(event));
                }
            }
        }
    });

    Ok(Sse::new(UnboundedReceiverStream::new(rx)).into_response())
}

GPT Image 모델 기능¶

라우터는 GPT Image 모델 (gpt-image-1, gpt-image-1.5, gpt-image-1-mini)에 대한 향상된 매개변수를 지원합니다:

모델 지원 매트릭스¶