DeepSeek V4 Pro (0813): 思考回傳與三個 API 矩陣

本文涵蓋了 deepseek-v4-pro-0813 的使用注意事項和陷阱。在 AIHubMix 上，該模型可通過 Chat Completions、Responses 和 Claude 兼容的 Messages API 獲得。另請參見：DeepSeek 官方 API 文檔。

每個部分的「已驗證」結論和示例回應來自於 2026-08-13 通過 AIHubMix APIs（Chat Completions / Responses / Messages）進行的實際調用；未標記為「已驗證」的規範項目來自 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 Chat API、一個兼容 Anthropic 的端點（/anthropic，將 claude-opus* 映射到此模型），以及 Responses API（DeepSeek 描述對該格式的原生支持，並對 Codex 進行了調整）。它還在單獨的端點上提供 FIM（中間填充）完成作為 Beta 功能，這不屬於三個 AIHubMix APIs 的一部分。
• 快取命中與快取未命中定價之間約 120 倍的差距：DeepSeek 公布的定價機制是快取命中 $0.003625/M 與快取未命中 $0.435/M（輸出 $0.87/M），並且快取是自動的，無需設置參數。對於重用長前綴的工作負載（系統提示、長文檔），這一差距主導了帳單。實際零售定價是模型頁面顯示的價格。

已驗證：超過 max_tokens 會被驗證拒絕，而不是靜默截斷——發送 max_tokens=9999999 會返回 HTTP 400，錯誤主體會命名該字段並給出上限 393216。

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

❗ 圖像不會引發錯誤，但會被丟棄：Responses API 的官方措辭是「不支持圖像和文件輸入（input_image 部分不會引發錯誤，但會被替換為佔位符文本）」——input_image 部分不會使請求失敗，而是被替換為佔位符文本。在 Chat Completions 中，使用者消息 content 僅接受字符串，而在 Messages 中 type="image" 區塊被標記為不支持。在構建多模態路由時，切勿將「無錯誤」視為模型實際看到圖像的證據。

2. 如何關閉思考？三個 API，三種字段形狀

V4 Pro 默認開啟思考：完全不發送參數，回應將返回思考內容。關閉思考在三個 API 上使用不同的字段形狀。

Chat Completions

使用頂層 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 一起消失，這確認了開關生效。

Responses

Responses 上沒有單獨的開關；關閉思考意味著將等級設置為 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 輸出項消失），這確認了其生效。

Messages

與 Chat Completions 相同的名稱和形狀：頂層 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"}},
)

# 開啟思考  (默認)：content = [思考區塊，文本區塊]
# 關閉思考（禁用）：content = [文本區塊]

已驗證：一旦禁用，thinking 區塊完全消失，僅剩 text 區塊。

關於思考等級：low 和 max 在 Chat Completions 測試中均返回 200（high 是默認並在省略字段時適用），但思考令牌計數顯示對於同一問題，等級之間沒有單調差異（簡單問題：low=43 / max=27；困難問題：low=114 / max=92），並且回應中沒有任何回聲——這些等級被接受，但從回應中無法觀察到區分信號。在 Responses 中，只有 none 等級（關閉思考）可以從回應端確認。

3. 為什麼多輪對話突然返回 400？思考歷史必須逐字回傳

這是該模型最常見的陷阱：在思考模式下，多輪對話必須逐字回傳前一輪的思考內容，否則請求將被拒絕。不是降級，不是低質量——而是硬性 HTTP 400。

這三個 API 在不同的字段名稱下攜帶相同的思考內容：

已驗證（觸發條件）：這一驗證在攜帶 tools 的多輪請求中始終觸發（模型發出工具調用，然後將工具結果發回）。在沒有工具的普通多輪請求中，模型直接回答，這一輪測試中驗證未觸發，請求返回 200。換句話說，工具協調（代理/函數調用工作負載）是最可能遇到的地方，因此將思考內容視為您持久化和重播的對話狀態的一部分。

Chat Completions

# 多輪：逐字回傳前一助手消息，包括 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 並正確繼續。

