协议先行:用四种事件描述一次回答
结论
一次流式回答不是“一个 JSON”,而是一段有类型、有顺序、有终态的事件序列。协议在组件之前定下来:sources 给出来源,token 追加文本,done 表示正常结束,error 表示中途失败。
前端只依赖这四个事件和它们的载荷。后端怎样检索、怎样调用模型,不应该泄漏到浏览器。
问题与设计
普通请求可以这样处理:等响应结束,判断 response.ok,再解析 JSON。流式回答不行。模型开始输出后,HTTP 状态通常已经是 200;此后再发生超时、上游限流或生成失败,只能用流内事件通知。
另一条路是 WebSocket,但这里只有服务端单向推送,没有双向实时协作的需求。SSE 更接近普通 HTTP:一个 POST 请求,一个响应流,代理和日志都容易处理。注意浏览器原生的 EventSource 只支持 GET,不能携带请求体,所以项目用 fetch() 读取 ReadableStream,自己解析 SSE。
协议如下:
| 事件 | data | 出现时机 | 前端动作 |
|---|---|---|---|
sources |
{ sources: [{ n, title, url, slug, score }] } |
检索完成、生成之前 | 保存引用表,可在回答前展示 |
token |
{ text } |
生成过程中可出现多次 | 按顺序追加到当前助手消息 |
done |
{ finishReason: 'stop' } |
正常结束时一次 | 把消息从 streaming 改为完成 |
error |
{ code, message } |
失败时一次 | 标记失败,展示可读信息 |
需要写进类型和测试的顺序约束:
sources在第一个token之前到达;来源列表可以为空。token可以出现零次或多次;空字符串 token 不应产生可见变化。done和error是互斥终态,正常路径只出现done。- 已经收到终态后,不再接受新的
token。 - 连接可能在没有任何终态的情况下断掉,前端必须把这种情况当成失败,而不是完成。
- 未知事件名可以忽略,给未来扩展留空间;已知事件名但载荷不合法必须报错。
请求体也要有稳定契约:
export interface ChatRequest {
query: string
history: Array<Pick<ChatMessage, 'role' | 'content'>>
top_k?: number
}
后端限制 query 最多 500 字、history 最多 6 条、top_k 在 1 到 10 之间。前端在发送前就按这些上限裁剪,避免把用户的正常操作变成 422。
关键代码
类型定义集中在 frontend/app/types/chat.ts,用可辨识联合把事件名和载荷绑在一起:
export type ChatSseEvent =
| { event: 'sources'; data: SourcesEvent }
| { event: 'token'; data: TokenEvent }
| { event: 'done'; data: DoneEvent }
| { event: 'error'; data: ErrorEvent }
这样在 useChat() 里写 if (event.event === 'token') 时,TypeScript 会自动把 event.data 收窄成 { text: string },不需要到处做类型断言。
服务端的编码只有一行核心逻辑,集中放在 _sse():
def _sse(event: str, data: dict[str, object]) -> str:
return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
空行是 SSE 的事件边界。ensure_ascii=False 让中文在调试时保持可读;真正的边界仍然由 event: 和 data: 字段决定,不靠换行猜。
前端解析器只接受这四个事件名,并校验最小载荷:
const payload = parsed as { text?: unknown }
if (eventName === 'token' && typeof payload.text !== 'string') {
throw new Error('SSE token event has an invalid payload')
}
这里的取舍是“已知事件严格、未知事件忽略”。严格校验能在联调时尽早暴露协议漂移;忽略未知事件则允许后端以后增加 heartbeat 之类的事件,而不必同时发布前端。
验证
直接用 curl -N 观察服务端是否逐事件输出,避免把代理缓冲误判成“后端没有流”:
curl -N -X POST http://127.0.0.1:8000/api/chat \
-H 'content-type: application/json' \
-d '{"query":"多阶段构建解决了什么问题?","history":[],"top_k":5}'
正常路径:
event: sources
data: {"sources":[...]}
event: token
data: {"text":"多阶段"}
event: token
data: {"text":"构建"}
event: done
data: {"finishReason":"stop"}
失败路径可能是:
sources → token → error
而不是 done。如果模型未配置,后端会在建立流之前返回 503 chat_unavailable;这是 HTTP 层错误,前端走 response.ok 分支。两种情况要分开处理。
边界
- SSE 是文本协议,不等于“自动重连”。这里的 POST 流没有
Last-Event-ID,断线后由用户重试,不做透明续传。 done只表示生成流程结束,不保证回答正确或引用充分;质量评估是另一层问题。- 协议目前没有版本号。事件名和字段一旦变更,前后端必须同步发布;规模变大后应增加版本或兼容策略。
- 不要把内部错误堆栈放进
error.message。前端展示的是可读文案,细节留在服务端日志。
下一篇处理最容易出错的一层:字节流并不会按事件边界到达。