결정 모델 (Decision Models)¶

결정 모델(Decision Model)은 자유 형식의 텍스트를 생성하는 대신, 단일 문서나 상태(state)에 대한 정형화된 질문들을 한 번의 추론(forward pass)으로 평가하고 각 질문에 대한 확률 분포를 반환하는 모델입니다.

Continuum Router는 두 가지 방식으로 결정 모델을 지원합니다.

• 클라이언트 API 제공: POST /v1/decisions (별칭 POST /v1/systemone) 엔드포인트를 통해 외부 클라이언트에 결정 추론 API를 직접 제공합니다.
• 내부 라우터 소비자(Consumer): 다음 다섯 가지 내부 기능에서 결정 모델을 호출합니다.
  1. 콘텐츠 안전 스크리닝 (가드레일 프로바이더)
  2. 요청 복잡도 및 도메인 분류 (스마트 라우팅 분류기)
  3. 에이전트 도구 호출 안전성 평가 (Action Safety)
  4. 응답 품질 기반 모델 폴백 (fallback.quality_check, 모델 폴백)
  5. 응답 후 품질 지표 계측 (usage.quality_judgment)

결정 모델이 반환하는 confidence는 출력 확률 분포의 집중도를 나타내는 통계치일 뿐, 실제 운영 환경에서의 정답 확률을 보장하지 않습니다. 따라서 차단이나 강제 라우팅(enforce)으로 전환하기 전에 반드시 자체 데이터셋으로 임계값을 보정(calibration)해야 합니다. 이 문서에 수록된 기본 임계값은 모두 저장소에 커밋된 기준 보정 실행에서 도출되었으며, 측정 정확도가 단순 최빈값 기준선(constant-answer baseline)을 넘지 못한 기능은 기본적으로 모니터링 전용(monitor, shadow, advisory) 모드로 동작합니다.

지원 모델 카탈로그¶

라우터는 네 가지 프로바이더 프로필(generic, typesafe, foundry, llama_cpp)을 통해 System One 프로토콜을 지원하며(프로바이더 프로필과 실험적 미디어 참고), 호스팅 서비스와 자체 호스팅 오픈 웨이트 모델을 아우르는 내장 메타데이터 카탈로그를 제공합니다.

와이어 프로토콜¶

POST /v1/decisions (또는 POST /v1/systemone) 요청은 model, 평가 대상 문서인 state(문자열, JSON 객체, JSON 배열, 또는 지원되는 llama_cpp 계열의 경우 null), 그리고 questions 맵을 받습니다. 각 질문은 다음 네 가지 타입 중 하나를 사용합니다.

• noul: 주어진 명제가 참일 확률(0.0~1.0)을 구하는 이진 판정 질문입니다. 선택적으로 criteria: {"true": ..., "false": ...}를 지정할 수 있습니다.
• choice: 1~255개의 이름 붙은 선택지(OpenJev는 1~52개)에 대한 확률 분포를 구하며, 최댓값 선택지인 choice, 각 선택지의 probabilities, 선택적 confidence를 반환합니다.
• score: 순서가 있는 등급(generic, foundry, llama_cpp는 2~10개 등급, typesafe는 1~10개 등급)에 대한 확률 분포를 구하며, 확률 가중 평균 인덱스인 score, 선택적 legend, probabilities, 선택적 confidence를 반환합니다.
• box: 정규화된 바운딩 박스 좌표(0.0~1.0 범위의 box: {top, bottom, left, right} 및 선택적 confidence)를 반환하며, protocol: typesafe에서 typesafe_images: true와 jev-1.14.0 (jev-preview)을 함께 설정했을 때 사용할 수 있습니다.

{
  "model": "jev-latest",
  "state": {"request": "Write a Rust function that parses a CSV file", "message_count": 1},
  "questions": {
    "domain": {
      "type": "choice",
      "instructions": "What domain does `request` belong to?",
      "criteria": {"general": "...", "code": "...", "reasoning": "..."}
    },
    "complexity": {
      "type": "score",
      "instructions": "How hard is `request`?",
      "criteria": ["trivial", "simple", "moderate", "complex", "expert"]
    }
  }
}