Responses

# 多輪：input = 前一輸入 + response.output（包含推理項） + 新消息
input = previous_input + response.output + [
    {"role": "user", "content": "在結果上加 1。"}
]

# 過濾掉 type="reasoning" 項 -> HTTP 400

已驗證：將 response.output 原樣拼接回去就是所需的。通過 type == "message" 過濾輸出項時，組裝歷史會丟棄 reasoning 項並觸發 400——這是最常見的被咬到的方式。

Messages

# 多輪：逐字回傳 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 以其自己的協議形狀聲明工具；這些形狀不可互換。

Chat Completions

嵌套形狀（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。

Responses

平面形狀（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"}

已驗證：將 Chat Completions 嵌套形狀（function: {...}）複製到 Responses 返回 400——請使用平面形狀。tool_choice: "required" 受到與 Chat 相同的思考模式限制。

Messages

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 被忽略，而 Responses 頁面同樣指出 parallel_tool_calls | 被忽略（並行工具調用始終啟用）。測試結果一致：同時詢問兩個城市時，即使設置了 disable_parallel_tool_use: true，仍然返回兩個 tool_use 區塊。如果您需要串行執行，請在客戶端側先執行第一個調用或自行排隊。

工具數量和上下文成本：在單個請求中發送 200 個函數定義仍然返回 200 並給出正常答案，並且未觸發任何計數驗證（在此路徑上觀察到；未測試更高的計數）。但該請求的 prompt_tokens 達到 6,105——工具定義完全進入上下文並計費。當您有許多工具時，請根據場景修剪工具集，而不是無條件地聲明所有工具。

5. 結構化輸出

Chat Completions

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。

Responses

通過 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}

已驗證：輸出嚴格符合給定的模式。

Messages

Messages（Anthropic）協議沒有 response_format / text.format 的等效項。通常的解決方法是將模式放在工具中——聲明一個工具，其 input_schema 是您的目標模式，設置 tool_choice: {"type": "any"}，並從 tool_use 區塊的 input 中讀取結構化結果。本輪測試未特別驗證該模式；當您需要硬性模式保證時，請優先考慮 Chat Completions 或 Responses。

6. 如何啟用上下文快取？您無需啟用，它是自動的

上下文快取（相同的前綴被重用，快取部分以較低的費率計費）默認開啟，無需參數。第二次請求使用相同的長前綴時，會在 usage 中報告命中，字段名稱因 API 而異。有關快取詳細信息和當前定價，請參見 模型頁面；有關跨模型快取策略和命中率技術，請參見 提示快取實踐。

Chat Completions

# 使用相同長前綴的第二次調用
"prompt_tokens_details": {"cached_tokens": 640}   # 第一次調用：0

已驗證：在同一通道上進行的兩次連續調用，使用相同的長前綴，將 cached_tokens 從 0 移動到 640。

Responses

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

Messages

# 使用長系統前綴已經預熱的調用
"cache_read_input_tokens": 896

已驗證：上述前綴已通過具有相同內容的 Responses 請求預熱，第一次 Messages 調用立即命中 896——與快取基於內容前綴並在協議表面之間共享的情況一致。

7. logprobs：Chat 返回兩個通道

logprobs（對數概率——模型對每個候選令牌的信心詳細信息）在兩個 API 上以不同的形狀返回，解析代碼必須分開處理它們。

Chat Completions

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[]  -> 思考文本的令牌

❗ 已驗證：Chat 返回 content 和 reasoning_content 的對數概率。僅讀取 logprobs.content 的代碼，根據標準 OpenAI 回應形狀，將不會出錯，但會靜默錯過思考通道；如果您的代碼假設 logprobs 下有單個數組，請先添加形狀檢查。

Responses

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

# 觀察到：對數概率僅在最後的消息項上
#   output[-1].content[0].logprobs[] 具有 logprob + top_logprobs 詳細信息

已驗證：Responses 僅將對數概率附加到最後的文本項——沒有在 Chat 上看到的雙通道形狀。

Messages

