DeepSeek V4 Pro (0813): 思维回传与三种 API 矩阵

本文涵盖了 deepseek-v4-pro-0813 的使用注意事项和常见问题。在 AIHubMix 上，该模型通过聊天补全、响应和 Claude 兼容消息 API 提供。另请参见：DeepSeek 官方 API 文档。

每个部分中的“已验证”结论和示例响应来自于 2026-08-13 通过 AIHubMix API（聊天补全/响应/消息）进行的实际调用；未标记为“已验证”的规格项来自 DeepSeek 的官方文档。

1. 模型定位和规格一览

V4 Pro 是 DeepSeek V4 代的高端版本（轻量级 deepseek-v4-flash 是其兄弟产品）。发布线追溯至 2026-04-24 的 DeepSeek-V4 预览版，0813 是 DeepSeek 分配给当前构建的模型版本标签。除了原始规格外，有四个方面使其与众不同：

• 稀疏前沿模型：1.6T 总参数 / 49B 激活（MoE，即专家混合架构——每次推理仅激活一部分专家网络：总参数决定知识容量，激活参数决定每次调用的计算成本）。模型卡列出了 CSA+HCA 混合注意力、mHC 和 Muon 优化器。
• MIT 下的开放权重：deepseek-ai/DeepSeek-V4-Pro 在 HuggingFace 上以 MIT 许可证发布（这是最宽松的开源许可证之一——允许商业使用和闭源再分发），并可以自托管。对于这种规模的模型，MIT 许可证并不常见。模型卡的自托管说明还建议在 Think Max（最高思维级别）下运行时上下文窗口应为 ≥384K 令牌——这是自托管的部署指导，而不是托管 API 的规格。
• 多协议支持是第一方，而非第三方翻译：DeepSeek 自身提供 OpenAI 聊天 API、与 Anthropic 兼容的端点（/anthropic，将 claude-opus* 映射到该模型）和响应 API（DeepSeek 描述了对该格式的原生支持，并为 Codex 进行了适配）。它还在一个单独的端点上提供 FIM（填充中间）补全作为 Beta 功能，这不属于三种 AIHubMix API 的一部分。
• 缓存命中和未命中定价之间约 120 倍的差距：DeepSeek 发布的定价机制是缓存命中 $0.003625/M vs 缓存未命中 $0.435/M（输出 $0.87/M），且缓存是自动的，无需设置参数。对于重用长前缀（系统提示、长文档）的工作负载，这一差距主导了账单。实际零售定价为模型页面所示。

已验证：超过 max_tokens 会被验证拒绝，而不是静默截断——发送 max_tokens=9999999 返回 HTTP 400，错误主体命名字段并给出上限 393216。

# max_tokens=9999999 -> HTTP 400
"...max_tokens... 393216"

❗ 图像不会引发错误，但会被丢弃：响应 API 的官方措辞是“图像和文件输入不受支持（input_image 部分不会引发错误，但会被替换为占位符文本）”——input_image 部分不会使请求失败，而是被占位符文本替换。在聊天补全中，用户消息 content 仅接受字符串，而在消息中 type="image" 块被标记为不支持。在构建多模态路由时，切勿将“无错误”视为模型实际看到图像的证据。

2. 如何关闭思维？三种 API，三种字段形状

V4 Pro 默认开启思维：完全不发送参数，响应将返回思维内容。关闭思维在三种 API 中使用不同的字段形状。

聊天补全

使用顶层 thinking 对象。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="deepseek-v4-pro-0813",
    messages=[{"role": "user", "content": "2 + 2 等于多少？"}],
    extra_body={"thinking": {"type": "disabled"}},
)

# 思维开启（默认）：message.reasoning_content 存在，reasoning_tokens = 43
# 思维关闭（禁用）：reasoning_content 缺失，reasoning_tokens 缺失

已验证：使用 thinking.type="disabled"，message.reasoning_content 和 usage.completion_tokens_details.reasoning_tokens 一起消失，确认切换生效。

响应

响应中没有单独的开关；关闭思维意味着将级别设置为 none。

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="2 + 2 等于多少？",
    reasoning={"effort": "none"},
)

# effort="none"：usage.output_tokens_details.reasoning_tokens = 0
#                output[0] 是直接的消息项（没有推理项）
# effort 未设置：输出始终以推理项开头

已验证：reasoning.effort="none" 与默认级别显著不同（思维令牌降至零，reasoning 输出项消失），确认切换生效。

消息

与聊天补全相同的名称和形状：顶层 thinking 对象。

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com",
)

response = client.messages.create(
    model="deepseek-v4-pro-0813",
    max_tokens=1024,
    messages=[{"role": "user", "content": "2 + 2 等于多少？"}],
    extra_body={"thinking": {"type": "disabled"}},
)