응답에는 요청한 질문 ID별 결과, 실제 처리에 사용된 model 이름, 그리고 usage.input_tokens와 usage.output_tokens가 포함됩니다.

내부 소비자 (Internal Consumers)¶

Continuum Router는 다음 다섯 가지 내부 기능에서 결정 모델을 호출합니다.

각 기능의 상세 설정은 가드레일, System One 분류기, Claude Code 연동, 모델 폴백 문서를 참고하십시오.

결정 호출의 사용량 계측¶

내부 소비자가 업스트림 서버로 보낸 모든 결정 호출(재시도 포함)은 상위 요청에 연결된 별도의 사용량 레코드로 기록되며, 소비자별로 다음과 같은 purpose 값을 갖습니다.

• guardrail: System One 가드레일 프로바이더
• classifier: 스마트 라우팅 분류기
• action_safety: Action Safety 평가기
• quality_judgment: usage.quality_judgment 및 fallback.quality_check
• client: 클라이언트가 직접 호출한 POST /v1/decisions 요청 (아키텍처 문서의 라우터 시작 호출 섹션 참고)

대상 블록의 count_toward_budgets 설정은 smart_routing_system_one_classifier_input_tokens_total 메트릭의 counted 레이블에만 영향을 줍니다.

사용량 품질 판정 (usage.quality_judgment)¶

usage.quality_judgment는 클라이언트에게 반환된 채팅 응답(비스트리밍 및 스트리밍 모두 포함)을 백그라운드에서 평가하고, 그 확률값(베이시스 포인트 단위)과 판정에 사용된 judge_model을 컨트롤 플레인 사용량 레코드에 첨부합니다. 클라이언트 응답 경로를 지연시키거나 수정하지 않으면서, Continuum Hub에서 모델별·API 키별·실험군별 응답 품질을 비교할 수 있게 해 줍니다.

비동기 실행과 late / skipped 집계 규칙¶

• 비차단 백그라운드 실행: 품질 판정은 응답이 끝난 뒤 별도의 비동기 태스크에서 실행되므로, 사용량 집계나 Hub 배치 전송을 블로킹하지 않습니다.
• late 판정 드롭: 사용량 레코드가 포함된 업로드 배치가 이미 확정(seal)된 뒤에 완료된 판정은 late로 집계되고 버려집니다. 응답이 느린 판정일수록 배치 마감 시각을 넘길 가능성이 높으므로, late 비율이 높으면 빠른 요청 위주로 품질 점수가 편향될 수 있습니다. late 비율을 줄이려면 control_plane.usage_push_interval_secs 주기를 늘리거나 지연 시간이 짧은 자체 호스팅 결정 모델을 사용하십시오.
• 스트리밍 샘플링: 스트리밍 응답은 입력 가드레일 직후 샘플링 여부를 결정하고, 스트림 종료 시점의 사용량 레코드가 생성되는 즉시 판정을 시작합니다. 메모리에는 클라이언트가 실제로 수신한 텍스트의 앞부분과 뒷부분만 max_reply_bytes 한도 내에서 유지하며, 추론(reasoning) 토큰은 포함하지 않습니다.
• 통합 stream 레이블: 모든 판정 결과 메트릭(usage_quality_judgments_total)에는 stream="true" 또는 stream="false" 레이블이 기록됩니다.

라우트별 평가 대상 추출 및 제외(skipped) 규칙¶

전체 설정 구문은 전체 설정 예제의 usage 블록을 참고하십시오.

fallback.quality_check와의 결정 호출 공유¶

비스트리밍 /v1/chat/completions 요청에서 다음 세 가지 조건이 모두 충족되면, fallback.quality_check와 usage.quality_judgment는 결정 모델을 두 번 호출하지 않고 한 번의 호출 결과를 공유합니다.

1. 두 기능이 모두 활성화되어 있고 동일한 target 블록을 지정한 경우
2. 두 기능의 max_request_bytes 및 max_reply_bytes 설정값이 동일한 경우
3. 현재 요청이 usage.quality_judgment로 도구 결과를 보내지 않는 경우 (include_tool_results: false이거나 현재 턴에 도구 결과가 없는 경우)

