DeepSeek API 联网搜索与 URL 读取:配置、价格和 400 报错

使用 deepseek-flash 在 Chat Completions、Messages 和 Responses API 中启用服务端联网搜索与 URL 读取。本文介绍 thinking 模式如何决定普通搜索或深度思考搜索,如何保留多轮对话的 signature,以及搜索、网页抓取、文件解析、OCR、ASR 和 TTS 的计费方式。提供可参考的 Bash 和 Python 请求示例、成本计算、常见 400 错误排查方法,并说明何时应该改用独立 Search 和 Fetch API。

本文内容
DeepSeek API 联网搜索与 URL 读取:配置、价格和 400 报错

如果你的聊天应用需要联网查资料并附上来源,可以使用 deepseek-flash,声明 deepseek_web_search,同时关闭 thinking。需要跨多个搜索步骤核对信息时,开启 thinking;如果主要任务是阅读用户提供的链接,则使用 deepseek_read_url。建议先通过 DeepSeek 官方 API 接入,因为普通的兼容网关不一定能完整传递这些服务端工具的专有字段。

DeepSeek 于 2026 年 11 月 13 日开放了这些能力。联网搜索、URL 读取、文件解析和语音服务除了模型 Token 费用,还会产生独立的工具调用费用。

下面从实际接入出发,说明三种对话 API 的请求格式、结果检查、多轮上下文保留、费用计算、常见报错,以及独立工具 API 的适用场景。

DeepSeek 11 月 13 日的 API 更新了什么?

DeepSeek 将原本主要在聊天应用中提供的联网、文件和语音相关能力开放给了 API 开发者。

根据 11 月 13 日的官方更新日志,DeepSeek V4.1 Flash 对应的模型 ID 为 deepseek-flash,新增支持以下能力:

  • 联网搜索与图片搜索:模型按需搜索,并在答案中提供引用来源。
  • 深度思考搜索:模型可以边推理边搜索、打开网页,并在页面内查找内容。
  • URL 读取:识别用户消息中的链接,读取网页后再回答。
  • 文件输入:解析 PDF、Office 文档和图片,支持纯文本提取或富布局解析。
  • 模型内容安全检查:检查输入与输出,并在触发安全规则时返回拒绝标记。

这些能力可在 Messages、Responses 和 Chat Completions API 中使用。

对于内置工具,DeepSeek 会在服务端执行搜索或网页抓取,并将结果加入模型上下文。你的应用不需要自行执行这些搜索工具。

与此同时,DeepSeek 还开放了独立的 Search、Fetch、OCR、ASR 和 TTS API。它们会将搜索结果、提取的文本、语音转写或生成的音频直接返回给应用代码。

普通搜索、深度思考搜索和 URL 读取怎么选?

决定 deepseek_web_search 行为的关键参数是 thinking。

模式工具声明Thinking实际行为
普通联网搜索deepseek_web_search关闭模型按需搜索,生成带引用的答案
深度思考搜索deepseek_web_search开启模型在多个推理步骤中搜索、打开网页并查找内容
URL 读取deepseek_read_url关闭,或开启但不声明联网搜索模型检查最新用户消息中的 URL
联网搜索与 URL 读取同时声明两个工具关闭模型可以选择搜索或读取用户提供的链接

官方文档指出,深度思考搜索在回答前最多会进行约 20 次工具调用。这是近似上限,不代表每次请求都会执行这么多次。

还有一个容易忽略的组合规则。

开启 thinking 并声明 deepseek_web_search 后,该轮请求会进入深度思考搜索,不再单独执行 deepseek_read_url 的链接读取流程。

如果你的应用必须重点处理用户指定的几个网页,应只声明 deepseek_read_url。

另外,声明工具不等于强制调用。是否需要搜索、读取哪一个网页,由模型决定。

如果还需要了解模型版本与代码任务表现,可以参考 DeepSeek V4.1 Flash 编程能力与价格指南。

