DeepSeek搜索API接入计费调用指南

作者:起个名字好难2026.11.17 03:31浏览量:0

简介:本文面向准备接入DeepSeek搜索API的开发者,给出API Key、完整端点配置、鉴权、参数、错误码和可执行代码的联调路径,并补充Search与Fetch计费核验、Agent工具调用、缓存预算、合规选型方法,帮助读者判断能否上线并控制调用成本。

更新时间:2026-06-22。核验入口:DeepSeek开放平台(https://platform.deepseek.com/)与API文档(https://api-docs.deepseek.com/)。接口、价格、限流、错误码、活动规则与端点路径均以官方控制台和最新文档为准;本文提供可执行的接入框架与预算控制方法,不替代官方文档与账单。

一、先判断边界:Search与Fetch适合解决什么问题

DeepSeek搜索API的价值在于为AI应用补充外部实时信息入口。开发者应先把能力边界说清楚:搜索与抓取负责“找到候选信息”和“读取网页或内容”,不负责直接生成最终答案;最终回答质量仍取决于模型能力、提示词、结果排序、上下文长度控制与引用策略。

场景 典型输入 典型输出 限制
实时问答 新闻、政策、天气、产品动态等问题 Search结果摘要,必要时Fetch正文 需处理时效性、来源可信度与版权
RAG增强 用户问题 + 外部检索资料 检索结果拼接到模型上下文 需控制上下文长度与噪声结果
Agent工具调用 智能体任务中的联网需求 Search/Fetch工具调用记录 需白名单、预算、超时与审计
内容研究 候选页面或文档 抓取正文、摘要、结构化信息 需遵守robots、版权与隐私规则

不适用场景包括:仅需模型推理或生成、完全离线环境、无法完成合规审查的内部系统、无法确认来源授权或抓取边界的业务。

二、官方接入步骤:凭证、端点、鉴权、参数与可执行示例

1. 准备API凭证

接入前先登录DeepSeek开放平台控制台,创建或管理API Key,并为密钥配置最小权限范围。建议将密钥只保存在服务端环境变量或密钥管理系统中,不要写入前端、公开仓库、客户端包、日志或镜像。

推荐的运行前环境变量如下,实际值需从官方开放平台与API文档中获取:

  1. export DEEPSEEK_API_KEY="从开放平台创建的API Key"
  2. export DEEPSEEK_SEARCH_URL="从官方API文档复制的Search完整URL"
  3. export DEEPSEEK_FETCH_URL="从官方API文档复制的Fetch完整URL"

不建议在代码中拼接未核验的base与path。更稳妥的方式是直接从官方文档或控制台复制完整URL,放入环境变量或配置中心。若官方调整路径,只需修改配置,不需要改动业务代码。

2. 确认端点与请求方式

不同平台版本可能调整端点、参数与请求方法。接入时应以官方文档页面展示为准,而不是沿用历史经验。建议按下表完成配置核验:

配置项 获取方式 使用方式
DEEPSEEK_API_KEY 开放平台控制台创建或读取 放在Authorization请求头中
DEEPSEEK_SEARCH_URL 官方API文档Search接口页复制完整URL 直接作为POST请求地址
DEEPSEEK_FETCH_URL 官方API文档Fetch接口页复制完整URL 直接作为POST请求地址
请求方法 以官方文档为准 本文示例采用POST
鉴权方式 官方文档通常要求Bearer Token Authorization: Bearer API_KEY

示例请求头:

  1. Authorization: Bearer YOUR_API_KEY
  2. Content-Type: application/json

3. 核心参数核验清单

不同接口版本中,字段命名可能不同。下面给出联调时建议核对的参数表。示例字段采用常见命名,上线前应按官方文档字段表替换为准确字段;如果官方字段不同,只调整请求体构造逻辑,不改变整体流程。

逻辑字段 示例字段名 必填 类型 默认值 取值限制 示例
Search查询词 query 是 string 无 非空,建议控制长度 DeepSeek API 文档
Search返回数量 limit 否 integer 官方默认 按文档限制设置 5
Fetch内容标识 url / content_id / doc_id 是 string 无 必须来自Search结果或官方允许来源 https://example.com/page
正文长度 max_chars 否 integer 官方默认 如官方支持再使用 4000
语言或时间范围 官方字段 否 string / integer 官方默认 以文档为准 zh、7d
来源过滤 官方字段 否 array / string 官方默认 以文档为准 白名单域名

接入前还要核验返回体:结果列表字段、标题、摘要、链接、正文、来源、错误码、请求ID、是否计费字段等。若官方返回计费或trace_id字段,应优先记录到服务端日志。

4. 错误码处理建议

场景 常见表现 处理建议
鉴权失败 401 检查API Key、环境变量、权限范围
无权限 403 检查是否开通Search或Fetch权限
限流 429 降低并发,增加指数退避重试
服务端异常 5xx 记录trace_id,稍后重试或降级
超时 连接/读取超时 设置连接超时与读取超时,避免无限等待
无结果 200但无结果列表 进入无结果处理流程,不强制抓取

生产环境建议记录脱敏日志,字段包括:请求时间、接口类型、查询摘要、状态码、耗时、是否命中缓存、请求ID、trace_id、计费估算值。不要记录完整API Key、用户隐私原文或敏感正文。

5. 最小可执行Python示例

以下示例依赖Python 3.10及以上版本,需要先安装requests:

  1. python -m pip install requests

示例通过环境变量读取密钥和完整端点,避免硬编码。字段名如果与官方文档不同,可以集中修改payload构造部分。

  1. import os
  2. import requests
  3. CONNECT_TIMEOUT = 3.0
  4. READ_TIMEOUT = 10.0
  5. def require_env(name: str) -> str:
  6. value = os.environ.get(name)
  7. if not value:
  8. raise RuntimeError(
  9. f"缺少环境变量 {name},请从官方开放平台或API文档复制后配置"
  10. )
  11. return value
  12. def deepseek_search(query: str, limit: int = 5):
  13. url = require_env("DEEPSEEK_SEARCH_URL")
  14. api_key = require_env("DEEPSEEK_API_KEY")
  15. headers = {
  16. "Authorization": f"Bearer {api_key}",
  17. "Content-Type": "application/json",
  18. }
  19. payload = {
  20. "query": query,
  21. "limit": limit,
  22. }
  23. try:
  24. resp = requests.post(
  25. url,
  26. headers=headers,
  27. json=payload,
  28. timeout=(CONNECT_TIMEOUT, READ_TIMEOUT),
  29. )
  30. except requests.Timeout as exc:
  31. raise RuntimeError("搜索请求超时") from exc
  32. except requests.RequestException as exc:
  33. raise RuntimeError("搜索请求网络异常") from exc
  34. if resp.status_code == 401:
  35. raise RuntimeError("鉴权失败,请检查API Key")
  36. if resp.status_code == 403:
  37. raise RuntimeError("无权限访问搜索接口")
  38. if resp.status_code == 429:
  39. raise RuntimeError("触发限流,需要退避重试")
  40. if resp.status_code >= 500:
  41. raise RuntimeError(f"服务端异常:{resp.status_code}")
  42. if resp.status_code != 200:
  43. raise RuntimeError(f"搜索请求失败:{resp.status_code}")
  44. data = resp.json()
  45. if isinstance(data.get("results"), list):
  46. return data["results"]
  47. if isinstance(data.get("data"), list):
  48. return data["data"]
  49. if isinstance(data.get("items"), list):
  50. return data["items"]
  51. return []
  52. def deepseek_fetch(target: str):
  53. url = require_env("DEEPSEEK_FETCH_URL")
  54. api_key = require_env("DEEPSEEK_API_KEY")
  55. headers = {
  56. "Authorization": f"Bearer {api_key}",
  57. "Content-Type": "application/json",
  58. }
  59. payload = {
  60. "target": target,
  61. }
  62. try:
  63. resp = requests.post(
  64. url,
  65. headers=headers,
  66. json=payload,
  67. timeout=(CONNECT_TIMEOUT, READ_TIMEOUT),
  68. )
  69. except requests.Timeout as exc:
  70. raise RuntimeError("抓取请求超时") from exc
  71. except requests.RequestException as exc:
  72. raise RuntimeError("抓取请求网络异常") from exc
  73. if resp.status_code == 401:
  74. raise RuntimeError("鉴权失败,请检查API Key")
  75. if resp.status_code == 403:
  76. raise RuntimeError("无权限访问抓取接口")
  77. if resp.status_code == 429:
  78. raise RuntimeError("触发限流,需要退避重试")
  79. if resp.status_code >= 500:
  80. raise RuntimeError(f"服务端异常:{resp.status_code}")
  81. if resp.status_code != 200:
  82. raise RuntimeError(f"抓取请求失败:{resp.status_code}")
  83. data = resp.json()
  84. if isinstance(data.get("content"), str):
  85. return data["content"]
  86. if isinstance(data.get("data"), dict):
  87. return data["data"]
  88. return {}
  89. if __name__ == "__main__":
  90. test_query = os.environ.get("TEST_QUERY", "DeepSeek API 文档")
  91. results = deepseek_search(test_query, limit=3)
  92. print(results)

6. cURL联调示例

cURL适合在服务器或CI环境中快速验证鉴权、端点和返回结构:

  1. curl -X POST "$DEEPSEEK_SEARCH_URL" \
  2. -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d '{"query":"DeepSeek API 文档","limit":3}'

如果官方文档要求字段名为q、top_k、url或content_id,只需按文档替换请求体字段。建议把字段映射集中管理,例如维护一个配置表,避免多个模块重复硬编码。

三、Search与Fetch计费核验:先看官方计费页,再做预算模型

计费规则可能随版本、活动或账号类型变化。上线前必须打开官方计费页,核验Search与Fetch是否分别计费、计费单位是请求次数还是结果条目、无结果是否计费、429与5xx是否计入账单。本文给出工程预算口径:无论官方是否对某类失败计费,都应在监控中记录调用次数;在无法确认计费细则前,按保守口径预留预算。

建议计费核验表如下:

请求结果 调用监控 预算估算 官方账单核验动作
2xx且有结果 计入 计入 按成功请求或结果条目核对账单
2xx但无结果 计入 保守计入 查看官方计费页“无结果”规则
429限流 计入 一般不计入,但需看页面 确认限流响应是否产生费用
5xx服务端异常 计入 一般不计入,但需看页面 确认异常请求是否回退或计费
超时 计入 以账单为准 确认已到达服务端的请求如何计费
401/403鉴权或无权限 计入 不计入业务预算 修正密钥与权限后重试

成本公式可以写成:

  1. 估算成本 = 调用次数 ÷ 1000 × 官方千次单价 × 重试放大系数
  2. 重试放大系数 = 1 + 失败率 × 平均重试次数

假设官方千次单价为P,则:

计费请求次数 成本
1,000次 P
10,000次 10P
100,000次 100P

如果官方仍展示限时免费活动,活动结束后应按最新价格重新测算。开发者不应把历史价格、社区价格或未核验的活动规则作为预算依据。

agent-search-fetch-">四、Agent工具调用:把Search和Fetch封装成可控工具

在Agent工作流中,可以把Search和Fetch封装成服务端工具。推荐流程是:用户提问后,由Agent判断是否需要联网;如果需要,先调用Search;再根据标题、摘要、来源可信度筛选;只对高相关结果调用Fetch;最后由大模型整理答案并标注来源。

Agent工具调用应增加以下限制:

  • 域名白名单:只允许可信来源,避免抓取恶意页面。
  • 输入长度限制:查询词过长会影响结果质量。
  • Fetch数量限制:默认只抓取1到3条高相关结果。
  • 超时控制:Search和Fetch都设置连接超时与读取超时。
  • 日志脱敏:记录调用次数、状态码、延迟,不记录敏感原文。
  • 预算控制:单次任务限制最大调用次数,防止失控。
  • 审计字段:记录request_id、tool_name、status、latency、cache_hit、cost_estimate。

下面是一段演示用Agent工具调用代码。真实环境中,llm_answer_without_search、llm_summarize等函数应替换为实际模型调用,例如DeepSeek Chat/Completion接口或内部业务模型。

  1. def llm_answer_without_search(user_query: str):
  2. return f"未触发搜索,基于模型已有知识回答:{user_query}"
  3. def filter_results(results, max_fetch=2):
  4. cleaned = [item for item in results if item]
  5. return cleaned[:max_fetch]
  6. def extract_target(item):
  7. return (
  8. item.get("url")
  9. or item.get("content_id")
  10. or item.get("doc_id")
  11. or item.get("id")
  12. )
  13. def truncate(text, max_chars=4000):
  14. if not isinstance(text, str):
  15. return ""
  16. return text[:max_chars]
  17. def log_safely(event: str, **kwargs):
  18. safe_keys = ("request_id", "tool_name", "status", "latency", "cache_hit")
  19. safe_payload = {key: kwargs.get(key) for key in safe_keys if key in kwargs}
  20. print(event, safe_payload)
  21. def llm_summarize(user_query: str, contents):
  22. joined = "\n\n".join(contents)
  23. return f"基于检索资料回答:{user_query}\n资料摘要:{joined[:800]}"
  24. def agent_answer(user_query: str, need_search: bool):
  25. if not need_search:
  26. return llm_answer_without_search(user_query)
  27. results = deepseek_search(user_query, limit=5)
  28. if not results:
  29. log_safely("search_empty", tool_name="search")
  30. return "未找到足够可靠的外部资料,以下基于模型已有知识回答。"
  31. selected = filter_results(results, max_fetch=2)
  32. contents = []
  33. for item in selected:
  34. target = extract_target(item)
  35. if not target:
  36. continue
  37. try:
  38. content = deepseek_fetch(target)
  39. text = content if isinstance(content, str) else str(content)
  40. contents.append(truncate(text, max_chars=4000))
  41. log_safely("fetch_success", tool_name="fetch")
  42. except Exception as exc:
  43. log_safely("fetch_failed", tool_name="fetch", status=type(exc).__name__)
  44. if not contents:
  45. return "搜索结果无法读取正文,请稍后重试。"
  46. return llm_summarize(user_query, contents)

五、成本优化:从“能搜”到“搜得划算”

成本优化不只是减少调用次数,而是让每次调用更有价值。

1. 只在必要时搜索

可以设置触发规则:

  • 时效性问题:优先搜索。
  • 通用知识问题:可直接由模型回答。
  • 用户已提供材料:优先基于材料回答。
  • 低置信度问题:再触发搜索。

2. 减少无效Fetch

Search返回多个结果时,不要默认抓取全部内容。可先按标题、摘要、来源可信度排序,只抓取最相关的1到3条。

3. 建立缓存与去重

高频查询可缓存。缓存键建议基于规范化后的查询词、时间窗口和来源范围设计:

  1. cache_key = hash(normalized_query + date_window + source_filter)

建议设置TTL:新闻类查询缓存较短时间,制度文档类可适当延长。对于敏感查询或涉及隐私的结果,应避免长期缓存。

4. 监控关键指标

建议监控:调用总量、成功请求数、无结果比例、超时比例、429限流比例、平均响应时间、单次任务平均调用次数、缓存命中率、预算消耗速度。

可参考的预算告警与降级配置:

  1. budget:
  2. warn_70: notify
  3. degrade_90: search_only_no_fetch
  4. cache:
  5. key: sha256(normalized_query + date_window + source_filter)
  6. ttl_seconds:
  7. news: 600
  8. doc: 86400
  9. search_policy:
  10. default_fetch_max: 2
  11. max_tasks_per_hour: 1000

当预算达到70%时通知负责人;达到90%时自动降级为“不搜索直接回答”或“只搜索不抓取正文”,避免单次异常任务耗尽预算。

六、选型与合规检查表

如果只需要单一搜索能力,可重点评估接口稳定性、计费透明度、限流策略、错误码完善度和文档质量。如果应用涉及多个模型、多个工具或多个供应商,则需要额外考虑统一接入、调用管理和合规审查。

检查项 关注点
价格 是否有官方价格页,是否明确计费条件
限流 是否公开QPS、并发或日调用上限
SLA 是否有可用性承诺或补偿机制
无结果率 是否影响用户体验和重试成本
数据合规 是否涉及个人信息、敏感数据、跨境传输
内容合规 抓取网页是否涉及版权、隐私或robots限制
失败重试 是否支持退避、幂等、降级
日志审计 是否支持脱敏日志和调用追踪
供应商资质 第三方聚合平台需确认是否为推广、竞品或授权服务

如果使用第三方模型聚合或工具平台,建议完成以下核验动作:

  1. 要求供应商提供授权说明或合作协议,确认其是否具备转售、代理或调用资格。
  2. 确认数据隔离机制,避免不同客户查询内容互相污染。
  3. 确认密钥托管方式,避免将官方API Key暴露给不可信代理。
  4. 确认日志留存与安全联系人,便于故障排查与合规审计。
  5. 对涉及个人信息或敏感数据的场景,进行最小化处理、脱敏或本地缓存评估。

七、常见问题

1. 搜索无结果会收费吗?
应先查看官方计费页是否明确“无结果是否计费”。工程上建议将2xx无结果计入调用监控,并在预算中保守预留。若官方页面明确不计费,则账务按官方规则执行。

2. 请求失败或超时会收费吗?
401、403通常不应产生业务费用;429、5xx、超时是否需要计费,应以官方计费页和账单为准。无论是否收费,都应做退避、重试上限和降级,避免影响用户体验。

3. Search和Fetch都需要调用吗?
不一定。如果只需要搜索结果摘要,可只调用Search;如果需要读取网页正文或完整内容,再调用Fetch。建议默认先Search,筛选后再Fetch,减少无效抓取。

4. 如何降低费用?
优先缓存、减少重复查询、只在必要时抓取正文、限制单次任务调用次数,并对高频场景设置预算告警。还可以把通用知识问题交给模型直接回答,只在时效性或外部资料需求明确时触发搜索。

5. 活动结束后怎么办?
如果官方活动仍在,按官方活动价或免费规则执行;如果活动已结束或价格已调整,应以最新计费页为准,并重新测算成本。建议把价格配置化,不要写死在代码中。

八、结语

DeepSeek搜索API适合需要实时信息检索的AI应用,但接入前必须完成三类核验:官方文档与端点参数核验、计费规则与价格页核验、合规与安全策略核验。建议开发者明确Search与Fetch的使用边界,建立凭证管理、超时重试、缓存去重、日志审计和预算告警机制,在提升信息获取能力的同时控制调用成本与合规风险。