호출 공유 시 동작 방식은 다음과 같습니다.

• fallback.quality_check가 초기 응답을 검사할 때 answered, refusal, truncated와 함께 language_match(해당되는 경우)를 동일한 요청에 포함해 질의합니다. 이때 language_match 응답이 누락되거나 형식이 잘못되더라도 폴백 판정 자체는 실패하지 않습니다.
• 초기 응답이 품질 검사를 통과해 그대로 반환되면, usage.quality_judgment는 별도의 호출이나 max_in_flight 슬롯을 소비하지 않고 즉시 해당 응답 확률을 재사용합니다. 핸들러가 반환되는 시점에 이미 판정값이 준비되어 있으므로 late 누락도 발생하지 않습니다.
• 만약 공유 호출 응답에서 사용량 판정에 필요한 일부 질문의 답이 빠졌다면, usage.quality_judgment는 누락된 질문만 별도로 재질의하여 병합합니다(단, 재질의에서 다른 judge_model이 반환되면 invalid로 처리하고 버립니다).
• fallback.quality_check가 품질 미달로 판단해 다음 폴백 모델로 홉(hop)한 경우, usage.quality_judgment는 추가 호출 없이 skipped로 기록합니다.
• 폴백 체인에 다음 후보가 없거나 예산 소진·호출 실패 등으로 fallback.quality_check가 실행되지 않은 경우에는 usage.quality_judgment가 평소처럼 독립적인 백그라운드 호출을 수행합니다.
• 공유된 호출은 systemone_requests_total{consumer="fallback_quality"}로 집계되며, usage_quality_judgments_total{outcome}에는 샘플링된 요청당 하나의 결과가 그대로 기록됩니다.

클라이언트 결정 엔드포인트 제공 (/v1/decisions)¶

클라이언트는 라우터의 API 키 인증, 스코프, 속도 제한, 예산, 폴백 체인 정책 아래에서 POST /v1/decisions (별칭 POST /v1/systemone)를 직접 호출할 수 있습니다.

• 네이티브 전달: 요청한 model이 decisions.targets[]에 등록되어 있으면 해당 System One 서버로 요청을 직접 전달합니다.
• 채팅 모델 에뮬레이션: decisions.targets[]에 없는 모델 이름은 일반 채팅 모델에서 강제 도구 호출(emit_decision)을 통해 에뮬레이션됩니다. 에뮬레이션 응답은 원-핫(one-hot) 확률 분포를 반환하고 confidence를 생략하며, 호출자가 네이티브 확률 분포와 구분할 수 있도록 emulated: true를 표시합니다.

이 엔드포인트는 순수 프록시/에뮬레이터로 동작하며 라우터 내부 소비자의 임계값을 적용하지 않습니다. 자세한 요청/응답 스키마는 API 레퍼런스를 참고하십시오.

데이터 외부 전송(Egress) 및 운영 시 주의 사항¶

• 데이터 외부 전송(Egress): 모든 결정 호출은 요청에서 추출한 텍스트로 state 객체를 구성해 전송합니다.
  • 가드레일: 마지막 사용자 턴과 길이 제한이 적용된 최근 대화 이력(history_turns, max_turn_bytes).
  • 스마트 라우팅 분류기: 마지막 사용자 메시지와 시스템 프롬프트 앞부분 200자. /v1/chat/completions에서는 섀도 모드를 포함해 항상 입력 가드레일 단계 이후에 분류기 state를 구성하므로, 차단된 프롬프트는 전송되지 않고 마스킹된 프롬프트는 마스킹된 상태로 전송됩니다.
  • Action Safety: 실행하려는 도구 이름, 전체 인자(arguments), 사용자의 최신 지시문.
  • 응답 품질 폴백 및 사용량 품질 판정: 앞/뒤 길이 제한이 적용된 마지막 사용자 메시지와 어시스턴트 응답(usage.quality_judgment는 include_tool_results: true일 때만 현재 턴의 도구 결과를 추가).
  • 프롬프트나 응답 데이터를 외부 서드파티(예: 호스팅 TypeSafe Jev)로 전송할 수 없는 환경에서는 모든 소비자의 대상을 자체 호스팅 서버로 지정해야 합니다.
