赛博鸡蛋JIDAN.SI

GUIDE · DeepSeek

DeepSeek Search 接入 Agent 教程：网页搜索与抓取 API 配置指南

DeepSeek Search/Fetch 是独立的网页搜索与抓取 HTTP API，使用统一的 DeepSeek API Key。本文提供可运行的 Python 搜索示例与 Fetch 最小用法，并说明直接调用接口、客户端集成和 Agent 函数调用的区别。

适用对象
想为 AI Agent 或自动化脚本添加实时联网搜索能力、降低爬虫维护成本的开发者
预计用时
约 12 分钟
最后核实

准备

  • 一个有效的 DeepSeek 开放平台账号及可用 API Key（在 DeepSeek 开放平台 获取）
  • Python 3（示例只使用标准库，无须安装 OpenAI SDK 或第三方依赖）
  • 仅在需要模型自主决定搜索时，才另行准备支持工具调用的 Agent 环境；直接调用 Search/Fetch 不需要选择推理模型

步骤

  1. 先弄清 DeepSeek 搜索抓取服务是什么与计费规则

    DeepSeek 的 Search 按关键词返回结构化搜索结果，Fetch 抓取单个网页并返回 Markdown 正文。两者都是独立的 HTTP JSON API；直接调用即可取得网页资料，不需要先调用模型。将资料交给模型生成回答，是后续单独的一步。

    • 计费时间：官方说明当前调用未计费，将于北京时间 2026 年 11 月 1 日 00:00 起计费。
    • 正式单价：Search、Fetch 分别为 ¥5 / 1,000 次成功请求。只有 HTTP 200 且产生结果才收费：Search 的 results 非空，Fetch 返回网页正文。失败、搜索无结果或超时不计费。count 不影响单次请求价格，搜索后再 Fetch 是两次独立请求。模型输入/输出 Token 另行计费。

  2. 获取 DeepSeek API Key 并配置环境变量

    访问 DeepSeek 开放平台控制台，在 API Keys 页面创建密钥。Search、Fetch 与模型 API 使用同一个 DeepSeek API Key，以 Authorization: Bearer <API Key> 鉴权，请求体为 JSON。

    将密钥保存在环境变量 DEEPSEEK_API_KEY，不要写入代码或提交到仓库。下面的 Python 示例不调用推理模型，也不需要 model 参数；如需模型总结结果，再按实际使用的模型接口配置。

  3. 在 DeepSeek Harness 中使用已有集成

    官方搜索指南确认：在 DeepSeek Harness、Claude Code、Codex 中使用 DeepSeek API 时，已有通过 Server 端工具调用 访问 Search/Fetch 的集成，这些调用也将从北京时间 2026 年 11 月 1 日 00:00 起计费。

    使用 Harness 时按其当前版本文档配置 DeepSeek API Key，并查看实际搜索请求与返回结果。客户端的开关和日志入口以实际版本为准；不能仅凭回答包含链接或最新日期，就认定已经联网。

  4. 在 Claude Code 与 Codex CLI 中配合使用

    需要区分三种接入方式：

    • 直接调用 Search/Fetch：你的脚本发送 HTTP 请求并读取结果，下面的 Python 示例采用这种方式。
    • 官方服务端工具集成：官方指南提到的客户端场景由对应集成完成搜索；仅把 Base URL 或模型提供方改成 DeepSeek，不能据此保证任意客户端或网关都具备这一能力。Agent 自带的其它 Web 工具也不等于 DeepSeek Search。
    • 自定义函数调用：Chat Completions 中声明一个名为 web_search 的函数，只是告诉模型可请求这个函数，不会自动执行搜索，也不是官方预置搜索工具。自行实现时，必须读取 tool_calls、校验函数名及 JSON 参数、实际调用 Search/Fetch、保留 assistant 的工具调用消息，再用匹配的 tool_call_id 将结果作为 role: tool 消息回传模型，并继续请求直到生成回答；还需限制工具轮数。本文不提供省略这些步骤的函数调用示例。

    使用第三方网关时，应确认其适配文档和实际请求记录，不能假设声明 web_search 插件后就会自动路由到官方 Search API。

  5. 自主开发 Agent：通过原生 API 调用搜索工具

    将下列代码保存为 deepseek_search.py，先在终端设置 export DEEPSEEK_API_KEY="你的密钥"，再运行 python3 deepseek_search.py。代码直接 POST 到 https://api.deepseek.com/v1/tools/search，输出真实搜索结果，不生成模型回答。

    Search 请求字段：query 必填，1～128 个 Unicode 字符且不能全为空白；count 可选，1～50，默认 10；need_content 默认 false，此时结果的 content 为空字符串。可选 ori_question 是 1～128 字符的原始问题（null 视为未提供），localization 是用于本地化排序的 IP 地址，默认空字符串。

    成功响应是包含 results 数组的 JSON 对象，数组可能为空。每项包含 title、url、短摘要 snippet、长摘要 summary、content、rerank_score、authority，以及可为 null 的 site_name、site_icon、date。下面只读取标题、链接和长摘要，按需再抓取正文。

    python
    import json
