Skip to content

API.md

Latest commit

 

History

History
136 lines (95 loc) · 2.38 KB

API.md

File metadata and controls

136 lines (95 loc) · 2.38 KB
Raw

API 接口说明

后端基于 FastAPI，默认地址 http://localhost:8000，交互式文档见 /docs。 所有响应为 JSON（流式接口除外）。

1. 健康检查

GET /api/health

{ "status": "ok" }

2. 上传文档（解析 + 切片 + 入库）

POST /api/upload
Content-Type: multipart/form-data
字段 类型 说明
file File PDF 或 Word(.docx)，≤ 50MB

响应 200

{
  "doc_id": "3f2a...",
  "filename": "手册.docx",
  "chunk_count": 42
}

错误

  • 400 不支持的文件类型
  • 413 文件过大
  • 500 解析/入库失败

示例（curl）

curl -F "file=@手册.pdf" http://localhost:8000/api/upload

3. 流式对话（SSE）

POST /api/chat/stream
Content-Type: application/json
字段 类型 说明
query string 用户问题（必填）
session_id string 会话 ID（可选，缺省自动新建）
top_k int 检索切片数（可选，默认 4）

响应：text/event-stream，事件顺序：

  1. event: session → 返回 session_id（便于前端绑定会话）
  2. data: {"content": "..."} → 逐 token 返回（多行）
  3. event: done → 结束信号 {"status":"ok"}
  4. event: error → 出错时返回 {"error":"..."}

示例（curl）

curl -N -X POST http://localhost:8000/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"query":"退货政策是怎样的？","session_id":"abc123"}'

前端解析提示：按 \n\n 切分 SSE 帧，逐帧解析 data: 后的 JSON，event: session 取 session_id，其余 content 累加展示。

4. 历史会话

4.1 会话列表

GET /api/sessions

[ { "session_id": "abc123", "created_at": "2026-07-13 10:00:00" } ]

4.2 单会话消息

GET /api/sessions/{session_id}/messages

[
  { "role": "user", "content": "退货政策？" },
  { "role": "assistant", "content": "根据文档……" }
]

4.3 删除会话

DELETE /api/sessions/{session_id}

5. 文档管理

5.1 已入库文档列表

GET /api/documents

[ { "doc_id": "3f2a...", "filename": "手册.docx", "chunk_count": 42, "created_at": "..." } ]

5.2 删除文档（含向量库记录）

DELETE /api/documents/{doc_id}