# 思维开启（默认）：内容 = [思维块，文本块]
# 思维关闭（禁用）：内容 = [文本块]

已验证：一旦禁用，thinking 块完全消失，仅保留 text 块。

关于思维级别：low 和 max 在聊天补全中测试时均返回 200（high 为默认值，省略字段时适用），但思维令牌计数在同一问题的不同级别之间没有单调差异（简单问题：low=43 / max=27；难题：low=114 / max=92），且响应中没有回显——级别被接受，但响应中没有可观察的区分信号。在响应中，只有 none 级别（思维关闭）可以从响应侧确认。

3. 为什么多轮对话突然返回 400？思维历史必须逐字回传

这是该模型中最常见的触发条件：在思维模式下，多轮对话必须逐字回传上一个回合的思维内容，否则请求将被拒绝。不是降级，不是低质量——是硬性 HTTP 400。

这三种 API 在不同字段名称下携带相同的思维内容：

已验证（触发条件）：此验证在携带 tools 的多轮请求中始终触发（模型发出工具调用，然后返回工具结果）。在没有工具的普通多轮请求中，模型直接回答，此轮测试中未触发验证，请求返回 200。换句话说，工具编排（代理/函数调用工作负载）是最可能触发的地方，因此将思维内容视为您持久化和重放的对话状态的一部分。

聊天补全

# 多轮：逐字回传上一个助手消息，包括 reasoning_content
messages = [
    {"role": "user", "content": "1 + 1 等于多少？记住结果。"},
    {
        "role": "assistant",
        "content": "2",
        "reasoning_content": "<来自上一个响应的 reasoning_content>",
    },
    {"role": "user", "content": "在结果上加 1。"},
]

# 丢弃 reasoning_content -> HTTP 400 invalid_request_error

已验证：缺失 reasoning_content 的历史助手消息返回 400；将其添加回来使相同请求返回 200 并正确继续。

响应

# 多轮：输入 = 上一个输入 + response.output（包含推理项） + 新消息
input = previous_input + response.output + [
    {"role": "user", "content": "在结果上加 1。"}
]

# 过滤掉 type="reasoning" 项 -> HTTP 400

已验证：将 response.output 原样拼接回来就是所需的。通过 type == "message" 过滤输出项时，组装历史会丢弃 reasoning 项并触发 400——这是最常见的触发方式。

消息

# 多轮：逐字回传 response.content 作为助手消息
messages = [
    {"role": "user", "content": "巴黎的天气怎么样？"},
    {"role": "assistant", "content": response.content},   # 思维 + 工具使用块
    {"role": "user", "content": [tool_result_block]},
]

# 去掉思维块 -> HTTP 400

已验证：从内容数组中移除 thinking 块返回 400（error.type 设置为 invalid_request_error）。

4. 工具调用

每个 API 以其自己的协议形状声明工具；这些形状不可互换。

聊天补全

嵌套形状（一个 function 对象包装 name / parameters）。命名函数 tool_choice 强制调用。

completion = client.chat.completions.create(
    model="deepseek-v4-pro-0813",
    messages=[{"role": "user", "content": "巴黎的天气怎么样？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取城市天气",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
    tool_choice={"type": "function", "function": {"name": "get_weather"}},
)

# 观察到：finish_reason "tool_calls"，tool_calls[0].function.arguments = {"city": "Paris"}

❗ 已验证：tool_choice: "required" 在思维开启时无法使用——它返回 400 思维模式不支持此 tool_choice；禁用思维（thinking.type="disabled"）使相同请求返回 200。当您需要“必须调用工具”的语义时，请使用命名函数 tool_choice（如上所示，适用于思维开启），或先禁用思维，然后再使用 required。

响应

平面形状（type / name / parameters 在同一层级）。

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="巴黎的天气怎么样？",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "获取城市天气",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
)

# 观察到的输出项：["reasoning", "function_call"]; arguments = {"city": "Paris"}

已验证：将聊天补全的嵌套形状（function: {...}）复制到响应中返回 400——使用平面形状。tool_choice: "required" 受与聊天相同的思维模式限制。

消息

Anthropic 原生形状（input_schema），使用 tool_choice: {"type": "any"} 强制调用。

response = client.messages.create(
    model="deepseek-v4-pro-0813",
    max_tokens=1024,
    tools=[{
        "name": "get_weather",
        "description": "获取城市天气",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "巴黎的天气怎么样？"}],
)

# 观察到：内容包含一个工具使用块，名称 = get_weather，输入 = {"city": "Paris"}

❗ 并行工具调用无法关闭，这是 DeepSeek 自身的设计——官方的 Anthropic 兼容页面在 tool_choice 行中声明，disable_parallel_tool_use 被忽略，响应页面同样声明 parallel_tool_calls | 被忽略（并行工具调用始终启用）。测试结果一致：同时询问两个城市时，即使设置了 disable_parallel_tool_use: true，仍然返回两个 tool_use 块。如果您需要串行执行，请在客户端侧选择第一个调用或自己排队。

工具计数和上下文成本：在单个请求中发送 200 个函数定义仍然返回 200 并给出正常答案，没有触发任何计数验证（在此路径上观察到；未测试更高计数）。但该请求的 prompt_tokens 达到 6,105——工具定义完整进入上下文并计费。当您有许多工具时，按场景修剪工具集，而不是无条件声明所有工具。

5. 结构化输出

聊天补全

response_format 支持 JSON 模式。

completion = client.chat.completions.create(
    model="deepseek-v4-pro-0813",
    messages=[{"role": "user", "content": "返回 {\"a\": 1} 作为 JSON。"}],
    response_format={"type": "json_object"},
)

# 观察到的响应内容：{"a":1}

已验证：输出是有效的 JSON。

响应

通过 text.format 声明 JSON Schema，支持 strict 模式。

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="在键 a 下返回数字 1。",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"a": {"type": "integer"}}, "required": ["a"]},
        }
    },
)

