LLM 提供商兼容性

​

提供商检测

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"（模型自由决定），无论此设置如何都适用于所有模型。

​

提供商能力矩阵

​

表 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 blob 自己携带状态，所以删除 id 没有成本（sanitize_reasoning_item）。

​

表 B：冲突与解决方案

​

表 C：思维协议

​

中继/代理陷阱

​

推荐的按模型配置

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

​

故障排除