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

​

结构化输出：四个保证层级

​

T1和T2不可互换

​

T2的成本

• schema子集。 OpenAI的strict mode要求每个对象都设置additionalProperties: false，并将每个属性都列入required；可选性通过与null组成联合类型来表示，而不是从required中省略。根节点必须是对象。属性总数和嵌套深度也存在上限。大多数手写schema在符合要求前都需要进行编辑。
• 语法编译。 携带新schema的首次请求需要承担提供商侧一次性的编译延迟。复用稳定的schema可以分摊这项开销；而每个请求都生成全新的schema则无法做到这一点。
• 新的失败面。 不愿回答的模型会返回拒答，而不是符合schema结构的对象，因此调用方需要为此增加一个分支。

​

没有任何层级能够保证的内容

​

FIM One 所处的位置

1. 链中没有可回退到的 schema 约束层级。 当 Level 1 失败时，下一层是 json_object，它只能保证文本可解析。不存在仍然强制要求字段的中间步骤。
2. Level 1 的保证弱于其名称所暗示的程度。 未启用 strict 时，原生函数调用属于 2024 年之前的非严格形式：模型通常会遵循 schema，但不会被阻止省略必填字段、编造键，或在声明为数字时返回字符串。
3. 在 anthropic/ 路由上，Level 2 实际上并不是真正的 T3。 Anthropic Messages API 没有 response_format，因此 LiteLLM 会通过注入 assistant prefill 来模拟 JSON mode。这是一种提示词层面的机制，使实际保证介于 T4 和 T3 之间，而不是达到 T3。下文记录的 Bedrock prefill 陷阱，就是这种模拟机制明显失败的表现；更隐蔽的代价在于，这种保证从未达到参数名称所暗示的程度。
4. 结果不会在之后根据 schema 进行验证。 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

​

每个层级的提供商支持情况

​

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

• 通过 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()能够可靠地解析自由格式的内容。失去的是保证，而不是输出：现在链路会在 T4 结束，此时除了提示词之外，没有任何机制约束结果。对于anthropic/路由来说，这种损失没有看起来那么大，因为模拟的 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"] 则会请求返回加密载荷。如果不包含该字段，返回的推理项将为空，重放会悄无声息地变成空操作。
• 重放的推理项必须去除服务器端的 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）。

​

表 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 中）和/或推理策略查找。

​

故障排除