DeepSeek API的JSON模式不是设了参数就稳定，关键在于把契约、采样、样例与校验串成闭环。本文给出可落地的实战方法。
在AI指导老师类产品里，模型输出往往要直接进入题目渲染、评分报告和学习计划页面，JSON解析失败会立刻变成白屏或脏数据。很多团队第一次接入DeepSeek API时，以为把response_format设为json_object就万事大吉，结果仍然遇到前后解释文字、字段名漂移、数组元素结构不一致和finish_reason为length导致的截断。要让JSON模式更“听话”，不能依赖单点参数，而要把提示词契约、采样控制、结构样例和工程校验连成一条链路。下面四个小节从实战角度拆解可复用的做法。
1. 把输出契约写进系统提示
JSON模式只约束输出格式倾向，不会替开发者定义业务字段。系统提示需要明确“只输出一个合法JSON对象，不要输出Markdown代码块、解释文字或前后缀”，并显式包含json这个关键词，因为DeepSeek API在启用JSON Output时要求提示词中出现相关字样，同时给出字段清单和类型约束。更稳妥的写法是把契约拆成三部分：输出范围、字段字典、禁止项。输出范围写清楚本次任务只生成题目解析对象还是评分报告对象；字段字典逐项说明必填字段、数据类型、枚举值和空值规则；禁止项列出不要注释、不要尾随逗号、不要中英文混用字段名。这样模型在解码阶段就有明确的收敛目标。
系统提示和用户提示要有分工。系统提示负责稳定契约，用户提示只放任务数据和业务上下文，两者不要互相覆盖。例如生成初中数学单选题时，系统提示固定question_type、options、answer、explanation、knowledge_points等字段，用户提示只提供知识点、难度和题干素材。用户输入最好用明确分隔符包裹，避免其中出现“忽略以上指令”之类的注入内容。契约中还要写清数组和空值的表达，比如没有选项时返回空数组而不是null，解析失败时返回error字段而不是自由文本。这些细节看似琐碎，却能显著减少后处理成本。
一个常见误区是把字段说明写成自然语言长句，模型容易理解成建议而非硬约束。更有效的是给出字段名、类型和允许值的紧凑描述，并在系统提示末尾再次强调“输出必须能被JSON.parse直接解析”。对于AI指导老师场景，知识点标签、难度等级、题型枚举最容易漂移，建议在契约中直接限定允许值，不要让模型自由创造同义词。契约越具体，JSON模式越接近“听话”，后续校验和重试的压力也越小。
2. 用采样参数压缩自由发挥空间
JSON模式解决的是格式倾向，采样参数决定模型在格式边缘游走的幅度。生成结构化数据时，temperature应压到0.1至0.3，top_p保持在0.8左右，避免同时使用高temperature和高top_p。较高的随机性会让模型在字段名、枚举值和数组长度上产生不必要的变体，尤其是在长输出中更容易出现前后不一致。frequency_penalty和presence_penalty不建议调高，这两项在结构化输出里可能促使模型改写字段名或插入额外说明，反而增加解析风险。
max_tokens要按目标结构估算，而不是沿用聊天场景的默认值。一个包含题干、四个选项、答案、解析和三个知识点标签的题目对象，通常需要数百个token；评分报告如果包含分项得分和改进建议，预算还要更高。预算不足时，finish_reason会返回length，JSON会在中途截断，前端拿到的是半截字符串。实战中可以先按字段数量和平均长度做粗算，再留出百分之三十左右的缓冲。如果仍然频繁截断，优先简化嵌套结构或拆分多次调用，而不是盲目放大预算。
流式响应需要额外注意拼接逻辑。JSON对象必须等整个响应结束后再解析，不能在流式片段上逐段做JSON.parse。可以把流式只用于展示进度，最终解析仍以完整拼接结果为准。请求参数中的response_format要明确设为json_object，不要和普通文本模式混用；同一业务链路里保持参数稳定，避免A/B测试时把格式失败误判为模型能力问题。采样控制的目标不是让输出变得死板，而是把随机性留给业务内容，把稳定性留给结构。
3. 用最小样例固定字段语义
JSON模式对“什么是合法JSON”有基本约束，但对“字段语义是否一致”约束有限，因此少样本样例比长篇说明更有效。样例应该是一个最小完整对象，覆盖必填字段、枚举值、数组元素和空值表达，不要放注释，也不要用省略号。比如题目对象可以给出一个单选题样例，其中options是包含label和text的对象数组，answer是选项label，knowledge_points是字符串数组，explanation是完整解析。模型会模仿样例的结构和命名习惯，样例越干净，输出越稳定。
样例设计要避免过度嵌套。AI指导老师类数据常见三层以上嵌套，例如学习计划包含周计划、日任务和资源推荐，如果每一层都塞入可变字段，模型很容易在深层数组里丢失字段。更稳妥的做法是把核心对象控制在两到三层，深层结构用扁平化字段或分次调用解决。字段命名统一使用snake_case，不要中英文混用，也不要在不同样例里给同一含义起不同名字。枚举值要写全，比如question_type只允许single_choice、multiple_choice、fill_blank、short_answer，不要让模型自行扩展。
需要提醒的是，DeepSeek API的response_format目前主要提供json_object模式，开发者不能假设服务端会按完整JSON Schema做严格校验。因此样例和提示词里的字段字典仍然是第一道防线，JSON Schema更适合放在应用侧做二次校验。可以在提示词中附上一段紧凑的schema描述，但不要指望它替代样例。对于空数组、null和缺失字段要明确区分：列表无内容返回空数组，标量无内容返回null，必填字段不允许缺失。把这三类情况在样例中各展示一次，比反复强调“不要漏字段”更有效。
4. 把校验重试做成工程闭环
无论提示词多细，生产环境都不能假设JSON一定合法。解析层要先捕获JSONDecodeError，再进入结构校验。结构校验可以用Pydantic或jsonschema完成，重点检查必填字段、类型、枚举值、数组元素结构和数值范围。AI指导老师场景里，评分报告的score必须是数字而不是字符串，题目选项的label必须唯一，知识点标签必须落在允许集合内，这些规则都应在应用侧显式实现。校验失败时不要直接把原始输出透传给前端，也不要静默丢弃，而要记录原始响应、finish_reason和错误摘要，为后续分析留下样本。
重试策略要有针对性。第一次失败后，把原始输出和校验错误摘要拼回新的用户提示，明确要求“只修复JSON结构，不改变业务语义”，同时把temperature降到0，重试次数控制在两到三次。如果错误是截断导致，应提高max_tokens或简化结构；如果是字段名漂移，应把正确字段名和样例再次强调；如果是枚举越界，应把允许值列表放在错误摘要旁边。重试不是简单重复请求，而是把校验结果变成下一轮的约束条件。超过重试次数后要有降级路径，例如返回带默认值的空结构、切换更简单的输出模板或转人工处理。
监控指标要围绕失败模式设计。可以统计解析失败率、schema校验失败率、finish_reason为length的比例、重试成功率和字段缺失分布。某类字段反复缺失，往往说明提示词契约不清或样例覆盖不足；某个枚举频繁越界，说明允许值没有写全。把这些指标按业务场景拆分，比如题目生成、错题解析、学习计划分别看，才能定位是模型问题还是契约问题。工程闭环的价值在于让每一次失败都变成可复用的约束，而不是把JSON模式当成一次性开关。监控面板按场景拆分后，团队才能判断问题出在契约、采样还是校验规则，而不是把所有失败都归因于模型。
