API 接入指南
从创建密钥到第一次请求的全面环节与报错排查。
查看接入指南把 DeepSeek 接进系统后,真正的难点从"能不能调通"变成"能不能可靠、可控地跑"。
本教程讲三件事:让模型可靠输出可直接入库的 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)重试时把具体的校验错误原样回传,比重新问一遍管用得多,模型几乎总能一次改对。生产环境里给重试设上限(譬如两次),规避在异常输入上无限循环。
函数请求(工具请求)让模型能使用你自己的能力,整个过程分四步:
工具声明(要点)
{
"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 消息回传
→ 模型据此回答用户问题几个容易踩的坑:工具介绍写得太笼统会导致选错工具;工具返回信息太长会挤占上下文,需要自行截断或摘要;涉及写操作时要加二次核实,不要让模型直接决定执行删除或支付这类动作。
最高频的是模型在 JSON 前后加了解释性文字,或是字段名与要求不一致。解决办法是开启 JSON 对象的响应格式模式,在系统提示中给出字段定义与示例,并在代码里做一次解析校验,失败时带着错误资料重试一次。
基本流程是四步:你在请求里声明可用工具及参数结构,模型评估需要请求时返回工具名与参数,你在自己的代码里真正执行这个函数,再把执行结果作为一条消息回传给模型,让它基于真实结果产出最终答复。执行动作始终发生在你自己的代码里,模型只负责决定请求什么。