DeepSeek V4 Pro (0813)：思考パスバックと3API対応マトリクス

本記事ではdeepseek-v4-pro-0813の利用上の注意点と落とし穴を扱います。AIHubMixでは、本モデルをChat Completions、Responses、Claude互換のMessages APIで利用できます。関連情報：DeepSeek公式APIドキュメント。

各セクションの「Verified」(検証済み)の結論とサンプルレスポンスは、2026-08-13にAIHubMixのAPI（Chat Completions / Responses / Messages）で実際に行った呼び出しに基づいています。「Verified」と記載のない仕様項目は、DeepSeekの公式ドキュメントに基づいています。

1. モデルの位置づけと仕様一覧

V4 Proは、DeepSeek V4世代のハイエンド版です（軽量版のdeepseek-v4-flashが兄弟モデルにあたります）。リリースの系譜は2026-04-24のDeepSeek-V4 Previewにさかのぼり、0813はDeepSeekが現行ビルドに付与したMODEL VERSIONラベルです。生の仕様に加え、以下の4点が特徴です：

• スパースなフロンティアモデル：総パラメータ1.6T、活性化パラメータ49B（MoE、すなわちmixture-of-experts（専門家混合）アーキテクチャです。推論の各パスでは専門家ネットワークの一部だけが動作します。総パラメータは知識容量を決め、活性化パラメータは呼び出しごとの計算コストを決めます）。モデルカードには、CSA+HCAハイブリッドアテンション、mHC、Muonオプティマイザが記載されています。
• MITライセンスのオープンウェイト：deepseek-ai/DeepSeek-V4-Proは、MITライセンス（最も寛容なオープンソースライセンスの一つで、商用利用とクローズドソースでの再配布の両方が許可されています）のもとでHuggingFaceに公開されており、自前でホスティングすることもできます。この規模のモデルでMITは珍しい選択です。モデルカードのセルフホスティングに関する注記では、Think Max（最も高い思考レベル）で実行する場合に≥384Kトークンのコンテキストウィンドウを推奨しています。これはセルフホスティング向けの導入ガイダンスであり、ホスト型APIの仕様ではありません。
• マルチプロトコル対応は第三者による変換ではなく、提供元自身によるもの：DeepSeek自身がOpenAI Chat API、Anthropic互換エンドポイント（/anthropic、claude-opus*を本モデルにマッピング）、そしてResponses APIを提供しています（DeepSeekはこの形式をネイティブにサポートし、Codex向けの調整を行うと説明しています）。また、別のエンドポイントでFIM（fill-in-the-middle、穴埋め）補完をベータ機能として提供していますが、これはAIHubMixの3つのAPIには含まれません。
• キャッシュヒットとキャッシュミスの価格差は約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の公式の記載は「Image and file inputs are not supported (input_image parts do not cause an error, but are replaced with a placeholder text)」です。つまりinput_imageパーツはリクエストを失敗させず、プレースホルダーのテキストに置き換えられます。Chat Completionsでは、userメッセージのcontentは文字列のみを受け付け、Messagesではtype="image"ブロックが非対応とマークされています。マルチモーダルのルーティングを構築する際は、「エラーが出ない」ことをモデルが実際に画像を見た証拠として扱ってはいけません。

2. 思考をオフにするには？3つのAPIと3つのフィールド形式

V4 Proはデフォルトで思考します。パラメータを何も送らなければ、思考内容を含むレスポンスが返ります。思考をオフにする方法は、3つの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": "What is 2 + 2?"}],
    extra_body={"thinking": {"type": "disabled"}},
)

# Thinking on  (default): message.reasoning_content present, reasoning_tokens = 43
# Thinking off (disabled): reasoning_content absent, reasoning_tokens absent

検証済み：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="What is 2 + 2?",
    reasoning={"effort": "none"},
)

# effort="none": usage.output_tokens_details.reasoning_tokens = 0
#                output[0] is the message item directly (no reasoning item)
# effort unset : output always starts with a reasoning item

検証済み：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": "What is 2 + 2?"}],
    extra_body={"thinking": {"type": "disabled"}},
)

# Thinking on  (default): content = [thinking block, text block]
# Thinking off (disabled): content = [text block]

検証済み：無効にすると、thinkingブロックは完全に消え、textブロックだけが残ります。

思考レベルについて：テストでは、Chat Completionsでlowとmaxがどちらも200を返しました（highがデフォルトで、フィールドを省略した場合に適用されます）。ただし、同じ質問に対する思考トークン数は、レベル間で単調な差を示しません（簡単な質問：low=43 / max=27、難しい質問：low=114 / max=92）。また、レスポンスには何もエコーバックされません。レベルは受け付けられますが、レスポンスから区別できるシグナルは観測できません。Responsesでは、noneレベル（思考オフ）だけがレスポンス側から確認できます。

3. マルチターン会話が突然400を返すのはなぜか？思考履歴はそのままパスバックする必要がある