Messages（Anthropic）協議沒有等效字段。要獲取令牌級概率詳細信息，請使用 Chat Completions 或 Responses。

8. 哪些 API 可以搜索網頁？

這裡的網頁搜索是一個伺服器端工具（檢索在伺服器上運行；客戶端從不發出請求），並且在測試中確實在 Responses 和 Messages APIs 上執行。

Responses

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

# 觀察到的輸出項序列：
# ["reasoning", "web_search_call", "reasoning", "message"]

已驗證：web_search_call 項出現在輸出序列中，這意味著伺服器確實執行了檢索。

Messages

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——檢索請求確實發生並被計量。

Chat Completions

無法在 Chat 上觸發網頁搜索。DeepSeek 的官方 Chat API 參考中在請求架構中沒有任何搜索工具字段（這是通過逐一檢查字段列表確定的缺失；DeepSeek 沒有明確聲明否認支持）。明確聲明支持伺服器端搜索的 API 是 Responses（web_search），官方 Messages 兼容性頁面也列出了與搜索相關的內容區塊。

# 三個控制組，相同問題需要實時信息，全部 HTTP 200：
# A 無搜索字段       -> "無法檢索"，註釋 = null
# B web_search_options    -> "無法檢索"，註釋 = null，使用與 A 相同
# C enable_search         -> "無法檢索"，註釋 = null，使用與 A 相同

已驗證：發送 web_search_options 或 enable_search 不會引發錯誤，但也不會檢索任何內容——回應不攜帶 annotations（當網頁搜索運行時附加到回應的引用列表），並且使用與控制組逐字段匹配。要訪問網頁，請使用 Responses 或 Messages 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 生產 APIs 的實際調用。

圖例：✅ 驗證有效 · 🟡 接受但無法確認有效 · ❗ 需要注意（見上文說明） · ➖ 此 API 上沒有此概念

常見問題

deepseek-v4-pro-0813 在 AIHubMix 上支持哪些 API？
Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Claude 兼容的 Messages API（/v1/messages）。

為什麼多輪對話突然返回 400？
最常見的原因是未回傳的思考歷史。在思考模式下，前一輪的思考內容必須逐字重播：Chat 中助手消息的 reasoning_content、Responses 中的 type="reasoning" 輸出項，以及 Messages 中的 thinking 內容區塊。攜帶工具的多輪請求最容易出現此問題——許多框架在組裝歷史時通過 type == "message" 過濾輸出項，這會丟棄推理項。

可以關閉思考嗎？
可以。在 Chat 或 Messages 中發送 thinking: {"type": "disabled"}，在 Responses 中發送 reasoning: {"effort": "none"}。一旦關閉，思考內容和思考令牌都會消失。

三個 reasoning_effort 等級有區別嗎？
low / high / max 都被接受（默認為 high；medium 和 xhigh 被映射到 high 以保持兼容性）。在測試中，對於同一問題的思考令牌計數顯示等級之間沒有單調差異，且沒有回聲，因此無法從調用者端確認區別。只有 Responses 中的 none 等級（關閉思考）產生明顯可觀察的差異。

為什麼 tool_choice: "required" 返回 400？
該值在思考開啟時不被接受（錯誤主體顯示 思考模式不支持此 tool_choice）。使用命名函數 tool_choice（{"type": "function", "function": {"name": "..."}}）在思考開啟時強制特定調用，或者先禁用思考然後再使用 required。

如何啟用上下文快取？
您無需啟用——它是自動的。將穩定、不變的內容（系統提示、知識片段、工具定義）放在請求的前面，命中計數在使用中報告：Chat 上的 prompt_tokens_details.cached_tokens、Responses 上的 input_tokens_details.cached_tokens，以及 Messages 上的 cache_read_input_tokens。

有關定價和實時狀態，請參見 deepseek-v4-pro-0813 模型頁面；有關更多模型，請訪問 模型畫廊。

相關實作指南：Kimi K3 實作指南（新參數和三個 API 支持矩陣）以及 GPT-5.6 提示快取和計費變更。