简介:本文面向准备接入DeepSeek搜索API的开发者,给出API Key、完整端点配置、鉴权、参数、错误码和可执行代码的联调路径,并补充Search与Fetch计费核验、Agent工具调用、缓存预算、合规选型方法,帮助读者判断能否上线并控制调用成本。
更新时间:2026-06-22。核验入口:DeepSeek开放平台(https://platform.deepseek.com/)与API文档(https://api-docs.deepseek.com/)。接口、价格、限流、错误码、活动规则与端点路径均以官方控制台和最新文档为准;本文提供可执行的接入框架与预算控制方法,不替代官方文档与账单。
DeepSeek搜索API的价值在于为AI应用补充外部实时信息入口。开发者应先把能力边界说清楚:搜索与抓取负责“找到候选信息”和“读取网页或内容”,不负责直接生成最终答案;最终回答质量仍取决于模型能力、提示词、结果排序、上下文长度控制与引用策略。
| 场景 | 典型输入 | 典型输出 | 限制 |
|---|---|---|---|
| 实时问答 | 新闻、政策、天气、产品动态等问题 | Search结果摘要,必要时Fetch正文 | 需处理时效性、来源可信度与版权 |
| RAG增强 | 用户问题 + 外部检索资料 | 检索结果拼接到模型上下文 | 需控制上下文长度与噪声结果 |
| Agent工具调用 | 智能体任务中的联网需求 | Search/Fetch工具调用记录 | 需白名单、预算、超时与审计 |
| 内容研究 | 候选页面或文档 | 抓取正文、摘要、结构化信息 | 需遵守robots、版权与隐私规则 |
不适用场景包括:仅需模型推理或生成、完全离线环境、无法完成合规审查的内部系统、无法确认来源授权或抓取边界的业务。
接入前先登录DeepSeek开放平台控制台,创建或管理API Key,并为密钥配置最小权限范围。建议将密钥只保存在服务端环境变量或密钥管理系统中,不要写入前端、公开仓库、客户端包、日志或镜像。
推荐的运行前环境变量如下,实际值需从官方开放平台与API文档中获取:
export DEEPSEEK_API_KEY="从开放平台创建的API Key"export DEEPSEEK_SEARCH_URL="从官方API文档复制的Search完整URL"export DEEPSEEK_FETCH_URL="从官方API文档复制的Fetch完整URL"
不建议在代码中拼接未核验的base与path。更稳妥的方式是直接从官方文档或控制台复制完整URL,放入环境变量或配置中心。若官方调整路径,只需修改配置,不需要改动业务代码。
不同平台版本可能调整端点、参数与请求方法。接入时应以官方文档页面展示为准,而不是沿用历史经验。建议按下表完成配置核验:
| 配置项 | 获取方式 | 使用方式 |
|---|---|---|
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 |
示例请求头:
Authorization: Bearer YOUR_API_KEYContent-Type: application/json
不同接口版本中,字段命名可能不同。下面给出联调时建议核对的参数表。示例字段采用常见命名,上线前应按官方文档字段表替换为准确字段;如果官方字段不同,只调整请求体构造逻辑,不改变整体流程。
| 逻辑字段 | 示例字段名 | 必填 | 类型 | 默认值 | 取值限制 | 示例 |
|---|---|---|---|---|---|---|
| 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字段,应优先记录到服务端日志。
| 场景 | 常见表现 | 处理建议 |
|---|---|---|
| 鉴权失败 | 401 | 检查API Key、环境变量、权限范围 |
| 无权限 | 403 | 检查是否开通Search或Fetch权限 |
| 限流 | 429 | 降低并发,增加指数退避重试 |
| 服务端异常 | 5xx | 记录trace_id,稍后重试或降级 |
| 超时 | 连接/读取超时 | 设置连接超时与读取超时,避免无限等待 |
| 无结果 | 200但无结果列表 | 进入无结果处理流程,不强制抓取 |
生产环境建议记录脱敏日志,字段包括:请求时间、接口类型、查询摘要、状态码、耗时、是否命中缓存、请求ID、trace_id、计费估算值。不要记录完整API Key、用户隐私原文或敏感正文。
以下示例依赖Python 3.10及以上版本,需要先安装requests:
python -m pip install requests
示例通过环境变量读取密钥和完整端点,避免硬编码。字段名如果与官方文档不同,可以集中修改payload构造部分。
import osimport requestsCONNECT_TIMEOUT = 3.0READ_TIMEOUT = 10.0def require_env(name: str) -> str:value = os.environ.get(name)if not value:raise RuntimeError(f"缺少环境变量 {name},请从官方开放平台或API文档复制后配置")return valuedef deepseek_search(query: str, limit: int = 5):url = require_env("DEEPSEEK_SEARCH_URL")api_key = require_env("DEEPSEEK_API_KEY")headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json",}payload = {"query": query,"limit": limit,}try:resp = requests.post(url,headers=headers,json=payload,timeout=(CONNECT_TIMEOUT, READ_TIMEOUT),)except requests.Timeout as exc:raise RuntimeError("搜索请求超时") from excexcept requests.RequestException as exc:raise RuntimeError("搜索请求网络异常") from excif resp.status_code == 401:raise RuntimeError("鉴权失败,请检查API Key")if resp.status_code == 403:raise RuntimeError("无权限访问搜索接口")if resp.status_code == 429:raise RuntimeError("触发限流,需要退避重试")if resp.status_code >= 500:raise RuntimeError(f"服务端异常:{resp.status_code}")if resp.status_code != 200:raise RuntimeError(f"搜索请求失败:{resp.status_code}")data = resp.json()if isinstance(data.get("results"), list):return data["results"]if isinstance(data.get("data"), list):return data["data"]if isinstance(data.get("items"), list):return data["items"]return []def deepseek_fetch(target: str):url = require_env("DEEPSEEK_FETCH_URL")api_key = require_env("DEEPSEEK_API_KEY")headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json",}payload = {"target": target,}try:resp = requests.post(url,headers=headers,json=payload,timeout=(CONNECT_TIMEOUT, READ_TIMEOUT),)except requests.Timeout as exc:raise RuntimeError("抓取请求超时") from excexcept requests.RequestException as exc:raise RuntimeError("抓取请求网络异常") from excif resp.status_code == 401:raise RuntimeError("鉴权失败,请检查API Key")if resp.status_code == 403:raise RuntimeError("无权限访问抓取接口")if resp.status_code == 429:raise RuntimeError("触发限流,需要退避重试")if resp.status_code >= 500:raise RuntimeError(f"服务端异常:{resp.status_code}")if resp.status_code != 200:raise RuntimeError(f"抓取请求失败:{resp.status_code}")data = resp.json()if isinstance(data.get("content"), str):return data["content"]if isinstance(data.get("data"), dict):return data["data"]return {}if __name__ == "__main__":test_query = os.environ.get("TEST_QUERY", "DeepSeek API 文档")results = deepseek_search(test_query, limit=3)print(results)
cURL适合在服务器或CI环境中快速验证鉴权、端点和返回结构:
curl -X POST "$DEEPSEEK_SEARCH_URL" \-H "Authorization: Bearer $DEEPSEEK_API_KEY" \-H "Content-Type: application/json" \-d '{"query":"DeepSeek API 文档","limit":3}'
如果官方文档要求字段名为q、top_k、url或content_id,只需按文档替换请求体字段。建议把字段映射集中管理,例如维护一个配置表,避免多个模块重复硬编码。
计费规则可能随版本、活动或账号类型变化。上线前必须打开官方计费页,核验Search与Fetch是否分别计费、计费单位是请求次数还是结果条目、无结果是否计费、429与5xx是否计入账单。本文给出工程预算口径:无论官方是否对某类失败计费,都应在监控中记录调用次数;在无法确认计费细则前,按保守口径预留预算。
建议计费核验表如下:
| 请求结果 | 调用监控 | 预算估算 | 官方账单核验动作 |
|---|---|---|---|
| 2xx且有结果 | 计入 | 计入 | 按成功请求或结果条目核对账单 |
| 2xx但无结果 | 计入 | 保守计入 | 查看官方计费页“无结果”规则 |
| 429限流 | 计入 | 一般不计入,但需看页面 | 确认限流响应是否产生费用 |
| 5xx服务端异常 | 计入 | 一般不计入,但需看页面 | 确认异常请求是否回退或计费 |
| 超时 | 计入 | 以账单为准 | 确认已到达服务端的请求如何计费 |
| 401/403鉴权或无权限 | 计入 | 不计入业务预算 | 修正密钥与权限后重试 |
成本公式可以写成:
估算成本 = 调用次数 ÷ 1000 × 官方千次单价 × 重试放大系数重试放大系数 = 1 + 失败率 × 平均重试次数
假设官方千次单价为P,则:
| 计费请求次数 | 成本 |
|---|---|
| 1,000次 | P |
| 10,000次 | 10P |
| 100,000次 | 100P |
如果官方仍展示限时免费活动,活动结束后应按最新价格重新测算。开发者不应把历史价格、社区价格或未核验的活动规则作为预算依据。
在Agent工作流中,可以把Search和Fetch封装成服务端工具。推荐流程是:用户提问后,由Agent判断是否需要联网;如果需要,先调用Search;再根据标题、摘要、来源可信度筛选;只对高相关结果调用Fetch;最后由大模型整理答案并标注来源。
Agent工具调用应增加以下限制:
下面是一段演示用Agent工具调用代码。真实环境中,llm_answer_without_search、llm_summarize等函数应替换为实际模型调用,例如DeepSeek Chat/Completion接口或内部业务模型。
def llm_answer_without_search(user_query: str):return f"未触发搜索,基于模型已有知识回答:{user_query}"def filter_results(results, max_fetch=2):cleaned = [item for item in results if item]return cleaned[:max_fetch]def extract_target(item):return (item.get("url")or item.get("content_id")or item.get("doc_id")or item.get("id"))def truncate(text, max_chars=4000):if not isinstance(text, str):return ""return text[:max_chars]def log_safely(event: str, **kwargs):safe_keys = ("request_id", "tool_name", "status", "latency", "cache_hit")safe_payload = {key: kwargs.get(key) for key in safe_keys if key in kwargs}print(event, safe_payload)def llm_summarize(user_query: str, contents):joined = "\n\n".join(contents)return f"基于检索资料回答:{user_query}\n资料摘要:{joined[:800]}"def agent_answer(user_query: str, need_search: bool):if not need_search:return llm_answer_without_search(user_query)results = deepseek_search(user_query, limit=5)if not results:log_safely("search_empty", tool_name="search")return "未找到足够可靠的外部资料,以下基于模型已有知识回答。"selected = filter_results(results, max_fetch=2)contents = []for item in selected:target = extract_target(item)if not target:continuetry:content = deepseek_fetch(target)text = content if isinstance(content, str) else str(content)contents.append(truncate(text, max_chars=4000))log_safely("fetch_success", tool_name="fetch")except Exception as exc:log_safely("fetch_failed", tool_name="fetch", status=type(exc).__name__)if not contents:return "搜索结果无法读取正文,请稍后重试。"return llm_summarize(user_query, contents)
成本优化不只是减少调用次数,而是让每次调用更有价值。
可以设置触发规则:
Search返回多个结果时,不要默认抓取全部内容。可先按标题、摘要、来源可信度排序,只抓取最相关的1到3条。
高频查询可缓存。缓存键建议基于规范化后的查询词、时间窗口和来源范围设计:
cache_key = hash(normalized_query + date_window + source_filter)
建议设置TTL:新闻类查询缓存较短时间,制度文档类可适当延长。对于敏感查询或涉及隐私的结果,应避免长期缓存。
建议监控:调用总量、成功请求数、无结果比例、超时比例、429限流比例、平均响应时间、单次任务平均调用次数、缓存命中率、预算消耗速度。
可参考的预算告警与降级配置:
budget:warn_70: notifydegrade_90: search_only_no_fetchcache:key: sha256(normalized_query + date_window + source_filter)ttl_seconds:news: 600doc: 86400search_policy:default_fetch_max: 2max_tasks_per_hour: 1000
当预算达到70%时通知负责人;达到90%时自动降级为“不搜索直接回答”或“只搜索不抓取正文”,避免单次异常任务耗尽预算。
如果只需要单一搜索能力,可重点评估接口稳定性、计费透明度、限流策略、错误码完善度和文档质量。如果应用涉及多个模型、多个工具或多个供应商,则需要额外考虑统一接入、调用管理和合规审查。
| 检查项 | 关注点 |
|---|---|
| 价格 | 是否有官方价格页,是否明确计费条件 |
| 限流 | 是否公开QPS、并发或日调用上限 |
| SLA | 是否有可用性承诺或补偿机制 |
| 无结果率 | 是否影响用户体验和重试成本 |
| 数据合规 | 是否涉及个人信息、敏感数据、跨境传输 |
| 内容合规 | 抓取网页是否涉及版权、隐私或robots限制 |
| 失败重试 | 是否支持退避、幂等、降级 |
| 日志审计 | 是否支持脱敏日志和调用追踪 |
| 供应商资质 | 第三方聚合平台需确认是否为推广、竞品或授权服务 |
如果使用第三方模型聚合或工具平台,建议完成以下核验动作:
1. 搜索无结果会收费吗?
应先查看官方计费页是否明确“无结果是否计费”。工程上建议将2xx无结果计入调用监控,并在预算中保守预留。若官方页面明确不计费,则账务按官方规则执行。
2. 请求失败或超时会收费吗?
401、403通常不应产生业务费用;429、5xx、超时是否需要计费,应以官方计费页和账单为准。无论是否收费,都应做退避、重试上限和降级,避免影响用户体验。
3. Search和Fetch都需要调用吗?
不一定。如果只需要搜索结果摘要,可只调用Search;如果需要读取网页正文或完整内容,再调用Fetch。建议默认先Search,筛选后再Fetch,减少无效抓取。
4. 如何降低费用?
优先缓存、减少重复查询、只在必要时抓取正文、限制单次任务调用次数,并对高频场景设置预算告警。还可以把通用知识问题交给模型直接回答,只在时效性或外部资料需求明确时触发搜索。
5. 活动结束后怎么办?
如果官方活动仍在,按官方活动价或免费规则执行;如果活动已结束或价格已调整,应以最新计费页为准,并重新测算成本。建议把价格配置化,不要写死在代码中。
DeepSeek搜索API适合需要实时信息检索的AI应用,但接入前必须完成三类核验:官方文档与端点参数核验、计费规则与价格页核验、合规与安全策略核验。建议开发者明确Search与Fetch的使用边界,建立凭证管理、超时重试、缓存去重、日志审计和预算告警机制,在提升信息获取能力的同时控制调用成本与合规风险。