このモデルで最も多いつまずきポイントです。思考モードでは、マルチターン会話で前のターンの思考内容をそのままパスバックしなければなりません。さもないとリクエストは拒否されます。品質が低下するのではなく、HTTP 400という厳格なエラーになります。

3つのAPIは同じ思考内容を、異なるフィールド名で保持しています：

検証済み（トリガー条件）：このバリデーションは、toolsを含むマルチターンのリクエスト（モデルがツール呼び出しを行い、その後ツールの結果を送り返す場合）で一貫して発動しました。ツールを使わず、モデルが直接回答する単純なマルチターンのリクエストでは、今回のテストではバリデーションは発動せず、200が返されました。つまり、ツールのオーケストレーション（エージェントやファンクションコーリングのワークロード）で最も遭遇しやすく、思考内容は保存して再送すべき会話状態の一部として扱うべきです。

Chat Completions

# Multi-turn: pass the previous assistant message back verbatim, including reasoning_content
messages = [
    {"role": "user", "content": "What is 1 + 1? Remember the result."},
    {
        "role": "assistant",
        "content": "2",
        "reasoning_content": "<reasoning_content from the previous response>",
    },
    {"role": "user", "content": "Add 1 to the result."},
]

# Dropping reasoning_content -> HTTP 400 invalid_request_error

検証済み：履歴のassistantメッセージにreasoning_contentがないと400が返ります。それを追加すると、同一のリクエストが200を返し、正しく続行されます。

Responses

# Multi-turn: input = previous input + response.output (reasoning item included) + new message
input = previous_input + response.output + [
    {"role": "user", "content": "Add 1 to the result."}
]

# Filtering out the type="reasoning" item -> HTTP 400

検証済み：response.outputをそのまま履歴に戻すだけで済みます。履歴を組み立てる際に出力アイテムをtype == "message"でフィルタリングすると、reasoningアイテムが落ちて400が発生します。これが最もよくある落とし穴です。

Messages

# Multi-turn: pass response.content back verbatim as the assistant message
messages = [
    {"role": "user", "content": "What's the weather in Paris?"},
    {"role": "assistant", "content": response.content},   # thinking + tool_use blocks
    {"role": "user", "content": [tool_result_block]},
]

# Stripping the thinking block -> HTTP 400

検証済み：contentの配列から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": "What's the weather in Paris?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a city",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
    tool_choice={"type": "function", "function": {"name": "get_weather"}},
)

# Observed: finish_reason "tool_calls", tool_calls[0].function.arguments = {"city": "Paris"}

❗ 検証済み：思考が有効な間はtool_choice: "required"を使えません。Thinking mode does not support this tool_choiceというメッセージとともに400が返されます。思考を無効にする（thinking.type="disabled"）と、同一のリクエストが200を返します。「必ずツールを呼ぶ」という意味が必要な場合は、代わりに名前付き関数のtool_choiceを使ってください（上記のとおり、思考が有効でも動作します）。または、先に思考をオフにしてからrequiredを使ってください。

Responses

フラット形式（type / name / parametersが同じ階層にある）。

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="What's the weather in Paris?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
)

# Observed output items: ["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": "Get weather for a city",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Observed: content contains a tool_use block, name = get_weather, input = {"city": "Paris"}

❗ 並列ツール呼び出しはオフにできません。DeepSeek自身の設計によるものです。公式のAnthropic互換ページでは、tool_choiceの行にdisable_parallel_tool_use is ignoredと明記されており、Responsesページも同様にparallel_tool_calls | Ignored (parallel tool calling is always enabled)と記載しています。テストでも一致しました。disable_parallel_tool_use: trueを指定して2つの都市について同時に尋ねても、2つの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": "Return {\"a\": 1} as JSON."}],
    response_format={"type": "json_object"},
)

# Observed response content: {"a":1}

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

Responses

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

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="Return the number 1 under key a.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"a": {"type": "integer"}}, "required": ["a"]},
        }
    },
)

# Observed output text: {"a":1}

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

Messages

Messages（Anthropic）协议没有与 response_format / text.format 对应的功能。常用的变通方法是把 Schema 放在工具中：声明一个 input_schema 为目标 Schema 的工具，设置 tool_choice: {"type": "any"}，然后从 tool_use 块的 input 中读取结构化结果。本轮测试没有专门验证这一模式；如果需要严格的 Schema 保证，请优先选择 Chat Completions 或 Responses。

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

上下文缓存（相同前缀会被复用，缓存部分按较低费率计费）默认开启，无需任何参数。第二次使用相同长前缀的请求会在 usage 中报告命中情况，字段名因 API 而异。关于缓存细节和当前价格，请参阅模型页面；关于跨模型的缓存策略和命中率技巧，请参阅提示词缓存实践。

Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 640}   # first call: 0

已验证：在同一通道上连续两次调用相同的长前缀，cached_tokens 从 0 变为 640。

Responses

# usage of the second call with identical long instructions
"input_tokens_details": {"cached_tokens": 896}    # first call: 0

Messages

# usage of a call whose long system prefix was already warmed
"cache_read_input_tokens": 896

