2026 年 11 月 13 日,DeepSeek 把网页端和 App 里的对话能力整体开放成 API,官方叫「全家桶应用 API」。联网搜索、深度思考搜索、文件输入、阅读链接、内容安全、会话标题、用户元信息标记都进了对话请求;搜索、抓取、OCR、语音合成、语音识别另外开放成五个独立接口。官方同时开源了一份前端 demo(deepseek-ai/chat-demo,TypeScript),可以导入从网页端导出的历史对话。
这次变化最实质的一点是工具不在客户端执行。搜索、抓网页、解析文件、跑语音识别,全部在 DeepSeek 服务端完成,客户端拿到的是已经执行完的内容块,自己只负责渲染和回传。后面所有实现细节都从这条推出来:内容块怎么关联、网页正文藏在哪里、哪些参数会失效、费用怎么算。
对话能力清单
| 能力 | 开启方式 | 客户端要做的事 |
|---|---|---|
| 联网搜索 | 声明 deepseek_web_search,关闭思考 | 渲染搜索结果卡片和引用角标 |
| 深度思考搜索 | 声明 deepseek_web_search,开启思考 | 同上,另加多步检索的中间块 |
| 阅读链接 | 声明 deepseek_read_url | 渲染网页卡片,原样回传 signature |
| 文件输入 | 上传 Files API 拿 file_id,对话中引用 | 上传并保存 file_id |
| 模型内容安全 | safety_check.level = high | 处理三条协议各自的拒答字段 |
| 会话标题 | title.enabled = true | 从响应里取标题存本地 |
| 用户元信息 | 插一条 latest_reminder 消息 | 按固定格式拼字符串 |
| 朗读回答 | 调 /v1/tools/tts 合成音频 | 播音频 |
| 语音输入 | 调 /v1/tools/asr 转文字 | 录音上传,把 text 当消息发 |
这些能力目前只在 deepseek-flash(DeepSeek-V4.1-Flash-1017)上提供,上下文 1M,单次输出最大 384K。同一套能力在三条协议上都有:
| 协议 | 接口 | 鉴权头 |
|---|---|---|
| Messages | POST https://api.deepseek.com/anthropic/v1/messages | x-api-key |
| Responses | POST https://api.deepseek.com/responses | Authorization: Bearer |
| Chat Completions | POST https://api.deepseek.com/chat/completions | Authorization: Bearer |
Messages 挂的是 Anthropic 兼容层,鉴权头写作 x-api-key,另外两条用 Bearer。把鉴权抽成统一逻辑的实现会在这里吃 401。
开启两个联网工具、安全审核和会话标题的请求长这样:
curl https://api.deepseek.com/anthropic/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: ${DEEPSEEK_API_KEY}" \ -d '{ "model": "deepseek-flash", "thinking": {"type": "enabled"}, "tools": [ {"type": "deepseek_web_search", "name": "deepseek_web_search"}, {"type": "deepseek_read_url", "name": "deepseek_read_url"} ], "safety_check": {"level": "high"}, "title": {"enabled": true}, "messages": [{"role": "user", "content": "DeepSeek V4.1 有哪些更新?"}], "stream": true }'客户端不再执行工具
一次开了联网工具的响应,content 是一串块,用 tool_use_id 把调用和结果配对:
| 块类型 | 含义 |
|---|---|
thinking | 思考过程,界面上折叠显示 |
server_tool_use | 一次服务端工具调用:action、参数、kind |
web_search_tool_result | 一次搜索的结果列表,每条带标题、URL、摘要、站点名 |
web_fetch_tool_result | 一次打开网页的结果,正文加密在 signature 里 |
text | 回答正文,可能带 citations |
kind 标出这次调用属于哪种能力,五个取值:search、deep_search、read_link、image_search、deep_image_search。name 是请求里声明的工具名,它不在 Anthropic SDK 的类型定义里,但 SDK 运行时不校验。
流式输出时,server_tool_use 和结果块的内容一次性出现在 content_block_start 里,不分片下发。客户端不能指望边收边拼这两个块,只能在 content_block_start 里一次拿到完整 JSON。
结果也不一定紧跟调用。模型一次发起多个调用时,服务端先下发全部调用块,再下发结果块;开了内容安全,结果还要等审核通过。关联只能靠 tool_use_id,而且每个调用都有结果,调用没跑完时结果是 unavailable 错误。
搜索在思考与非思考下是两条路径
关闭思考时,deepseek_web_search 就是普通联网搜索:一次调用带一组查询词,全列在 input.queries,kind 为 search。回答里的引用通过 text 块的 citations 给出,每条引用带 URL、标题和 cited_text。cited_text 是当前块截至该引用处的回答文本,不是从来源摘录的原文,拿它和网页内容做匹配会全部对不上。
开启思考时,同一个工具换成深度思考搜索,kind 变成 deep_search,input.action 有三种:
action | 步骤 |
|---|---|
search | 联网搜索 |
open_page | 打开搜索到的网页 |
find_in_page | 在已打开的网页里查找,带 pattern |
模型最多调用约 20 次工具后作答。文档给的示例顺序能看出这套编排有多密:
thinkingserver_tool_use search 4 queriesweb_search_tool_resultthinkingserver_tool_use open_page https://www.toureiffel.paris/...server_tool_use open_page https://en.tokyotower.co.jp/company/web_fetch_tool_resultweb_fetch_tool_resultthinkingserver_tool_use open_page https://en.tokyotower.co.jp/server_tool_use find_in_page pattern "330"server_tool_use find_in_page pattern "meter"server_tool_use find_in_page pattern "333"web_fetch_tool_result (4 results)thinkingserver_tool_use search 3 queriesweb_search_tool_resultthinkingserver_tool_use open_page (2 calls)web_fetch_tool_result (2 results)thinkingtext 4 blocks, 3 of them with citations深度思考搜索里打开的网页只返回 URL、标题和发布时间,data 是空字符串,也没有 signature。这些网页不会活到下一轮,能留下来的只有回答正文。
图片搜索走同一个工具,kind 为 image_search,深度思考时是 deep_image_search。它的 queries 是空数组,每条结果多一个 image_url,那个地址只供展示,可能不存在也可能打不开。
读链接靠 signature 存活
deepseek_read_url 只在最后一条用户消息里识别 URL,重复的算一个,最多考虑前 10 个不同链接,由模型决定读哪几个。每个网页产生一个 action 为 read_link 的调用块和一个 kind 为 read_link 的抓取结果块。
网页正文不返回,块长这样:
{ "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_rl_01_9c1d...", "content": { "type": "web_fetch_result", "url": "https://example.com/a", "content": { "type": "document", "source": {"type": "text", "media_type": "text/plain", "data": ""}, "title": "页面标题" }, "published_at": "2026-01-01" }, "kind": "read_link", "signature": "q3J0b1RmZ1c4cE1x..."}data 恒为空,正文加密在 signature 里。下一轮把整个块原样回传,服务端才用 signature 把网页拼回该轮用户消息的末尾。签名丢了,这段网页就不存在,但请求不会报错,你只会发现模型突然忘了内容。
块里的 url、title、data、published_at 都只供展示,回传前改它们没有影响;能影响上下文的只有 signature。这条规则对存储和序列化影响很大:会话落库时不能用「只存展示字段」的 DTO 反序列化再重组,否则 signature 会在这场往返里消失。
还有一个容易误判的组合:开启思考并且声明了 deepseek_web_search 时,本轮走深度思考搜索,不单独读链接。只有关闭思考、或者只声明 deepseek_read_url 时才会读。想稳定复现「读这个 URL」的行为,就别同时开思考。
同一轮读多个链接时,单个网页可用的长度会减少,长页会被截断。
上下文里留下了什么
这是多轮对话最容易想错的地方。搜索结果、打开的网页、之前轮次的思考都不进后续上下文,只保留回答正文;例外是 read_link 的网页,靠 signature 还原。
所以「联网搜索」在第二轮不记得它搜过什么,只记得它写过什么。产品如果要求模型在后续轮次继续引用某个来源,那一轮要么重新搜索,要么把网页作为链接放进用户消息重新读。
服务端接管的参数
声明联网工具、把 safety_check.level 设为 high、或开启 title,三种情况下服务端会接管采样参数,请求里传的值被忽略:
| 协议 | 被忽略的参数 |
|---|---|
| Messages | temperature、top_p、top_k、stop_sequences、thinking.budget_tokens、preserve_thinking、tool_choice.disable_parallel_tool_use、metadata(user_id 除外) |
| Responses | temperature、top_p、reasoning.summary、text.verbosity、include、max_tool_calls、truncation、metadata、parallel_tool_calls、store |
| Chat Completions | temperature、top_p、frequency_penalty、presence_penalty、stop、seed、n、preserve_thinking、parallel_tool_calls |
max_tokens 照常生效,含义变了:它限制一轮里每一步推理的输出长度,不限制整轮总输出。开了深度思考搜索的请求,20 次工具调用里每一步都有自己的 max_tokens 预算。
tool_choice 不能指定这两个联网工具,指定了返回 400,因为是否联网由模型判断。tool_choice 设为 none 会关掉全部工具,包括阅读链接。
计费和展示是两套计数
工具调用在 token 之外按次收费,和五个独立接口同价:
| 项目 | 计费单位 | 价格 |
|---|---|---|
| 搜索(文字、图片) | 每 1,000 次 | 5 元 |
| 网页抓取 | 每 1,000 次 | 5 元 |
| 文件解析、OCR | 每 1,000 页 | 1.5 元 |
| 语音合成 TTS | 每 10,000 字符 | 3 元,限时 1.5 元 |
| 语音识别 ASR | 每小时音频 | 0.78 元,限时 0.39 元 |
模型 token 另算:deepseek-flash 输出 4 元/百万 token(空闲时段),输入未命中缓存 1 元、命中 0.02 元。北京时间周一至周五 9:00–12:00、14:00–18:00(不含法定节假日)是高峰时段,价格翻倍。
usage.server_tool_use 里有两组容易混的字段。web_search_requests 和 web_fetch_requests 是响应里结果块的数量,含错误块,仅供展示;真正对应计费的是 tool_search、tool_fetch、tool_image_search。拿前一组做成本看板,数字会偏。
计费单位也不是「调用次数」:
- 网页搜索按返回了结果的调用里包含的查询词条数计,一次调用带 3 个查询词算 3 次;失败或没有结果不计费。
- 图片搜索按张计,模型框选图片中的区域时,每个区域再算 1 次。
- 网页抓取按成功抓取的网页数计,包含开启内容安全后被替换成
url_not_allowed或unavailable错误的页面;抓取失败的不计。 - 深度思考搜索里再次打开同一网页、在网页中翻页、打开内容已随搜索结果返回的网页都不计费,
find_in_page不计费。
TTS 的字符口径不一样:汉字算 2 个字符,字母、数字、空格算 1 个。用字数估成本时,一段中文差不多要乘 2。
生成中途失败时 HTTP 状态码已经是 200,响应以 error 结束,失败之前执行的推理、搜索和阅读照常计费。开启内容安全后,审核消耗的 token 计入输出 token,并单列在 output_tokens_details.safety_tokens。
拒答在三条协议里是三个字段
| 协议 | 识别方式 |
|---|---|
| Messages | stop_reason 为 refusal,另带 stop_details |
| Responses | status 为 incomplete,incomplete_details.reason 为 content_filter |
| Chat Completions | finish_reason 为 content_filter,content 为空字符串 |
图片被拦时的位置又各不一样:Messages 在 stop_details.explanation,Responses 在 output 里某条 message 的 refusal 内容,Chat Completions 在 message.refusal,流式是最后一个 chunk 的 delta.refusal。
流式场景有个绕不过去的现实:开启安全校验后,输出结束时连接不立即关闭,服务端要对完整输出再审核一遍,这期间已经下发的文本撤不回来。拒答到达时,客户端只能删掉已展示的内容,换成自己的拒答文案。
level 只有 low 和 high,low 等同于不传。对外提供服务时这个参数能帮上合规,但不替代你自己的义务:内容安全审核、大模型登记、AI 标识仍然是服务提供者的责任,输入没过审返回的 400 也照常计费。
工具 API 是同一批能力的裸接口
五个独立接口都在 /v1/tools/ 下,鉴权统一用 Bearer:
| 接口 | 用途 | 关键限制 |
|---|---|---|
POST /v1/tools/search | 网页搜索,返回结构化结果 | 100 QPS |
POST /v1/tools/fetch | 抓单页,返回 Markdown | 25 QPS,另按目标域名限速 |
POST /v1/tools/ocr | 按页识别文档 | 100 MiB、1,000 页、15 并发 |
POST /v1/tools/tts | 文本转音频 | 单次 10,000 计费字符、30 分钟音频 |
POST /v1/tools/asr | 音频转文本 | 8 MiB、120 秒、不支持流式 |
价格和对话里用同一批工具完全一致,对话里的 server tool 就是这套接口的服务端编排。自己搭工作流时值得关注 Search 返回的三个字段:
rerank_score:0 到 3,1.5 以上算优质,适合做过滤阈值。authority:0 到 4,-1 表示未知,3 以上是极权威来源。summary:600 到 800 字的长摘要,给模型读;snippet只有 100 到 200 字,给界面展示。
搜索语法原样透传:site:、-site:、"精确短语"、lang:zh,en、after:2025-06-01。need_content 为 true 时才返回正文,否则 content 恒为空字符串。另外 Search 目前还不支持图片搜索,图片搜索只有联网工具里有。
OCR 的布局标记有用。逐页识别会保留 <|ref|>、<|box|> 标记和坐标,坐标形如 [[x1,y1,x2,y2]],原点在页面左上,按页面宽高归一化到 0 到 1000;还原像素要 x × 页面宽度 ÷ 1000。做版面还原,比如把识别文本按原位叠回原图,靠的就是这组坐标。
边界
这些限制散在各页里,凑起来决定了几种方案做不了:
- 服务端工具不能和自定义 function calling 混用。同时声明返回 400:
other tools cannot be used together with deepseek_web_search, deepseek_read_url, safety_check or title yet。想让模型既查你的知识库又联网,只能拆成两次请求,或者先把检索结果拼进用户消息。 - 用过联网工具或阅读链接的回复不能续写,会返回 400;产品要做「继续生成」,就得去掉工具重发。Chat Completions 那边还要在 beta 接口上给最后一条 assistant 消息加
prefix: true。 - Responses API 不支持继续生成,
latest_reminder也只支持 Messages 和 Chat Completions。选协议时这几项要先对齐。 - 联网工具不接受
allowed_domains、blocked_domains、user_location,同一工具声明两次也会 400。按域名限流或限定站点的需求,只能走/v1/tools/search自己拼site:。 - 文件解析在上传时完成,上传和解析都要等:120 秒内传完,解析再过 120 秒,超时是 504。客户端和反向代理的超时要按「上传 + 解析」设。解析结果不提供下载。
latest_reminder的content必须是字符串,传对象在请求体解析阶段就返回 422,不是 400。Messages 里它要紧跟所属的 user 消息,不能插在 tool_use 和 tool_result 之间。- 会话标题在回答结束时生成,响应最多为它等 5 秒,标题不计费,也可能不返回(拒答或出错时),客户端要有兜底文案。
判断
从接口形状看,DeepSeek 把 agent loop 收进了服务端:客户端不实现工具调度,也就不需要跟着迭代检索策略、安全规则和编排逻辑,升级是服务端单方面的事。
代价同样明确。检索源不能换,参数不能调,计费按次走且以服务端口径为准,工具能力必须和 DeepSeek 自己的协议绑定。想接自己的搜索后端、想在检索链路上做精细控制,这套接口帮不上,还是得自己搭。
对多数做 Chatbot 的场景这笔交换是划算的:搜网页、读链接、解析文件、语音进出,这四件事以前要接四家服务、写四套错误处理,现在是一个参数加一段块渲染。真正需要认真对待的只有一件事,把 signature 完整地存下来、原样传回去。