• 적대적 공격에 대한 한계: 결정 모델은 빠른 1차 스크리닝 및 관측 신호용 도구이며, 단독으로 적대적 탈옥 공격을 방어하는 용도가 아닙니다. 가드레일 보정 코퍼스 측정에서도 기본 Laya 체크포인트는 0.5 임계값 기준 대부분의 카테고리에서 단순 최빈값 기준선 이하의 점수를 기록했고, 비라틴 문자 텍스트를 높은 신뢰도로 오분류하는 경향을 보였습니다. enforce 경로에서는 결정 모델을 단독 차단기로 쓰지 말고 Llama Guard나 Qwen3Guard 같은 전용 안전 모델과 함께 배치하십시오.
• 언어 및 문자 체계(Script) 민감도: Laya의 english 체크포인트는 한글 등 비라틴 문자를 읽지 못합니다. 기본 laya-serve는 비라틴 문자 입력을 multilingual 체크포인트로 보내는데, 이 체크포인트는 영어와 한국어 라우팅 정확도가 상대적으로 낮습니다. 운영 적용 전에 반드시 영어(en), 한국어(ko), 비라틴(non_latin) 슬라이스를 각각 분리해 측정하십시오.

결정 모델 적합성 가이드¶

프로바이더 프로필과 실험적 미디어¶

각 System One 대상 블록에서는 모델 별칭과 무관하게 protocol 필드(generic, typesafe, foundry, llama_cpp)로 와이어 프로필을 명시적으로 선택합니다.

• generic (기본값): 텍스트 전용 System One 기본 계약입니다.
• typesafe: TypeSafe의 구조화된 질문 스키마와 선택적 기능 헤더(typesafe_images, typesafe_long_context)를 활성화합니다.
• foundry: Azure AI Foundry의 프로바이더 경로(/providers/microsoft/v1/systemone)와 배포 이름 체계를 사용합니다.
• llama_cpp: llama-server의 인라인 멀티모달 데이터 URL 및 모델 계열별 제약(model_family)을 활성화합니다.

decisions:
  enabled: true
  targets:
    - name: jev
      protocol: typesafe
      endpoint: https://api.typesafe.ai/v1/systemone
      api_key_env: TYPESAFE_API_KEY
      model: jev-1.14.0
      typesafe_images: false         # JSON assets 및 Box 질문 사용 시 true
      typesafe_long_context: false   # 장문 컨텍스트 개별 옵트인
    - name: microsoft-decision
      protocol: foundry
      endpoint: https://RESOURCE.services.ai.azure.com
      auth: api_key                 # auto 설정 시에도 Foundry는 api-key를 선택함
      api_key_env: AZURE_FOUNDRY_API_KEY
      model: support-decisions      # 카탈로그 별칭이 아닌 Foundry 배포 이름
    - name: local-decision
      protocol: llama_cpp
      endpoint: http://127.0.0.1:8080/v1/systemone
      model: local-decision
      model_family: generic         # openjev 지정 시 52개 choice 상한 적용

대상 설정 레퍼런스 (SystemOneTargetConfig)¶

decisions.targets[], guardrails.providers[].systemone, smart_routing.classifier.system_one, safeguards.action_safety.systemone, fallback.quality_check.target, usage.quality_judgment.target은 모두 아래의 동일한 대상 스키마를 공유합니다.

프로바이더 프로필 비교¶

프로필별 세부 규칙 및 요청 예시¶

Foundry 인증 및 전송 규칙¶

