LLM 제공자 호환성

Documentation Index

Fetch the complete documentation index at: https://docs.fim.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

제공자 감지

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을 파싱하며, 이는 최신 모델에서 안정적으로 작동합니다.

​

사고 모델 + 강제 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" (모델이 자유롭게 결정)를 사용하며, 이 설정과 관계없이 모든 모델에서 작동합니다.

​

빠른 참조: 어디서 작동하는가

​

모델별 권장 구성

# 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. 온도가 1.0으로 강제됩니다. Bedrock은 사고가 활성화되었을 때 temperature != 1.0을 거부합니다. FIM One은 이를 자동으로 처리합니다 — 사용자 조치가 필요하지 않습니다.
2. 도구가 있는 GPT-5.x: tools가 있을 때 reasoning_effort는 자동으로 삭제됩니다. GPT-5 /v1/chat/completions 엔드포인트가 이 조합을 거부하기 때문입니다. 이는 ReAct 도구 루프에만 영향을 미칩니다. tools 매개변수가 없는 structured_llm_call 호출은 영향을 받지 않습니다.

​

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

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 계열 (including anthropic/, bedrock/anthropic, vertex_ai/claude). Thinking 블록은 반드시 signature와 함께 재생되어야 합니다. Anthropic은 signature가 누락되거나 변경되면 후속 턴을 거부합니다.
• informational_only — CoT를 생성하지만 재생을 기대하지 않는 모델: DeepSeek R1 / R1-Distill, Qwen QwQ, Gemini 2.x thinking, OpenAI o1 / o3 / o4. 이들의 문서에는 명시적으로 “메시지 히스토리에 reasoning_content를 다시 보내지 마세요”라고 나와 있습니다. 이를 무시하고 전송하면:
  • 제공자 계약을 위반합니다 (향후 버전에서 거부를 시작할 수 있음)
  • 자동 prefix 캐시를 조용히 무효화합니다 — 메시지 바이트가 매 턴마다 변경되어 해시를 깨뜨립니다
• unsupported — 추론 기능이 없는 모델 (GPT-4o, GPT-4 Turbo, Gemini 1.5, Mistral, Llama). 재생할 CoT가 없으므로 필드가 나타나면 안 됩니다. 이 정책은 알 수 없는 모델 ID에 대한 안전한 기본값이기도 합니다.

​

강제 실행

​

사용자용

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

​

문제 해결