logo

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 三项即可迁移。

联网搜索、网页抓取、文件解析等能力不能想当然地认为默认存在。使用前应查阅官方文档,确认哪些功能由平台直接提供、哪些需要自己实现。文档没有列出的能力,可以用本文后面介绍的工具调用机制,由自有服务完成。

接入前的准备工作

接入前需要完成三件事。

  1. 在 DeepSeek 开放平台申请 API Key,并保存到环境变量 DEEPSEEK_API_KEY 中。密钥不要写进代码仓库,也不要打印到日志。
  2. 确认目标模型的上下文窗口大小和单次输出上限,避免长文本超出限制后请求失败。
  3. 在平台或自有监控系统中设置余额和用量告警,防止费用超支或服务因余额不足中断。

最小可运行示例

鉴权方式为 HTTP 请求头 Authorization: Bearer <API Key>。请求地址为 https://api.deepseek.com/chat/completions,请求体为 JSON,Content-Type 设为 application/json。

用 curl 发起一次调用:

  1. curl https://api.deepseek.com/chat/completions \
  2. -H "Content-Type: application/json" \
  3. -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  4. -d '{
  5. "model": "deepseek-chat",
  6. "messages": [
  7. {"role": "system", "content": "你是一名简洁的技术助手。"},
  8. {"role": "user", "content": "用两句话解释什么是 HTTP 幂等性。"}
  9. ],
  10. "stream": false
  11. }'

用 Python 的 OpenAI SDK 调用,需要显式设置超时,并关闭 SDK 自带的重试,由业务代码统一控制重试逻辑:

  1. import os
  2. import time
  3. from openai import OpenAI, APIError, APITimeoutError, RateLimitError
  4. client = OpenAI(
  5. api_key=os.environ["DEEPSEEK_API_KEY"],
  6. base_url="https://api.deepseek.com",
  7. timeout=30.0,
  8. max_retries=0,
  9. )
  10. def ask(prompt: str, model: str = "deepseek-chat", max_attempts: int = 3) -> str:
  11. for attempt in range(max_attempts):
  12. try:
  13. resp = client.chat.completions.create(
  14. model=model,
  15. messages=[{"role": "user", "content": prompt}],
  16. temperature=0.3,
  17. )
  18. return resp.choices[0].message.content or ""
  19. except (RateLimitError, APITimeoutError):
  20. if attempt == max_attempts - 1:
  21. raise
  22. time.sleep(2 ** attempt)
  23. except APIError:
  24. raise
  25. raise RuntimeError("重试次数已用完")

示例中 temperature 设为较低值,适合需要稳定输出的场景。是否需要调整,应结合自己的测试结果决定。

工具调用:让模型请求外部函数

工具调用(function calling)是把外部能力接入对话的常用方式。开发者在请求中声明函数的名称、用途和参数结构。模型判断需要时,会在响应中返回待调用的函数名和参数。应用执行该函数后,把结果以 tool 角色消息回传,模型再据此生成最终回答。

下面的例子声明一个查询天气的函数:

  1. import json
  2. tools = [
  3. {
  4. "type": "function",
  5. "function": {
  6. "name": "get_weather",
  7. "description": "查询指定城市当前的天气情况。",
  8. "parameters": {
  9. "type": "object",
  10. "properties": {
  11. "city": {"type": "string", "description": "城市名称,例如:北京"}
  12. },
  13. "required": ["city"],
  14. },
  15. },
  16. }
  17. ]
  18. def get_weather(city: str) -> dict:
  19. # 这里替换为真实的天气服务调用
  20. return {"city": city, "condition": "晴", "temperature_c": 18}
  21. def chat_with_tools(user_text: str) -> str:
  22. messages = [{"role": "user", "content": user_text}]
  23. for _ in range(5): # 限制最大轮数,防止无限循环
  24. resp = client.chat.completions.create(
  25. model="deepseek-chat",
  26. messages=messages,
  27. tools=tools,
  28. )
  29. choice = resp.choices[0]
  30. if choice.finish_reason != "tool_calls":
  31. return choice.message.content or ""
  32. messages.append(choice.message)
  33. for call in choice.message.tool_calls:
  34. if call.function.name != "get_weather":
  35. result = {"error": "未知函数"}
  36. else:
  37. try:
  38. args = json.loads(call.function.arguments)
  39. result = get_weather(**args)
  40. except (json.JSONDecodeError, TypeError) as e:
  41. result = {"error": f"参数错误:{e}"}
  42. messages.append({
  43. "role": "tool",
  44. "tool_call_id": call.id,
  45. "content": json.dumps(result, ensure_ascii=False),
  46. })
  47. 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。

选型清单

上线前可以按以下问题逐项确认。

  1. 业务是否需要实时信息?如果需要,应确认官方是否提供对应能力;若不提供,需要自建搜索或抓取服务,并处理来源与版权问题。
  2. 文档是否过长?长文档应先切片、建立索引,再按相关性检索后送入模型,不宜整篇直接拼接。
  3. 是否需要多个模型?建议在代码中加一层统一封装,把模型名、价格和参数集中管理,方便切换和对比。
  4. 并发量多大?需要根据限流规则设计队列和并发上限。
  5. 质量如何验证?应准备一组固定测试问题和标准答案,每次更换模型或修改提示词后都重新跑一遍,记录准确率变化。

以上步骤完成后,系统就具备了可核验的接入基础。接下来的重点是持续观察指标、补充测试用例,并根据用户反馈调整提示词和工具设计。

发表评论

活动