LLM ChatServer 实战 - 会话管理、SSE 流式与错误语义的接口设计（附清单）

客服机器人从命令行 demo 变成给三个人用的内部工具，中间隔着一层 HTTP 服务。模型本身早就调通了，这两天把服务层重构了一遍，精力主要消耗在把会话管理、流式输出和错误语义这些杂事做对。这篇文章把接口设计里的关键决策和踩过的坑整理出来。

先给结论

接口	方法	功能	关键点
/api/session	POST	创建会话	绑定模型，返回 session_id
/api/sessions	GET	会话列表	附带首条消息，方便 UI 展示
/api/session/{id}/history	GET	历史消息	时间戳统一 int64
/api/session/{id}	DELETE	删除会话	不存在返回 404
/api/message	POST	发消息（全量）	简单场景用
/api/message/async	POST	发消息（SSE 流式）	前端体验的刚需

多轮对话场景直接用流式接口，全量接口留着给后台批处理和测试用。

统一响应格式

所有接口返回同一个骨架，前端只需要写一次解析逻辑。

json 复制代码

{
  "success": true,
  "message": "create session success",
  "data": {}
}

错误语义也固定下来，不要每个接口自己发明。

状态码	含义
200	业务成功
400	请求体解析失败、字段缺失
404	session_id 不存在
500	模型调用失败等内部错误

我专门写了 build_response(message, success) 这么一个函数，所有错误响应都从它出去。一开始每个接口里手写 JSON 序列化，改一次错误格式要动七个地方，后来收拢到一处，字段增减只改一行。

流式接口是体验的生死线

全量接口下用户盯着转圈等十几秒，感觉系统死了。改用 SSE（Server-Sent Events）分块传输后，首字响应压到一秒内，体感完全不同。

几个协议层面的细节值得单独拎出来。

响应头设 text/event-stream，关缓存、保持长连接
每帧以 data: 开头，两行换行符收尾，收尾时发一个 [DONE] 标记
模型吐出的增量文本必须做 JSON 转义再放进帧里。模型输出里出现引号和换行是常态，不转义直接把前端的事件解析打碎，而且这种 bug 表现为随机丢字，很难定位
连接建立后立刻发一个空帧。模型首 token 之前有一段静默期，不发空帧某些代理和网关会判定连接超时掐掉

python 复制代码

async def stream_chat(session_id: str, message: str):
    yield sse_frame("")          # 先发空帧防网关超时
    async for chunk in llm.call_stream(session_id, message):
        yield sse_frame(json.dumps({"delta": chunk}))
    yield sse_frame("[DONE]")

另外踩过一个隐蔽的坑。流式回调函数返回 false 时，底层直接断流，后半段内容全部丢失且没有任何报错。回调里的异常处理一定要包住，转成日志而不是让它炸穿传输层。

分层

协议归协议，业务归业务。服务层只做三件事，解析请求、校验参数、组织响应。会话管理和模型调用全部下沉到 SDK 层。

刚开始我把模型重试逻辑写在接口处理器里，三个接口各复制了一份，后来一次超时参数调整只改了两处，漏了第三处，线上行为不一致折腾了半天。分层是给未来的自己留活路。协议层保持轻薄，业务变更就不会碰坏传输层。

踩坑清单速查

时间戳序列化时统一转 int64，否则 JSON 输出类型飘忽不定
路径参数用正则捕获组取值，下标写错会静默取到空值
SSE 帧少了尾部换行符，前端 EventSource 解析不到事件
删除不存在的会话返回 404，别图省事返回 200
流式回调里的异常必须捕获，否则静默断流

结合系列

模型调用失败的重试与降级，在《多模型路由实战》里有完整方案
流式首字延迟的测量口径见《LLM 延迟实战》里的 TTFT、TPOT 与首字慢的排查顺序
会话历史越积越长之后怎么办，见《Agent 记忆实战》的截断与摘要方案
接口鉴权和防注入边界，参考《Agent 安全护栏实战》

写在最后。服务层没有算法难点，全是约定和细节，但这些约定直接决定前端工程师骂不骂你。把响应格式、错误语义、流式协议三件事定死，后面的接口就是在流水线上复制粘贴。

下一篇写会话服务加上多用户隔离的实践，觉得有用的话点个关注，有问题评论区聊。

参考《【AI大模型接入SDK】ChatServer接口实现》，作者艾莉丝努力练剑。结构借鉴，实现与结论按本项目场景独立重写。