DeepSeekガイド
DeepSeek APIのJSON出力:3つの条件と、空白が返ったときの対処
DeepSeek APIで確実にJSONを受け取るには、response_formatの指定・プロンプトへの「json」という語と見本・max_tokensの余裕の3つが要ります。さらに公式には、JSONと認識できない出力は空白に置き換えられるという仕様があります。2026年11月11日に確認した内容をまとめます。
JSON出力を有効にする3つの条件
公式のJSON Outputのページが挙げる条件は次の3つです。どれか1つでも欠けると、JSONにならない・途中で切れるといった失敗につながります。
- response_formatを{"type": "json_object"}にする。OpenAI SDKでは response_format 引数にそのまま渡せます。
- システムまたはユーザーのプロンプトに「json」という語を入れ、欲しい形の見本を示す。日本語のプロンプトでも、見本のJSONを添えるのが確実です。
- max_tokensを十分に大きくする。上限が小さいと、JSONの文字列が途中で切れて、読み込み時にエラーになります。
見本を添える理由は、モデルに「どのキーを・どの型で返すか」を伝えるためです。JSON出力は「有効なJSON文字列を返す」ことを保証する仕組みで、キーの名前や型までは指定できません。キーや型まで縛りたいときは、ツール呼び出しのstrictモードを検討します。
サンプルコード(日本語の請求メモを項目に分ける)
公式の例は英語の試験問題を「question」と「answer」に分けるものです。ここでは、日本語のメモを項目に分ける形に書き換えました。
import json
from openai import OpenAI
client = OpenAI(api_key="<APIキー>", base_url="https://api.deepseek.com")
system_prompt = """
ユーザーが請求のメモを送ります。「会社名」「金額」「支払期限」を取り出し、json形式で出力してください。
入力の例:
株式会社サンプルに12万円、来月末までに支払い
jsonの出力例:
{"会社名": "株式会社サンプル", "金額": 120000, "支払期限": "来月末"}
"""
response = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": "有限会社テストへ8万円、今月25日が期限"},
],
response_format={"type": "json_object"},
max_tokens=500,
)
print(json.loads(response.choices[0].message.content))プロンプトの中に「json」という語(上の例では「json形式」「jsonの出力例」)が入っている点に注目してください。公式は、この語を入れることを条件にしています。
空白が返る仕様と、再試行の書き方
公式のページには、見落としやすい注意が1つあります。出力がJSONとして認識できないとき、APIはその内容を空白(U+0020)に置き換えます。その結果、返ってきた content が空白だけになり、finish_reason が stop でも空に見えることがあります。公式は、プロンプトを直して緩和すること、そして空白のときに再試行するなどの処理をコードに入れることを勧めています。
def ask_json(messages, retries=2):
for _ in range(retries + 1):
res = client.chat.completions.create(
model="deepseek-flash",
messages=messages,
response_format={"type": "json_object"},
max_tokens=500,
)
text = res.choices[0].message.content or ""
if text.strip(): # 空白だけなら再試行
try:
return json.loads(text)
except json.JSONDecodeError:
pass # 途中で切れた場合も再試行
raise ValueError("JSONを得られませんでした")上のコードは、公式の注意に沿ってこのサイトで書いた例です。再試行のたびに料金がかかるため、回数は2〜3回に限り、失敗が続くならプロンプトの見本を見直します。残高不足や429などAPI側のエラーは別の話で、エラーコードの一覧で切り分けます。
JSON出力・strictツール・プレフィックスの使い分け
| 方法 | 得られるもの | 向く場面 | 注意 |
|---|---|---|---|
| JSON出力(json_object) | 有効なJSON文字列 | 自由な形のメモを項目に分ける、抽出 | キーや型は指定できない。空白が返ることがある |
| ツール呼び出しのstrict(Beta) | JSON Schemaに沿った引数 | キー・型・取りうる値まで固定したいとき | base_urlをbetaにし、全関数にstrictを付ける |
| プレフィックス補完(Beta) | 指定した書き出しの続き | コードブロックだけ欲しいとき | stopと組み合わせる |
思考モードをオンにした状態でJSON出力を使うときの細かい挙動は、公式のJSON Outputのページに書かれていません。重要な処理に組み込む前に、使うモデルと設定で手元で試して確かめてください。思考モードの設定はモデルの選び方にあります。
JSON出力はいつからある機能か
公式の更新履歴では、JSON Modeは2024年7月25日のAPI更新(Function Calling・チャットプレフィックス補完とともに)で追加されています。その後、2025年5月28日にdeepseek-reasonerがR1-0528へ更新された際に「JSON出力とFunction Callingに対応」と記載されました。現在のモデルの一覧(2026年11月11日)では、deepseek-flashとdeepseek-v4-proのどちらも「Json Output」に対応と表示されています。更新の流れは更新履歴の年表で見られます。
確認した公式資料
上の資料は2026年11月11日に確認しました。内容は予告なく変わるため、使う前に公式のページで最新の表示を確かめてください。サンプルコードは公式の例をもとに、このサイトで読みやすく書き換えたものです。
あわせて読むページ
よくある質問
JSON出力に「json」という語が必要なのはなぜですか?
公式のJSON Outputのページが、有効にする条件として「システムまたはユーザーのプロンプトにjsonという語を入れ、欲しいJSONの見本を示す」ことを挙げています。語が無いと、期待どおりに動かない場合があります。
返ってきた内容が空白だけでした。故障ですか?
公式に書かれた仕様の可能性があります。出力がJSONとして認識できないと、その内容が空白に置き換えられます。プロンプトの見本を直し、空白のときは再試行する処理を入れてください。
キーの名前まで固定できますか?
JSON出力では固定できません。キーや型まで縛るなら、ツール呼び出しのstrictモード(Beta)を使います。詳しくはツール呼び出しのページにあります。