MerchantOps-KBQA 实践（八）：FastAPI 与 WebSocket 流式问答接口设计

知识库问答不仅是一个模型函数，还需要让前端、诊断和评估稳定调用。项目使用 FastAPI 提供 HTTP 与 WebSocket 两条入口。

一、主要接口

GET /health、GET /ready、POST /api/query、WebSocket /api/stream、POST /api/create_session、GET /api/history/{session_id}、GET /api/sources。

流式接口按start -> token -> end返回事件。会话创建和历史查询独立于单次提问，避免把浏览器状态混入模型调用逻辑。

二、统一输入边界

HTTP 和 WebSocket 共用校验：query必须是非空文本且不超过 1000 字符；source_filter必须属于配置白名单。空问题返回 422，而不是进入检索后才失败。

三、不要让文档落后于代码

项目当前使用/api/stream，不再保留旧的/ws/{session_id}描述。接口契约与真实路由统一后，前端联调、面试讲解和后续维护才有同一个可信来源。