使用 POST https://api.deepseek.com/chat/completions,指定模型 deepseek-flash,并在 tools 数组中声明 deepseek_web_search。

运行前需要准备有效的 DeepSeek API Key,以及 Bash、cURL 和 jq。

下面的 Bash 请求使用普通联网搜索,并启用内容安全检查。第一条命令会等待你输入 API Key,输入内容不会回显,也不会作为密钥明文写入命令历史。

read -rs DEEPSEEK_API_KEY && export DEEPSEEK_API_KEY

curl -sS https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "thinking": {"type": "disabled"},
    "tools": [
      {"type": "deepseek_web_search"}
    ],
    "safety_check": {"level": "high"},
    "messages": [
      {
        "role": "user",
        "content": "What did DeepSeek announce on November 13, 2026? Cite the official sources."
      }
    ]
  }' | jq '{
    error: .error,
    answer: .choices[0].message.content,
    citations: .choices[0].message.annotations,
    tool_calls: .choices[0].message.server_tool_calls,
    finish_reason: .choices[0].finish_reason,
    usage: .usage
  }'

成功执行联网搜索的响应中,可能出现以下字段:

  • choices[0].message.content:模型生成的答案正文。
  • choices[0].message.annotations:引用来源 URL,以及引用在答案中的位置。
  • choices[0].message.server_tool_calls:服务端执行的搜索步骤。
  • usage.server_tool_use:搜索、网页抓取等工具的使用量计数。

完整回答对应 choices[0].finish_reason = "stop"。

如果返回 length,表示答案因输出长度限制而截断;content_filter 表示响应被内容安全检查拒绝。

如果响应里没有 server_tool_calls,不一定是调用失败。模型可能认为当前问题不需要联网。可以改用一个明显需要最新信息的问题,再检查搜索步骤和引用。

如何开启深度思考搜索?

保留 deepseek_web_search,将 thinking 设置改为开启:

{
  "thinking": {"type": "enabled"},
  "tools": [
    {"type": "deepseek_web_search"}
  ]
}

当问题需要多次搜索、交叉核对信息,或者对多个来源进行比较时,可以选择这个模式。

深度思考搜索除了搜索,还能打开网页并在网页正文中查找内容。因此,它可能比普通搜索消耗更多推理 Token,并产生更多可计费的网页抓取。

具体调用次数和步骤由模型决定,不能仅凭开启 thinking 预测最终费用。

如何只读取 URL,不进行网页搜索?

只声明 deepseek_read_url,并把需要读取的地址放在最新的用户消息中:

{
  "thinking": {"type": "disabled"},
  "tools": [
    {"type": "deepseek_read_url"}
  ],
  "messages": [
    {
      "role": "user",
      "content": "Summarize https://api-docs.deepseek.com/updates/ and identify the November 13 changes."
    }
  ]
}

这一段请求体仍使用前面的 Chat Completions 地址、模型、认证方式和安全检查配置。

URL 读取有明确限制:

  • 只检查最后一条用户消息。
  • 重复出现的同一个 URL 只算一次。
  • 最多考虑消息中前 10 个不同的 URL。
  • 由模型决定实际读取哪些候选链接。
  • 同一轮读取多篇长网页时,单篇网页可用的上下文空间会减少,内容可能被截断。

这些限制来自 DeepSeek 官方 Web Tools 文档。

不要把链接只放在较早的对话消息里,然后期待下一轮请求自动重新抓取。

Messages 和 Responses API 如何声明相同工具?

三种对话 API 都支持新工具,但请求字段和响应结构并不完全相同。

API路径官方示例中的工具声明Thinking 控制字段
Chat Completions/chat/completions{"type":"deepseek_web_search"}thinking.type
Messages/anthropic/v1/messages{"type":"deepseek_web_search","name":"deepseek_web_search"}thinking.type
Responses/responses{"type":"deepseek_web_search"}reasoning.effort

三个路径都使用 https://api.deepseek.com 作为主机地址。

