第 2 章:JSON 模式管什么、不管什么
本章目标:分别用「随口一句」和「写清约定」两种 Prompt 要 JSON,再打开 DeepSeek 的 JSON 模式,看清它保证了什么、没保证什么。
开篇:「用 JSON 输出」就够了吗
上一章的 Prompt 写得很细:字段名、每个字段的意思、示例、「不要输出任何其他文字」。日常更常见的写法是随口一句:
……用 JSON 格式输出每条的编号、类别和理由。DeepSeek 的 API 还有一个专门的开关,叫 JSON 模式。打开它,是不是随口一句也够了?
学完这一章,你能:
- 在代码里打开 JSON 模式
- 说清 JSON 模式保证了什么:输出一定是合法的 JSON
- 说清它不保证什么:形状和字段名,还得靠你约定
2.1 打开 JSON 模式
只多一个参数:
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": prompt}],
response_format={"type": "json_object"}, # JSON 模式
extra_body={"thinking": {"type": "disabled"}},
)
data = json.loads(resp.choices[0].message.content)DeepSeek 的文档要求:用 JSON 模式时,Prompt 里要提到 JSON,最好给一个样例。
2.2 随口一句:每次都不一样
Prompt 只写「把下面这些读者留言分类(提问、纠错、建议、感谢、广告、其他),用 JSON 格式输出每条的编号、类别和理由」,开关 JSON 模式各跑三次:
能直接 json.loads 吗 | 最外层是什么 | 字段名 | |
|---|---|---|---|
| 不开,第 1 次 | ✅ | 以编号为键的对象:{"1": {...}, "2": {...}} | 类别、理由(中文) |
| 不开,第 2 次 | ❌ | 外面包了一层 ```json 代码块 | 编号、类别、理由(中文) |
| 不开,第 3 次 | ✅ | {"items": [...]} | id、category、reason |
| 开,第 1 次 | ✅ | {"分类结果": [...]} | 编号、类别、理由(中文) |
| 开,第 2 次 | ✅ | {"items": [...]} | id、category、reason |
| 开,第 3 次 | ✅ | 以编号为键的对象:{"1": {...}} | category、reason |
不开 JSON 模式时,第 2 次把 JSON 包在了 ```json 和 ``` 中间:给人看是好意,给程序读就是错误,json.loads 直接报错。
打开 JSON 模式以后,三次都是合法的 JSON,这个问题没了。但三次是三种形状、两种语言的字段名。 你的程序今天写成 data["items"][0]["category"],明天碰上 data["分类结果"][0]["类别"],照样报错。
2.3 写清约定:每次都一样
换成上一章那种写清约定的 Prompt(字段名、意思、示例),打开 JSON 模式跑三次,再加上第 3 章校验时又跑的 8 次:11 次都是同一个形状,最外层 items,每条都是 id、category、reason、reply 四个字段,20 条正常留言的分类都是满分。
约定里最管用的是那一行示例:
{"items": [{"id": 99, "category": "提问", "reason": "问自己电脑上的设置", "reply": "先把报错贴上来,我帮你看看。"}]}它一次性说清了:最外层是什么、字段叫什么、值是什么类型。示例的编号用 99,内容也不来自测试集,原因《Prompt 工程》第 5 章说过:示例会被照抄。
最外层要不要包一层 items
实测 DeepSeek 的 JSON 模式最外层直接用数组也可以。本课还是包一层 {"items": [...]}:以后想加别的字段(比如「这批留言的总体情况」),不用改动原来的结构。
2.4 更严格的模式:DeepSeek 暂不支持
有的平台支持更严格的做法:你把字段约定写成一份 JSON Schema 交给它,它保证输出完全按这份约定来(OpenAI 叫 Structured Outputs)。
我在 DeepSeek 上试了一下,写这一章时(2026 年 11 月)返回的是:
Error code: 400 - This response_format type is unavailable now所以在 DeepSeek 上,能拿到的保证只有「是合法的 JSON」。字段对不对、值合不合规矩,得自己在程序里检查,这就是下一章的内容。换到支持严格模式的平台,也建议照样检查:多一道检查不费事,平台换了也不怕。
2.5 小结成一张表
| 随口一句 | 写清约定 | 写清约定 + JSON 模式 | |
|---|---|---|---|
一定能 json.loads | ❌ 可能带代码块 | 本课实测都能 | ✅ |
| 形状、字段名每次一样 | ❌ | ✅ | ✅ |
| 值一定合规矩(类别在清单里) | ❌ | 不保证 | 不保证 |
推荐的组合是最右边一栏,再加上下一章的校验。
试一试
- [ ] 用随口一句的 Prompt 开着 JSON 模式跑三次,数一数你拿到几种形状
- [ ] 给 Prompt 加上一行示例,再跑三次
- [ ] 在你常用的其他平台上查一查:它支持 JSON Schema 那种严格模式吗?
本章小结
| 要点 | 说明 |
|---|---|
| 打开方式 | response_format={"type": "json_object"},Prompt 里要提到 JSON 并给样例 |
| 它保证的 | 输出是合法的 JSON,不会包代码块、不会夹杂说明文字 |
| 它不保证的 | 最外层的形状、字段名、值是不是合规矩 |
| 约定 | 字段名、意思、一行示例;示例别用测试集里的 |
| 严格模式 | DeepSeek 写本章时不支持 json_schema,返回 400 |
下一章预告
形状和字段名稳住了,可值呢?类别会不会写成清单外的「置顶」?该有的回复会不会漏掉?
下一章用 Pydantic 给每个字段立规矩,不合格的当场拦下,再把报错发回去让它自己改。