DeepSeek API 的 JSON 与工具调用：Agent 如何避免把模型输出当成可靠动作

先说结论

先把时间范围说清楚：今天抓到的官方新闻候选没有提供可核验的、最近 72 小时内的新技术公告。本文因此不是当天快讯，而是一次近期技术复盘，主材料是 DeepSeek API 官方在 2024 年 7 月 25 日发布的 API 更新说明。

这份旧公告今天仍然值得重读，因为它把 Agent 最容易出事故的三件事放在了一起：结构化 JSON、工具调用，以及对输出长度和格式的约束。我的判断是，JSON Output 和 Function Calling 只能把模型输出变得更容易接入，不能把模型推断变成事实，更不能绕过权限、Schema、幂等性和人工确认。真正可靠的 Agent，应该把模型当作候选动作生成器，把确定性校验放在动作执行之前。

发生了什么

主体来源是 DeepSeek API 官方文档中的 New API Features，发布日期为 2024-07-25。官方公告介绍了 /chat/completions 的 JSON Output、Function Calling、Chat Prefix Completion，以及新的 /completions FIM Completion；同时说明这些能力面向 deepseek-chat 和 deepseek-coder。

下面的接口能力、支持范围和官方示例属于官方事实。我对 Agent 架构、失败处理、评测方式和上线边界的讨论属于我的判断。由于文章并非最近 72 小时新闻，读者在实际接入前仍应以当前模型列表、API 参考和兼容性说明为准，不能把历史公告中的型号和限制直接视为今天的服务承诺。

这条更新的意义不在于“模型终于会输出 JSON”，而在于它推动了一个接口层变化：模型响应可以被后续程序当作结构化候选继续处理，模型也可以提出调用外部工具的意图。对 Agent 来说，这比单纯生成一段自然语言更接近真正的执行链，但也因此需要更严格的边界。

技术细节

1. JSON Output 解决的是语法问题，不是语义问题

官方文档要求在请求中设置 response_format 为 JSON object，并在提示中明确引导模型输出 JSON；同时提醒合理设置 max_tokens，避免结果在中途被截断。这里有一个容易被忽略的区别：合法 JSON 只说明文本能被解析，不说明字段值正确。

例如，模型返回下面这样的结构，解析器可以顺利接受：

1
2
3
4
5

{
  "action": "create_task",
  "priority": "urgent",
  "due_date": "tomorrow"
}

但 action 是否属于允许集合、priority 是否符合业务枚举、日期是否有明确时区、当前调用者是否有创建权限，都不是 JSON 语法能够回答的问题。安全链路应当是：

1
2
3
4
5
6
7
8
9

模型生成候选对象
       ↓
JSON 解析
       ↓
版本化 Schema 校验
       ↓
字段范围、权限、影响面和幂等检查
       ↓
低风险动作执行，高风险动作确认

所以，工程验收不能只统计“JSON 解析成功率”。还要统计 Schema 通过率、字段准确率、无效值拒绝率、缺失信息时的澄清率，以及最终任务是否完成。

2. Function Calling 是动作提议，不是动作授权

DeepSeek 官方公告说明 Function Calling 支持一次调用中的多个函数，最多支持 128 个函数，并支持并行函数调用。这个能力让模型能够根据上下文选择一个或多个工具，并填充对应参数，应用程序再根据结果继续对话或执行流程。

从系统角度看，模型并没有真正“执行函数”。它只是返回一个候选调用，包括函数名和参数。真正的执行权仍应掌握在应用程序里。一个稳妥的处理过程至少包含四步：先确认函数名来自服务端允许集合，再按函数对应的 Schema 校验参数，然后检查权限、资源范围、幂等键和副作用，最后才决定执行或要求人工确认。

并行调用尤其需要明确失败语义。三个工具同时启动时，如果其中一个失败，系统是返回另外两个结果，还是回滚全部操作？如果两个工具都修改同一份资源，如何避免顺序竞争？如果用户取消任务，已经发出的调用能否停止？这些都必须由运行时定义，不能交给模型临场猜测。

3. Prefix Completion 和 FIM 适合控制生成边界

官方更新还介绍了 Chat Prefix Completion，以及面向代码补全的 FIM Completion。它们的共同点，是让应用程序提供更明确的生成起点或上下文边界，从而减少模型每次都从空白开始组织输出。

这类能力对代码、固定格式文档和模板化响应很有帮助，但边界控制不等于内容可信。前缀可能把模型带入错误的格式，代码补全也可能生成不存在的函数、过时的接口或不安全的调用。使用时仍要执行语法检查、静态分析、依赖检查和沙箱测试；不能因为输出看起来像完整代码，就直接放进生产执行路径。

