LLM 제공자 호환성

​

제공자 감지

1. 명시적 제공자 (DB ModelConfig.provider 필드에서) — 최우선 순위. 제공자가 URL의 알려진 도메인과 일치하면 api_base가 반환되지 않습니다(LiteLLM이 네이티브로 라우팅). 그렇지 않으면 api_base가 릴레이 URL로 설정됩니다.
2. 도메인 매칭 KNOWN_DOMAINS 대비 — 공식 API 엔드포인트는 호스트명으로 인식됩니다.
3. URL 경로 힌트 PATH_PROVIDER_HINTS 대비 — UniAPI와 같은 릴레이 플랫폼에서 경로의 /claude 또는 /anthropic이 업스트림 프로토콜을 나타냅니다.
4. 폴백 — openai/ 접두사(일반 OpenAI 호환).

​

tool_choice — 네 가지 모드

​

tool_choice가 사용되는 곳

​

ReAct 엔진 — tool_choice=“auto”

​

structured_llm_call — tool_choice=forced

​

구조화된 출력: 네 가지 보장 수준

​

T1과 T2는 서로 대체할 수 없습니다

​

T2의 비용

• 스키마의 부분 집합. OpenAI의 strict mode에서는 모든 객체에 additionalProperties: false를 지정하고 모든 속성을 required에 나열해야 합니다. 선택 사항은 required에서 생략하는 대신 null과의 유니온으로 표현합니다. 루트는 객체여야 합니다. 전체 속성 수와 중첩 깊이에도 제한이 있습니다. 직접 작성한 스키마 대부분은 사용 가능해지기 전에 수정이 필요합니다.
• 문법 컴파일. 새로운 스키마를 포함하는 첫 번째 요청은 provider 측에서 일회성 컴파일 지연을 발생시킵니다. 안정적인 스키마를 재사용하면 이 비용을 분산할 수 있지만, 요청마다 새로운 스키마를 생성하면 그렇지 않습니다.
• 새로운 실패 지점. 응답하지 않는 모델은 스키마 형태의 객체 대신 refusal을 반환하므로, 호출자는 이를 처리하는 분기를 추가해야 합니다.

​

어떤 tier도 보장하지 않는 것

​

FIM One의 위치

1. 체인에는 스키마로 제한된 대체 단계가 없습니다. Level 1이 실패하면 다음 단계는 json_object이며, 이는 텍스트가 파싱된다는 것만 보장합니다. 필드를 계속 강제하는 중간 단계는 없습니다.
2. Level 1의 보장은 이름이 암시하는 것보다 약합니다. strict가 없으면 네이티브 함수 호출은 2024년 이전의 비엄격 방식으로 동작합니다. 모델은 일반적으로 스키마를 따르지만, 필수 필드를 누락하거나, 존재하지 않는 키를 만들거나, 숫자로 선언된 위치에 문자열을 반환하는 것이 방지되지는 않습니다.
3. anthropic/ 경로에서는 Level 2가 실제로 T3가 아닙니다. Anthropic Messages API에는 response_format이 없으므로 LiteLLM은 assistant 프리필을 삽입해 JSON 모드를 에뮬레이션합니다. 이는 프롬프트 계층의 장치이므로 실질적인 보장은 T4와 T3 사이에 있으며, T3 수준의 보장을 제공하지 않습니다. 아래에 설명된 Bedrock 프리필 문제는 이 에뮬레이션이 명시적으로 실패하는 경우입니다. 더 조용한 문제는 매개변수 이름이 암시하는 보장이 애초에 제공되지 않았다는 점입니다.
4. 이후 결과를 스키마에 대해 검증하는 과정이 없습니다. jsonschema는 의존성에 포함되어 있지 않습니다. 수행되는 검사는 무엇이든 선택적 parse_fn 내부의 호출 지점별 검사이며, 엄격성은 호출 지점마다 다릅니다.
5. 실패가 드러나지 않고 흡수됩니다. 거의 모든 호출자가 default_value를 전달하므로, 체인을 모두 소진해도 예외가 발생하는 대신 그럴듯해 보이는 객체가 반환됩니다. StructuredCallResult.level_used는 값을 생성한 단계를 기록하지만, 어떤 호출 지점에서도 이를 읽지 않습니다. 또한 default_value 경로에서는 실제로 아무것도 생성되지 않은 체인인데도 plain_text로 보고합니다.

