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. 显式提供商（来自数据库 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 预填陷阱

{"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

• 数据库配置的模型：在 Admin → Models → Advanced settings 中切换。该标志存储在 ModelProviderModel.json_mode_enabled 上（默认值 TRUE）。
• 环境变量配置的模型：在环境中设置 LLM_JSON_MODE_ENABLED=false。
• 效果：禁用时，abilities["json_mode"] 返回 False → response_format 永远不会被传递 → 无预填充 → Bedrock 正常工作。降级链变为 native_fc → plain_text，完全跳过注定失败的 json_mode 调用。
• 无质量损失：模型仍然返回有效的 JSON，因为系统提示指示它这样做。plain_text 级别使用 extract_json() 从自由格式内容中解析 JSON，这在现代模型中工作可靠。

​

思维模型 + 强制 tool_choice

tool_choice 'specified' is incompatible with thinking enabled

​

修复：tool_choice_enabled

• 数据库配置的模型：在 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 系列（包括 anthropic/、bedrock/anthropic、vertex_ai/claude）。思考块必须附加 signature 进行重放；如果缺少或更改签名，Anthropic 会拒绝后续轮次。
• informational_only — 发出 CoT 但不期望重放的模型：DeepSeek R1 / R1-Distill、Qwen QwQ、Gemini 2.x thinking、OpenAI o1 / o3 / o4。它们的文档明确说明”不要在消息历史中发送 reasoning_content”。即使发送：
  • 违反提供商合约（未来版本可能开始拒绝）
  • 静默失效其自动前缀缓存 — 消息字节在每个轮次变化，破坏哈希
• unsupported — 不具备推理能力的模型（GPT-4o、GPT-4 Turbo、Gemini 1.5、Mistral、Llama）。没有 CoT 可重放；字段不应出现。此策略也是未知模型 ID 的安全默认值。

​

执行

​

对于用户

• 如果您在同一对话中在 Claude 和 DeepSeek 智能体之间切换，历史记录会完整保存思考块；在下一轮中，传出消息形状会根据当前模型进行调整。
• 如果您使用代理 / 自定义 BaseLLM 子类，请确保其模型 id 是可识别的（包含其中一个片段），否则默认的 unsupported 策略将适用 — 这是安全的，但意味着异常代理后的 Claude 可能会丢失思考重放。将模型 id 片段添加到 _CACHE_CAPABLE_MODEL_FRAGMENTS（在 core/prompt/caching.py 中）和/或推理策略查找。

​

故障排除