• 엔드포인트 정규화: 리소스 루트, /providers/microsoft, /providers/microsoft/v1, /providers/microsoft/v1/systemone은 모두 /providers/microsoft/v1/systemone으로 정규화됩니다. Foundry 프로필은 인라인 endpoint만 허용하며 backend: 참조는 거부합니다. 원격 엔드포인트는 반드시 HTTPS를 사용해야 하며, HTTP는 로컬 개발 및 테스트용 루프백 호스트(localhost, 127.0.0.0/8, ::1)에서만 허용됩니다.
• Entra 토큰 수명 주기: auth: entra는 클라이언트를 생성할 때 api_key_env 환경 변수에서 외부 발급 Entra 토큰을 읽어 Bearer 헤더로 전송합니다. 라우터가 직접 토큰을 발급받거나 자동 갱신하지 않으며, 만료된 토큰으로 인한 HTTP 401/403 응답은 재시도하지 않고 즉시 실패 처리합니다.

페이로드 크기 제한 및 TypeSafe box / assets¶

• 구조적 안전 한도: 개별 문자열 필드는 최대 8 KiB, JSON 중첩 깊이는 최대 64단계, score 등급은 최대 10개로 제한됩니다. 공개 엔드포인트(/v1/decisions)는 압축되지 않은 JSON을 최대 2 MiB까지 허용하며, 멀티파트 요청이나 압축된 요청 본문은 HTTP 415로 거부합니다.
• TypeSafe 이미지 및 box: typesafe_images: true를 설정하면 인라인 assets 맵을 사용할 수 있고 TypeSafe-Danger-Zone-Images: true 헤더가 전송됩니다. box 질문은 여기에 더해 model이 jev-1.14.0 또는 jev-preview로 명시되어야 합니다. 운영자가 비활성화한 기능을 클라이언트가 임의 헤더를 보내 활성화할 수는 없습니다.

{
  "model": "jev",
  "state": {"photo": "asset-photo-1"},
  "assets": {
    "asset-photo-1": {
      "type": "image",
      "format": "png",
      "data_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
    }
  },
  "questions": {
    "location": {
      "type": "box",
      "instructions": "Locate the red rectangle in photo."
    }
  }
}

box 응답은 0.0~1.0으로 정규화된 좌표(top, bottom, left, right)와 선택적 confidence를 반환합니다.

{
  "model": "jev-1.14.0",
  "answers": {
    "location": {
      "type": "box",
      "box": {"top": 0.12, "bottom": 0.64, "left": 0.2, "right": 0.85},
      "confidence": 0.91
    }
  },
  "usage": {"input_tokens": 310, "output_tokens": 12}
}

llama.cpp 멀티모달 입력¶

protocol: llama_cpp는 max_media_bytes(기본값 4 MiB, 최대 16 MiB) 한도 내에서 인라인 files/images 데이터 URL 또는 이미지/오디오 데이터 URL이 포함된 멀티모달 메시지 state를 허용합니다. 외부 http(s) 미디어 URL이나 로컬 파일 시스템 경로, 네이티브 비디오 전송은 거부됩니다.

{
  "model": "local-decision",
  "state": "Does this receipt show a total above $50?",
  "images": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
  ],
  "questions": {
    "over_fifty": {"type": "noul", "instructions": "Is the receipt total above $50?"}
  }
}

모델 탐색, 폴백 및 사용량 회계¶

• 모델 탐색 (/v1/models): 모델 페처는 TypeSafe의 GET /v1/models 응답 형식과 llama.cpp의 architecture.output_modalities 배열을 모두 정규화합니다. output_modalities에 "decisions"가 있으면 decisions 기능을 부여하고, Granite Switch 4.1처럼 "text"와 "decisions"를 모두 광고하는 모델에는 chat과 decisions 기능을 모두 유지합니다.
• 폴백 및 에뮬레이션 검증: 모든 폴백 홉마다 프로필 호환성을 검사합니다. 이미지 에셋, state: null, box 질문을 포함한 요청은 호환되지 않는 프로필이나 텍스트 전용 채팅 에뮬레이션으로 폴백할 수 없습니다. 카탈로그에서 decisions 전용인 모델은 반드시 네이티브 대상이 설정되어야 하며 채팅 에뮬레이션으로 대체되지 않습니다.
• 토큰 회계: 프로바이더의 출력 토큰 단가가 무료($0)이더라도 응답과 통계에는 반환된 input_tokens와 output_tokens가 모두 그대로 기록되며, 요금 계산 단계에서만 출력 단가 0원이 적용됩니다. 응답에 confidence가 없을 때 임의의 값을 만들어내지 않으며, confidence를 요구하는 내부 소비자는 보수적으로 폴백합니다.

