DeepSeek API 工程化与业务函数

这里从 API 的返回结果出发,介绍如何定义字段、检查结构并处理失败,再把模型的工具调用请求交给应用执行。最后讨论批量处理。

输出约束的三项准备

希望结果可以直接入库,需要同时准备三类约束。不完整的约束可能使回答变回叙述文字。

  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 配置说明。需要把该流程放到本地时,请阅读 本地部署操作说明。

使用问答

接口流程问题解答

字段和 JSON 格式不符怎么处理?

常见解析失败是 JSON 周围夹带解释,或字段名不符合约定。使用 JSON 对象模式,在系统提示写清字段及示例,应用侧验证失败后携错误信息重试一次。

谁负责执行模型请求的工具?

先声明工具与参数,再由模型返回所需工具名和参数。由你的代码执行函数、回传真实结果,最后模型给出回复;执行不交给模型。

接续阅读

下一步实践指南