DeepSeek 的 Messages 官方示例同时包含 type 和 name 字段。不过,示例本身不能证明所有有效请求都必须提供 name,因此接入时直接遵循官方示例即可。

认证方式也不同:

  • Messages 使用 x-api-key。
  • Chat Completions 和 Responses 使用 Authorization: Bearer。

不同协议之间还有其他兼容性差异。可以参考 Messages、Chat Completions 与 Responses API 兼容性指南。

Messages API 请求示例

以下 Bash 示例使用 Anthropic 兼容的 Messages 格式读取用户提供的链接。

curl -sS https://api.deepseek.com/anthropic/v1/messages \
  -H "x-api-key: ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "thinking": {"type": "disabled"},
    "tools": [
      {
        "type": "deepseek_read_url",
        "name": "deepseek_read_url"
      }
    ],
    "safety_check": {"level": "high"},
    "messages": [
      {
        "role": "user",
        "content": "Summarize https://api-docs.deepseek.com/updates/"
      }
    ]
  }' | jq '{
    content: .content,
    stop_reason: .stop_reason,
    usage: .usage
  }'

模型答案保存在 content 块中。服务端工具调用使用 server_tool_use 块,后面跟随对应的结果块。

引用信息附着在文本块上。完整回答的结束原因是 stop_reason = "end_turn"。

如果使用流式响应,完整用量要从最后的 message_delta 事件读取。message_start 中的 usage 只覆盖第一步推理。

Responses API 请求示例

Responses API 使用 reasoning.effort,而不是 thinking.type。

设置为 none 可以关闭 thinking;设置为 low、high 或 max 可以按指定强度开启。

curl -sS https://api.deepseek.com/responses \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "reasoning": {"effort": "high"},
    "tools": [
      {"type": "deepseek_web_search"}
    ],
    "safety_check": {"level": "high"},
    "input": "Research the November 13, 2026 DeepSeek API update and compare the official documentation."
  }' | jq '{
    status: .status,
    output: .output,
    usage: .usage
  }'

Responses API 会在 output 中使用 web_search_call 项表示工具执行过程。

最终答案是一个 message 项,引用来源位于 output_text 的 annotations 中。

成功完成时,status = "completed"。如果达到输出上限或被内容检查中断,可能返回 incomplete;生成失败时可能返回 failed。

决定是否重试之前,应先检查 incomplete_details.reason 或 error.code。

不要假设三种协议的响应对象完全相同。特别是在需要保留服务端工具历史时,应按对应协议保存数据。

为什么多轮对话必须保留 signature?

deepseek_read_url 成功读取网页后,DeepSeek 会将网页内容的加密表示放在 signature 字段中。

抓取结果不会直接把网页全文作为普通文本返回。url、title、data 和 published_at 等字段主要用于展示。

在后续对话中,DeepSeek 会通过有效的 signature 恢复之前读取的网页内容,并将其加入模型上下文。

因此,上一轮的 assistant 响应必须原样传回,包括 kind、signature 和完整的服务端工具调用结构。

下面的 Python 示例使用 Chat Completions,保留第一轮完整的 assistant 消息,然后继续提问。

运行前安装 requests,并确保已在环境变量中导出 DEEPSEEK_API_KEY。

import os
import requests

endpoint = "https://api.deepseek.com/chat/completions"

headers = {
    "Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}",
    "Content-Type": "application/json",
}

tools = [{"type": "deepseek_read_url"}]

messages = [
    {
        "role": "user",
        "content": (
            "Read https://api-docs.deepseek.com/updates/ "
            "and summarize the November 13, 2026 entry."
        ),
    }
]


def complete_turn(history):
    response = requests.post(
        endpoint,
        headers=headers,
        json={
            "model": "deepseek-flash",
            "thinking": {"type": "disabled"},
            "tools": tools,
            "safety_check": {"level": "high"},
            "messages": history,
        },
        timeout=180,
    )

    response.raise_for_status()
    data = response.json()

    if data.get("error"):
        raise RuntimeError(data["error"])

    choice = data["choices"][0]

    if choice["finish_reason"] != "stop":
        raise RuntimeError(
            f"Incomplete response: {choice['finish_reason']}"
        )

    return choice["message"]