스마트 라우팅 분류기 단계적 도입 (Rollout)¶

스마트 라우팅 분류기는 smart_routing.classifier.system_one 아래에서 동일한 프로바이더 프로필을 사용합니다. 실제 라우팅 결정을 넘기기 전에 안전하게 검증하려면 method: rule(또는 llm / hybrid)을 유지한 채 shadow: true로 시작하십시오.

# TypeSafe Jev (보정된 특정 버전을 고정)
smart_routing:
  classifier:
    method: rule
    system_one:
      shadow: true
      protocol: typesafe
      endpoint: https://api.typesafe.ai/v1/systemone
      api_key_env: TYPESAFE_API_KEY
      model: jev-1.14.0

# Microsoft-Decision-1 (model에는 Foundry 리소스의 배포 이름 지정)
smart_routing:
  classifier:
    method: rule
    system_one:
      shadow: true
      protocol: foundry
      endpoint: https://RESOURCE.services.ai.azure.com
      auth: api_key
      api_key_env: AZURE_FOUNDRY_API_KEY
      model: support-decisions

# 네이티브 llama.cpp (서버에 설정된 모델 별칭 지정)
smart_routing:
  classifier:
    method: rule
    system_one:
      shadow: true
      protocol: llama_cpp
      endpoint: http://127.0.0.1:8080/v1/systemone
      model: kev-local

주요 동작 규칙:

• 섀도 측정: 섀도 모드는 실제 생성 모델 선택을 바꾸지 않으면서 활성 분류기와의 일치율(smart_routing_shadow_agreement_total{field, agree}), 지연 시간, 토큰 사용량(purpose: classifier)을 기록합니다.
• 결정론적 폴백: method: system_one에서 응답 실패, 타임아웃, confidence 누락, 또는 min(confidence) < min_confidence가 발생하면 규칙 분류기 결과로 폴백합니다. method: hybrid_system_one에서는 신뢰도가 낮을 때 설정된 LLM 분류기를 먼저 시도하고, 그마저 실패하면 규칙 분류기 결과를 사용합니다.
• 생성 후보 풀 필터링: text/chat 기능 없이 decisions만 지원하는 모델은 티어 프로필에 이름을 올리더라도 생성 후보 풀에서 자동 제외되며, GET /admin/smart-routing/status의 excluded_incompatible_models에 별도로 집계됩니다.
• 캐시 무효화: 분류기 캐시 키에는 상태 텍스트, 대상 프로필, 요청 모델, 질문 묶음, 백엔드 토폴로지 세대(cache_target_identity)가 모두 포함되므로, 백엔드 비활성화나 자격 증명 회전 시 이전 캐시가 자동으로 무효화됩니다.

자체 트래픽에서 결정 모델 보정하기¶

결정 모델이 보고하는 confidence는 보정되지 않은 분포 집중도 통계치이므로, 운영 트래픽에서 enforce나 실제 라우팅을 켜기 전에 아래 절차에 따라 자체 코퍼스와 엔드포인트를 대상으로 보정을 수행해야 합니다.

1. 엔드포인트 기동¶

기본 설정인 make calibrate-systemone은 deploy/docker-compose.systemone.yml에 정의된 자체 호스팅 CPU laya-serve 컨테이너(Laya 체크포인트 3종 사전 로드, 127.0.0.1:8000 바인딩)를 자동으로 띄웁니다.

특정 Laya 체크포인트 하나만 고정해서 측정하거나 Kev 서버를 측정하려면 직접 엔드포인트를 먼저 기동하십시오.

# 단일 Laya 체크포인트 고정 실행 (기본 laya-serve는 문자 체계로 자동 라우팅함)
uv run --no-project --with 'laya-serve[inference]==0.1.1' \
  python scripts/systemone/laya_pinned_serve.py --checkpoint english --device cpu --port 8011

