AIGC标识 chat-demo 源码解析与 DeepSeek 全家桶 API 能力盘点

先给结论

chat-demo 是 DeepSeek 官方放出的一个静态聊天示例:没有后端、没有会话库,浏览器直接拿着你的 API Key 去请求你配置的服务。它小到可以一下午读完全部逻辑,又完整到把流式、思考、搜索、引用、附件、语音、分支、导入导出全做了一遍。

如果你的目标是“接一套对话产品”,它给的是一条最短路径;如果你的目标是“搞清这套 API 能干什么”,它就是一份可执行的 API 说明书。

一、它是什么:定位与代价

README 的原话是:基于 DeepSeek API 的静态聊天示例,无需应用后端,浏览器直接请求配置的 API 服务。仓库是 deepseek-ai/chat-demo,版本 v0.1.1,MIT 协议。

这个定位意味着取舍非常清楚。省掉的是服务端、会话库、账号体系;换来的是零后端部署、打包即静态站、数据全在本地。代价同样明确:

  • 隔离性 密钥只能待在浏览器里,所以只能自用或给可信的人用;
  • 多端 会话存在 IndexedDB,换设备、换浏览器就是两份数据;
  • 可控性 所有调用都绕不开服务端的策略与限流,客户端无法兜底。

技术栈也很克制:React 18.3、Zustand 4、Rspack 2、idb、Mermaid、KaTeX、Prism,15 个运行时依赖(另外 5 个是 @types/*,不打包)。

目录

文件数

有效行数

职责

services/

38

7 382

会话、消息、API、历史、语音、附件

components/

68

5 569

聊天、设置、Markdown、搜索卡片

i18n/

3

380

中英文案,167 对键

app/

3

294

布局、主题、视口

utils/

3

49

日期、格式化、id

src/ 根

2

20

main.tsx 挂载、env.d.ts 环境声明

合计

117

13 694

逻辑层比界面层更重

表 1 代码形状:services 占了一半以上,界面反而是最薄的一层。

二、五层架构:界面从不直接发请求

整个应用可以拆成五层,从上到下依次收窄职责。数据只从下往上流,任何一层都能替换而不动界面。

图 1 五层架构:组件 / 状态 / 会话服务 / API 客户端 / IndexedDB

最值得读的两个文件都在第三层。store.ts 有 1094 行,是整个应用的编排台:会话缓存(上限 5 个)、生成中止(每轮一个 AbortController)、落盘失败重试、附件失效补传。

reply.ts 负责把流式事件合并进当前回复,这里有一条不显眼但很硬的规矩:只追加能识别的内容块,跳过的块不占位。因为流事件带的是服务端索引,客户端要维护“服务端索引 → 本地块下标”的映射;跳过的块如果占了位,后面的增量就会写到错误的位置上。

// 只映射能渲染的块;tool_use 这类客户端工具内容不保存

case 'content_block_start': {

blockIndexes.delete(event.index)

const block = toReplyBlock(event.content_block, now)

if (!block) return next // 不占位

blockIndexes.set(event.index, next.blocks.length)

return { ...next, blocks: [...next.blocks, block] }

}

拼请求上下文时它同样克制:失败的轮次不进历史,被安全拒绝的回答不回传,服务端模板提示被排除。

  • 会进上下文:成功完成的问答、被停止但已有正文的回复、阅读链接的结果。
  • 不回传:报错或空回答、被安全拒绝的轮次、服务端模板提示。

三、流式协议:一条消息是怎么长出来的

核心只有一条路径:POST /anthropic/v1/messages,带上 stream: true。服务端回的是标准事件流,六种事件,收到 message_stop 就收工。

图 2 一条回复的流式事件序列,以及三处容易被忽略的实现细节

三个细节决定了这个客户端“像不像成品”。

  • ① 解码 多字节字符跨分片时用 TextDecoder 的流式模式解码,中文不会被截断;结尾孤零零的一个回车,要等下一片再判断是不是 CRLF 的前半。
  • ② 中止 用户点停止时,不是等网络把中止传下去,而是主动 reader.cancel(),立刻释放连接——否则连接会一直挂到服务端写完。
  • ③ 收尾 每轮生成挂一个 AbortController,断开的同时把已生成内容按 stopped 状态落盘,用户不会“点了停止就全没了”。

错误被分成五类,因为分类决定重试策略,而不是决定文案:

图 3 五类错误:前两类可重试,后三类要人看环境或日志

四、附件与多模态:先上传,再引用编号

上传走 Files 接口。关键设计是请求体里只放文件编号(file_id),不放文件内容,所以同一份附件可以在多轮对话里反复引用,不需要每次重传。

图 4 四步上传链路,以及写死在源码里的四个上限

两类 purpose 的区别值得单独说:rich_layout_recognition 用于 PDF / Word / PPT,服务端会真的把版面结构读出来;其余文本、代码、表格、电子书用 user_data,只当数据存。这也解释了两套体积上限——解析类 64 MB,普通数据 32 MB。

发请求时,图片用 image 块,其它用 document 块,都靠 file_id 引用;一旦带文件,还要多带一个 anthropic-beta: files-api-2025-04-14 请求头,否则服务端不认。

编号会过期。应用的处理是:服务端判定失效,就重新上传原件并重发,最多两次,指数退避;仍然失败才把原始报错摊给用户看。

五、联网搜索与引用:结果不是一段拼接文本

这是最容易做出差异化的部分。它在请求里声明两个服务端工具:deepseek_web_search 与 deepseek_read_url。搜索又分四种形态:普通、深度、图搜、深度图搜。

搜索结果的结构化程度是关键:

字段

含义

用处

title / url

标题与链接

来源卡片、跳转

snippet

可直接展示的摘要

悬停预览

site_icon / site_name

站点图标与名称(可能为 null)

来源卡片的视觉

page_age

RFC 3339 发布时间(可能为 null)

时效性判断

encrypted_content

AES-256-GCM 加密的摘要正文

客户端解不开,服务端继续用

image_url

图搜召回的原站图片

当前只保存不展示

表 2 一条 web_search_result 带的字段。结构化是“能做成产品”和“只能贴一段文字”的区别。

引用也不是事后加的:服务端把模型写的引用标记还原成来源,挂在对应的文本块上,所以一段话可以精确对应到几个网址,界面因此能做段落级溯源、悬停预览、按网址去重。

读链接更有意思:页面正文被加密在结果块的 signature 里,多轮对话要原样回传,服务端解密后把网页拼回那一轮提问的末尾。签名丢了,这段上下文就接不上——所以代码里“没有有效签名的读链接,调用和结果一起丢掉”,不留半截。

六、深度思考与续写

思考块也是流式的三段式:content_block_start 记下开始时间,thinking_delta 不断追加,content_block_stop 记下结束时间——界面上因此能显示“思考了 3 秒”。签名在块结束前经 signature_delta 下发,值是本次响应的消息 id。

续写只允许两种情况:被用户停止的回复,或者撞到输出上限(max_tokens)的回复。报错的、被安全拒绝的、调用过服务端工具的这一轮,都不能接着写。

实现方式很省:把末尾那条助手消息再发一遍当前缀,让模型接着写。历史轮次的思考不回传,只保留本轮非空白的思考与签名。

拒绝也要处理干净:一旦结束原因是安全拒绝(stop_reason: refusal),已经下发的思考和正文按协议必须由客户端丢弃,否则下一次请求会把不该保留的内容带回去。

用量统计分四类:未命中缓存的输入、写入缓存的输入、命中缓存的输入、输出,外加搜索请求次数。这四个数决定了成本分析能不能做。

七、语音与本地数据

语音输入没有调浏览器的语音识别,而是在页面里用 AudioContext 按 16 kHz 采成单声道 PCM,再上传给 POST /v1/tools/asr:单次最多 120 秒、8 MiB。录音时输入框里那条实时频谱,就是这个 AnalyserNode 的输出。

朗读走 POST /v1/tools/tts,返回的是 24 kHz 的裸 PCM,不是压缩音频——可以一边收一边播,延迟更低;服务端默认会过滤代码块、表格、引用标记和长公式。

本地数据分两处:设置与密钥在 localStorage,会话与附件原件在 IndexedDB(库版本已到 11)。会话列表单独存摘要,并给摘要建了 fileIds 多值索引——删除会话时靠这个索引判断原件是否还被别的会话引用,避免误删。

历史导入导出是整套 ZIP。导入先写进暂存区,全部校验通过后在一个事务里替换正式数据,失败只清空暂存;导出只带走会话与可用图片,不带密钥、设置、非图片附件。

消息分支靠父子指针连成树,selectedChildId 指定当前路径;展示与会话上下文同源,切分支时两者一起变。

八、能力地图:六组接口能拼出什么

把前面讲的摊开看,接口层面其实只有六组。

图 5 六组接口:其余能力都是这六组的组合

这六组接口带来的能力可以归纳成五个维度:

图 6 五个能力维度:模型之外,接口层还在替你做什么

能力

接口

自己实现的话要做什么

流式输出

messages + stream

SSE 解析、事件合并、中止与续写、断线重连

服务端联网

deepseek_web_search

爬虫、去重、摘要、召回排序、时效判断

读链接

deepseek_read_url

正文抽取、编码嗅探、反爬、分块与上下文拼装

多模态文件

files + image/document

版面解析、PDF 拆页、图片理解、存储与配额

双向语音

tools/asr + tools/tts

ASR 模型、TTS 音色、降噪、采样率对齐

引用与用量

citations + usage

来源对齐、缓存计费、成本看板

表 3 这五列是“要不要自己搭”的判断依据。表里每一行都不便宜。

九、拿这套 API 能做什么

按接口组合拆,大致是三类产品。

1. 知识型:文档问答、合同比对、带出处的客服

用 Files 上传文档,靠版面识别保住结构,再让模型带着引用回答。价值不在“能读 PDF”,而在每句答案都能钉回原文第几段——这才是能进企业流程的前提。

2. 检索型:行业简报、竞品跟踪、舆情汇总

用深度搜索把多个页面读进来再综合,适合需要交叉验证的场景。读链接的签名机制保证多轮里网页上下文不丢,追问时不用重新抓一遍。

3. 交互型:会议记录、车载助手、无障碍朗读

语音进、语音出,中间是流式回答。裸 PCM 让边收边播成为可能,首字延迟能压得很低;代价是要自己处理播放队列与打断。

如果你要做一个自己的对话产品,这个仓库给的是最短路径:

可以直接复用

需要自己补

流式事件合并、错误五分类、附件重传、分支与上下文过滤

账号体系与额度、服务端代理、多端同步

SSE 解码(含 CRLF 与保活)、中止控制

审计与合规、内容安全兜底

IndexedDB 存储模型、ZIP 导入导出、草稿与上传队列

团队协作、分享链接、埋点与可观测

表 4 可直接复用 / 需要自己补。左边是这份源码最值钱的部分。

十、结语:价值在接口层

这份源码读下来,最该记住的不是某个组件的写法,而是一个事实:搜索、读链接、版面解析、语音、引用、缓存计费,这些笨重的基础设施已经被做成了几个可以直接调的接口。模型能力只是其中一环。

所以真正的问题不是“模型够不够聪明”,而是“你打算把这些接口拼成什么”。源码就在那里,117 个文件、13 694 行,从 store.ts 和 reply.ts 开始读,一个下午够了。

 

文章对应的视频地址:DeepSeek全家桶应用 API及chat-demo解读_哔哩哔哩_bilibili

posted @ 2026-11-16 13:04  我才是银古  阅读(99)  评论(0)    收藏  举报