推理 / 思考参数¶

现代 LLM 可以在生成最终回答之前进行显式的思维链推理。各提供商通过不同的参数名称、结构和语义来暴露这一能力。LLM-Rosetta 的 ReasoningConfig 提供了统一的 IR 层，映射到所有支持的提供商。

提供商对比¶

模式控制¶

各提供商如何控制推理的开启、关闭或自动模式：

努力级别¶

模型应投入多少推理"努力"。各提供商支持的粒度不同：

预算 Token 数¶

模型可用于推理的最大 token 数：

总览矩阵¶

IR ReasoningConfig¶

LLM-Rosetta 定义了统一的 ReasoningConfig TypedDict，包含三个字段：

class ReasoningConfig(TypedDict, total=False):
    mode: Literal["auto", "enabled", "disabled"]
    effort: Literal["minimal", "low", "medium", "high", "xhigh", "max"]
    budget_tokens: int   # 推理的最大 token 数

三个字段均为可选。可根据需要设置任意组合。

输入归一化¶

转换器在处理之前会对外部输入的 effort 值进行归一化：

归一化由 normalize_reasoning_input() 在进入转换器之前执行，不会修改原始输入。

字段语义¶

• mode -- 控制推理行为："enabled"（始终开启）、"disabled"（关闭）或 "auto"（由模型决定）。省略则由提供商使用默认行为。
• effort -- 模型在推理上应投入多少"努力"。这是一个独立于 mode 的横切关注点。
• budget_tokens -- 推理 token 数的硬上限。仅对支持该功能的提供商有效（Anthropic、Google）。

IR 到提供商的映射¶

mode: "enabled"（无 effort、无 budget）¶

最简单的开启推理方式：

ir_request: IRRequest = {
    "model": "claude-sonnet-4-20250514",
    "messages": [...],
    "reasoning": {"mode": "enabled"},
}

{
  "thinking": {"type": "adaptive"}
}

{
  "reasoning": {"type": "enabled"}
}

mode: "enabled" + budget_tokens¶

显式控制推理预算：

ir_request: IRRequest = {
    "model": "claude-sonnet-4-20250514",
    "messages": [...],
    "reasoning": {"mode": "enabled", "budget_tokens": 10000},
}

{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

{}

{
  "reasoning": {"type": "enabled"}
}

{
  "thinking_config": {
    "thinking_budget": 10000
  }
}

mode: "disabled"¶

显式关闭推理：

ir_request: IRRequest = {
    "model": "claude-sonnet-4-20250514",
    "messages": [...],
    "reasoning": {"mode": "disabled"},
}

{
  "thinking": {"type": "disabled"}
}

{
  "reasoning": {"type": "disabled"}
}

effort（可搭配或不搭配 mode）¶

设置推理努力级别：

ir_request: IRRequest = {
    "model": "claude-sonnet-4-20250514",
    "messages": [...],
    "reasoning": {"effort": "high"},
}

{
  "thinking": {
    "type": "adaptive",
    "effort": "high"
  }
}

{
  "reasoning_effort": "high"
}

{
  "reasoning": {
    "effort": "high"
  }
}

{
  "thinking_config": {
    "thinking_level": "high"
  }
}

努力级别映射¶

IR 支持六个努力级别。实际映射由各提供商 shim 的 effort_map 声明，以下是内置 shim 的默认映射：

:material-alert: = 被 max_effort 上限或 effort_map 降级

— = Google shim 的 effort_field 为 "none"，effort 不发送给上游

提供商到 IR 的映射（反向）¶

将提供商原生请求转换为 IR 时的映射：

设计决策¶

为什么 mode 是三态字段¶

IR 使用显式的 mode: "auto" | "enabled" | "disabled" 而非布尔值：

1. 与提供商直接对齐。 Anthropic 的 thinking.type 有三个值（"adaptive"、"enabled"、"disabled"），OpenAI Responses 的 reasoning.type 同样如此。三态 mode 实现了 1:1 映射，支持无损往返转换。
2. 省略仍然有效。 当 mode 未设置时，提供商使用其默认行为 -- 即思考能力模型的自动推理。这与 mode: "auto" 不同，后者是显式请求自适应行为。
3. effort 作为横切关注点。 单独设置 effort（不设 mode）可以让模型自行决定是否推理，同时控制推理时投入的努力程度。

为什么 effort 有 6 个级别¶

IR 支持 minimal、low、medium、high、xhigh 和 max，使其成为所有提供商级别的超集：

• Google 支持 minimal，但其他提供商不支持（降级为 low）
• Anthropic 支持 xhigh 和 max，但 OpenAI 不支持（被 max_effort: high 截断）
• 中间三个级别（low、medium、high）被所有提供商普遍支持

这确保了同一提供商内的无损往返转换，同时在跨提供商时提供尽力而为的映射。

Shim 驱动的 effort 映射¶

从 v0.6.8 起，effort 映射不再硬编码在各转换器中，而是由提供商 shim 的 ReasoningCapability 配置声明。运行时流程：

1. 网关加载提供商 shim，将 provider.yaml 中的 reasoning 段解析为 ReasoningCapability
2. 请求到达时，_inject_shim_reasoning() 将 ReasoningCapability 注入转换上下文
3. 各转换器的 ir_reasoning_config_to_p 委托给 apply_reasoning_config()，传入 shim 配置
4. apply_reasoning_config() 先调用 normalize_reasoning_input() 归一化输入，然后按 effort_map 和 max_effort 映射

详细的 ReasoningCapability 字段和 YAML 配置请参见 提供商 Shim · 推理配置。

预算 token：仅 Anthropic 和 Google 支持¶

OpenAI（Chat 和 Responses）不支持显式的推理预算控制。当 IR 中设置了 budget_tokens 且目标为 OpenAI 时，将发出警告并静默丢弃该字段。这是设计意图 -- IR 是超集，有损转换会被显式标记。

完整示例：跨提供商推理¶

from llm_rosetta import convert

# 带自适应推理的 Anthropic 请求
anthropic_request = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 8096,
    "thinking": {
        "type": "adaptive",
        "effort": "high",
    },
    "messages": [
        {"role": "user", "content": "请逐步解释量子纠缠。"}
    ],
}

# 转换为 OpenAI Chat 格式
openai_request = convert(anthropic_request, target="openai_chat")
# 结果包含: {"reasoning_effort": "high", ...}

# 转换为 Google GenAI 格式
google_request = convert(anthropic_request, target="google_genai")
# 结果包含: {"thinking_config": {"thinking_level": "high"}, ...}