3620 字
18 分钟
DeepSeek 全家桶应用 API:构建 Chatbot 与工具 API 的实现拆解

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。同一套能力在三条协议上都有:

协议接口鉴权头
MessagesPOST https://api.deepseek.com/anthropic/v1/messagesx-api-key
ResponsesPOST https://api.deepseek.com/responsesAuthorization: Bearer
Chat CompletionsPOST https://api.deepseek.com/chat/completionsAuthorization: Bearer

Messages 挂的是 Anthropic 兼容层,鉴权头写作 x-api-key,另外两条用 Bearer。把鉴权抽成统一逻辑的实现会在这里吃 401。

开启两个联网工具、安全审核和会话标题的请求长这样:

Terminal window
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 次工具后作答。文档给的示例顺序能看出这套编排有多密:

thinking
server_tool_use search 4 queries
web_search_tool_result
thinking
server_tool_use open_page https://www.toureiffel.paris/...
server_tool_use open_page https://en.tokyotower.co.jp/company/
web_fetch_tool_result
web_fetch_tool_result
thinking
server_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)
thinking
server_tool_use search 3 queries
web_search_tool_result
thinking
server_tool_use open_page (2 calls)
web_fetch_tool_result (2 results)
thinking
text 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,三种情况下服务端会接管采样参数,请求里传的值被忽略:

协议被忽略的参数
Messagestemperature、top_p、top_k、stop_sequences、thinking.budget_tokens、preserve_thinking、tool_choice.disable_parallel_tool_use、metadata(user_id 除外)
Responsestemperature、top_p、reasoning.summary、text.verbosity、include、max_tool_calls、truncation、metadata、parallel_tool_calls、store
Chat Completionstemperature、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。

拒答在三条协议里是三个字段#

协议识别方式
Messagesstop_reason 为 refusal,另带 stop_details
Responsesstatus 为 incomplete,incomplete_details.reason 为 content_filter
Chat Completionsfinish_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抓单页,返回 Markdown25 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 完整地存下来、原样传回去。

DeepSeek 全家桶应用 API:构建 Chatbot 与工具 API 的实现拆解
https://blog.xqcherry.top/posts/ai/deepseek-chatbot-and-tools-api/
作者
xqcherry
发布于
2026-11-14
许可协议
CC BY-NC-SA 4.0