接入 DeepSeek API
基础接入教程涵盖从 Key 到首个请求的步骤和排错。
阅读接入说明业务系统需要的不只是可读答案,还要有可解析的字段和明确的失败处理。下文围绕这两个要求说明结构化输出、工具执行与批量任务。
让输出成为可存储的数据,要给足三项说明。若有遗漏,模型可能仍以普通文字回答。
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)把验证失败的具体信息返回模型,能让重试更清楚地对准问题。还要限制重试次数,例如最多两次,避免在异常数据上不停重试。
函数调用将应用功能交给模型选择,执行流程可拆为四个环节:
工具声明(要点)
{
"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 消息回传
→ 模型据此回答用户问题注意说明是否准确,以及工具结果是否过长;前者影响选择,后者需要截断或摘要。写入类操作应加二次确认,删除和支付不能仅由模型自行决定。
基础调用所需的接口地址、密钥及模型名称,可查看 接入 DeepSeek API。本地执行同类流程的步骤见 自行部署 DeepSeek。
模型添加额外文字、使用了不同字段名称,都是 JSON 解析与校验的常见问题。处理办法是约定 JSON 模式与字段样例,代码中解析校验,出错时附具体错误重试。
流程从提供可用工具和参数定义开始,模型决定调用时返回名称及参数。函数由应用代码真正运行,结果作为消息返给模型生成答案,模型本身不直接执行。