스마트 라우팅 거버넌스 (Smart Routing Governance)¶

Continuum Hub에 등록된 라우터는 정책 엔벨로프(policy envelope)를 통해 스마트 라우팅 정책을 전달받을 수 있습니다. 이 구조에서 Continuum Hub는 라우팅 의도(티어 구성, 도메인/복잡도 규칙, 모델 프로필, 분류기 방식)를 선언하고, 로컬 라우터는 실제 인프라 배선과 실행 제어권(백엔드 URL, 인증 정보, 기능 활성화 스위치, 런타임 한도)을 온전히 유지합니다.

로컬 설정 스키마 자체에 대한 자세한 설명은 스마트 라우팅 문서를 참고하십시오.

사전 요구 사항¶

허브 기반 스마트 라우팅 거버넌스가 동작하려면 다음 세 가지 조건이 모두 충족되어야 합니다. 하나라도 충족되지 않으면 허브 정책은 적용되지 않으며, 로컬 smart_routing: 설정만 단독으로 사용됩니다.

• control-plane 기능 빌드: control-plane Cargo 기능이 활성화된 바이너리여야 합니다(모든 공식 릴리스 바이너리에 기본 포함).
• 컨트롤 플레인 정책 활성화: control_plane.enabled: true 및 control_plane.policy.enabled: true가 모두 설정되어 있어야 합니다.
• 설정 관리자(ConfigManager) 연결: 설정 파일로 기동된 표준 CLI 바이너리이거나, 빌더에서 ConfigManager가 연결된 인스턴스여야 합니다. 설정 관리자 없이 구성된 임베디드 라이브러리 빌드(ContinuumRouter::from_config, serve_embedded)나 핫 리로드를 비활성화한 빌더는 거버넌스 조정기(reconciler)를 연결하지 않으며 smart_routing_policy_v1 및 guardrail_policy_v1 기능을 광고하지 않습니다(라이브러리 사용 참고).

버전 호환성¶

허브 기반 스마트 라우팅 거버넌스는 라우터 v1.32.0부터 지원됩니다.

• v1.32.0 미만 라우터: 엔벨로프의 smart_routing 필드를 무시하고 smart_routing_policy_v1 기능을 광고하지 않습니다. 허브는 확인 응답을 기다리지 않고 해당 라우터를 즉시 unsupported 상태로 표시합니다.
• 구버전 허브 + v1.32.0 이상 라우터: 허브가 smart_routing 필드를 보내지 않으면, 라우터는 smart_routing_policy_v1 기능만 광고하면서 로컬 smart_routing: 설정으로 동작합니다.

혼합 버전 플릿에서의 스마트 라우팅 및 가드레일 거버넌스 전체 호환성 표는 거버넌스 호환성 매트릭스를 참고하십시오.

허브에서 지정할 수 있는 항목¶

허브가 전달하는 정책 스키마는 아래의 고정된 필드로만 구성됩니다(정규 JSON 인코딩 기준 최대 256 KiB). 모든 필드는 선택 사항이며, 생략된 필드(또는 빈 배열)는 로컬 설정값을 그대로 유지합니다.

프로토콜 참고 사항:

• 티어 이름 표기: 네트워크 전송 시 티어는 로컬 설정의 숫자(1, 2, 3) 대신 이름(flagship, standard, lightweight)으로 전달됩니다.
• 티어별/조직별 조건 제외: 라우터 로컬 전용 조건인 when.key_tier와 when.org는 허브 규칙에서 사용할 수 없습니다.

로컬 전용 설정 (허브 제어 불가 항목)¶

백엔드 인프라 연결과 운영 안전 한도는 언제나 로컬 라우터가 단독으로 관리합니다. 아래 항목들은 거버넌스 프로토콜에 존재하지 않으므로 허브 정책이 설정하거나 덮어쓸 수 없으며, 허브로 역전송되지도 않습니다.

• 기능 활성화 스위치 (smart_routing.enabled): 로컬에서 enabled: false로 설정하면 항상 비활성 상태가 유지되며, 허브 정책이 스마트 라우팅을 강제로 켤 수 없습니다.
• 백엔드 URL 및 자격 증명 (backends[]): 모든 백엔드의 url, api_key, auth, type 및 전송 설정. 허브는 분류기 백엔드의 논리적 이름(backend)만 지정할 수 있으며, 라우터는 해당 이름을 로컬 backends[] 목록에서 찾아 연결합니다.
• 부하 관리 및 비용 메타데이터: load_management, default_tier, debug_headers, 모델 프로필의 토큰당 비용 필드(cost_per_1k_input_tokens, cost_per_1k_output_tokens).
• 분류기 세부 튜닝 및 엔드포인트: classifier.llm 운영 파라미터(타임아웃, 재시도, temperature, 프롬프트, 캐시), classifier.rule 설정, 그리고 classifier.system_one 결정 모델 대상(endpoint, api_key_env).
• 로컬 전용 규칙 조건: when.key_tier 및 when.org.

