围绕DeepSeek JSON输出，拆解调用条件、Schema设计、参数调优与生产校验，给出可落地的工程化方法。
结构化输出正在从演示技巧变成工程接口。在AI指导老师场景里，学习计划、错题诊断、课堂反馈如果缺少稳定JSON，下游排课、题库和报表系统就要反复清洗文本，接口成本会迅速上升。DeepSeek提供JSON Output模式，通过response_format引导模型返回JSON对象，但它不是数据库约束，仍需要提示词、参数和校验层配合。实际项目里更值得关注的不是“能不能输出JSON”，而是“输出能否稳定通过业务校验”。
1. JSON输出能力边界与调用前置条件
DeepSeek的JSON模式通过请求参数response_format={“type”:”json_object”}开启，API与OpenAI接口风格接近，迁移成本不高。需要明确的是，它更接近解码阶段的格式引导，而不是强制绑定某一份JSON Schema。模型会倾向于输出合法JSON对象，但字段名、枚举值和嵌套结构仍可能出现漂移。调用时提示词中必须出现“json”相关表述，并给出期望格式的简短示例；如果只设置response_format而不在提示词里说明JSON，部分请求可能返回空内容或退回普通文本。生产环境优先选择deepseek-chat这类通用对话模型，推理模型在结构化输出上的表现需要单独评估，不宜直接假设一致。
调用前置条件还包括长度和随机性控制。max_tokens要按目标JSON的最大可能长度估算，并留出约两成余量，否则内容会在数组中间截断，表现为finish_reason为length，后续解析必然失败。temperature建议压到0到0.2之间，降低字段名改写和枚举值漂移。系统消息适合固定输出协议，用户消息负责具体任务和Schema示例，两者不要混在一起。以AI指导老师生成学习计划为例，提示词里要同时写明“只输出一个json对象”、字段清单和一条完整样例，而不是只写“请返回JSON”。不少团队踩过的坑是模型用Markdown代码块包裹JSON，解析前需要做剥离处理。
2. Schema设计与提示词约束方法
Schema设计要服务于下游系统，而不是追求字段多。字段名使用稳定的snake_case，类型明确到字符串、整数、布尔和数组，枚举字段尽量封闭，必填与可选字段分开定义，嵌套层级控制在三层以内。数组元素必须结构一致，空值策略要提前约定，例如缺失信息统一用null而不是空字符串。可以用Pydantic定义模型并导出JSON Schema，再改写成提示词中的精简示例，这样既保留类型约束，又避免把完整Schema塞进上下文造成 token 浪费。AI指导老师场景下，学习计划可以包含student_id、diagnosis、weekly_tasks数组，数组元素再包含day、knowledge_point、exercise_type和estimated_minutes，字段边界清晰后，排课系统才能直接消费。
提示词约束要具体到可执行。系统消息固定输出协议，声明只输出一个JSON对象、不输出解释、不使用Markdown围栏、不写注释、不留尾逗号；用户消息给出任务背景、字段说明、两个正例和一个反例。少样本示例比抽象描述更有效，尤其是枚举值。例如exercise_type只允许“基础巩固”“变式训练”“错题重做”三类，提示词里就要把这几个值原样列出，并说明不得自造同义词。日期统一为YYYY-MM-DD，数字字段不要加引号，这些细节看起来琐碎，却能明显降低校验失败率。
常见歧义来自中英文混用和格式不统一。同一字段有时返回“薄弱点”，有时返回weak_points，下游映射就会出错；布尔值有时写true，有时写“是”，Pydantic校验会直接拒绝。虽然JSON模式不强制Schema，但可以在提示词中明示enum和pattern，把约束前移。字段较多时，先让模型输出核心字段，再通过二次调用补全扩展字段，比一次性要求几十个字段更稳。Schema版本也要写进提示词模板，避免模型在旧字段和新字段之间摇摆。
3. 参数配置、解析与异常处理
参数配置要围绕“可解析”目标展开。max_tokens按Schema最大长度估算，数组类输出尤其要留余量；temperature压到0到0.2，top_p保持默认即可，不必频繁调整。流式输出可以改善首字节等待，但解析必须等流结束后累积完整内容，不能对半截JSON做json.loads。每次响应都要检查finish_reason，出现length就说明截断，应直接进入重试或降级，而不是把残缺内容交给修复逻辑。DeepSeek返回内容通常位于choices[0].message.content，封装客户端时要统一提取路径，避免上层业务重复处理。
解析层要做三件事：剥离可能的代码块围栏和前后说明文字，调用json.loads，再用Pydantic模型做字段级校验。捕获JSONDecodeError和ValidationError后，不要立即盲目重试，先把错误信息拼进下一次提示词，例如“上次输出缺少weekly_tasks字段，请补全并只输出json”。轻量规则可以修复尾逗号、未转义引号等常见问题，但不要写过于激进的自动修复，否则容易把错误数据洗成“看起来合法”的数据。重试控制在两到三次，配合指数退避和幂等键，避免重复调用放大成本。
日志要记录request_id、prompt版本、原始输出、校验错误类型和重试次数，敏感字段脱敏后再落盘。以错题诊断为例，模型返回的diagnosis数组缺少knowledge_point，校验失败后重试一次仍失败，就应降级到人工复核或模板化输出，而不是让脏数据进入题库。异常处理的目标不是追求百分之百解析成功，而是让失败可观测、可定位、可降级。
4. 生产集成与质量评估闭环
生产集成要把JSON输出当作接口契约管理。封装统一的DeepSeek客户端，集中管理Schema版本、提示词模板、超时、重试、限流和降级策略；输出层只接受通过校验的对象，校验失败时返回明确错误码，由业务决定重试、人工介入还是使用默认模板。Prompt模板和Schema都要版本化，字段变更先跑回归集再上线，避免排课系统因为一个字段改名而静默失败。对于AI指导老师这类多角色场景，学生端、教师端和管理端可以共享同一套底层Schema，但通过不同模板控制字段可见范围。
质量评估需要黄金集。准备一百到三百条覆盖典型和边界场景的样本，包括长文本、空字段、多义枚举和超长数组，定期统计解析成功率、字段准确率、枚举合规率、截断率、重试率、P95延迟和单次成本。解析成功率低往往不是模型能力问题，而是提示词缺少示例或max_tokens不足；枚举合规率低则要检查Schema是否把可选值写全。监控告警可以按模板和模型版本拆分，发现某版本重试率突增时快速回滚。
安全与合规同样不能缺位。用户输入不要直接拼进系统消息，减少提示词注入对输出结构的干扰；输出字段采用白名单，避免模型附带多余信息；涉及学生姓名、成绩等敏感数据时，在日志和评估集中脱敏。Schema版本要向前兼容，新增字段优先设为可选，废弃字段保留一个过渡周期。学习计划JSON进入排课系统后，字段稳定性和校验通过率比单次生成速度更重要，这也是JSON输出从“能用”走向“可运营”的关键。