# Kev 서버 실행 (Apple Silicon에서는 MLX 자동 사용)
git clone https://github.com/jaredpalmer/kev && cd kev
uv sync --extra serve && uv run python -m kev.serve --run jaredpalmer/kev-0.8b --port 8008

2. 보정 실행¶

# 기본 compose 서비스(CPU)를 대상으로 세 소비자 전체 보정 및 임계값 도출
make calibrate-systemone

# 가장 작은 라우팅 코퍼스(200행)만 실행
SYSTEMONE_CONSUMERS=routing make calibrate-systemone

# 다른 엔드포인트를 대상으로 실행 (API 키는 SYSTEMONE_API_KEY_ENV에 지정한 환경 변수에서 읽음)
SYSTEMONE_ENDPOINT=http://127.0.0.1:8008/v1/systemone SYSTEMONE_RUN_LABEL=kev-0.8b \
SYSTEMONE_MODEL=kev-latest SYSTEMONE_CHECKPOINT=jaredpalmer/kev-0.8b \
SYSTEMONE_CHECKPOINT_REVISION=54f4f8777356cd5bbbb6c6919c657f26e6f2f6d8 \
  make calibrate-systemone

make calibrate-systemone은 scripts/systemone/calibrate-compose.sh를 통해 tests/systemone_calibration_test.rs의 소비자별 보정 테스트를 실행하고, 원시 응답과 도출된 임계값(derived.json)을 tests/fixtures/systemone/calibration/<date>/<label>/(또는 SYSTEMONE_REPORT_DIR)에 기록합니다. 동시성, 타임아웃, 실행 행 수는 SYSTEMONE_CONCURRENCY(기본값 1), SYSTEMONE_TIMEOUT_SECS(기본값 120), SYSTEMONE_LIMIT 환경 변수로 조절할 수 있습니다.

전체 코퍼스를 돌리지 않고 실제 엔드포인트의 최소 연동만 빠르게 확인하려면 다음 스모크 테스트를 실행하십시오.

SYSTEMONE_SMOKE_ENDPOINT=http://127.0.0.1:8000/v1/systemone \
SYSTEMONE_SMOKE_MODEL=laya-english \
SYSTEMONE_SMOKE_PROFILE=generic \
  cargo test --test systemone live_smoke_test::configured_native_endpoint_answers_a_text_decision -- --ignored --exact

3. 임계값 도출 규칙¶

tests/systemone_support/derive.rs는 고정된 격자(grid)를 탐색하여 최소 근거 요건을 만족하는 보수적인 임계값을 도출하며, 요건을 충족하지 못하면 벤더 기본값을 유지합니다.

• 가드레일 category_thresholds.<c> (차단): 양성 레이블이 최소 5개 이상이고 예측된 차단이 최소 3건 이상일 때, 차단 정밀도(precision)가 0.90 이상에 도달하는 0.50..=0.95(간격 0.05) 구간 내 최소 임계값.
• 가드레일 review_threshold (플래그): 비안전 행에 대한 행 단위 재현율(recall)을 0.90 이상으로 유지하는 0.05..=0.50 구간 내 최대 임계값.
• 분류기 min_confidence: 0.00..=1.00 구간에서 system_one -> rule 폴백 체인의 domain 및 complexity 평균 정확도를 극대화하는 임계값(동률 시 더 높은 임계값 선택). 어떤 임계값에서도 규칙 분류기 단독 정확도를 넘지 못하면 값을 도출하지 않습니다.
• Action Safety: action 선택 정확도가 최빈값 기준선을 넘는 경우에만 도출합니다. deny_threshold는 최소 3건 이상의 거부에서 거부 정밀도 0.90을 달성하는 0.30..=0.95 내 최소값이며, allow_threshold와 min_confidence는 block 레이블 오허용 0건, 허용 정밀도 0.95 이상, 최소 5건 이상 허용 조건에서 허용 건수를 극대화하는 조합입니다.

제공 기본값¶