first_reply = complete_turn(messages)

# Preserve the complete assistant object, including server_tool_calls.
messages.append(first_reply)

messages.append(
    {
        "role": "user",
        "content": "Which developer features does that entry list?",
    }
)

second_reply = complete_turn(messages)
print(second_reply["content"])

这个示例展示了官方文档所描述的多轮请求格式,不代表已经通过实际 API 调用测试。

可以检查 first_reply["server_tool_calls"],确认模型是否真正读取了 URL。

如果没有出现 read_link 调用,说明第一轮没有产生需要保留的已抓取网页 signature。

其他协议也有对应的历史传递要求:

API下一轮需要原样传回的内容
Messages上一轮 assistant 的完整 content 块,包括 kind 和 signature
Responses上一轮完整的 output 项,包括 web_search_call、kind 和 signature
Chat Completions完整的 assistant 消息,包括 server_tool_calls

如果框架或网关删除了 signature,下一轮请求仍可能成功,但之前读取的网页内容不会恢复到上下文。

普通搜索结果、深度思考搜索打开的网页,以及上一轮推理过程,也不会自动以完整原文进入后续上下文。通常保留下来的是上一轮的答案文本。

有效的 URL 读取 signature 是官方文档明确说明的例外。

如果你的应用需要在后续对话中引用已读取网页,就不要把历史 assistant 消息简化成只有 role 和 content 的对象。

什么时候应该使用独立 Search、Fetch、OCR、ASR、TTS API?

如果应用需要自行控制检索、内容处理和结果存储,优先考虑独立 API。

内置工具由模型决定何时执行;独立 API 则直接将结果交给你的代码。你可以自行过滤、验证、保存,再决定将哪些内容提供给模型。

独立 API 的地址、输入和输出

APIhttps://api.deepseek.com 下的路径必要输入返回结果
SearchPOST /v1/tools/searchJSON query结构化搜索 results
FetchPOST /v1/tools/fetchJSON url网页 title 和 Markdown content
OCRPOST /v1/tools/ocrMultipart file、purposepages[].text 和 page_count
ASRPOST /v1/tools/asrMultipart 音频 file转写 text 和 duration_ms
TTSPOST /v1/tools/ttsJSON textWAV 或 PCM 音频

这五个 API 都使用 Bearer 认证。

下面是 Bash 中的独立请求示例,沿用此前导出的 DEEPSEEK_API_KEY。

# Search for pages and return structured results.
curl -sS https://api.deepseek.com/v1/tools/search \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query":"DeepSeek API release","count":5,"need_content":true}' \
  | jq '.results[] | {title, url, summary, content}'

# Fetch one page as Markdown.
curl -sS https://api.deepseek.com/v1/tools/fetch \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api-docs.deepseek.com/updates/"}' \
  | jq '{title, content}'

# Extract text from a local PDF.
curl -sS https://api.deepseek.com/v1/tools/ocr \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -F purpose="text_recognition" \
  -F file="@document.pdf" \
  | jq '{page_count, pages}'

# Transcribe a local audio file.
curl -sS https://api.deepseek.com/v1/tools/asr \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -F file="@speech.wav" \
  | jq '{text, duration_ms}'

# Generate a WAV file.
curl -sS https://api.deepseek.com/v1/tools/tts \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from DeepSeek.","voice_id":"stella"}' \
  --output speech.wav

OCR 和 ASR 示例需要本地输入文件。TTS 命令会在当前工作目录生成 speech.wav。

