Kimi K3.1 Pro Tool Choice 配置：自动、强制与禁用工具调用

一句话结论

Kimi K3.1 Pro 的 tool_choice 可按请求选择自动判断、禁止工具、至少调用一个工具，或指定某个函数；工具搜索常用首轮 required、检索后切回 auto。

适用场景

• 适合的任务：需要控制本轮是否进入工具路径的 Chat Completions 请求，例如强制检索、普通对话和纯文本回答。

• 不适合的任务：没有声明可调用工具却使用 required，或在启用 thinking 时强制指定某个函数。

• 适用的模型版本：kimi-k3.1-pro；官方完整请求示例明确使用该模型 ID。

• 适用的客户端、Agent 或 API：Kimi API Chat Completions；请求由客户端声明 tools 并处理工具结果。

• 推荐的推理档位和参数：页面未给出独立推理档位建议；指定函数与启用 thinking 不兼容，返回 400。

可直接使用的内容

四种选择方式如下。省略 tool_choice 等同于 "auto"：

{"tool_choice": "auto"}
{"tool_choice": "none"}
{"tool_choice": "required"}
{"tool_choice": {"type": "function", "function": {"name": "get_weather"}}}

• auto：由模型根据上下文决定是否调用工具，也是默认值。

• none：禁止工具调用，模型返回纯文本且不产生 tool_calls。

• required：本轮至少调用一个工具；请求必须声明至少一个可调用工具。

• 函数对象：强制调用指定函数；启用 thinking 时不兼容。

官方 K3.1 Pro 请求示例：

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -d '{
    "model": "kimi-k3.1-pro",
    "messages": [{
      "role": "user",
      "content": "What is the weather like in Beijing today?"
    }],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a given city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "required"
  }'

测试或工作流步骤

1. 在 tools 中声明本轮允许调用的完整函数定义；普通对话省略 tool_choice，或显式设置 "auto"。

2. 强制检索或数据库查询时设置 "required"，并确认至少有一个可调用工具；工具搜索可在首轮强制调用 search_tools。

3. 工具检索完成后，下一次请求切回 "auto"，让模型决定是否调用检索到的工具。

4. 只需文本回答时设置 "none"，避免误触发工具并减少延迟与 token 消耗。

5. 只允许某个函数时使用函数对象并确认未启用 thinking；tool_choice 每次请求独立约束该次生成，可按轮次调整。

原始证据与数据

• 页面将 auto 定义为默认值；不设置 tool_choice 与设置 "auto" 等价。required 要求本轮至少调用一个工具，且请求声明至少一个可调用工具。

• none 产生纯文本、不生成 tool_calls，页面指出这也能减少延迟和 token 消耗。

• 指定函数使用 {"type":"function","function":{"name":"get_weather"}}；页面明确它与启用 thinking 不兼容，会返回 400。

• 官方完整请求示例使用 model: "kimi-k3.1-pro"、天气函数和 tool_choice: "required"；首轮也可用 required 强制调用 search_tools，检索后切回 auto。

• tool_choice 只约束当前请求的生成；设置或调整它不会使前缀缓存失效。

适用边界

• required 的“至少一个调用”以声明了可调用工具为前提；页面没有给出无 tools 请求的具体错误码，因此不能扩展为未经验证的报错结论。

• none 只表达本轮不产生工具调用；工具是否被声明、历史消息如何处理仍由客户端决定。页面没有说明 auto、none 或 required 在 thinking 下的全部行为。

• K3.1 Pro 的专属依据是官方完整请求中的模型 ID；页面对 tool_choice 的通用说明不能冒充其他旧版模型的专属实测。

• tool_choice 不负责执行函数、校验参数、权限控制、超时或重试；这些职责仍在客户端。

• 本稿没有使用 API Key 发起本地或线上调用，未记录成功率、延迟、成本或真实 400 响应。

复现说明

1. 打开官方 Tool Choice，核对四种取值和 K3.1 Pro 完整请求示例。

2. 使用可用 API Key，以 model="kimi-k3.1-pro" 和至少一个函数工具分别发送 auto、none、required 请求。

3. 先用 required 调用工具搜索函数，再在下一请求切换为 auto，核对每轮的工具选择。

4. 单独发送指定函数对象并启用 thinking，记录 API 返回的 400；不要把静态文档示例当作已完成的 API 实测。

5. 记录每次请求的 tool_choice、是否产生 tool_calls、响应状态和 token usage；日志不要写入 API Key 或敏感参数。