已验证：上述前缀先由一个内容相同的 Responses 请求预热，随后第一次 Messages 调用立即命中了 896 个 token —— 这与缓存以内容前缀为键、且在各协议接口之间共享的情况相符。

7. logprobs：Chat 返回两个通道

logprobs（对数概率，即模型对每个候选 token 的置信度明细）在两个 API 上的返回结构不同，解析代码需要分别处理。

Chat Completions

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

# Observed: choices[0].logprobs contains TWO arrays
#   logprobs.content[]            -> tokens of the final answer
#   logprobs.reasoning_content[]  -> tokens of the thinking text

❗ 已验证：Chat 同时为 content 和 reasoning_content 返回对数概率。仅读取 logprobs.content 的代码（符合标准 OpenAI 响应结构）不会报错，但会悄无声息地漏掉思考通道；如果你的代码假设 logprobs 下只有一个数组，请先加上结构判断。

Responses

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="Say hi.",
    top_logprobs=3,
)

# Observed: logprobs only on the final message item
#   output[-1].content[0].logprobs[] with logprob + top_logprobs details

已验证：Responses 只把 logprobs 附加在最终文本项上，没有 Chat 中所见的双通道结构。

Messages

Messages（Anthropic）协议没有等价字段。如需 token 级别的概率明细，请使用 Chat Completions 或 Responses。

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

这里的网页搜索是服务端工具（检索在服务器端执行，客户端从不自行发出请求），测试中它在 Responses 和 Messages API 上都确实得到了执行。

Responses

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="What is the latest stable version of Python?",
    tools=[{"type": "web_search"}],
)

# Observed output item sequence:
# ["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": "What is the latest stable version of Python?"}],
)

# Observed content block sequence:
# ["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 兼容页面也列出了与搜索相关的内容块。

# Three control groups, same question requiring live information, all HTTP 200:
# A no search field       -> "cannot retrieve", annotations = null
# B web_search_options    -> "cannot retrieve", annotations = null, usage identical to A
# C enable_search         -> "cannot retrieve", annotations = null, usage identical to A

已验证：发送 web_search_options 或 enable_search 不会报错，但也不会进行任何检索 —— 响应中不带 annotations（网页搜索执行时附在响应上的引用列表），并且 usage 与对照组逐字段一致。如需联网访问，请使用 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 生产 API 的实际调用。

凡例：✅ 動作確認済み · 🟡 受け付けられるが効果は確認できない · ❗ 注意が必要（上記の注記を参照） · ➖ この API には該当する概念がない

FAQ

deepseek-v4-pro-0813 は AIHub Mix でどの API をサポートしていますか？
Chat Completions（/v1/chat/completions）、Responses（/v1/responses）、Claude 互換の Messages API（/v1/messages）です。

複数ターンの会話で突然 400 が返るのはなぜですか？
最も多い原因は、渡されなかった thinking の履歴です。thinking モードでは、前のターンの thinking 内容をそのまま再送する必要があります。Chat では assistant メッセージの reasoning_content、Responses では type="reasoning" の出力アイテム、Messages では thinking のコンテンツブロックが対象です。ツールを使う複数ターンの会話で特に問題になりやすく、多くのフレームワークは履歴を組み立てる際に type == "message" で出力アイテムをフィルタするため、reasoning アイテムが失われます。

thinking はオフにできますか？
はい。Chat または Messages では thinking: {"type": "disabled"} を、Responses では reasoning: {"effort": "none"} を送信してください。オフにすると、thinking 内容と thinking トークンの両方が出力されなくなります。

3 つの reasoning_effort レベルに違いはありますか？
low / high / max はいずれも受け付けられます（デフォルトは high。互換性のため medium と xhigh は high にマッピングされます）。テストでは、同じ質問に対する thinking トークン数はレベル間で単調な差が見られず、何も返されないため、呼び出し側からは違いを確認できません。明確に観測できる違いが出るのは、Responses における none レベル（thinking オフ）だけです。

なぜ tool_choice: "required" で 400 が返るのですか？
thinking が有効な間は、この値は受け付けられません（エラー本文は Thinking mode does not support this tool_choice となります）。thinking を有効にしたまま特定の呼び出しを強制するには、名前付きの関数 tool_choice（{"type": "function", "function": {"name": "..."}}）を使ってください。または、先に thinking を無効にしてから required を使うこともできます。

コンテキストキャッシュはどのように有効にしますか？
有効化の操作は不要で、自動的に行われます。変化しない安定した内容（システムプロンプト、ナレッジの断片、ツール定義など）をリクエストの先頭に置くと、ヒット数が usage に報告されます。Chat では prompt_tokens_details.cached_tokens、Responses では input_tokens_details.cached_tokens、Messages では cache_read_input_tokens です。

料金と現在のステータスについては deepseek-v4-pro-0813 モデルページ をご覧ください。その他のモデルは モデルギャラリー からご確認いただけます。

関連する実践ガイド：Kimi K3 実践ガイド（新しいパラメータと 3 API のサポート一覧）と GPT-5.6 のプロンプトキャッシュと課金の変更点。