DeepSeek-V4-Pro 思考档位与工具调用工作流

一句话结论

V4-Pro 默认开启 thinking、默认 effort 为 high；简单任务用 low，日常 Agent 用 high，复杂任务用 max，并在工具调用的每一轮完整回传 reasoning_content。

适用场景

• 适合的任务：多轮工具调用、代码 Agent、复杂规划、需要在工具结果基础上继续推理的 API 工作流。

• 不适合的任务：把 max 当作所有请求的默认值，或在没有保存 assistant 状态的情况下直接拼接多轮消息。

• 适用的模型版本：deepseek-v4-pro；官方页面说明 effort 映射同样适用于 deepseek-v4-flash，本文重点为 Pro。

• 适用的客户端、Agent 或 API：OpenAI-compatible Chat Completions、Anthropic 格式和 Responses API；工具链需按对应协议回放字段。

• 推荐的推理档位和参数：简单任务 low，日常 Agent high，复杂任务 max；思考模式不支持 temperature、top_p、presence/frequency penalty。

可直接使用的内容

OpenAI-compatible Chat Completions 的最小配置（官方参数名）：

from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{
        "role": "user",
        "content": "Inspect the repository, use tools only when needed, and return evidence plus the smallest safe fix.",
    }],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

print(response.choices[0].message.content)

工具 Agent 的循环骨架（保留 assistant 的完整消息，避免丢失思考/工具字段）：

while True:
    response = client.chat.completions.create(
        model="deepseek-v4-pro",
        messages=messages,
        tools=tools,
        reasoning_effort="high",
        extra_body={"thinking": {"type": "enabled"}},
    )

    assistant = response.choices[0].message
    messages.append(assistant)

    if not assistant.tool_calls:
        break

    for call in assistant.tool_calls:
        result = run_tool_safely(call.function.name, call.function.arguments)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": result,
        })

测试/工作流步骤

1. 按任务桶建立 effort 基线：简单问答 low，日常 Agent high，复杂长程任务 max。

2. 开启工具时，把每次返回的完整 assistant 消息（包括 reasoning_content 和 tool_calls）原样加入历史。

3. 执行工具前校验函数名、参数和副作用；工具结果用结构化文本返回，并让模型继续下一轮。

4. 没有工具调用时结束当前循环；将最终 content 与工具轨迹、错误、耗时和 token 一起保存。

5. 对同一任务比较 low/high/max 的成功率、过度思考、延迟和成本；不要用单次主观体验决定档位。

原始证据与数据

• DeepSeek 官方表格：thinking toggle 可用 OpenAI thinking.type 或 Responses reasoning.effort；none 可禁用，low/high/max 控制 effort。

• 官方默认 thinking 为 enabled，默认 effort 为 high；requested medium、high、xhigh 均映射为 actual high，max 映射为 max。

• 工具调用后，reasoning_content 必须在所有后续请求中完整回传，否则 API 返回 400。

• thinking mode 不支持 temperature、top_p、presence_penalty、frequency_penalty；即使兼容层不报错，设置也不会生效。

适用边界

• 官方示例用天气函数演示循环，不代表天气数据真实或工具本身安全；生产环境必须替换为有权限、可审计的工具。

• reasoning_content 是协议状态的一部分；是否向终端用户展示应由产品策略决定，不要把内部推理文本当作未经验证的证据。

• 不同 SDK/协议的字段位置不同；OpenAI SDK 的 thinking 需要放在 extra_body，Responses API 使用 reasoning.effort。

• effort 映射表是 DeepSeek 文档当前说明，模型更新后应重新核对。

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

官方明确写道：工具请求中 reasoning_content “must be fully passed back to the API”，否则会返回 400。