DeepSeek 的结构化输出,我先把两条最容易翻车的规则摆出来。第一条,JSON 输出解析失败时,返回的 content 会被替换成空格,不是报错。第二条,thinking 模式下只要请求带了 tools 参数,上一轮的 reasoning_content 就必须完整回传,漏了就是 400。这两条官方文档都写了,但埋在示例里,不看全就踩。

我打开官方文档核了 1 遍模型口径。现在模型就两个:deepseek-flash 是 DeepSeek-V4.1-Flash-1017,deepseek-v4-pro 是 DeepSeek-V4-Pro-0813。我查了 1 遍价格页,旧的 deepseek-chat 和 deepseek-reasoner 已经不在上面了。这是硬伤。deepseek-v4-flash 这种 legacy 名字还接受,但指向的是退役模型。别拿旧名字写新代码。上下文 1M,最大输出 384K,并发限制 flash 2500、pro 500。

上下文 1M 要看清边界。它是输入能塞多少,不是输出能吐多少。最大输出 384K 是另一条线。喂超长文档没问题,想一次吐出几十万字,会被 384K 卡住。这条要记牢。

JSON 输出,失败是空格不是报错

JSON 输出靠 response_format 参数,官方写法是 response_format={'type': 'json_object'}。它有两个前置条件:prompt 里必须出现 json 这个词,还要给一个目标格式的示例,缺一条模型就不一定吐合法 JSON。

最要命的是失败行为。官方原话是,输出识别不成 JSON 时,API 把非 JSON 内容替换成空格,也就是 U+0020。结果 content 可能只剩空格,看着是空的,finish_reason 还是 stop。别直接解析。我建议先判空 content,retry 一次,再进解析。

import json
from openai import OpenAI

client = OpenAI(api_key="", base_url="https://api.deepseek.com")

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": "输出 JSON 格式,字段 question 和 answer。"},
        {"role": "user", "content": "世界上最高的山?"},
    ],
    response_format={"type": "json_object"},
)
content = resp.choices[0].message.content
if not content or not content.strip():
    raise RuntimeError("JSON 输出为空,需重试")
print(json.loads(content))

这段是我自己写的,含空 content 的兜底。max_tokens 也要给够,官方明确提醒 JSON 字符串可能被截断,截断就是 finish_reason="length",这跟解析失败是两回事。我建议 max_tokens 至少给到期望 JSON 长度的 1.5 倍。

reasoning_content 的两种回传规则

thinking 模式默认开启,默认 effort 是 high。开启后模型先输出思维链 reasoning_content,再给 content,两者同级。这个字段怎么处理,取决于请求带不带 tools,这是官方文档最容易看漏的地方。

不带 tools 参数时,reasoning_content 不需要回传,你回传了它也被忽略,不会拼进上下文。带 tools 参数时,情况反过来,所有历史轮的 reasoning_content 必须完整回传,哪怕那一轮模型没调工具。官方明确写,回传不完整,API 返回 400。这条要记牢,它是工具调用场景下最常见的一个 400。

# 带 tools 时,必须把整条 assistant 消息原样 append,含 reasoning_content
messages.append(response.choices[0].message)

# 等价于手动保留三个字段
# messages.append({
#     "role": "assistant",
#     "content": msg.content,
#     "reasoning_content": msg.reasoning_content,
#     "tool_calls": msg.tool_calls,
# })

这段是我照官方示例的结构写的。关键就是别只 append content 丢掉 reasoning_content。不带 tools 的普通多轮,官方说 reasoning_content 会被忽略,所以你只 append content 也安全。

参数兼容的边界

thinking 模式不支持 temperature、presence_penalty、frequency_penalty。官方说为了兼容,你设置这些参数不会报错,但也不生效。这是隐藏坑,别拿 openai 的默认值套上去。

top_p 的行为分模型,我把差异写清楚。deepseek-flash 在 thinking 模式有效范围 0.95 到 1.0,低于 0.95 按 0.95 处理;deepseek-v4-pro 在 thinking 模式直接忽略你的 top_p。这俩我核了 1 遍文档,同一套代码切模型时行为不一样。

并发也分档,flash 2500、pro 500。做高吞吐的批量任务,别全押 pro,flash 量大,先拿它扛并发,要深度推理再上 pro。这条最坑。

还有一条成本账要算。thinking 默认开、effort 默认 high,意味着你每次调用都在付思维链的 token,简单任务也不例外,这笔钱日积月累不小。做高频的简单调用,最好显式关掉 thinking。这条别忽略。

我给个判断收尾。DeepSeek 这两条规则,本质都是「官方把机制写全了,但读文档的人只看示例不看注意」。JSON 输出的空格坑,reasoning_content 的 tools 回传坑,都是上线后才爆的问题。你接 DeepSeek 做结构化输出,把空 content 兜底和 reasoning_content 回传这两件事先写进代码,比事后排查省十倍时间。