structured_llm_call: fn=classify_mode level=native_fc attempt=first calls=1
structured_llm_call: fn=annotate_tables level=json_mode attempt=reformat_retry calls=3

​

각 tier의 Provider 지원

​

Bedrock prefill 함정

{"role": "assistant", "content": "{"}

ValidationException: This model does not support assistant message prefill.
The conversation must end with a user message.

1. 모델이 anthropic/ 접두사로 해석됩니다(도메인 일치 또는 URL 경로 힌트를 통해).
2. response_format={"type":"json_object"}이 전달됩니다(structured_llm_call의 json_mode 코드 경로).
3. 실제 백엔드는 AWS Bedrock입니다(프리필을 거부함).

​

해결 방법: json_mode_enabled

• DB로 구성된 모델: 관리자 → 모델 → 고급 설정에서 토글합니다. 이 플래그는 ModelProviderModel.json_mode_enabled에 저장되며 기본값은 TRUE입니다.
• ENV로 구성된 모델: 환경에 LLM_JSON_MODE_ENABLED=false를 설정합니다.
• 효과: 비활성화하면 abilities["json_mode"]가 False를 반환하므로 response_format이 전달되지 않고, 프리필도 수행되지 않아 Bedrock이 작동합니다. 성능 저하 체인은 native_fc → plain_text가 되며, 문제가 발생하는 json_mode 호출을 완전히 건너뜁니다.
• 건너뛰기의 비용: 시스템 프롬프트가 JSON 형식으로 반환하도록 요청하고 최신 모델에서는 extract_json()이 자유 형식 콘텐츠를 안정적으로 파싱하므로, 실제로 모델은 여전히 유효한 JSON을 반환합니다. 손실되는 것은 출력이 아니라 보장입니다. 이제 체인은 T4에서 끝나며, 결과를 제약하는 것은 프롬프트뿐입니다. anthropic/ 라우트에서는 에뮬레이트된 JSON 모드가 디코더 수준의 보장을 제공한 적이 없으므로 이러한 손실이 보이는 것보다 작습니다.

​

Thinking models + forced tool_choice

tool_choice 'specified' is incompatible with thinking enabled

​

해결책: tool_choice_enabled

• DB 구성 모델: Admin → Models → Advanced → “Native Function Calling”에서 토글합니다. 플래그는 ModelProviderModel.tool_choice_enabled에 저장됩니다 (기본값 TRUE).
• ENV 구성 모델: 환경에서 LLM_TOOL_CHOICE_ENABLED=false를 설정합니다.
• 효과: 비활성화되면 abilities["tool_choice"]는 False를 반환 → 저하 체인이 Level 2 (json_mode) 또는 Level 3 (plain_text)에서 시작되며, native_fc를 완전히 건너뜁니다. 이는 호환되지 않는 모델에 대한 구조화된 호출당 약 10초의 페널티를 제거합니다.
• ReAct 에이전트 영향 없음: tool_choice_enabled는 structured_llm_call에서만 강제 도구 선택을 제어합니다. ReAct 엔진은 tool_choice="auto" (모델이 자유롭게 결정)를 사용하며, 이 설정과 관계없이 모든 모델에서 작동합니다.

​

Provider Capability Matrix

​

표 A: 프로토콜 라우팅

