API 工程化:JSON 输出、函数调用与批量作业

把 DeepSeek 接进系统后,真正的难点从"能不能调通"变成"能不能一致、可控地跑"。

本教程讲三件事:让模型一致输出可直接入库的 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 消息回传 → 模型据此回答用户问题

几个容易踩的坑:工具解释写得太笼统会导致选错工具;工具返回资讯太长会挤占上下文,需要自行截断或摘要;涉及写操作时要加二次查证,不要让模型直接决定开展删除或支付这类动作。

批量作业的并发与成本

接口地址、密钥与模型名的齐备用法见 API 接入指南;当要在本地跑同样的流程,看 本地部署教程。

常见问题

工程化问答

让模型输出 JSON 时最常见的失败原因是什么?

最普遍的是模型在 JSON 前后加了解释性文字,抑或字段名与要求不一致。解决办法是开启 JSON 对象的响应格式模式,在系统提示中给出字段定义与示例,并在代码里做一次解析校验,失败时带着错误讯息重试一次。

函数调用是怎么工作的?

基本流程是四步:你在请求里声明可用工具及参数结构,模型识别需要调用时返回工具名与参数,你在自己的代码里真正开展这个函数,再把开展结果作为一条消息回传给模型,让它基于真实结果制作最终答复。开展动作始终发生在你自己的代码里,模型只负责决定调用什么。

相关阅读

接着看这几篇