import os
import sys
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen


def post_tool(tool, payload):
    if tool not in ("search", "fetch"):
        raise ValueError("只支持 search 或 fetch")
    api_key = os.environ.get("DEEPSEEK_API_KEY", "").strip()
    if not api_key:
        raise RuntimeError("请先设置 DEEPSEEK_API_KEY 环境变量")
    request = Request(
        "https://api.deepseek.com/v1/tools/" + tool,
        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
        headers={
            "Authorization": "Bearer " + api_key,
            "Content-Type": "application/json",
        },
        method="POST",
    )
    try:
        with urlopen(request, timeout=30) as response:
            data = json.loads(response.read().decode("utf-8"))
    except HTTPError as exc:
        raise RuntimeError(
            f"DeepSeek {tool} HTTP {exc.code}；请按下文状态码说明处理"
        ) from None
    except (URLError, TimeoutError):
        raise RuntimeError("网络连接失败或超时，请稍后检查重试") from None
    except (ValueError, UnicodeError):
        raise RuntimeError("接口未返回有效的 UTF-8 JSON") from None
    if not isinstance(data, dict):
        raise RuntimeError("接口响应应为 JSON 对象")
    return data


def search(query):
    data = post_tool("search", {
        "query": query, "count": 5, "need_content": False,
    })
    results = data.get("results")
    if not isinstance(results, list) or any(
        not isinstance(item, dict) or any(
            not isinstance(item.get(key), str)
            for key in ("title", "url", "summary")
        ) for item in results
    ):
        raise RuntimeError("Search 响应缺少有效的 results 数组或结果字段")
    return results


def fetch(url):
    page = post_tool("fetch", {"url": url})
    if not all(isinstance(page.get(key), str) for key in ("title", "content")):
        raise RuntimeError("Fetch 响应缺少 title/content 字符串")
    return page


def main():
    try:
        results = search("DeepSeek API 最新更新 site:api-docs.deepseek.com")
        if not results:
            print("未找到匹配结果，可调整关键词后再搜索。")
        for result in results:
            print(result["title"], result["url"])
            print(result["summary"])
    except RuntimeError as exc:
        print(str(exc), file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())

  6. 按需抓取网页正文：Fetch 最小用法

    复用上一节保存的 deepseek_search.py，将下面代码另存为 fetch_page.py，在同一目录运行 python3 fetch_page.py。它会 POST 到 https://api.deepseek.com/v1/tools/fetch，请求体为 {"url": "网页地址"}。

    url 必填，最长 8192 字符，必须是包含 host 的 HTTP/HTTPS 地址且不能带用户名或密码。响应是 {"title": "页面标题", "content": "Markdown 正文"}；标题缺失时为空字符串。Fetch 受目标站点可用性和访问策略影响，不能保证抓取所有网站。

    python
    import sys
from deepseek_search import fetch

try:
    page = fetch("https://api-docs.deepseek.com/zh-cn/guides/search/")
    print(page["title"])
    print(page["content"] or "页面正文为空")
