DeepSeek API接入指南:鉴权、工具调用与错误处理
作者:有好多问题2026.11.17 03:39浏览量:0简介:本文面向开发者,说明如何依据官方文档确认能力边界,完成鉴权与最小调用示例,并通过工具调用、错误分类重试和降级策略构建稳定的对话应用。文中还给出成本指标口径、合规检查项与选型清单,帮助读者上线前逐项核对。
先确认能力边界
接入前,请以 DeepSeek 官方 API 文档为准。文档地址为 https://api-docs.deepseek.com/ 。模型名、可用参数、上下文长度和计费规则都可能随版本调整,因此不要在业务代码中硬编码这些信息。建议把模型名、超时时间和重试次数放进配置文件,便于后续切换。
DeepSeek 的对话接口兼容 OpenAI Chat Completions 的请求格式。已经使用 OpenAI SDK 的项目,通常只需修改 base_url、api_key 和 model 三项即可迁移。
联网搜索、网页抓取、文件解析等能力不能想当然地认为默认存在。使用前应查阅官方文档,确认哪些功能由平台直接提供、哪些需要自己实现。文档没有列出的能力,可以用本文后面介绍的工具调用机制,由自有服务完成。
接入前的准备工作
接入前需要完成三件事。
- 在 DeepSeek 开放平台申请 API Key,并保存到环境变量
DEEPSEEK_API_KEY中。密钥不要写进代码仓库,也不要打印到日志。 - 确认目标模型的上下文窗口大小和单次输出上限,避免长文本超出限制后请求失败。
- 在平台或自有监控系统中设置余额和用量告警,防止费用超支或服务因余额不足中断。
最小可运行示例
鉴权方式为 HTTP 请求头 Authorization: Bearer <API Key>。请求地址为 https://api.deepseek.com/chat/completions,请求体为 JSON,Content-Type 设为 application/json。
用 curl 发起一次调用:
curl https://api.deepseek.com/chat/completions \-H "Content-Type: application/json" \-H "Authorization: Bearer $DEEPSEEK_API_KEY" \-d '{"model": "deepseek-chat","messages": [{"role": "system", "content": "你是一名简洁的技术助手。"},{"role": "user", "content": "用两句话解释什么是 HTTP 幂等性。"}],"stream": false}'
用 Python 的 OpenAI SDK 调用,需要显式设置超时,并关闭 SDK 自带的重试,由业务代码统一控制重试逻辑:
import osimport timefrom openai import OpenAI, APIError, APITimeoutError, RateLimitErrorclient = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"],base_url="https://api.deepseek.com",timeout=30.0,max_retries=0,)def ask(prompt: str, model: str = "deepseek-chat", max_attempts: int = 3) -> str:for attempt in range(max_attempts):try:resp = client.chat.completions.create(model=model,messages=[{"role": "user", "content": prompt}],temperature=0.3,)return resp.choices[0].message.content or ""except (RateLimitError, APITimeoutError):if attempt == max_attempts - 1:raisetime.sleep(2 ** attempt)except APIError:raiseraise RuntimeError("重试次数已用完")
示例中 temperature 设为较低值,适合需要稳定输出的场景。是否需要调整,应结合自己的测试结果决定。
工具调用:让模型请求外部函数
工具调用(function calling)是把外部能力接入对话的常用方式。开发者在请求中声明函数的名称、用途和参数结构。模型判断需要时,会在响应中返回待调用的函数名和参数。应用执行该函数后,把结果以 tool 角色消息回传,模型再据此生成最终回答。
下面的例子声明一个查询天气的函数:
import jsontools = [{"type": "function","function": {"name": "get_weather","description": "查询指定城市当前的天气情况。","parameters": {"type": "object","properties": {"city": {"type": "string", "description": "城市名称,例如:北京"}},"required": ["city"],},},}]def get_weather(city: str) -> dict:# 这里替换为真实的天气服务调用return {"city": city, "condition": "晴", "temperature_c": 18}def chat_with_tools(user_text: str) -> str:messages = [{"role": "user", "content": user_text}]for _ in range(5): # 限制最大轮数,防止无限循环resp = client.chat.completions.create(model="deepseek-chat",messages=messages,tools=tools,)choice = resp.choices[0]if choice.finish_reason != "tool_calls":return choice.message.content or ""messages.append(choice.message)for call in choice.message.tool_calls:if call.function.name != "get_weather":result = {"error": "未知函数"}else:try:args = json.loads(call.function.arguments)result = get_weather(**args)except (json.JSONDecodeError, TypeError) as e:result = {"error": f"参数错误:{e}"}messages.append({"role": "tool","tool_call_id": call.id,"content": json.dumps(result, ensure_ascii=False),})raise RuntimeError("工具调用轮数超过上限")
这段代码有三个要点。第一,循环次数有上限,避免模型反复请求工具导致费用失控。第二,模型给出的参数必须先解析和校验,不能直接传入业务函数。第三,工具执行失败时,错误信息要以结构化形式回传,让模型能够向用户说明情况。
错误处理与重试策略
不同错误应采用不同处理方式。下表列出常见类别,具体错误码和含义请以官方错误说明为准。
| 错误类型 | 典型原因 | 处理方式 |
|---|---|---|
| 400 / 422 | 请求格式或参数有误 | 不重试,记录请求并修复代码 |
| 401 | API Key 无效或缺失 | 不重试,检查环境变量与密钥状态 |
| 402 | 余额不足 | 不重试,触发告警,切换备用方案 |
| 429 | 请求速率超限 | 指数退避重试,控制并发数 |
| 5xx | 服务端故障或繁忙 | 指数退避重试,设置最大次数 |
| 超时 | 网络或模型响应慢 | 适当重试,并记录耗时用于分析 |
重试只适用于 429、5xx 和超时。对 400、401、402 重试没有意义,只会增加无效请求。
失败降级清单
线上服务应提前定义失败时的行为,常见场景如下。
- 模型调用超时:返回“服务繁忙,请稍后重试”,并保存原始请求,便于后台补偿。
- 工具执行失败:把错误原因回传给模型,或直接告诉用户该功能暂不可用,不让模型编造工具结果。
- 网页读取失败:明确说明未能获取内容,不基于猜测回答。
- 文件解析失败:返回具体原因,例如格式不支持或文件过大,并提示用户转换格式后重新上传。
- 余额不足或达到用量上限:切换到备用模型,或暂停非核心功能并通知管理员。
引用来源的保留
回答中若包含外部资料,应同时保存来源地址、标题和获取时间。展示给用户时,把来源列在回答末尾,方便核验。对于无法确认来源的内容,应注明“未经核实”,而不是直接当作事实呈现。
成本评估的指标口径
成本评估需要统一口径,否则不同时期的数据无法比较。建议至少统计以下指标。
| 指标 | 统计方法 | 用途 |
|---|---|---|
| 输入 token 数 | 按请求记录 usage 中的输入字段 | 判断上下文是否过长 |
| 输出 token 数 | 按请求记录 usage 中的输出字段 | 评估回答长度是否合理 |
| 工具调用次数 | 每轮 tool_calls 计数 | 发现工具滥用或循环调用 |
| P50 与 P95 耗时 | 记录请求开始与结束时间 | 评估用户等待体验 |
| 请求成功率 | 成功请求数除以总请求数 | 衡量稳定性 |
| 单次成功请求成本 | 总费用除以成功请求数 | 比较不同模型或策略的性价比 |
计费口径应以官方价格页面为准。若计费规则区分缓存命中与未命中,统计时也应分开记录。
合规与安全
提供面向公众的生成式 AI 服务时,应遵守《生成式人工智能服务管理暂行办法》等相关法规,并按主管部门要求履行备案、内容审核和标识义务。具体要求以最新法规和监管部门说明为准。
工程上可以落实以下做法。
- 对用户输入和模型输出做敏感内容过滤,并记录审核结果。
- 发送给模型的数据先脱敏,去除身份证号、手机号、密钥和未公开的内部文档。
- 日志设置保留期限,到期自动删除。
- 密钥定期轮换,并为不同环境使用不同的 Key。
选型清单
上线前可以按以下问题逐项确认。
- 业务是否需要实时信息?如果需要,应确认官方是否提供对应能力;若不提供,需要自建搜索或抓取服务,并处理来源与版权问题。
- 文档是否过长?长文档应先切片、建立索引,再按相关性检索后送入模型,不宜整篇直接拼接。
- 是否需要多个模型?建议在代码中加一层统一封装,把模型名、价格和参数集中管理,方便切换和对比。
- 并发量多大?需要根据限流规则设计队列和并发上限。
- 质量如何验证?应准备一组固定测试问题和标准答案,每次更换模型或修改提示词后都重新跑一遍,记录准确率变化。
以上步骤完成后,系统就具备了可核验的接入基础。接下来的重点是持续观察指标、补充测试用例,并根据用户反馈调整提示词和工具设计。

登录后可评论,请前往 登录 或 注册