截至 2026 年 11 月 14 日,官方文档列出了以下主要限制:

  • Search: query 长度为 1–128 个 Unicode 字符。count 可设置为 1–50。账户级限流为 100 QPS。
  • Fetch: 每次请求处理一个 HTTP 或 HTTPS URL,并受目标网站访问策略限制。账户级限流为 25 QPS,另外还存在域名级 QPS 限制。
  • OCR: 单文件最大 100 MiB,最多 1,000 页。每个账户最多同时执行 15 个识别任务。
  • ASR: 单次请求最长 120 秒,最大 8 MiB。支持 16-bit PCM WAV 和 Ogg Opus。
  • TTS: 单次请求最多 10,000 个计费字符。支持完整文本合成,也提供 WebSocket 流式接口。

独立 Search API 支持 site:、lang:、after: 等搜索运算符。

截至 2026 年 11 月 14 日,独立 Search API 尚不支持图片搜索。图片搜索需要使用内置的 deepseek_web_search。

具体参数与文件格式要求可参考官方 Search 与 Fetch、OCR、ASR 和 TTS 文档。

文件输入和独立 OCR 有什么区别?

文件输入适合让模型直接理解文档并回答问题。独立 OCR 则适合将提取的文本返回给应用程序自行处理。

使用文件输入时,流程如下:

  1. 通过 multipart/form-data 向 POST https://api.deepseek.com/files 上传文件。
  2. 在 Multipart 表单中,必须先发送 purpose 字段,再发送 file 字段。顺序颠倒可能导致 400。
  3. 将解析方式设置为 text_recognition 或 rich_layout_recognition。
  4. 上传解析成功后,读取响应中的 id,并将这个值作为后续 deepseek-flash 对话请求中的 file_id。

以下 Bash 示例上传本地 PDF 文件:

curl -sS https://api.deepseek.com/files \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -F purpose="text_recognition" \
  -F file="@report.pdf" \
  | jq '{id, filename, purpose}'

-F 会让 cURL 发送 Multipart 表单。务必保持 purpose 在前、file 在后的顺序。

不要自行覆盖 Multipart Content-Type 中的 boundary 参数,cURL 会自动生成。

上传响应包含 id,在后续对话中应把它作为 file_id 使用。文件解析在上传请求期间完成,不需要另外轮询解析状态。

两种解析方式的区别是:

  • text_recognition:提取文本,但不会保留图表、照片或示意图供模型理解。
  • rich_layout_recognition:除了文本,还会将检测到的图片按原始位置提供给模型。

在 Chat Completions 中,可以这样引用已上传的文件:

{
  "role": "user",
  "content": [
    {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
    {"type": "text", "text": "Summarize the key points of this document."}
  ]
}

file-api-xxxxxxxxxxxxxxxx 只是示例 ID,实际请求必须使用上传响应中的 id。

单次请求最多引用 20 个文档,所有文档解析后的文本合计最多 8 MiB。

成功上传时,文件解析按页计费一次。之后每次在模型请求中引用文档,都需要按该模型的输入 Token 价格支付文档内容的 Token 费用。

接入前建议阅读 DeepSeek 文件解析指南。

DeepSeek 联网搜索、OCR 和语音 API 怎么收费?

截至 2026 年 11 月 14 日,DeepSeek 将模型推理费用和工具使用费用分开计算。

根据 官方模型与工具价格表,美元价格如下:

功能计费单位价格
文本联网搜索每 1,000 次可计费搜索$0.75
图片搜索每 1,000 次可计费搜索$0.75
网页 Fetch 或 URL 读取每 1,000 次可计费抓取$0.75
文件解析或 OCR每 1,000 个成功解析的页面$0.225
ASR每 1 小时音频限时价 $0.058;原价 $0.116
TTS每 10,000 个计费字符限时价 $0.225;原价 $0.45

ASR 和 TTS 的折扣被标记为限时优惠。已查阅的官方价格和 API 文档没有注明具体结束日期。

TTS 的字符计算规则也需要注意:每个汉字按两个计费字符计算,其他字符(包括空格)按一个计算。

ASR 按音频时长计费,精确到秒,不足一秒的部分向上取整。

usage 里的哪些字段才是真正的计费次数?

使用 DeepSeek 内置联网工具时,应读取以下字段:

  • usage.server_tool_use.tool_search:可计费的文本搜索次数。
  • usage.server_tool_use.tool_image_search:可计费的图片搜索次数。
  • usage.server_tool_use.tool_fetch:可计费的网页抓取次数。

不要使用 web_search_requests 或 web_fetch_requests 来计算费用。

这两个字段表示响应中的搜索结果块和抓取结果块数量,其中也包括错误结果。它们用于展示,不等于实际计费数量。

一次服务端搜索工具调用可能包含多个查询。如果一次调用提交了三个成功返回结果的查询,tool_search 就可能增加三次。

搜索失败或者没有返回结果时,不收取该次搜索费用。

图片搜索则按图片和区域计算:每张图片算一次搜索;模型在图片中选中的每个区域,再增加一次搜索。 搜索失败或没有结果时不计费。

URL 读取按成功抓取的页面计费。即使网页后来因安全检查被替换为 url_not_allowed 或 unavailable 错误,只要网页已经成功抓取,仍可能产生费用。

在深度思考搜索中,重新打开已在上下文中的网页、在同一页面内移动,或者打开搜索结果已经包含正文的页面,都不会再次产生 Fetch 费用。在页面内查找文字也不收费。

独立 Search 和 Fetch 的计费规则有所不同:每个成功返回结果的请求计费一次。Search 返回多少条结果,不会让这一请求的费用按结果数量倍增。

用 100 次请求计算实际预算

假设有 100 次关闭 thinking 的 DeepSeek Flash 请求,产生如下用量:

使用量假设值
可计费文本搜索查询200
可计费网页抓取100
未命中缓存的输入 Token200,000
命中缓存的输入 Token0
输出 Token(包含可能的安全检查 Token)50,000
图片搜索0

根据 2026 年 11 月 14 日的官方价格,deepseek-flash 非高峰时段的未缓存输入价格为每百万 Token $0.15,输出价格为每百万 Token $0.60。

计算如下:

Text searches = 200 / 1,000 × $0.75 = $0.150
Page fetches  = 100 / 1,000 × $0.75 = $0.075
Input tokens  = 200,000 / 1,000,000 × $0.15 = $0.030
Output tokens = 50,000 / 1,000,000 × $0.60 = $0.030

Estimated total = $0.285 for 100 requests

因此,这组假设下的非高峰总费用估算为 $0.285,覆盖 100 次请求。

这是根据公开费率计算的示例,不是实际执行测试得到的账单。

DeepSeek 文档规定,高峰时段为周一至周五的 01:00–04:00 和 06:00–10:00 UTC,中国法定节假日除外。其他时间均为非高峰时段。

高峰时,Flash 的未缓存输入价格是每百万 Token $0.30,输出价格是每百万 Token $1.20。

使用完全相同的假设用量,高峰时段的总费用估算为 $0.345。

真实费用还会受到推理步骤、thinking Token、缓存命中、图片搜索、网页抓取、安全检查以及实时价格变化的影响。

注意,thinking Token 已经包含在输出 Token 中,不应再次单独计费。

请求失败了,还会扣费吗?

有可能,关键在于失败前是否已经执行了模型推理或工具调用。

如果生成已经开始,随后才发生超时或中断,DeepSeek 可能已经返回 HTTP 200,但响应正文中仍包含错误。

失败前已完成的推理、搜索和网页读取仍会正常计费。

因此,流式请求不能仅根据最初的 HTTP 状态判断成功,应检查最终事件和最终 usage。

对于非流式 Chat Completions,即使 HTTP 状态是 200,也需要检查是否有 error 对象。

使用 Responses 时,应检查 status,包括 failed 和 incomplete。

DeepSeek 联网工具常见 400 报错怎么解决?

大多数请求验证错误来自强制选择服务端工具、重复声明工具,或者混用了不支持的参数。

DeepSeek 官方 Web Tools 错误说明列出了以下典型错误。

识别错误的关键字符串原因解决方法
tool_choice: deepseek_web_search cannot be forced使用 tool_choice 强制指定联网工具删除强制选择,让模型自行决定
tools: deepseek_web_search can only be declared once重复声明同一工具只保留一次声明
tools: allowed_domains is not supported by deepseek_web_search使用了不支持的域名或位置参数删除 allowed_domains、blocked_domains 和 user_location
tools: other tools cannot be used together with deepseek_web_search, deepseek_read_url, safety_check or title yet声明了冲突的其他服务端工具删除冲突的服务端工具
safety_check: level must be low or high安全检查级别无效设置为 low 或 high
messages: the last assistant message used deepseek_web_search or deepseek_read_url and cannot be continued; resend the previous request尝试续写使用过联网工具的部分响应重新发送原请求,不要续写该响应

原始错误文本会使用反引号包住部分字段名。上表为了便于阅读,省略了这些额外的反引号。

不用逐一尝试所有修复方法。先找到实际返回的错误,再修改对应的请求参数,最后重新发送请求进行验证。

可以通过 tool_choice 强制联网搜索吗?

不可以。

tool_choice 不能强制指定 deepseek_web_search 或 deepseek_read_url。

如果设置 tool_choice: "none",所有工具都会被关闭,包括 URL 读取。

在 Chat Completions 和 Responses 中,与这些联网工具一起使用 tool_choice: "required" 时,DeepSeek 会将其视为 auto。因此,这也不能保证发生搜索。

如果业务要求必须执行某个查询,例如固定关键词检索或指定网站搜索,应直接调用独立 Search API。

能和普通 function calls 混用吗?

官方文档中的冲突错误,明确针对不兼容的服务端工具声明。

这不能直接推导出所有普通 function tools 都被禁止。但同样没有证据证明它能兼容每一种 Agent 框架的函数调用。

Responses API 还明确限制了一些组合:

  • 不能把它与 Responses 自带的 web_search 工具一起声明。
  • 不支持 custom、namespace 和 tool_search 等工具类型。

因此,如果你想将新联网工具加进 Claude Code、OpenCode 或已经使用函数调用的自建 Agent,应先测试完整的请求、工具执行和结果返回过程。

普通 OpenAI 兼容请求成功,不代表加入这些 DeepSeek 服务端工具后也能成功。

为什么联网搜索后的续写会返回 400?

这里必须区分开启下一轮对话和继续生成同一个未完成的回答。

正常的下一轮对话,是将完整 assistant 响应放入历史,再附加一条新的用户消息。

续写则是希望模型在同一条未完成的 assistant 消息后继续生成。

DeepSeek 不允许续写使用过 deepseek_web_search 或 deepseek_read_url 的响应。

如果联网后的回答因输出限制被截断,应调整输出预算后重新发送之前的请求。

注意,重新请求可能再次执行搜索或抓取,因此也可能再次产生工具费用。

对于其他允许续写的 Chat Completions 响应,官方文档提供了 beta 端点配合最后一条 assistant 消息的 prefix: true 设置。但这项机制不能绕过联网工具的续写限制。

url_not_accessible、url_not_allowed、unavailable 分别是什么意思?

网页抓取失败时,DeepSeek 会返回类型为 web_fetch_tool_result_error 的错误结果,并且不会包含 signature。

具体错误类型由 error_code 区分。

错误码含义建议处理
url_not_accessible链接无法读取检查 URL、网页是否可访问、是否需要登录,以及站点访问限制
url_not_allowed禁止读取,或网页未通过内容安全检查不要绕过限制,改用允许访问的来源
unavailable服务不可用、深度搜索期间无法打开网页,或调用没有完成检查响应状态,必要时进行有限次数的重试

这些错误不能混为一谈。

url_not_allowed 不一定代表网络故障,也可能是内容安全检查拒绝了网页。

unavailable 也不代表一定没有费用。如果错误发生前已成功抓取网页,仍可能计费。

流式处理时,应通过工具调用标识符匹配调用与结果。一次读取多个页面时,结果不一定紧跟对应调用返回。

还需要检查各协议的结束状态:

  • Messages 的 end_turn 表示回答完成。
  • max_tokens 表示输出长度达到上限,或者搜索和读链接后上下文空间耗尽。
  • refusal 表示内容安全检查拒绝了响应。

Chat Completions 对应的结束原因包括 stop、length 和 content_filter。

如果应用面向公众提供服务,应启用安全检查:

{
  "safety_check": {"level": "high"}
}

DeepSeek 要求公开提供服务的开发者开启安全检查。它能对模型输入与输出进行基础审核。

但该功能不能代替应用自身的内容审核,以及适用的模型备案、AI 生成内容标识等合规义务。

即使回答被拒绝,拒绝前已经消耗的 Token 仍可能产生费用。

各协议的拒绝响应格式可以查看 Model Content Safety 官方指南。

应该用 DeepSeek 内置工具,还是自己接搜索 API?

如果目标是让模型在对话中自主搜索、阅读和整合来源,优先使用内置工具。

如果你的应用必须控制每个检索步骤,或需要直接获得网页正文、结构化搜索结果和原始处理数据,就应选择独立 API。

应用需求建议先使用选择原因
聊天机器人回答最新问题并引用来源关闭 thinking 的 deepseek_web_search不需要自行编排搜索流程
需要多来源核对的研究任务开启 thinking 的 deepseek_web_search模型可以多次搜索、打开网页并核对内容
总结用户提供的链接deepseek_read_url读取候选 URL,并通过 signature 保留页面上下文
搜索指定网站或获取结构化结果独立 Search应用控制查询语法、结果数量和后续处理
获取指定 URL 的 Markdown 正文独立 Fetch网页内容直接返回给应用
从大量文档中提取文本独立 OCR获取按页组织的识别结果
对上传文档直接提问File Parsing 加 deepseek-flash文档解析结果进入模型上下文
做语音输入或文字朗读ASR 和 TTS使用专门的音频处理接口

对于已经有一套工具调用流程的编程 Agent,外部搜索集成仍可能更合适。

例如,接入独立搜索工具可以保留 Agent 原有的工具编排、结果过滤和页面处理逻辑。

Parallel Search MCP 接入现有 Agent 的指南介绍了另一种搜索与网页提取方式。选择之前,应比较相同任务下的真实成本、工具兼容性和检索效果。

BetterToken 和其他兼容 API 网关能使用这些工具吗?

截至 2026 年 11 月 14 日,BetterToken 的模型目录列出了 deepseek-flash。选择访问渠道前,可以查看当前模型价格。

但模型已经上架,不等于新服务端工具也已得到完整支持。

对于 BetterToken,目前尚未验证以下行为:

  • 能否将 deepseek_web_search 和 deepseek_read_url 声明完整转发给上游。
  • 能否保留 server_tool_calls、kind 和加密的 signature。
  • 能否返回 DeepSeek 专有的 usage.server_tool_use 计费字段。
  • 能否正确记录和结算搜索、网页抓取等额外工具费用。

因此,本文所有接入示例均使用 DeepSeek 官方 API 地址。

如果准备通过兼容网关使用这些功能,应先分别验证一次联网搜索、一次 URL 读取,以及保留 signature 的第二轮对话。

之后核对返回的 usage 字段和实际扣费,再决定是否用于生产环境。

对于新应用,建议从关闭 thinking 的普通联网搜索开始,先检查引用来源和实际工具使用量。只有任务确实需要多次检索时,再启用深度思考搜索。对必须由应用代码控制的查询和抓取流程,则保留独立 Search 与 Fetch API。

BetterToken · 企业采购
企业专属价
支持开发票对公转账 / 支付宝 / 微信支付全系列文本 / 编程、图像、视频模型
文本 / 编程
图像
视频
专属技术支持领取企业折扣价目表 →