DeepSeek-V3.2 的思考式工具调用与多轮状态配置

一句话结论

V3.2 把 thinking 直接融入 tool-use；多轮工具请求必须完整回传上一轮 reasoning_content，否则 API 会报错或丢失推理状态，且 thinking 模式不应配置 temperature/top_p。

适用场景

• 适合的任务：需要多步检索、函数调用、代码/数据工具和跨轮状态的 Agent。

• 不适合的任务：要求 Speciale 直接调用工具；官方发布说明 Speciale 当时 API-only 且 no tool-use。也不适合把 reasoning_content 当作可公开解释文本。

• 适用的模型版本：deepseek-chat/V3.2 API 具体 alias 以当前 docs 为准；V3.2-Speciale 是独立变体，发布时临时 endpoint 且不支持工具。

• 适用的客户端、Agent 或 API：OpenAI-compatible Chat Completions；可用 OpenAI SDK extra_body 传 thinking。

• 推荐的推理档位和参数：thinking 默认开启、默认 high；明确传 reasoning_effort=low/high/max（当前文档映射需核对）和 extra_body={"thinking":{"type":"enabled"}}。thinking 时 temperature/top_p/presence_penalty/frequency_penalty 无效。

可直接使用的内容

from openai import OpenAI
import json

client = OpenAI(
    api_key="<DEEPSEEK_API_KEY>",
    base_url="https://api.deepseek.com"
)

tools = [{
    "type": "function",
    "function": {
        "name": "search_docs",
        "description": "Search approved documents and return source IDs. Never invent results.",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"]
        }
    }
}]

messages = [{
    "role": "user",
    "content": "查找与 <topic> 相关的资料。每个结论附 source_id；找不到时明确写未找到。"
}]

while True:
    response = client.chat.completions.create(
        model="deepseek-v3.2",
        messages=messages,
        tools=tools,
        reasoning_effort="high",
        extra_body={"thinking": {"type": "enabled"}},
    )
    assistant = response.choices[0].message
    # 官方要求：把 content、reasoning_content、tool_calls 一起保留
    messages.append(assistant)
    if not assistant.tool_calls:
        print(assistant.content)
        break
    for call in assistant.tool_calls:
        args = json.loads(call.function.arguments)
        result = run_approved_tool(call.function.name, args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": result,
        })

测试/工作流步骤

1. 用无工具和有工具两组任务验证 reasoning_content 的保存/回传；工具路径中把完整 assistant message 原样追加。

2. 固定 reasoning_effort，分别跑 low/high/max；不要同时调 temperature/top_p。

3. 记录每个子回合的 reasoning token、工具调用、错误、最终答案和总成本。

4. 服务端对工具名/参数做 schema、权限和结果来源校验；reasoning_content 不直接展示给终端用户。

原始证据与数据

• DeepSeek 发布说明称 V3.2 是首个把 thinking 直接集成到 tool-use 的模型，并支持 thinking/non-thinking 两种工具模式。

• 官方 thinking 文档写明带 tools 的请求必须在所有后续请求中完整回传 reasoning_content，否则 API 返回 400。

• 官方文档说明 thinking 模式不支持 temperature、top_p、presence_penalty、frequency_penalty；即使兼容接口不报错也不会生效。

• 官方发布说明称 Speciale 以最高推理为目标、API-only，且当时 no tool-use；不要把普通 V3.2 的工具代码复制给 Speciale。

适用边界

• 当前 docs 页面包含后续模型示例/effort 映射，生产部署必须确认 V3.2 当前 alias 和 endpoint，而不是照抄页面中其他型号名。

• “默认 high”及 effort 映射可能随 API 版本变化；固定 model snapshot 并记录响应 metadata。

• reasoning_content 属于模型内部推理上下文，保存是 API 状态协议要求，不等同于向用户暴露 chain-of-thought。

• 工具循环必须有最大子回合、超时、重复调用检测和预算，避免模型无限调用。

来源摘录或观察（仅做合规短引）

DeepSeek 官方的关键要求是：带工具调用时，reasoning_content must be fully passed back（合规短引）。