一次对话里塞进搜索、读文件和深度思考:全家桶 API 的开关逻辑
一次对话里塞进搜索、读文件和深度思考:全家桶 API 的开关逻辑
DeepSeek 开放“全家桶”应用 API 之后,社区里最直接的反应是:终于可以 1:1 复刻一个完整的 App 了。但真正落到代码上,这件事并没有那么像“把几个功能拼起来”。深度思考是 thinking 字段,联网搜索是一个工具声明,阅读链接是另一个工具声明,文件输入走 Files API 的 file_id,会话标题又是 title.enabled 的一次性开关——它们分布在请求体的不同层级,彼此还有隐式的耦合。
本文以开源项目 chat-demo 为样本,把这个“全家桶”的开关逻辑从 UI 一直追到 HTTP 请求:哪些参数对应哪些能力、组合调用时顺序和副作用是什么、以及一个极简前端如何用两个胶囊按钮把这些协议分支可视化。所有结论都能在仓库源码里找到对应位置。
参数与能力的映射表
chat-demo 是一个纯静态前端,浏览器直连 API 服务,所有请求都发往 ${API_ORIGIN}/anthropic/v1 下的 Anthropic 兼容接口(client.ts)。因此它的请求构造过程是“裸”的,没有任何中间层做参数补全,正好适合观察全家桶各能力的真实开关。
把散落在各处的字段汇总起来,映射关系大致如下:
| 能力 | 请求字段 | 代码位置 | 是否受 UI 开关控制 |
|---|---|---|---|
| 深度思考 | thinking: { type: 'enabled' | 'disabled' } |
reply 请求构造 | 是,settings.thinking |
| 联网搜索(含边想边搜) | tools 中追加 deepseek_web_search |
serverTools() | 是,settings.search |
| 阅读链接 | tools 中常驻 deepseek_read_url |
serverTools() | 否,始终声明 |
| 文件输入 | 用户消息里的 image / document 块,source.type: 'file' |
toFileBlocks() | 由是否附件决定 |
| 会话标题 | title: { enabled: true } |
streamReply() | 仅会话无标题时 |
| 系统信息快照 | role: 'latest_reminder' 的消息 |
toRequestMessages() | 自动,不可关 |
| 安全审核 / 扩展模式 | safety_check: { level: 'high' } |
SAFETY_CHECK | 否,固定开启 |
真正由用户控制的只有两项,这也是输入框里只有两个胶囊按钮的原因。serverTools() 的实现只有几行,但把“哪个是开关、哪个是常量”表达得非常清楚:
/** 阅读链接始终开启,智能搜索开关控制是否另行声明搜索工具(含边想边搜)。 */
const serverTools = (search: boolean): CreateMessageRequest['tools'] => {
const tools: CreateMessageRequest['tools'] = [
{ type: 'deepseek_read_url', name: 'deepseek_read_url' },
]
if (search) {
tools.push({ type: 'deepseek_web_search', name: 'deepseek_web_search' })
}
return tools
}
两个工具都用了服务端工具的形式,name 字段在服务端并不校验,真正的语义在 type 上。这一点在官方文档里也写明了:deepseek_web_search 让模型联网搜索,开启思考时进行深度思考搜索;deepseek_read_url 让模型阅读最后一条用户消息中的链接。
值得注意的是仓库里没有任何地方设置 max_uses 和 tool_choice。按文档,前者留空即服务端默认值,后者留空等价于 auto。这是一个有意的选择:前端不限制单轮搜索次数,把预算控制交给服务端;也不强制调用工具,让模型自己决定“这一问要不要搜”。
system 字段同样被固定为一句极简的身份说明,而不是从设置里拼接:
const SYSTEM_PROMPT = '该助手为DeepSeek,由深度求索公司创造。'
这句话和 latest_reminder 是配套的:日期、星期、地点、平台、语言由 latest_reminder 提供(latestReminder.ts),身份由 system 提供,两者不重复。快照格式就是文档规定的五元组:
return [
formatDate(now),
new Intl.DateTimeFormat(locale, { weekday: 'long' }).format(now),
locationName(location, locale),
'Web',
translate('latestReminderLanguage'),
].join(',')
读文件其实是两条路径
“文件输入”最容易被误解成一个开关,实际上它在协议上有两条完全不同的路径,而且和搜索、思考共用同一个请求体。
第一条是模型侧的内容块。附件先经 Files API 上传拿到 file_id,再在用户消息里以 image 或 document 块引用(reply.ts):
const toFileBlocks = (files: FileAttachment[]): FileBlockParam[] =>
files.flatMap(({ serverId, isImage }) =>
serverId
? [
{
type: isImage ? 'image' : 'document',
source: { type: 'file', file_id: serverId },
},
]
: []
)
这里有三个容易被忽略的细节。
其一是请求头。只有请求体里真的出现了图片或文档块,才会附加 anthropic-beta: files-api-2025-04-14(client.ts 里的 hasFile()),纯文本聊天不带这个头。把 beta 头做成条件式而非全局,避免了无谓的兼容性风险。
其二是 purpose。上传时按扩展名分档:图片不传该字段,PDF、Word、PPT 用 rich_layout_recognition 让服务端做版面解析,纯文本、代码、表格、电子书用 user_data。体积上限也随之分档,分别是 64MB 和 32MB(attachments.ts)。这是“文件输入”在全家桶里最重的一块工程成本——它不是把字节丢上去就完事。
其三,也是最关键的一点:仓库的类型注释直接写明了一个硬约束。
/**
* 文件块:引用经 Files API 上传的文件,图片用 image、其余用 document;
* 图片请求需带 anthropic-beta: files-api-2025-04-14;扩展模式不支持 document,返回 400。
*/
而 SAFETY_CHECK 是固定开启的,注释写的是“安全审核固定开启,所有请求都走扩展模式”。也就是说,当请求同时携带文档块和全家桶扩展参数时,协议分支会收窄:文档输入与扩展能力并非任意组合都成立。这类约束不会在小规模 demo 里以“功能不可用”的温和形式出现,而是直接一个 400。理解这一点,比记住“支持 PDF”重要得多。
发送前的补传逻辑同样体现了“文件是外部状态”这个事实。prepareFiles() 会先补齐本轮提问的 serverId,再对进入上下文的历史轮次里缺失 serverId 的附件(多为导入的图片)从最新往前逐张补传;本轮失败即整体失败,历史失败则静默跳过、下次再试。若服务端判定 file_id 失效,reuploadInvalidatedFiles() 会清掉对应附件的 serverId,退避重传后重发,最多两次,且一旦已经收到过内容块就不再自动重发(store.ts)。这套“自愈”路径的存在,说明全家桶里的文件能力是有生命周期的,不是一次上传永久有效。
组合调用的顺序与副作用
单个参数看懂了,组合起来才是真正的坑。以下五条都能在源码里找到对应判断。
第一,读链接常开,意味着“关闭搜索”并不等于“不联网”。 serverTools(false) 依然会声明 deepseek_read_url。用户关闭智能搜索后,只要消息里有 URL,模型仍可能发起 read_link 调用。这也是类型定义里那句话的来源:“关闭时仍声明 deepseek_read_url”(chat/types.ts)。
第二,思考与搜索叠加会切换搜索的“种类”,而种类会改变 UI 的聚合与文案。 文档说明“开启思考时进行深度思考搜索”,对应到返回块的 kind 就是 deep_search。仓库在 view.ts 里对两种搜索做了不同处理:普通搜索按种类聚合到首次出现的位置,边想边搜只合并相邻、同种类的调用。文案也随之切换——普通搜索说“已阅读 N 个网页”,深度搜索说“搜索到 N 个网页”。同一份内容块,因为两个开关的组合不同,读起来是两件事。
第三,开启工具会牺牲“继续生成”。 这是最不直观的副作用。canContinueReply() 明确拒绝任何包含服务端工具调用或结果块的回复:
reply.blocks.some(
(block) =>
block.type === 'server_tool_use' ||
block.type === 'web_search_tool_result' ||
block.type === 'web_fetch_tool_result' ||
(block.type === 'text' && block.isTemplate)
)
原因不难推:续写需要把已生成内容作为 assistant 前缀回传,而一旦本轮发生过工具往返,前缀就不再是“纯文本 + 思考”,服务端需要完整的工具调用与结果配对,凭空截断会破坏协议。于是产品上出现了一个隐式规则:搜过一次,这一轮就收尾,想接着写只能重新生成。
第四,历史回传是“有损”的,且损失规则由签名决定。 多轮对话必须把历史 assistant 内容块传回去,但 toAssistantParam() 只保留 kind === 'read_link' 的工具块,搜索结果块一律不回传。更细的是,成功的 read_link 依赖结果块上的 signature 恢复网页正文,仓库先收集所有缺签名的 tool_use_id,再把对应的调用与结果成对丢弃:
const unsignedReadLinks = new Set(
blocks.flatMap((block) =>
block.type === 'web_fetch_tool_result' &&
block.kind === 'read_link' &&
block.content.type === 'web_fetch_result' &&
!block.signature?.trim()
? [block.tool_use_id]
: []
)
)
这与官方文档一致:web_fetch_result.content.source.data 恒为空串,read_link 的网页正文放在 signature 里,回传时需原样保留。换句话说,历史里“读过什么网页”这件事不靠 URL 记录,靠一段不透明密文。序列化时丢一个字段,模型就失忆了。
第五,安全拒绝会连带丢弃已下发的内容。 settleReply() 在 stop_reason: 'refusal' 时把思考和正文块全部过滤,只留工具块:
blocks: reply.blocks.flatMap((block): ReplyBlock[] => {
if (reply.stopReason === 'refusal' && (block.type === 'thinking' || block.type === 'text')) {
return []
}
...
})
这是协议要求而非产品偏好——拒答轮次里已经流出的思考与正文不能展示,也不能进入下一轮上下文。isUsableReply() 同样把 refusal 和模板提示排除在上下文之外。
另外两个“顺序敏感”的点值得单独记一笔。
latest_reminder 必须紧贴它所属的 user 消息之前,否则服务端返回 400。仓库用一个“内容变化才插入”的去抖策略来控制数量(reply.ts):
const appendReminder = (reminder: string | undefined) => {
// 仅在当前分支首次出现或内容变化时插入快照;缺少快照的消息保持原有内容。
if (reminder && reminder !== previousReminder) {
messages.push({ role: 'latest_reminder', content: reminder })
previousReminder = reminder
}
}
title 则是一次性开关。titleRequests 这个 Set<AbortController> 只在会话还没有标题时登记控制器;一旦 message_delta 带回非空 title,立刻写入并注销。用户在生成过程中手动重命名,也会把这个控制器移出集合——避免自动标题覆盖人工输入。
最后是开关的“时间语义”。createReply() 在请求发起的一刻把 thinking 和 search 快照进 assistant 消息(store.ts):“按当前开关创建回复:深度思考对应 thinking,智能搜索控制 deepseek_web_search。” 这意味着输入框里的两个按钮随时可点,但它们影响的是下一次请求,而不是正在流式输出的这一轮。切换会话、重新生成、续写时,读的是各自回答版本上的快照,只有老数据缺字段才回落到当前设置。开关状态因此成为消息的一部分,而不是全局的瞬时状态。
在极简前端里怎么把这些开关可视化
协议层有这么多的“不是简单布尔”的地方,UI 却只用了两个按钮。这恰恰是值得学习的地方:前端不需要把协议复杂度翻译给用户,只需要保证开关状态的读、写、快照三条链路准确。
按钮本体就是原生 <button>,用 aria-pressed 表达选中态,用 Tooltip 承载各自的一句话解释(ChatInput.tsx):
<Tooltip content={t('deactivatedThinkTooltip')}>
<button
type="button"
className={clsx(styles.toggle, thinking && styles.selected)}
aria-label={t('thinkingSwitch')}
aria-pressed={thinking}
onClick={() => setThinking(!thinking)}
>
<IconThinkOutline14 />
<span className={styles.toggleLabel}>{t('thinkingSwitch')}</span>
</button>
</Tooltip>
deactivatedThinkTooltip 与 deactivatedSearchTooltip 的中文文案分别是“先思考后回答,解决推理问题”和“按需搜索网页”(zh.ts)。注意后者用了“按需”——这是准确的:搜索是一个可被模型自主决定是否调用的工具,而不是“每次必搜”的开关。文案如果写成“开启联网”,就会误导用户对费用的预期。
窄屏下的降级也很克制。标签不是靠媒体查询硬隐藏,而是实测溢出后再折叠:
const updateLabels = () => {
toggles.classList.remove(styles.collapsedToggles)
toggles.classList.toggle(styles.collapsedToggles, toggles.scrollWidth > toggles.clientWidth)
}
updateLabels()
const observer = new ResizeObserver(updateLabels)
observer.observe(toggles)
配合 CSS 里的一行 .collapsedToggles .toggleLabel { display: none },按钮退化为纯图标,宽度自适应,不依赖断点猜测。选中态则由 CSS 变量统一接管,浅色深色主题自动跟随:
&.selected {
background-color: var(--dsw-alias-button-ghost-active-fill);
color: var(--dsw-alias-brand-text);
border-color: var(--dsw-alias-button-ghost-active-border);
}
状态本身存在 localStorage 的两个独立键上(chat-demo:thinking、chat-demo:search),由 zustand 的 useSettings 暴露(settings.ts)。选择独立键而不是一个 JSON 对象,是为了让“某一项解析失败”不会连累另一项,也让历史版本的默认值迁移变得简单。
真正把这些布尔值变成可读反馈的,是回复区的时间线。ReplyArea 的折叠标题不是写死的“思考中”,而是由内容块反推的(view.ts):有正文时显示“已思考(用时 N 秒)”,用时按各思考块累加且至少 1 秒;进行中则根据最后一个步骤的类型切换为“正在思考”“正在搜索”“正在浏览网页”“正在阅读”。未开启深度思考时没有折叠标题,只剩工具步骤行,此时普通搜索显示为“已阅读 N 个网页”,深度搜索显示为“搜索到 N 个网页”。
来源编号也有明确的规则:按搜索结果与打开网页在回复中出现的顺序编号,与正文引用无关;同一 URL 只编号一次,后续结果只补全元数据(标题、站点名、发布时间、摘要、图标),不覆盖已有信息。正文里的 [citation:N] 则插在被引用文本块的尾部空白之前——因为服务端在挂过引用的块之后另起新块,引用位置就是块尾。这些细节决定了“来源角标”点开后能不能对上号,属于可视化里最容易被做坏、也最影响可信度的部分。
最后是持久化的一致性。历史导出会把 thinking_enabled 与 search_enabled 写进归档(toArchive.ts),导入时再读回消息(toLocal.ts)。也就是说,一次对话里“哪一轮开了思考、哪一轮开了搜索”是可以被完整还原的。开关不是 UI 的装饰,而是对话记录的一部分。
结语
全家桶 API 的开放,把“搜索、读文件、深度思考”从产品功能变成了协议字段。但字段只是入口,真正的复杂度在组合:deepseek_read_url 常驻使得关闭搜索仍可能联网;思考与搜索叠加会切换 kind,进而改变聚合策略与文案;工具往返一旦发生,续写能力就被关闭;read_link 的上下文依赖签名而非 URL;固定开启的 safety_check 让请求始终处在扩展模式,从而与非图片文档块存在互斥。
chat-demo 的价值不在于它把功能做全了,而在于它把每个开关的“请求契约”写在了代码注释和类型定义里:一个 serverTools() 说清了谁是开关、谁是常量;一个 createReply() 说清了开关是快照而非全局状态;一个 canContinueReply() 说清了能力组合的代价。当你要把这些能力接进自己的产品时,照抄 UI 很容易,把这些边界条件一并抄走,才是真正省下返工的部分。