except RuntimeError as exc:
    print(str(exc), file=sys.stderr)
    sys.exit(1)

  7. 生产环境部署与避坑指南

    在将 Agent 接入搜索上线前，请关注以下要点：

    • 错误处理：错误 JSON 为 {"error":{"message":"…","type":"…","param":null,"code":"…"}}。400 表示参数或请求格式错误，401 检查 Key，402 先充值，403 表示 Fetch 被安全策略拒绝，404 表示 Fetch 未取得可用正文，413 表示请求体过大。这些错误应先修正原因，避免原样重试。
    • 稍后重试：408、429 或 5xx（例如 500、504）可等待后重试；429 还可能来自 Fetch 的目标域名限速。示例不自动重试，生产中应限制次数并退避。每账号 Search 100 QPS、Fetch 25 QPS，分别独立，换 Key 不会增加账号限额。
    • 控制调用与上下文：先筛选搜索摘要，再对有价值的 URL 调用 Fetch；限制 Agent 工具轮数与返回文本长度，避免重复搜索和过多输入 Token。网页资料应作为外部数据处理，不当作 Agent 指令。
    • 计费提醒：北京时间 2026 年 11 月 1 日 00:00 起按上述规则计费，记录 Search/Fetch 请求次数并预估预算。

注意事项

  • 计费起点：北京时间 2026 年 11 月 1 日 00:00 起，Search 和 Fetch 分别按每千次成功且有结果的请求 5 元计费；失败、搜索空结果和超时不计费。
  • 工具声明不会执行搜索：自定义函数名没有联网能力；需要执行器实际请求接口并回传结果。直接调用本文的 Search/Fetch 示例不涉及模型函数调用。
  • Token 费用独立：直接调用 Search/Fetch 按请求计费；仅在随后将网页资料送入模型时，相关内容才产生模型输入 Token 费用，模型生成也另行计费。

常见问题

DeepSeek 搜索 API 需要像 Google 或 Bing 那样单独申请专用的 Search Key 吗？

不需要。DeepSeek 的搜索与抓取能力直接挂载在统一的 DeepSeek API Key 权限下，一个密钥即可同时调用模型推理与联网搜索工具。

在限免期间调用搜索，会扣减 DeepSeek 账户原有的余额或体验赠金吗？

官方说明 Search/Fetch 当前未计费，将于北京时间 2026 年 11 月 1 日 00:00 起计费。模型 API 的输入/输出 Token 仍独立计费；直接运行本文搜索脚本不调用模型。

在客户端里怎么知道 Agent 到底有没有真正使用搜索？

查看执行器或服务端日志中的 Search/Fetch 实际 HTTP 请求与响应，或客户端提供的工具执行记录。仅有 tool_calls 表示模型提出了调用请求，不能证明工具已执行成功；仅凭回答有链接或看不到工具气泡，也不能判断是否联网。

调用 Fetch 接口抓取外部网页时支持防爬保护严重的站点吗？

Fetch 受目标站点可用性和访问策略影响。安全策略拒绝可能返回 403；URL 不可用、站点拦截、内容类型不支持或没有可提取的 Markdown 正文等情况可能返回 404。不能保证绕过登录或人机验证。

11 月 1 日之后如果不想使用搜索，会强制扣费吗？

只有实际调用 Search/Fetch 并满足成功且有结果的条件，才产生对应请求费。使用客户端的服务端集成时，要按该集成的配置停止搜索调用；仅删除自定义函数声明不能证明所有搜索路径都已关闭。模型 Token 费用仍独立计算。

相关优惠

查看 DeepSeek 的全部福利 →

信息来源

最后核实日期：2026-10-20 · 政策可能随时调整，请以官方页面为准

继续看

搜索福利

搜索 ChatGPT、Codex、Claude、DeepSeek 或各大模型，查找全站在线福利。

热门搜索：ChatGPT 优惠Codex 优惠Claude 优惠DeepSeek 优惠免费 API

提交优惠线索

AI 核验

分享活动或官方文档链接。线索先入队，AI 每天定时核对官方额度、领取条件和有效期，确认后才发布。