简介在AI应用开发中实时交互逐渐成为标配。如何将大模型生成的内容以流式方式推送到前端直接影响用户体验的流畅度。基于HTTP轮询或一次性返回的常规方案在长文本生成场景下往往延迟偏高、交互生硬而WebSocket凭借全双工通信能力天然适合承载模型输出的连续数据流。本文从大模型API接入认证、SSE分块解析、前端状态累积到Vite代理配置系统梳理了DeepSeek流式聊天的完整链路。通过OpenAI兼容的接口设计开发者可低成本切换模型服务同时借助心跳与断线重连机制保障长连接稳定性为构建智能化对话产品提供一条清晰可落地的技术路径。1. 深度集成DeepSeek大模型为什么流式聊天选WebSocket最近在拆一份DeepSeek大模型的聊天项目ReactVite前端、Python后端整条链路走WebSocket流式。核心不是把DeepSeek接口“包一层”而是把一次普通聊天请求变成真正的流式闭环浏览器输入消息→WebSocket送给本地服务→后端调DeepSeek接口拿到一小块一小块文本→顺着同一条连接推回页面。相比HTTP轮询或一次性返回这种方案延迟更低、交互更自然正是AI聊天应用里常见的打字机效果需要的。这份资源把“API调用”“流式传输”“前端渲染”串成了一个可运行的整体适合两类人一类是想用DeepSeek做对话产品、被SSE和WebSocket细节卡住的前端或全栈开发另一类是刚接触大模型开发、想用最小路径验证“流式响应到底怎么到浏览器”的初学者。解压资源后看文件结构会发现后端只有一个py/index.py前端由main.jsx和App.jsx构建没有很重的工程包袱复现门槛不高。2. 从py/index.py接入DeepSeek密钥、端点和流式参数后端是整个流式聊天的“翻译层”。前端不管DeepSeek接口长什么样它只负责把消息推到WebSocket真正跟大模型API打交道的是py/index.py。这一章先讲认证方式和API地址再说流式返回必须经历的结构这两个点没对齐聊天功能用一个卡一个。2.1 DeepSeek接口的OpenAI兼容属性base_url与model怎么填DeepSeek的大模型接口在协议上兼容OpenAI这意味着不用为新SDK重新学一套东西。项目中用Python集成时常见做法是把openai库的base_url切到DeepSeek的地址再单独设置api_key其余消息结构、温度、上下文方式都与Chat Completions保持对齐。刚好借py/index.py说说DeepSeek API怎么调最稳。如果你第一次接触这个接口先看这段最简调用import os from openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com, ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个简洁的技术助手}, {role: user, content: 用三句话解释WebSocket}, ], max_tokens256, streamTrue, )这段代码里有两个地方容易写错。第一是base_url有人写成“https://api.deepseek.com/v1”老版本确实没问题但现在统一为“https://api.deepseek.com”接口路径由SDK自动补齐不需要手动拼“chat/completions”。第二是api_key绝对不能硬编码进源码py/index.py里更常见的做法是读取环境变量比如前面这段os.getenv如果密钥被提交进Git仓库回头就是一次泄露事故这是血泪经验。参数方面model填“deepseek-chat”是对话模型填“deepseek-reasoner”会进入推理模式输出之前先给出思维链内容max_tokens限制单轮回复长度256对演示项目够用如果做知识库问答建议放到1024以上。最后是streamTrue很多第一次用的人会漏掉漏掉的结果是resp变成一个完整对象要等模型全部生成完才能拿到文本流式后面完全无从谈起。注意密钥本身属于敏感信息。环境变量设置好之后最好在py/index.py开头打印一次“是否存在key”的布尔值不要真的把key全量打出来。在流式集成场景里OpenAI兼容还有一个隐藏优势可以在不改前端的情况下把client替换成代理OpenAI或其他兼容服务py/index.py需要改的就只有base_url和model。其他大模型接口的切换成本因此被压得很低这一点后面会再提到。2.2 流式模式不是拿全文chunk迭代与SSE数据解析当streamTrue时create的返回值不再是普通ChatCompletion对象而是一个可迭代的流流里每条记录对应一小块生成内容。这就是SSEServer-Sent Events的表现后端每次把一小片数据推给你你需要自己逐条消费、逐条转发。先看怎么处理chunkdef gen_text(client, messages): stream client.chat.completions.create( modeldeepseek-chat, messagesmessages, streamTrue, temperature0.7, ) for chunk in stream: if not chunk.choices: continue delta chunk.choices[0].delta content delta.content if content: yield content yield None这段代码看起来简单真正运行时会碰到几个细节。第一chunk.choices可能为空原因在于DeepSeek在流式过程中会先推送一条带有usage信息的元数据如果不对choices做空判断直接取[0]会当场抛IndexError。第二delta.content可能为None并不是每块都有实际文本比如角色信息变化时delta会携带role但不携带content这里用if content过滤掉空块。yield出来的content已经是纯文本片段不再带“data:”前缀。因为在openai库内部已经替你解析了SSE的行格式如果你跳过SDK、直接用requests读原生流才会看到一行行以“data:”开头的原始数据那时需要自己切前缀还要处理结尾的“data: [DONE]”。项目里用openai库就是为了省掉这一层手工解析代码可读性高很多。基于这个生成器后面WebSocket转发就很有规律async def send_to_frontend(websocket, client, messages): for piece in gen_text(client, messages): if piece is None: await websocket.send_json({event: done}) break await websocket.send_json({event: text, content: piece})注意这里为什么说“常见做法是放到线程池里跑”。如果直接用for循环去消费同步生成器整个事件循环会被卡住前端消息会一直等着不动我一般会用asyncio.to_thread把同步循环丢到后台线程或者干脆换成异步HTTP客户端来避免这个问题。如果只是演示也可以不包异步把同步循环放到独立线程里跑然后通过队列把每块文本传给WebSocket主循环效果一样代码更绕一点。3. WebSocket流式推送一条消息怎么从DeepSeek流到浏览器API这一层通了之后剩下的问题只剩传输。这里的关键不是“用WebSocket代替HTTP”而在于怎么设计前后端都能理解的消息格式、怎么把后端生成的一大串文本变成浏览器里的流畅回复。这一章讲连接建立与消息协议把py/index.py里最核心的骨架拆开看。3.1 前后端消息协议一条聊天请求怎么在WebSocket上流转WebSocket本身只负责“双向、全双工、实时”的传输通道不管你要传的是文本、JSON还是二进制。项目中前后端约定使用JSON文本帧每条消息带type字段来区分用途避免把“聊天内容”“状态通知”“错误信息”混在一起。常见的约定是这样{type: chat, content: 你好帮我总结一段代码} {type: ping, timestamp: 1710000000} {type: text, content: 这是生成的一部分回复} {type: done, requestId: abc123} {type: error, message: 模型接口超时}设计协议时requestId字段值得保留。聊天窗口里用户可能连续发好几条每条请求对应一个requestId后端返回text块时带上它前端才能判断“这段文本到底属于哪一条消息”否则多条消息并发时所有文本会串在一起。项目虽小建议从第一版就把这个字段加上省得后面扩展成多轮对话时返工。后端WebSocket端点的实现简化下来是这样from fastapi import FastAPI, WebSocket, WebSocketDisconnect app FastAPI() app.websocket(/ws/chat) async def ws_chat(websocket: WebSocket): await websocket.accept() try: while True: data await websocket.receive_json() if data.get(type) ping: await websocket.send_json({type: pong}) continue user_msg data.get(content, ) messages build_messages(user_msg) await forward_stream(websocket, messages) except WebSocketDisconnect: print(client disconnected)这里只保留了主循环。receive_json拿到前端发来的聊天内容先处理心跳再进入forward_stream后者内部去调用DeepSeek流式接口并把生成的每块文本通过send_json推给浏览器。注意while True里没有break连接断开时由WebSocketDisconnect异常收尾这是FastAPI的WebSocket端点和普通HTTP路由最大的区别。这里要留意forward_stream不能直接阻塞事件循环。如果一端模型生成耗时很长另一个浏览器连进来就会被“饿死”多人使用时体验很糟。常见做法是把流式消费丢到后台任务并把结果通过queue传给当前WebSocket否则压力一上来连接数稍微多一点就开始排队。单用户测试看不出问题一旦开两三个标签页就很考验这部分代码的并发能力。3.2 前端onmessage与流式累积React状态下把碎片拼成话前端用浏览器原生WebSocket对象连接不引入额外的socket库。这样包最小也方便在React组件里控制连接生命周期。原生WebSocket的onmessage回调会在每个块到达时触发前端要做的核心工作就是把碎片累积成完整回复文本。const socket new WebSocket(ws://${location.host}/ws/chat) socket.onopen () { setConnected(true) } socket.onmessage (evt) { const msg JSON.parse(evt.data) if (msg.type text) { setAnswer((prev) prev msg.content) } else if (msg.type done) { setStreaming(false) } else if (msg.type error) { setError(msg.message) } }这段代码里的核心设计是setAnswer用函数式更新。为什么必须写成prev prev msg.content而不是直接把msg.content加到旧值上因为WebSocket回调并不保证严格串行多条消息到达时如果直接读旧state很容易拿到过期状态。函数式更新永远基于上一次的最新值这算React流式渲染的第一原则。done事件到达后要置streaming状态这个状态决定了前端“停止打字光标”和“禁用发送按钮”。如果没有这一步用户看到的光标一直闪烁以为还在生成同样发送过程中的按钮锁定也是靠streaming控制的否则用户连续点发送同一轮对话会塞进多条并发请求后端消息顺序整个乱掉。累积文本的过程中要留意渲染时机。React的setState是异步批处理的高频到达的text块会合并到一次渲染里所以“每次onmessage都触发render”并不是一个昂贵的行为不需要额外做节流。真正的问题出在文本量过大的情况下DOM更新跟不上这就放到下一章讨论。4. ViteReact把流式UI撑起来代理配置与状态设计聊到前端工程化很多人以为核心是CSS样式或者组件拆分但在流式聊天场景里真正影响成败的是两件事开发环境怎么把WebSocket代理过去以及React状态怎么划分才能撑住高频小文本累积。这两件事分别对应vite.config.js和App.jsx这也是拆这个项目时花时间最多的地方。4.1 vite.config.js代理跨域开发环境ws与http怎么转发前端开发服务器默认跑在5173Python后端跑在8000。直接让前端代码连ws://localhost:8000/ws/chat会碰到跨域问题而且浏览器对WebSocket的跨域限制和HTTP不完全一样。与其在后端开一堆CORS白名单不如在vite.config.js里做反向代理。export default defineConfig({ server: { port: 5173, proxy: { /ws: { target: ws://localhost:8000, ws: true, changeOrigin: true, }, }, }, })这段配置的核心是ws: true。很多人在Vite里代理过HTTP接口但忘了WebSocket升级握手也要走代理漏掉ws: true时前端连接会一直pending控制台不会报经典跨域错而是一个看起来像“网络超时”的假象。changeOrigin把请求头里的Host改成目标地址对FastAPI识别来源没有硬性影响但跨域场景下建议保留。配置好之后前端代码里创建WebSocket时用相对路径const protocol location.protocol https: ? wss : ws const socket new WebSocket(${protocol}://${location.host}/ws/chat)不要写死ws://localhost:8000。一旦后面部署到服务器域名变了、端口变了写死的地址就成了炸弹。用location.host自动带上当前页面域名Vite代理会把请求转给后端生产环境只需要在Nginx里配一条同样的/ws代理规则前端代码完全不用动。这个习惯能救你很多次。4.2 React状态分层messages与answer怎么划分及自动滚动App.jsx里最容易被忽略的设计是状态划分。见过很多实现把整个聊天记录放在一个大数组里每来一个text块就更新整个数组结果每秒钟要处理十几次大数组重新创建页面肉眼可见地掉帧。这个项目把“历史消息”和“当前生成中的回答”分开是很实用的设计。const [messages, setMessages] useState([]) const [answer, setAnswer] useState() const [streaming, setStreaming] useState(false) const send () { setMessages((prev) [ ...prev, { role: user, content: input }, ]) setInput() setAnswer() setStreaming(true) socket.send(JSON.stringify({ type: chat, content: input })) }messages负责渲染历史列表answer持有当前正在生成的文本流式结束之后再合并回messages。为什么分开因为messages变更会触发整个聊天区重渲染而answer只触发“正在输入的那一块”更新如果两者混合每块text到达时既要改数组又要改渲染树聊天记录一多性能就很难跟上。自动滚动在这个架构下也简单监听answer变化然后滚动到底部。useEffect(() { if (bottomRef.current) { bottomRef.current.scrollIntoView({ behavior: smooth }) } }, [answer])这里触发依赖是answer而不是messages因为只有answer代表“持续的文本增长”messages在一次发送结束前基本不变。scrollIntoView用smooth在长文本场景下会有一种“追赶内容”的动画效果但生成速度太快时会让人头昏我一般改成instant或者对滚动区域做条件判断避免每帧都在滚。5. 避坑DeepSeek流式聊天中常见的五个翻车现场这一章是按真实排障顺序整理的五个高频问题。每一条都按照“现象→原因→解决”来写你在复现时如果遇到类似症状可以直接对照处理。5.1 现象控制台报CORS跨域WebSocket一直连不上现象前端页面打开后控制台出现类似“Access-Control-Allow-Origin”的报错WebSocket连接卡在connecting状态刷新几次都一样。原因前端直接请求了后端8000端口浏览器把这次握手判定为跨域请求。很多人以为Vite代理会自动转发实际并没有——只有把后端地址写进server.proxy发往/ws的请求才会走代理。解决在vite.config.js里配置server.proxy并把ws设为true然后重启npm run dev。前端创建WebSocket时用相对路径开发和生产环境就不需要各写一套地址。这个配置也是后面一切功能能跑通的前提。5.2 现象聊天回复带着“data:”前缀像原始SSE没解析现象页面把后端返回的原始字节当作文本直接渲染回复内容前面全是“data:”开头末尾还露出“[DONE]”文本。原因跳过OpenAI的SDK直接用requests去请求DeepSeek接口拿到的是原始SSE字节流代码没有解析事件格式就把字节串发给了前端。解决用openai库替代手工HTTP调用或用sseclient之类工具解析原生流如果是自建协议在发送WebSocket消息前把每行开头的“data:”去掉遇到“[DONE]”时发送done事件终止本轮输出。判断一个项目是不是“裸流式”看它有没有独立解析层的代码就知道了。5.3 现象长时间不聊天后连接断开再发消息没响应现象聊天窗口挂机几分钟后再输入消息点发送消息一直停在界面里后端日志没有新的WebSocket消息到达。原因会话被代理或空闲超时机制断开。常见原因是前端没有心跳代理服务器默认空闲超时在60秒附近一旦长时间没有双向数据交换连接就会被回收。这个问题在本地开发时通常不出现部署到Nginx后才开始发作很玄学但本质就是保活机制缺失。解决在前后端实现心跳协议定时ping/pong。具体代码在下一章给完整模板你只需要把它复制进现有项目就能看到连接稳定性明显改善。5.4 现象多轮对话后接口报上下文长度超限现象对话进行到第20轮左右调用DeepSeek接口报错提示context length exceeded或类似长度超限信息。原因messages数组把历史对话全部传给模型token总量超过了模型上下文窗口。deepseek-chat的上下文长度不小但让模型“记住所有历史”并不现实翻车是迟早的事。解决在构建messages时只保留最近几轮。常见做法是固定窗口大小比如最近10条消息超过时截断最老的记录也可以用tiktoken类似的工具粗略估算token数超限就自动裁剪。这个窗口值不是越大越好提醒自己上下文越长单次请求的耗时和费用都在涨。5.5 现象流式输出时UI卡顿文本一长就掉帧现象生成的文本超过1000字后页面滚动不流畅输入框也有延迟感。原因每个text块都触发大列表状态更新或者自动滚动使用smooth模式不断追逐最新内容两种做法都会让浏览器主线程长期满负载。解决把answer单独作为一个状态等done之后才合并进messages自动滚动改成instant或做条件滚动给渲染线程留出处理新文本块的空闲时间。这条属于典型的“能跑但不好用”不影响功能但影响用户对产品流畅度的感知。6. 心跳机制与断线重连把“死”连接救活的关键技巧服务器空闲太久会回收WebSocket连接前端若没有感知就会一直以为自己是“在线”的等到发送消息时才发现连接早断了。这一章的内容是一个可复用的心跳断线重连模板不只DeepSeek聊天项目任何WebSocket场景都用得上。6.1 ping/pong与自动重连一套标准实现先看前端完整逻辑let ws null let heartbeatTimer null let reconnectTimer null function connect() { ws new WebSocket(${location.protocol https: ? wss : ws}://${location.host}/ws/chat) ws.onopen () { heartbeatTimer setInterval(() { ws.send(JSON.stringify({ type: ping })) }, 30000) } ws.onmessage (evt) { const msg JSON.parse(evt.data) if (msg.type pong) { // 收到pong说明连接还活着 return } // 其余逻辑与之前onmessage一致 } ws.onclose () { clearInterval(heartbeatTimer) reconnectTimer setTimeout(connect, 3000) } ws.onerror () { ws.close() } } connect()心跳间隔取30秒因为大多数代理服务器的空闲超时阈值在60秒左右30秒能保证连接在超时前至少有一次双向消息。重连延迟取3秒避免服务器未恢复时疯狂握手。onerror里主动调用ws.close()是为了让onclose尽快触发并进入重连队列不然有些浏览器只会静默失败。后端配合这段逻辑只需要在WebSocket主循环里多判断一种消息类型收到type为ping回一个type为pong。不需要额外做状态存储连接本身就能完成这一轮确认。如果生产环境要更严格可以加一个连续超时计数器连续几次没收到pong就主动断开演示项目不需要但当你开始做线上服务时这是必须补的一层。从那以后我每次上线WebSocket都会强制把心跳和重连逻辑写进去再也不会看到连接一直挂着、发送却石沉大海的情况。心跳间隔30秒、重连延迟3秒这两个参数直接决定了一个聊天功能的稳定性下限。希望帮到你——如果你正好在调DeepSeek流式聊天可以拿这套模板直接跑连接稳定性会有直观的改善。本文还有配套的精品资源点击获取 WebSocket流式聊天：从零接入DeepSeek大模型的完整指南
简介在AI应用开发中实时交互逐渐成为标配。如何将大模型生成的内容以流式方式推送到前端直接影响用户体验的流畅度。基于HTTP轮询或一次性返回的常规方案在长文本生成场景下往往延迟偏高、交互生硬而WebSocket凭借全双工通信能力天然适合承载模型输出的连续数据流。本文从大模型API接入认证、SSE分块解析、前端状态累积到Vite代理配置系统梳理了DeepSeek流式聊天的完整链路。通过OpenAI兼容的接口设计开发者可低成本切换模型服务同时借助心跳与断线重连机制保障长连接稳定性为构建智能化对话产品提供一条清晰可落地的技术路径。1. 深度集成DeepSeek大模型为什么流式聊天选WebSocket最近在拆一份DeepSeek大模型的聊天项目ReactVite前端、Python后端整条链路走WebSocket流式。核心不是把DeepSeek接口“包一层”而是把一次普通聊天请求变成真正的流式闭环浏览器输入消息→WebSocket送给本地服务→后端调DeepSeek接口拿到一小块一小块文本→顺着同一条连接推回页面。相比HTTP轮询或一次性返回这种方案延迟更低、交互更自然正是AI聊天应用里常见的打字机效果需要的。这份资源把“API调用”“流式传输”“前端渲染”串成了一个可运行的整体适合两类人一类是想用DeepSeek做对话产品、被SSE和WebSocket细节卡住的前端或全栈开发另一类是刚接触大模型开发、想用最小路径验证“流式响应到底怎么到浏览器”的初学者。解压资源后看文件结构会发现后端只有一个py/index.py前端由main.jsx和App.jsx构建没有很重的工程包袱复现门槛不高。2. 从py/index.py接入DeepSeek密钥、端点和流式参数后端是整个流式聊天的“翻译层”。前端不管DeepSeek接口长什么样它只负责把消息推到WebSocket真正跟大模型API打交道的是py/index.py。这一章先讲认证方式和API地址再说流式返回必须经历的结构这两个点没对齐聊天功能用一个卡一个。2.1 DeepSeek接口的OpenAI兼容属性base_url与model怎么填DeepSeek的大模型接口在协议上兼容OpenAI这意味着不用为新SDK重新学一套东西。项目中用Python集成时常见做法是把openai库的base_url切到DeepSeek的地址再单独设置api_key其余消息结构、温度、上下文方式都与Chat Completions保持对齐。刚好借py/index.py说说DeepSeek API怎么调最稳。如果你第一次接触这个接口先看这段最简调用import os from openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com, ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个简洁的技术助手}, {role: user, content: 用三句话解释WebSocket}, ], max_tokens256, streamTrue, )这段代码里有两个地方容易写错。第一是base_url有人写成“https://api.deepseek.com/v1”老版本确实没问题但现在统一为“https://api.deepseek.com”接口路径由SDK自动补齐不需要手动拼“chat/completions”。第二是api_key绝对不能硬编码进源码py/index.py里更常见的做法是读取环境变量比如前面这段os.getenv如果密钥被提交进Git仓库回头就是一次泄露事故这是血泪经验。参数方面model填“deepseek-chat”是对话模型填“deepseek-reasoner”会进入推理模式输出之前先给出思维链内容max_tokens限制单轮回复长度256对演示项目够用如果做知识库问答建议放到1024以上。最后是streamTrue很多第一次用的人会漏掉漏掉的结果是resp变成一个完整对象要等模型全部生成完才能拿到文本流式后面完全无从谈起。注意密钥本身属于敏感信息。环境变量设置好之后最好在py/index.py开头打印一次“是否存在key”的布尔值不要真的把key全量打出来。在流式集成场景里OpenAI兼容还有一个隐藏优势可以在不改前端的情况下把client替换成代理OpenAI或其他兼容服务py/index.py需要改的就只有base_url和model。其他大模型接口的切换成本因此被压得很低这一点后面会再提到。2.2 流式模式不是拿全文chunk迭代与SSE数据解析当streamTrue时create的返回值不再是普通ChatCompletion对象而是一个可迭代的流流里每条记录对应一小块生成内容。这就是SSEServer-Sent Events的表现后端每次把一小片数据推给你你需要自己逐条消费、逐条转发。先看怎么处理chunkdef gen_text(client, messages): stream client.chat.completions.create( modeldeepseek-chat, messagesmessages, streamTrue, temperature0.7, ) for chunk in stream: if not chunk.choices: continue delta chunk.choices[0].delta content delta.content if content: yield content yield None这段代码看起来简单真正运行时会碰到几个细节。第一chunk.choices可能为空原因在于DeepSeek在流式过程中会先推送一条带有usage信息的元数据如果不对choices做空判断直接取[0]会当场抛IndexError。第二delta.content可能为None并不是每块都有实际文本比如角色信息变化时delta会携带role但不携带content这里用if content过滤掉空块。yield出来的content已经是纯文本片段不再带“data:”前缀。因为在openai库内部已经替你解析了SSE的行格式如果你跳过SDK、直接用requests读原生流才会看到一行行以“data:”开头的原始数据那时需要自己切前缀还要处理结尾的“data: [DONE]”。项目里用openai库就是为了省掉这一层手工解析代码可读性高很多。基于这个生成器后面WebSocket转发就很有规律async def send_to_frontend(websocket, client, messages): for piece in gen_text(client, messages): if piece is None: await websocket.send_json({event: done}) break await websocket.send_json({event: text, content: piece})注意这里为什么说“常见做法是放到线程池里跑”。如果直接用for循环去消费同步生成器整个事件循环会被卡住前端消息会一直等着不动我一般会用asyncio.to_thread把同步循环丢到后台线程或者干脆换成异步HTTP客户端来避免这个问题。如果只是演示也可以不包异步把同步循环放到独立线程里跑然后通过队列把每块文本传给WebSocket主循环效果一样代码更绕一点。3. WebSocket流式推送一条消息怎么从DeepSeek流到浏览器API这一层通了之后剩下的问题只剩传输。这里的关键不是“用WebSocket代替HTTP”而在于怎么设计前后端都能理解的消息格式、怎么把后端生成的一大串文本变成浏览器里的流畅回复。这一章讲连接建立与消息协议把py/index.py里最核心的骨架拆开看。3.1 前后端消息协议一条聊天请求怎么在WebSocket上流转WebSocket本身只负责“双向、全双工、实时”的传输通道不管你要传的是文本、JSON还是二进制。项目中前后端约定使用JSON文本帧每条消息带type字段来区分用途避免把“聊天内容”“状态通知”“错误信息”混在一起。常见的约定是这样{type: chat, content: 你好帮我总结一段代码} {type: ping, timestamp: 1710000000} {type: text, content: 这是生成的一部分回复} {type: done, requestId: abc123} {type: error, message: 模型接口超时}设计协议时requestId字段值得保留。聊天窗口里用户可能连续发好几条每条请求对应一个requestId后端返回text块时带上它前端才能判断“这段文本到底属于哪一条消息”否则多条消息并发时所有文本会串在一起。项目虽小建议从第一版就把这个字段加上省得后面扩展成多轮对话时返工。后端WebSocket端点的实现简化下来是这样from fastapi import FastAPI, WebSocket, WebSocketDisconnect app FastAPI() app.websocket(/ws/chat) async def ws_chat(websocket: WebSocket): await websocket.accept() try: while True: data await websocket.receive_json() if data.get(type) ping: await websocket.send_json({type: pong}) continue user_msg data.get(content, ) messages build_messages(user_msg) await forward_stream(websocket, messages) except WebSocketDisconnect: print(client disconnected)这里只保留了主循环。receive_json拿到前端发来的聊天内容先处理心跳再进入forward_stream后者内部去调用DeepSeek流式接口并把生成的每块文本通过send_json推给浏览器。注意while True里没有break连接断开时由WebSocketDisconnect异常收尾这是FastAPI的WebSocket端点和普通HTTP路由最大的区别。这里要留意forward_stream不能直接阻塞事件循环。如果一端模型生成耗时很长另一个浏览器连进来就会被“饿死”多人使用时体验很糟。常见做法是把流式消费丢到后台任务并把结果通过queue传给当前WebSocket否则压力一上来连接数稍微多一点就开始排队。单用户测试看不出问题一旦开两三个标签页就很考验这部分代码的并发能力。3.2 前端onmessage与流式累积React状态下把碎片拼成话前端用浏览器原生WebSocket对象连接不引入额外的socket库。这样包最小也方便在React组件里控制连接生命周期。原生WebSocket的onmessage回调会在每个块到达时触发前端要做的核心工作就是把碎片累积成完整回复文本。const socket new WebSocket(ws://${location.host}/ws/chat) socket.onopen () { setConnected(true) } socket.onmessage (evt) { const msg JSON.parse(evt.data) if (msg.type text) { setAnswer((prev) prev msg.content) } else if (msg.type done) { setStreaming(false) } else if (msg.type error) { setError(msg.message) } }这段代码里的核心设计是setAnswer用函数式更新。为什么必须写成prev prev msg.content而不是直接把msg.content加到旧值上因为WebSocket回调并不保证严格串行多条消息到达时如果直接读旧state很容易拿到过期状态。函数式更新永远基于上一次的最新值这算React流式渲染的第一原则。done事件到达后要置streaming状态这个状态决定了前端“停止打字光标”和“禁用发送按钮”。如果没有这一步用户看到的光标一直闪烁以为还在生成同样发送过程中的按钮锁定也是靠streaming控制的否则用户连续点发送同一轮对话会塞进多条并发请求后端消息顺序整个乱掉。累积文本的过程中要留意渲染时机。React的setState是异步批处理的高频到达的text块会合并到一次渲染里所以“每次onmessage都触发render”并不是一个昂贵的行为不需要额外做节流。真正的问题出在文本量过大的情况下DOM更新跟不上这就放到下一章讨论。4. ViteReact把流式UI撑起来代理配置与状态设计聊到前端工程化很多人以为核心是CSS样式或者组件拆分但在流式聊天场景里真正影响成败的是两件事开发环境怎么把WebSocket代理过去以及React状态怎么划分才能撑住高频小文本累积。这两件事分别对应vite.config.js和App.jsx这也是拆这个项目时花时间最多的地方。4.1 vite.config.js代理跨域开发环境ws与http怎么转发前端开发服务器默认跑在5173Python后端跑在8000。直接让前端代码连ws://localhost:8000/ws/chat会碰到跨域问题而且浏览器对WebSocket的跨域限制和HTTP不完全一样。与其在后端开一堆CORS白名单不如在vite.config.js里做反向代理。export default defineConfig({ server: { port: 5173, proxy: { /ws: { target: ws://localhost:8000, ws: true, changeOrigin: true, }, }, }, })这段配置的核心是ws: true。很多人在Vite里代理过HTTP接口但忘了WebSocket升级握手也要走代理漏掉ws: true时前端连接会一直pending控制台不会报经典跨域错而是一个看起来像“网络超时”的假象。changeOrigin把请求头里的Host改成目标地址对FastAPI识别来源没有硬性影响但跨域场景下建议保留。配置好之后前端代码里创建WebSocket时用相对路径const protocol location.protocol https: ? wss : ws const socket new WebSocket(${protocol}://${location.host}/ws/chat)不要写死ws://localhost:8000。一旦后面部署到服务器域名变了、端口变了写死的地址就成了炸弹。用location.host自动带上当前页面域名Vite代理会把请求转给后端生产环境只需要在Nginx里配一条同样的/ws代理规则前端代码完全不用动。这个习惯能救你很多次。4.2 React状态分层messages与answer怎么划分及自动滚动App.jsx里最容易被忽略的设计是状态划分。见过很多实现把整个聊天记录放在一个大数组里每来一个text块就更新整个数组结果每秒钟要处理十几次大数组重新创建页面肉眼可见地掉帧。这个项目把“历史消息”和“当前生成中的回答”分开是很实用的设计。const [messages, setMessages] useState([]) const [answer, setAnswer] useState() const [streaming, setStreaming] useState(false) const send () { setMessages((prev) [ ...prev, { role: user, content: input }, ]) setInput() setAnswer() setStreaming(true) socket.send(JSON.stringify({ type: chat, content: input })) }messages负责渲染历史列表answer持有当前正在生成的文本流式结束之后再合并回messages。为什么分开因为messages变更会触发整个聊天区重渲染而answer只触发“正在输入的那一块”更新如果两者混合每块text到达时既要改数组又要改渲染树聊天记录一多性能就很难跟上。自动滚动在这个架构下也简单监听answer变化然后滚动到底部。useEffect(() { if (bottomRef.current) { bottomRef.current.scrollIntoView({ behavior: smooth }) } }, [answer])这里触发依赖是answer而不是messages因为只有answer代表“持续的文本增长”messages在一次发送结束前基本不变。scrollIntoView用smooth在长文本场景下会有一种“追赶内容”的动画效果但生成速度太快时会让人头昏我一般改成instant或者对滚动区域做条件判断避免每帧都在滚。5. 避坑DeepSeek流式聊天中常见的五个翻车现场这一章是按真实排障顺序整理的五个高频问题。每一条都按照“现象→原因→解决”来写你在复现时如果遇到类似症状可以直接对照处理。5.1 现象控制台报CORS跨域WebSocket一直连不上现象前端页面打开后控制台出现类似“Access-Control-Allow-Origin”的报错WebSocket连接卡在connecting状态刷新几次都一样。原因前端直接请求了后端8000端口浏览器把这次握手判定为跨域请求。很多人以为Vite代理会自动转发实际并没有——只有把后端地址写进server.proxy发往/ws的请求才会走代理。解决在vite.config.js里配置server.proxy并把ws设为true然后重启npm run dev。前端创建WebSocket时用相对路径开发和生产环境就不需要各写一套地址。这个配置也是后面一切功能能跑通的前提。5.2 现象聊天回复带着“data:”前缀像原始SSE没解析现象页面把后端返回的原始字节当作文本直接渲染回复内容前面全是“data:”开头末尾还露出“[DONE]”文本。原因跳过OpenAI的SDK直接用requests去请求DeepSeek接口拿到的是原始SSE字节流代码没有解析事件格式就把字节串发给了前端。解决用openai库替代手工HTTP调用或用sseclient之类工具解析原生流如果是自建协议在发送WebSocket消息前把每行开头的“data:”去掉遇到“[DONE]”时发送done事件终止本轮输出。判断一个项目是不是“裸流式”看它有没有独立解析层的代码就知道了。5.3 现象长时间不聊天后连接断开再发消息没响应现象聊天窗口挂机几分钟后再输入消息点发送消息一直停在界面里后端日志没有新的WebSocket消息到达。原因会话被代理或空闲超时机制断开。常见原因是前端没有心跳代理服务器默认空闲超时在60秒附近一旦长时间没有双向数据交换连接就会被回收。这个问题在本地开发时通常不出现部署到Nginx后才开始发作很玄学但本质就是保活机制缺失。解决在前后端实现心跳协议定时ping/pong。具体代码在下一章给完整模板你只需要把它复制进现有项目就能看到连接稳定性明显改善。5.4 现象多轮对话后接口报上下文长度超限现象对话进行到第20轮左右调用DeepSeek接口报错提示context length exceeded或类似长度超限信息。原因messages数组把历史对话全部传给模型token总量超过了模型上下文窗口。deepseek-chat的上下文长度不小但让模型“记住所有历史”并不现实翻车是迟早的事。解决在构建messages时只保留最近几轮。常见做法是固定窗口大小比如最近10条消息超过时截断最老的记录也可以用tiktoken类似的工具粗略估算token数超限就自动裁剪。这个窗口值不是越大越好提醒自己上下文越长单次请求的耗时和费用都在涨。5.5 现象流式输出时UI卡顿文本一长就掉帧现象生成的文本超过1000字后页面滚动不流畅输入框也有延迟感。原因每个text块都触发大列表状态更新或者自动滚动使用smooth模式不断追逐最新内容两种做法都会让浏览器主线程长期满负载。解决把answer单独作为一个状态等done之后才合并进messages自动滚动改成instant或做条件滚动给渲染线程留出处理新文本块的空闲时间。这条属于典型的“能跑但不好用”不影响功能但影响用户对产品流畅度的感知。6. 心跳机制与断线重连把“死”连接救活的关键技巧服务器空闲太久会回收WebSocket连接前端若没有感知就会一直以为自己是“在线”的等到发送消息时才发现连接早断了。这一章的内容是一个可复用的心跳断线重连模板不只DeepSeek聊天项目任何WebSocket场景都用得上。6.1 ping/pong与自动重连一套标准实现先看前端完整逻辑let ws null let heartbeatTimer null let reconnectTimer null function connect() { ws new WebSocket(${location.protocol https: ? wss : ws}://${location.host}/ws/chat) ws.onopen () { heartbeatTimer setInterval(() { ws.send(JSON.stringify({ type: ping })) }, 30000) } ws.onmessage (evt) { const msg JSON.parse(evt.data) if (msg.type pong) { // 收到pong说明连接还活着 return } // 其余逻辑与之前onmessage一致 } ws.onclose () { clearInterval(heartbeatTimer) reconnectTimer setTimeout(connect, 3000) } ws.onerror () { ws.close() } } connect()心跳间隔取30秒因为大多数代理服务器的空闲超时阈值在60秒左右30秒能保证连接在超时前至少有一次双向消息。重连延迟取3秒避免服务器未恢复时疯狂握手。onerror里主动调用ws.close()是为了让onclose尽快触发并进入重连队列不然有些浏览器只会静默失败。后端配合这段逻辑只需要在WebSocket主循环里多判断一种消息类型收到type为ping回一个type为pong。不需要额外做状态存储连接本身就能完成这一轮确认。如果生产环境要更严格可以加一个连续超时计数器连续几次没收到pong就主动断开演示项目不需要但当你开始做线上服务时这是必须补的一层。从那以后我每次上线WebSocket都会强制把心跳和重连逻辑写进去再也不会看到连接一直挂着、发送却石沉大海的情况。心跳间隔30秒、重连延迟3秒这两个参数直接决定了一个聊天功能的稳定性下限。希望帮到你——如果你正好在调DeepSeek流式聊天可以拿这套模板直接跑连接稳定性会有直观的改善。本文还有配套的精品资源点击获取