# 观察到的输出文本：{"a":1}

已验证：输出严格符合给定的 schema。

消息

消息（Anthropic）协议没有 response_format / text.format 等效项。通常的解决方法是将 schema 放在工具中——声明一个工具，其 input_schema 是您的目标 schema，设置 tool_choice: {"type": "any"}，并从 tool_use 块的 input 中读取结构化结果。本轮测试未特别验证该模式；当您需要严格的 schema 保证时，优先选择聊天补全或响应。

6. 如何启用上下文缓存？您不需要，它是自动的

上下文缓存（相同的前缀被重用，缓存部分按较低的费率计费）默认开启，无需参数。第二次请求相同的长前缀会在 usage 中报告命中，字段名称因 API 而异。有关缓存详细信息和当前定价，请参见 模型页面；有关跨模型缓存策略和命中率技术，请参见 提示缓存实践。

聊天补全

# 使用相同长前缀的第二次调用
"prompt_tokens_details": {"cached_tokens": 640}   # 第一次调用：0

已验证：在同一通道上，使用相同长前缀的两次连续调用将 cached_tokens 从 0 移动到 640。

响应

# 使用相同长指令的第二次调用
"input_tokens_details": {"cached_tokens": 896}    # 第一次调用：0

消息

# 使用已预热的长系统前缀的调用
"cache_read_input_tokens": 896

已验证：上述前缀已通过具有相同内容的响应请求预热，第一次消息调用立即命中 896——与缓存基于内容前缀并在协议表面之间共享一致。

7. logprobs：聊天返回两个通道

logprobs（对数概率——模型对每个候选令牌的置信度细节）在两个 API 上以不同形状返回，解析代码必须分别处理它们。

聊天补全

completion = client.chat.completions.create(
    model="deepseek-v4-pro-0813",
    messages=[{"role": "user", "content": "说声嗨。"}],
    logprobs=True,
    top_logprobs=2,
)

# 观察到：choices[0].logprobs 包含两个数组
#   logprobs.content[]            -> 最终答案的令牌
#   logprobs.reasoning_content[]  -> 思维文本的令牌

❗ 已验证：聊天返回 content 和 reasoning_content 的对数概率。仅读取 logprobs.content 的代码，根据标准 OpenAI 响应形状不会出错，但会静默错过思维通道；如果您的代码假设 logprobs 下有单个数组，请先添加形状检查。

响应

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="说声嗨。",
    top_logprobs=3,
)

# 观察到：logprobs 仅在最后的消息项上
#   output[-1].content[0].logprobs[] 具有 logprob + top_logprobs 详细信息

已验证：响应仅将 logprobs 附加到最后的文本项——没有在聊天中看到的双通道形状。

消息

消息（Anthropic）协议没有等效字段。要获取令牌级概率详细信息，请使用聊天补全或响应。

8. 哪些 API 可以搜索网络？

网络搜索是一个服务器端工具（检索在服务器上运行；客户端从不发出请求），在测试中它确实在响应和消息 API 上执行。

响应

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="Python 的最新稳定版本是什么？",
    tools=[{"type": "web_search"}],
)

# 观察到的输出项序列：
# ["reasoning", "web_search_call", "reasoning", "message"]

已验证：输出序列中出现 web_search_call 项，这意味着服务器确实进行了检索。

消息

response = client.messages.create(
    model="deepseek-v4-pro-0813",
    max_tokens=1024,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "Python 的最新稳定版本是什么？"}],
)