허브 정책과 로컬 설정의 합성 (Composition)¶

라우터는 허브에서 전달된 정책과 로컬 smart_routing: 섹션을 다음 규칙에 따라 합성합니다.

분류기 백엔드 해석 및 검증 규칙¶

합성된 정책이 LLM 기반 분류기(llm, hybrid, hybrid_system_one)를 사용할 때는 다음 검증이 적용됩니다.

• 백엔드 이름 해석: classifier.llm.backend 이름(허브 지정값 또는 로컬 고정값)은 라우터의 현재 유효 backends[] 목록(설정 동기화로 추가된 백엔드 포함)에서 조회합니다.
• 적격성 검사: internal: true 백엔드도 사용할 수 있습니다. 반면 존재하지 않거나 enabled: false인 백엔드 이름이 지정되면 정책 적용을 거부하며, 라우터가 임의로 다른 백엔드를 대체 선택하지 않습니다.
• 백엔드 고정 필수: 허브 정책이 LLM 기반 분류 방식을 활성화하면서 허브와 로컬 어느 쪽에도 classifier.llm.backend를 지정하지 않은 경우, 운영자가 의도하지 않은 일반 백엔드로 프롬프트가 전송되는 것을 막기 위해 해당 정책을 거부합니다.

원자적 재계산¶

로컬 설정이 핫 리로드되거나 새로운 허브 정책이 도착할 때마다 합성 결과가 즉시 다시 계산됩니다. 변경 사항은 티어 레지스트리, 스마트 라우터, 분류기, 부하 모니터에 원자적으로 한꺼번에 반영되므로 처리 중인 요청이 반쪽짜리 정책을 참조하는 일은 없습니다.

합성 예시¶

로컬 설정:

backends:
  - name: primary
    type: vllm
    url: http://vllm.internal:8000
    models: [big-model, small-model]
  - name: guard-classifier
    type: vllm
    url: http://classifier.internal:8000
    api_key: ${CLASSIFIER_API_KEY}
    internal: true
    models: [judge]

smart_routing:
  enabled: true
  virtual_model: auto
  intercept_all: true
  classifier:
    method: rule
  routing_policies:
    - name: local_all_light
      when: {}
      route_to:
        tier: 3
  model_profiles:
    - model: big-model
      tier: 1
      cost_per_1k_input_tokens: 0.010
    - model: small-model
      tier: 3
      cost_per_1k_input_tokens: 0.001

정책 엔벨로프로 수신된 허브 정책 본문:

{
  "schema_version": 1,
  "routing_policies": [
    { "name": "hub_code_to_flagship", "when": { "domain": ["code"] }, "route_to": { "tier": "flagship" } },
    { "name": "hub_default", "when": {}, "route_to": { "tier": "standard" } }
  ],
  "model_profiles": [
    { "model": "big-model", "tier": "flagship", "domains": ["code", "reasoning"] },
    { "model": "small-model", "tier": "standard" }
  ],
  "classifier": { "backend": "guard-classifier", "model": "judge", "method": "hybrid" },
  "intercept_all": false
}

라우터에서 최종 실행되는 설정:

만약 동일한 허브 정책이 도착했더라도 로컬 설정이 smart_routing.enabled: false라면 스마트 라우팅은 동작하지 않습니다(auto는 그대로 백엔드로 전달되고 분류기는 호출되지 않음). 이 경우 운영자가 로컬에서 enabled: true로 켜기 전까지 허브에는 smart_routing_unavailable 상태가 보고됩니다.

3단계 정책 전달 상태¶

정책 엔벨로프의 smart_routing 필드는 가드레일 정책과 동일하게 세 가지 상태를 구분해 전달합니다.

전달 및 메모리 유지 규칙:

• 해제 확인 응답: 정책이 명시적으로 해제({})되면 라우터는 해제된 정책의 정규 다이제스트(canonical digest)로 확인 응답을 보내므로, 허브 화면에서 해당 라우터가 pending이나 stale에 머무르지 않고 즉시 수렴합니다.
• 메모리 전용 보관: 허브 정책은 디스크에 기록되지 않고 메모리에만 유지됩니다. 라우터가 재시작되면 우선 로컬 smart_routing: 설정만으로 기동한 뒤, 다음 하트비트/동기화 주기에서 허브 정책을 다시 복원합니다.

정책 거부 사유 및 폴백 동작¶

라우터가 허브 정책을 적용할 수 없을 때는 warn 로그를 남기고 세 가지 거부 코드 중 하나를 허브에 보고합니다. 이때 와이어 검증 단계에서 거부되었는지, 합성/실행 단계에서 거부되었는지에 따라 폴백 동작이 달라집니다.

smart_routing_unavailable 상세 발생 조건¶

문법적으로 유효한 허브 정책이라도 다음 경우에는 실행할 수 없으므로 smart_routing_unavailable로 거부됩니다.

