API 参考
所有 API 端点以 /api/v1 为前缀。 除 health 端点外，均需鉴权。
鉴权方式
所有业务 API 请求需携带 HTTP Header：
Authorization: Bearer <API_KEY>
API_KEY 通过环境变量设置，默认值见 docker-compose.yml。
限流规则
| 端点 | 限制 |
|---|---|
| POST /api/v1/kb/chat | 30 次/分钟 |
| POST /api/v1/kb/documents | 10 次/分钟 |
| 其他 | 不限流 |
文档管理 API
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/kb/documents | 批量上传文档 (multipart/form-data) |
| GET | /api/v1/kb/documents | 分页查询文档列表 |
| GET | /api/v1/kb/documents/{id} | 获取文档详情 |
| PUT | /api/v1/kb/documents/{id} | 更新文档名称/描述 |
| DELETE | /api/v1/kb/documents/{id} | 软删除文档 |
| PUT | /api/v1/kb/documents/{id}/status | 切换启用/禁用 |
| POST | /api/v1/kb/documents/{id}/reindex | 增量重索引 |
智能问答 API
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/kb/chat | RAG 问答（SSE 流式响应） |
| GET | /api/v1/kb/chat/history | 会话问答历史（分页） |
| GET | /api/v1/kb/chat/sessions | 会话列表 |
| DELETE | /api/v1/kb/chat/sessions/{id} | 删除会话及关联数据 |
SSE 流式响应规范
POST /api/v1/kb/chat 返回 SSE 事件流，包含以下事件类型：
event: progress
data: {"stage":"intent","message":"识别用户意图...","timestamp":"..."}
event: progress
data: {"stage":"retrieval","message":"向量检索中...","timestamp":"..."}
event: progress
data: {"stage":"generation","message":"LLM 推理中...","timestamp":"..."}
event: token
data: {"text":"根据"}
event: token
data: {"text":"本地"}
event: done
data: {"message_id":"...","ref_chunks":[...],"model":"...","thinking_steps":[...]}progress：流程进度，前端展示推理步骤token：逐 token 推送，前端实现打字机效果done：完成信号，携带引用块和元数据
运维 & 检索 API
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/kb/retrieval/test | 检索测试沙盒 |
| GET | /api/v1/kb/documents/{id}/chunks | 文档切片列表 |
| PUT | /api/v1/kb/chunks/{id} | 编辑切片（自动重向量化） |
| DELETE | /api/v1/kb/chunks/{id} | 删除切片 |
| GET | /api/v1/kb/stats/overview | 知识库运维概览 |
| GET | /api/v1/kb/stats/frequent-questions | 高频问题 Top-N |