# 观察到的内容块序列：
# ["thinking", "server_tool_use", "web_search_tool_result", "thinking", "text"]
# usage.server_tool_use.web_search_requests = 1

已验证：usage.server_tool_use.web_search_requests 计数为 1——检索请求确实发生并被计量。

聊天补全

无法在聊天中触发网络搜索。DeepSeek 的官方聊天 API 参考中在请求模式中没有任何搜索工具字段（这是通过逐一检查字段列表建立的缺失；DeepSeek 没有明确声明否认支持）。明确声明支持服务器端搜索的 API 是响应（web_search），官方消息兼容页面也列出了与搜索相关的内容块。

# 三个控制组，相同问题需要实时信息，全部 HTTP 200：
# A 无搜索字段       -> "无法检索"，注释 = null
# B web_search_options    -> "无法检索"，注释 = null，使用与 A 相同
# C enable_search         -> "无法检索"，注释 = null，使用与 A 相同

已验证：发送 web_search_options 或 enable_search 不会引发错误，但也不会检索任何内容——响应不携带 annotations（在网络搜索运行时附加到响应的引用列表），使用与控制组逐字段匹配。要访问网络，请使用响应或消息 API。

9. 使用注意事项：DeepSeek 的设计与我们路径上的偏差

以下所有内容返回 HTTP 200，但行为与直觉相悖。原因不同，因此您应该采取的措施也不同，因此它们被单独列出：第一组是 DeepSeek 设计模型的方式，改变提供者不会改变这一点；第二组是 AIHubMix 路径上的当前行为，我们正在努力改进。

9.1 按 DeepSeek 的设计

9.2 AIHubMix 路径上的当前行为

9.3 DeepSeek 未定义，因此无论哪种方式都没有裁决

发送超出 reasoning_effort 枚举的值（例如 bogus_xyz）返回 200，并给出正常答案，没有错误，也没有可观察的效果。事实很明确——此路径当前不验证 reasoning_effort 枚举。尚不清楚的是它是否应该：DeepSeek 发布了合法枚举，但从未声明非法级别是否应被拒绝，因此没有基准可供判断，这意味着这既不算官方行为，也不算我们路径上的缺陷。安全的客户端侧方法：自行验证级别，不要指望 API 捕获它。

10. 能力 × API 支持矩阵

以下单元格给出了每个 API 的参数/字段拼写。除非标记为 DeepSeek 的明确措辞，否则每个结论均来自于 2026-08-13 对 AIHubMix 生产 API 进行的实际调用。

图例：✅ 验证有效 · 🟡 被接受但无法确认有效 · ❗ 需要注意（见上面的说明） · ➖ 此 API 中没有此概念

常见问题

deepseek-v4-pro-0813 在 AIHubMix 上支持哪些 API？
聊天补全（/v1/chat/completions）、响应（/v1/responses）和 Claude 兼容的消息 API（/v1/messages）。

为什么多轮对话突然返回 400？
最常见的原因是未回传的思维历史。在思维模式下，必须逐字回放上一个回合的思维内容：聊天助手消息中的 reasoning_content，响应中的 type="reasoning" 输出项，以及消息中的 thinking 内容块。携带工具的多轮对话是最容易触发的地方——许多框架在组装历史时通过 type == "message" 过滤输出项，这会丢弃推理项。

可以关闭思维吗？
可以。在聊天或消息中发送 thinking: {"type": "disabled"}，在响应中发送 reasoning: {"effort": "none"}。一旦关闭，思维内容和思维令牌都会消失。

这三个 reasoning_effort 级别有区别吗？
low / high / max 都被接受（默认 high；medium 和 xhigh 被映射到 high 以兼容）。在测试中，对于同一问题的思维令牌计数显示不同级别之间没有单调差异，且没有回显，因此无法从调用者的角度确认差异。只有响应中的 none 级别（思维关闭）产生明显可观察的差异。

为什么 tool_choice: "required" 返回 400？
在思维开启时，该值不被接受（错误主体显示 思维模式不支持此 tool_choice）。使用命名函数 tool_choice（{"type": "function", "function": {"name": "..."}}）在思维开启时强制特定调用，或者先禁用思维，然后再使用 required。

如何启用上下文缓存？
您不需要——它是自动的。将稳定、不变的内容（系统提示、知识片段、工具定义）放在请求的前面，命中计数在使用中报告：聊天中的 prompt_tokens_details.cached_tokens，响应中的 input_tokens_details.cached_tokens，以及消息中的 cache_read_input_tokens。

有关定价和实时状态，请参见 deepseek-v4-pro-0813 模型页面；有关更多模型，请访问 模型画廊。

相关实操指南：Kimi K3 实操指南（新参数和三种 API 支持矩阵）以及 GPT-5.6 提示缓存和计费变更。