아래 기본값은 기준 실행인 2026-09-24/laya-serve-compose-cpu(CPU 환경의 기본 laya-serve 0.1.1, Laya 번들 리비전 55cf4c4ebb4e, all 슬라이스)에서 도출되었습니다. tests/systemone_calibration_test.rs의 shipped_defaults_match_the_reference_run_and_the_docs 테스트가 라이브러리 상수와 영문/국문 문서의 이 표가 일치하는지 자동으로 검증합니다.

각 항목은 guardrails.providers[].options.review_threshold, guardrails.providers[].category_thresholds, smart_routing.classifier.system_one.min_confidence, safeguards.action_safety.systemone.{allow_threshold, deny_threshold, min_confidence}에 대응하며, 설정 파일에 명시한 값이 항상 우선합니다.

모니터 전용 판정¶

기준 실행(laya-serve-compose-cpu)에서 측정 정확도가 최빈값 기준선 이하인 기능이나 언어 슬라이스는 임계값과 관계없이 모니터링 전용 모드를 기본값으로 유지합니다.

• 가드레일 (모든 슬라이스에서 mode: monitor 권장): 도출된 기본값에서도 정상(clean) 행의 70.8%가 플래그 또는 차단되며(all 슬라이스, 차단 정밀도 0.652), 한국어(ko)와 비라틴(non_latin) 슬라이스에서는 정상 행의 92% 이상이 플래그됩니다. 기본값인 mode: monitor를 유지하고 카테고리별 점수를 보조 관측 신호로 활용하십시오.
• 스마트 라우팅 분류기 (한국어/비라틴 트래픽은 shadow: true 권장): 전체(all) 및 영어(en) 슬라이스에서는 min_confidence: 0.15를 적용한 system_one + rule 체인이 규칙 분류기 단독보다 높은 정확도를 보입니다(en: 0.628 대 0.544, all: 0.510 대 0.475). 반면 한국어(ko: 0.405 대 0.487)와 비라틴(non_latin: 0.418 대 0.428) 슬라이스에서는 Laya가 규칙 분류기를 넘지 못하므로, 한국어 비중이 높은 환경에서는 한국어 성능이 검증된 모델(예: kev-0.8b, 한국어 체인 정확도 0.639)을 쓰지 않는 한 method: rule과 shadow: true를 유지하는 것이 안전합니다.
• Action Safety (mode: advisory 권장): tool_calls.jsonl에서 action 정확도가 0.319로 최빈값 기준선(0.440)에 미치지 못하므로 기본값인 mode: advisory를 유지하십시오.
• 미측정 대상 및 소비자: 호스팅 TypeSafe Jev, Microsoft-Decision-1, kev-4b, 그리고 fallback.quality_check(기본 임계값 0.8, mode: shadow)는 오프라인 기준 실행에 포함되지 않았습니다. 운영 적용 전에 반드시 대상 엔드포인트에서 직접 보정을 수행하고, jev-latest처럼 예고 없이 갱신되는 별칭 대신 명시적 버전(jev-1.14.0 등)을 고정하십시오.

결과 (2026-09-24)¶

아래 요약 표는 tests/fixtures/systemone/calibration/2026-09-24/에 커밋된 세 코퍼스의 실행 결과에서 생성되었습니다.

• guardrail.jsonl: 총 244행 (실제 재생 223행: 영어 111행, 한국어 66행, 비라틴 106행)
• routing.jsonl: 총 200행 (영어 90행, 한국어 79행, 비라틴 104행)
• tool_calls.jsonl: 총 207행 (영어)

질문별 상세 Brier 점수, ECE, AUROC 및 슬라이스별 전체 표를 원시 JSON에서 다시 출력하려면 python3 scripts/systemone/results_tables.py 2026-09-24를 실행하십시오.

평가 엔드포인트¶

소비자별 지연 시간 및 입력 토큰 요약¶

라우팅 섀도 비교¶

언어 슬라이스별로 측정한 System One 단독 정확도, 규칙 분류기 단독 정확도, 두 분류기 간 일치율(smart_routing_shadow_agreement_total), 그리고 system_one -> rule 폴백 체인의 결합 정확도입니다.