DeepSeek API 的 JSON 输出与工具调用

把模型回答交给程序处理,需要明确结构并验证结果。本页依次介绍 JSON 输出、校验重试、工具调用流程,以及批量请求的并发和成本控制。

JSON 输出的三个条件

希望结果可以直接入库,需要同时准备三类约束。缺少其中一项,输出可能又回到自然语言。

  1. 约定响应格式:请求参数开启 JSON 对象格式,要求返回 JSON 而非解释性文字。
  2. 定义字段:逐项写明名称、类型、必填与否、取值范围和嵌套结构。
  3. 提供示例:给出符合要求的 JSON,帮助模型对齐目标结构。
messages=[ {"role":"system","content":"仅输出 JSON 对象。字段:order_id(字符串),amount(数字,保留两位小数),channel(枚举:web/app/store),tags(字符串数组,可为空)。"}, {"role":"user","content":"把这笔订单转成结构化记录:订单号 A2024-8891,金额 1284.5 元,来自小程序渠道。"} ] response_format={"type":"json_object"}

解析、校验和重试

模型输出具有概率性,不能假定每次都完全遵循要求。处理链路应包含解析、校验和失败重试。

import json def extract(text): try: data = json.loads(text) except json.JSONDecodeError as e: return None, f"JSON 解析失败:{e}" required = {"order_id", "amount", "channel", "tags"} missing = required - set(data) if missing: return None, f"缺少字段:{sorted(missing)}" if not isinstance(data["amount"], (int, float)): return None, "amount 不是数字" return data, None result, error = extract(text) if error: # 把错误信息带回对话,让模型自己修正一次 text = retry_with_error(text, error)

重试时带回原样的具体校验错误,比重新泛泛提问更有针对性。生产环境需设重试上限,例如两次,防止异常输入导致无限循环。

工具调用的四个环节

工具调用让模型选择使用应用提供的能力,通常分为以下四步:

  1. 声明可用工具:在请求中列出函数名称、用途及参数结构。参数说明越清楚,模型越容易选对。
  2. 由模型选择调用:需要工具时,模型返回函数名称与参数。这一步不应以编造答案替代真实调用。
  3. 应用本地执行:由你的程序调用函数并取得真实结果。执行动作始终在应用一侧,模型不直接接触系统。
  4. 回传工具结果:将真实执行结果作为消息再发给模型。模型随后依据这些数据生成最终答复。
工具声明(要点) { "name": "query_orders", "description": "按用户 ID 查询最近 30 天的订单列表,返回金额与渠道", "parameters": { "type": "object", "properties": { "user_id": {"type": "string"}, "days": {"type": "integer", "default": 30} }, "required": ["user_id"] } } 执行链路 模型请求调用 query_orders(user_id="U1024") → 你的代码查库并返回真实订单数组 → 把数组作为 tool 消息回传 → 模型据此回答用户问题

工具说明含糊会选错;返回内容太长会占据上下文,可在应用中截断或总结。涉及写操作需再确认,不要让模型独自决定删除、支付等执行动作。

批量调用的资源和成本

地址、Key 和模型名等基础配置,请阅读 API 调用指南。如果希望在本地运行同样流程,可继续查看 DeepSeek 本地运行指南。

问题解答

API 工程实践答疑

JSON 解析失败通常因为什么?

常见解析失败是 JSON 周围夹带解释,或字段名不符合约定。应启用对象响应模式,提示中提供字段定义与样例,程序解析验证,失败后带回错误再重试一次。

模型与应用如何完成工具调用?

先声明工具与参数,再由模型返回所需工具名和参数。自己的程序负责执行并回传结果,模型再形成答复;真正执行始终在应用侧,模型只决定请求什么。

相关操作指南

继续阅读相关教程