4. 截断是结构化 Agent 的隐蔽故障

官方提醒合理设置 max_tokens，原因并不只是用户体验差。自然语言被截断时，人还能看出句子没有写完；JSON 被截断时，解析器可能直接失败，或者在某些中间层被错误修复后继续传播。工具参数被截断，则可能导致字段缺失、默认值生效或业务动作偏离原意。

因此，服务端应把“长度不足”作为明确失败状态处理，而不是无限重试同一个请求。重试必须有上限，并且要区分模型输出被截断、网络超时、Schema 不通过和工具执行失败。不同原因需要不同降级：截断可以压缩上下文或降低字段数量，Schema 失败可以要求模型重新生成，权限失败则必须停止，不能靠再次提示绕过。

对 Agent / 工程的影响

第一，API 合同必须版本化。工具名称、参数 Schema、枚举值和返回结构都属于公共合同，不能只写在提示词里。模型看到的工具说明、服务端真正接受的 Schema 和日志里记录的版本必须保持一致；发生变更时，要用旧回放集验证兼容性。

第二，模型输出、规则结果和工具回执必须分开。模型说“任务已经完成”只是推断，只有工具返回成功并经过服务端确认，系统才可以把动作标记为完成。界面也应该明确区分模型建议、验证结果和真实执行状态，避免把生成文本包装成事实。

第三，Agent 评测要从格式测试升级为端到端回放。合成测试集应覆盖正常参数、缺失字段、错误枚举、边界数值、重复请求、并行分支冲突、权限不足和工具超时。核心指标除了 JSON 合法率，还包括合法调用率、错误动作拦截率、重试次数、任务成功率、平均延迟和单位任务成本。

第四，并行函数调用要配合成本闸门。一个输入可能同时触发多个模型或工具，成本、网络请求数和外部副作用会一起放大。服务端应设置单任务并发上限、超时、取消、预算和最大步骤数；高风险动作则先生成变更集，再由人确认。

第五，隐私最小化不能因为结构化接口而放松。工具描述和上下文只应包含完成任务所需的信息，不应把长期会话、无关原文或敏感字段全部送入模型。可观测性可以记录模型版本、Schema 版本、候选数量、校验结果和耗时等元数据，原始内容按最小化原则处理并设置保存期限。

我的判断

DeepSeek API 这次历史更新最值得借鉴的，不是某个字段名，而是“模型输出必须进入程序控制面”这一思路。JSON Output 负责可解析，Function Calling 负责可编排，确定性规则才负责可执行。

我建议把模型工具调用放在受控工作流里：先做候选生成，再做 Schema、权限和影响面校验，最后才执行可回滚的动作。对于删除、发送、付款、权限修改等不可逆操作，永远不要因为格式正确或模型信心很高就跳过确认。

Q&A

Q1：来源和发布日期是什么？

A：主体来源是 DeepSeek API 官方文档 New API Features，发布日期为 2024-07-25。本文明确是近期技术复盘，不是最近 72 小时内的新发布。

Q2：JSON Output 能保证字段内容正确吗？

A：不能。它主要帮助程序获得可解析的 JSON 文本。字段是否存在、类型是否正确、枚举是否允许、业务含义是否成立，仍需版本化 Schema 和确定性规则验证。

Q3：Function Calling 会自动执行工具吗？

A：不会。模型只提出候选函数名和参数，应用程序必须重新确认允许集合、权限、范围、幂等性和副作用，再决定是否执行。

Q4：怎么做最小验证？

A：用合成数据建立一个只读工具和一个可回滚工具，覆盖正常输入、缺失字段、非法枚举、重复调用、超时和权限不足；比较 JSON 解析率、Schema 通过率、错误拦截率、任务成功率和总延迟。

Q5：什么时候不适合直接接入生产？

A：当工具没有严格 Schema、缺少权限检查、无法撤销、并行失败语义不清，或系统无法区分模型推断与真实回执时，不应让模型输出直接触发外部动作。

参考资料：

1. New API Features — DeepSeek API Docs（2024-07-25，官方文档）
2. Tool Calls Guide — DeepSeek API Docs（官方接口指南）
3. JSON Output Guide — DeepSeek API Docs（官方接口指南）

本文性质：近期趋势/技术复盘，不是过去 72 小时内新闻。
字数自检：≥1500 个中文字符（不含 frontmatter）
隐私自检：未写入姓名、账号、用户输入、内部网络细节、凭据或会话标识
封面 seed：2026-09-02-deepseek-api-tool-calling（唯一）
coverWidth/Height：1600 / 900
categories：ai_tech