Kimi K3.1 Pro 推理档位与参数配置：reasoning_effort 的 low、high、max

一句话结论

Kimi K3.1 Pro 始终进行推理，使用 Chat Completions 请求顶层的 reasoning_effort 设置推理档位；可选值为 low、high、max，默认值为 max。

适用场景

• 适合的任务：为 Kimi K3.1 Pro 的 API 请求选择推理档位，或从 K2.x 的 thinking 配置迁移到 K3 的请求格式。

• 不适合的任务：据此比较不同档位的准确率、延迟或成本；官方页面只说明档位用于平衡推理深度、延迟和 token 使用量，没有提供本地测试数据。

• 适用的模型版本：官方页面明确覆盖 kimi-k3.1-pro；页面将该字段称为 K3 的顶层推理字段，未列出其他模型版本的兼容性清单。

• 适用的客户端、Agent 或 API：Kimi API 的 Chat Completions 接口，以及能够透传顶层 reasoning_effort 字段的兼容客户端。

• 推荐的推理档位和参数：未有统一档位推荐。按官方配置，low、high、max 均可用；不传该字段时使用默认值 max。

可直接使用的内容

原始配置（官方示例）

将 reasoning_effort 放在 Chat Completions 请求顶层：

{
  "model": "kimi-k3.1-pro",
  "messages": [{"role": "user", "content": "Derive the general formula for this sequence: 1, 4, 9, 25, 64, ..."}],
  "reasoning_effort": "high"
}

官方 Python 示例：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

completion = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[
        {"role": "user", "content": "Derive the general formula for this sequence: 1, 4, 9, 25, 64, ..."},
    ],
    reasoning_effort="high",
)

message = completion.choices[0].message
if hasattr(message, "reasoning_content"):
    print(getattr(message, "reasoning_content"))
print(message.content)

参数对照：

未实测推断

• 可以把 low、high、max 理解为由低到高的推理投入选项；这是根据官方“平衡推理深度、延迟和 token 使用量”的描述整理出的使用方向，不是本文的实测排序。

• 若客户端没有透传顶层 reasoning_effort 的能力，不能据此推断它会自动映射到旧版 thinking 参数；应先检查客户端的请求体或原始 API 日志。

测试或工作流步骤

1. 确认请求使用模型 ID kimi-k3.1-pro 和 Kimi API Chat Completions 接口。

2. 在请求顶层加入 reasoning_effort，值只使用 low、high 或 max。

3. 若不设置该字段，按官方说明使用默认值 max；不要把它嵌入 messages 或改写成 K2.x thinking 配置。

4. 从 K2.x 迁移时移除旧 thinking 配置，再按上方示例加入顶层 reasoning_effort。

5. 使用多轮对话或工具调用时，将 API 返回的完整 assistant 消息原样传回 messages，包括 reasoning_content 和 tool_calls。

6. 分别记录请求档位、响应耗时和 token 使用量后，再根据自己的任务选择档位；本文没有提供这些指标的实测结果。

原始证据与数据

• 官方页面写明：Kimi K3.1 Pro always reasons，通过请求顶层的 reasoning_effort 字段配置推理。

• 官方页面列出的合法值为 low、high、max，并明确 max 为默认值。

• 官方 JSON、curl 和 Python 示例都将 reasoning_effort 放在 Chat Completions 请求顶层；本文仅保留页面中完整的 JSON 和 Python 示例。

• 官方迁移说明要求从 K2.x 迁移到 K3 时移除 K2.x thinking 配置，并按需使用顶层 reasoning_effort。

• 官方字段说明要求多轮对话和工具调用把 API 返回的完整 assistant 消息原样传回，包括 reasoning_content 和 tool_calls。

• 本文只完成官方页面核验，未使用 API Key 发起请求，未实测档位对应的推理深度、延迟、token 用量、成功率或客户端兼容性。

适用边界

• reasoning_effort 的三个值和默认值是该官方页面对 Kimi K3.1 Pro 的说明，不能外推为所有 Kimi 模型或第三方客户端的通用参数。

• “始终进行推理”不等于每次请求都需要手动填写 reasoning_effort；不填写时仍按官方说明使用 max 默认值。

• K2.x 的 thinking 配置与 K3 的顶层 reasoning_effort 不是本文验证过的同一参数。迁移时应按 K3 文档改写请求，并检查客户端是否仍注入旧字段。

• 官方页面未给出 low、high、max 的具体 token 上限、价格、延迟或质量分数，本文不为这些指标补充推断数值。

复现说明

1. 打开原文并确认页面标题为 Reasoning Effort，记录采集日期、模型 ID、字段位置、可用值和默认值。

2. 对照页面中的 JSON、curl、Python 代码块，确认 reasoning_effort 位于 Chat Completions 请求顶层。

3. 核对迁移说明与字段说明，确认 K2.x thinking 配置迁移规则，以及多轮对话和工具调用需保留的 assistant 消息字段。

4. 本次复现仅完成官方页面配置核验；没有提交真实 API 请求，因此没有本地测试数据。