• store=false는 업스트림에서 대화 상태를 저장하지 않도록 하며, include=["reasoning.encrypted_content"]는 암호화된 페이로드를 반환하도록 요청합니다. include가 없으면 추론 항목은 비어 있는 상태로 도착하고, 재생은 아무런 표시 없이 작동하지 않게 됩니다.
• 재생할 추론 항목에서는 서버 측 id를 제거해야 합니다. store=false이면 업스트림에 아무것도 저장되지 않으므로, id를 그대로 돌려보내면 Item with id 'rs_...' not found. Items are not persisted when 'store' is set to false 오류가 발생합니다. encrypted_content 블롭에 상태가 자체적으로 담겨 있으므로 id를 제거해도 손실되는 것은 없습니다(sanitize_reasoning_item).

​

Table B: 충돌 및 해결 방법

​

Table C: Thinking protocol

​

Relay/proxy gotchas

​

모델별 권장 구성

# Disable native_fc globally (for thinking-model-only deployments)
LLM_TOOL_CHOICE_ENABLED=false

# Disable json_mode globally (for Bedrock relay deployments)
LLM_JSON_MODE_ENABLED=false

​

추론 노력 및 사고 구성

1. 온도는 자동으로 처리됩니다. 사고가 활성화된 anthropic/ 경로에서 _build_request_kwargs는 temperature를 1.0으로 고정합니다. 이는 Bedrock이 요구하는 값입니다. 샘플링 매개변수를 완전히 거부하는 모델(Opus 4.7 및 4.8, Fable 5, Mythos 5)은 사고 여부와 관계없이 요청에서 temperature가 제거됩니다. 이를 위해 LLM_TEMPERATURE=1을 수동으로 설정하지 마세요.
2. GPT-5.x는 가능한 경우 도구와 추론을 함께 유지합니다. FIM One은 GPT-5.x에 대해 먼저 Responses 브리지를 조사합니다. 왜냐하면 그것이 둘을 결합하는 유일한 표면이기 때문입니다. 사용 가능한 /v1/responses 경로가 없는 엔드포인트는 채팅 완성으로 폴백하고, 판정은 엔드포인트별로 캐시되며, 해당 경로에서 tools를 전달하는 요청은 명시적 reasoning_effort none을 전송합니다. 필드를 생략하는 것은 동등하지 않습니다. 서버 기본값이 none이 아니기 때문입니다.

​

구조화된 출력을 위한 방어적 파싱

1. 배열 대신 단일 객체. 일부 모델은 배열 {"steps": [{"id": "1", "task": "..."}]} 대신 {"steps": {"id": "1", "task": "..."}} (단일 스텝 객체)를 반환합니다. 파서는 id 또는 task 키를 확인하여 이를 감지하고 객체를 리스트로 래핑합니다.
2. 이중 인코딩된 JSON 문자열. 구조화된 출력이 json_mode (스키마 강제가 없음)로 폴백될 때, 일부 제공자는 steps 값을 네이티브 배열 대신 JSON 문자열로 반환합니다 — 예: {"steps": "[{\"id\": \"1\", ...}]"}. 이 문자열에는 표준 json.loads를 깨뜨리는 리터럴 줄바꿈 (모델의 포매팅에서 발생)이 포함될 수도 있습니다. 파서는 extract_json_value() (이는 _repair_json_strings를 포함)를 사용하여 다음을 처리합니다:
   • JSON 문자열 값 내의 리터럴 줄바꿈
   • 잘못된 이스케이프 시퀀스 (LaTeX 또는 코드 콘텐츠에서 일반적)
   • 호환성 계층의 기타 직렬화 특이성
3. 누락된 steps 래퍼. 모델이 steps 래퍼 키 없이 최상위 객체로 단일 스텝을 반환할 수 있습니다. 파서는 루트 레벨에서 id와 task를 감지하고 그에 따라 래핑합니다.

​

프롬프트 캐싱 (크로스 제공자)

​

아키텍처

• PromptSection — 정적 content: str 또는 동적 content: Callable을 가진 명명된 조각
• PromptRegistry — 메모이제이션된 저장소 (정적 섹션은 한 번만 렌더링되고, 동적 섹션은 호출마다 다시 렌더링됨)
• DYNAMIC_BOUNDARY — 레지스트리가 마지막 정적 섹션과 첫 번째 동적 섹션 사이에 삽입하는 센티널 마커로, 호출자가 캐시 중단점에서 렌더링된 提示词을 분할할 수 있도록 함

