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

​

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 구성 모델: Admin → Models → Advanced settings에서 토글합니다. 플래그는 ModelProviderModel.json_mode_enabled에 저장됩니다 (기본값 TRUE).
• ENV 구성 모델: 환경에서 LLM_JSON_MODE_ENABLED=false를 설정합니다.
• 효과: 비활성화되면 abilities["json_mode"]는 False를 반환 → response_format이 전달되지 않음 → prefill 없음 → Bedrock이 작동합니다. 성능 저하 체인은 native_fc → plain_text가 되어 실패할 json_mode 호출을 완전히 건너뜁니다.
• 품질 손실 없음: 시스템 프롬프트가 모델에 JSON을 반환하도록 지시하므로 모델은 여전히 유효한 JSON을 반환합니다. plain_text 레벨은 extract_json()을 사용하여 자유 형식 콘텐츠에서 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

​

Table A: Protocol routing

• 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 blob은 자체적으로 상태를 전달하므로 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 정책 조회에 추가하세요.

​

문제 해결