• 로컬 smart_routing.enabled가 false인 경우
• 지정된 classifier.llm.backend가 로컬 backends[]에 없거나 enabled: false인 경우, 또는 LLM 기반 분류 방식을 선택했으나 허브와 로컬 어디에도 분류기 백엔드가 지정되지 않은 경우
• 라우팅 규칙의 대상(route_to)이 티어가 아닌 특정 model ID로 지정된 경우
• 합성 결과가 smart_routing 자체 검증을 통과하지 못한 경우 (예: 로컬에 classifier.system_one 대상 블록이 없는데 method: system_one을 지정한 경우)
• 합성 결과가 섹션 간 교차 검증을 위반한 경우 (예: 허브의 virtual_model 이름이 로컬 model_experiments[].model과 충돌하는 경우)

정책 저장소는 smart_routing_unavailable로 거부된 선언도 메모리에 보관하고 있으므로, 이후 로컬 설정을 수정해 실행 조건이 충족되면(예: 누락되었던 분류기 백엔드를 핫 리로드로 추가) 새 엔벨로프를 기다리지 않고 즉시 활성(active) 상태로 전환됩니다.

허브에 보고되는 전파 상태¶

라우터는 스마트 라우팅 조정기가 연결되어 있으면(로컬 enabled: false일 때 포함) smart_routing_policy_v1 기능을 광고하며, 조정기가 합성된 정책을 실제 런타임 컴포넌트에 적용한 뒤에야 해당 다이제스트를 확인 응답합니다.

Continuum Hub는 라우터의 보고를 바탕으로 다음 다섯 가지 전파 상태를 표시합니다.

하트비트의 정책 거부 코드 슬롯은 가드레일 트랙과 스마트 라우팅 트랙이 하나를 공유합니다. 두 트랙에서 동시에 거부가 발생하면 가드레일 거부 코드가 우선 보고됩니다(가드레일 가이드의 허브 보고 섹션 참고).

로컬 편집 및 Admin API 동작¶

허브 정책이 적용 중일 때 로컬 설정 리로드와 Admin API는 다음과 같이 동작합니다.

• 파일 핫 리로드 및 PUT /admin/smart-routing/{policies,model-profiles}:
  • 변경 사항은 로컬 설정 계층에만 기록된 뒤 합성을 다시 트리거하며, 실행 중인 컴포넌트에 직접 덮어쓰거나 허브 설정값을 로컬 설정으로 복사하지 않습니다.
  • 허브가 지정하지 않은 필드를 로컬에서 수정하면 즉시 반영되고, 허브가 지정한 필드를 수정하면 합성 단계에서 여전히 허브 값이 우선합니다(PUT 응답에 "hub_governed": true가 표시됨).
  • PUT /admin/smart-routing/policies 요청에서 생략된 필드(virtual_model, intercept_all)는 합성된 런타임 값이 아니라 로컬 설정 섹션의 기존 값으로 채워집니다.
  • 핫 리로드 채널 없이 빌드된 라우터가 허브 거버넌스를 받는 상태라면, 반영될 수 없는 수정을 승인하는 대신 HTTP 503 ({"error": {"code": "hub_governed_no_config_channel", "section": "smart_routing", ...}})을 반환합니다.
• 설정 조회 (config show vs. GET /admin/smart-routing/*):
  • continuum-router config show와 디스크의 설정 파일에는 언제나 운영자가 직접 작성한 로컬 설정만 표시됩니다.
  • GET /admin/smart-routing/policies와 GET /admin/smart-routing/model-profiles는 실제 실행 중인 스마트 라우터와 티어 레지스트리를 읽으므로, 허브 거버넌스 아래에서는 합성이 완료된 규칙, 프로필, virtual_model, intercept_all 값을 반환합니다.

읽기 전용 허브 인벤토리 (smart_routing_inventory)¶

컨트롤 플레인 에이전트가 활성화되어 있으면, 라우터가 smart_routing_policy_v1 기능을 광고하는지 여부와 무관하게 등록 요청과 모든 하트비트에 현재 실행 중인 라우팅 구성을 요약한 읽기 전용 smart_routing_inventory 블록이 포함됩니다.

비활성 상태 보고 및 프라이버시 보장:

• 비활성 상태 명시: 스마트 라우팅이 꺼져 있는 라우터는 블록을 생략하지 않고 enabled: false, 개수 0, classifier_backend 없음, intercept_all: false로 명시해 보고합니다(블록 자체가 생략되는 경우는 이 기능을 지원하지 않는 구버전 라우터이거나 식별자 길이가 256바이트를 초과해 직렬화에서 제외된 경우뿐입니다).
• 메타데이터만 전송: 인벤토리에는 개수와 최상위 식별자 이름만 포함됩니다. 라우팅 규칙의 세부 조건이나 대상, 모델/프로필 목록, 분류기 프롬프트, System One 엔드포인트 URL 및 api_key_env 이름은 절대 외부로 전송되지 않습니다.