• 정적 접두사 (~提示词의 95%) — 정체성, 핵심 지침, 도구 설명
• 동적 접미사 — 현재 날짜/시간, 요청별 언어 지시문, 인계 컨텍스트

​

기능 감지

​

제공업체 간 지원 범위

​

관찰성

"cache": {
  "read_tokens": 1067,
  "creation_tokens": 0
}

​

멀티턴 캐시 ROI

​

추론 재생 정책 (모델 없는 정확성)

​

네 가지 정책

• anthropic_thinking — Claude 계열 (anthropic/, bedrock/anthropic, vertex_ai/claude). 사고 블록은 반드시 signature를 첨부하여 재생해야 합니다. Anthropic은 서명이 누락되거나 변경되면 이후 턴을 거부합니다.
• informational_only — CoT를 생성하지만 재생을 기대하지 않는 모델: DeepSeek 추론 모드 (V3.2의 deepseek-reasoner, 그리고 프래그먼트 테이블이 여전히 일치하는 이전 deepseek-r1 및 R1-Distill ID), Qwen QwQ, Gemini flash-thinking, OpenAI o1 / o3 / o4. 이들의 문서는 명시적으로 “메시지 히스토리에서 reasoning_content를 다시 보내지 마세요”라고 말합니다. 어쨌든 전송하면:
  • 제공자 계약을 위반합니다 (향후 버전에서 거부하기 시작할 수 있음)
  • 자동 접두사 캐시를 조용히 무효화합니다 — 메시지 바이트가 매 턴마다 변경되어 해시를 깨뜨립니다
• openai_responses — GPT-5.x, gpt-5 프래그먼트에서 일치합니다. 이 모델의 추론 상태는 텍스트가 아니라 암호화된 페이로드를 전달하는 불투명한 항목의 시퀀스이며, /v1/responses만 이들을 위한 슬롯을 가집니다. 해당 프로토콜에서 항목은 그대로 재생되며, 이것이 도구 라운드 전체에서 모델의 사고 연쇄를 유지하는 것입니다. 읽을 수 있는 요약은 여전히 나가는 요청에서 삭제되므로, chat-completions 폴백에서는 informational_only와 정확히 동일하게 작동합니다. 정보 프래그먼트 앞에서 확인되며, 이들의 일반 reasoning 항목은 그렇지 않으면 프록시 태그된 GPT-5 ID를 삼킬 것입니다.
• unsupported — 포괄적인 경우: 추론 기능이 없는 모델 (GPT-4o, Gemini 1.5, Mistral, Llama), 그리고 ID가 프래그먼트와 일치하지 않는 추론 모델 (GLM, MiniMax, Kimi, Doubao). 어느 쪽이든 필드를 재생해서는 안 되므로, 이 정책은 informational_only와 동일한 바이트를 전선에 배치합니다. 또한 알 수 없는 모델 ID에 대한 안전한 기본값입니다.

​

강제 실행

​

사용자용

• 같은 대화에서 Claude와 DeepSeek 간에 에이전트를 전환하는 경우, 히스토리는 thinking 블록이 그대로 저장되며, 다음 턴에서 발신 메시지 형태는 현재 모델에 맞게 조정됩니다.
• 프록시 / 커스텀 BaseLLM 서브클래스를 사용하는 경우, 모델 id가 인식 가능한지 확인하세요(조각 중 하나를 포함). 그렇지 않으면 기본 unsupported 정책이 적용되며, 이는 안전하지만 비정상적인 프록시 뒤의 Claude가 thinking 재생을 잃을 수 있습니다. 모델 id 조각을 _CACHE_CAPABLE_MODEL_FRAGMENTS(core/prompt/caching.py에 있음) 및/또는 reasoning 정책 조회에 추가하세요.

​

문제 해결