通用响应结构
除静态页面外，API 响应统一包装为：
{
"total": 1,
"code": 200,
"data": {},
"pageIndex": 1
}code：HTTP 对应状态码data：实际业务数据total：结果总数（服务端按数据类型推断）pageIndex：页码，默认1
错误示例：
{
"total": 0,
"code": 400,
"data": {
"error": "query is required"
},
"pageIndex": 1
}1. 健康检查
GET/health
data 示例：
{
"ok": true,
"message": "alive"
}1.1 会话
默认使用 Redis 原子自增生成会话 ID，可确保同一用户在高并发/多实例下不重复；若 Redis 不可用，服务会回退到内存生成（进程内唯一）。
GET/session
参数（query string）：
user_id/userId(string, 必填)
data 示例：
{
"ok": true,
"user_id": "user-001",
"session_id": "d8f4..."
}POST/session
请求体（JSON）：
{
"user_id": "user-001"
}data 示例：
{
"ok": true,
"user_id": "user-001",
"session_id": "d8f4..."
}2. 查询问答
支持 GET /query 或 POST /query。
2.1 GET /query
GET/query
参数（query string）：
query(string, 必填)k(int, 默认2)relevance_threshold(float, 可选)model_config_id(int, 可选，优先使用指定模型配置)model_config_name(string, 可选，按名称匹配模型配置)use_default_model_config(bool, 默认true)llm_model(string, 兼容字段，当前不作为模型选择依据)generate_answer(bool, 默认true)deep_think(bool, 默认true)temperature(float, 默认0.2)max_tokens(int, 可选，默认取config.json中knowledge_base.chat.max_tokens)user_id/userId(string, 可选)session_id/sessionId(string, 可选，未传且有 user_id 时自动生成)stream(bool, 可选，true启用 SSE 流式返回)pageIndex(int, 可选)
模型调用仅通过数据库模型配置执行：优先 model_config_id，其次 model_config_name，最后默认配置；若未配置可用模型，接口会返回错误。
当 stream=true 时，响应为 SSE（text/event-stream）。
若传入 user_id 但未传 session_id，服务端会生成新的 session_id 并在响应里返回。
2.2 POST /query
POST/query
请求体（JSON）：
{
"query": "如何重置密码？",
"k": 2,
"relevance_threshold": null,
"model_config_id": null,
"model_config_name": null,
"use_default_model_config": true,
"llm_model": null,
"generate_answer": true,
"deep_think": true,
"temperature": 0.2,
"max_tokens": 512,
"user_id": "user-001",
"session_id": "",
"stream": false,
"pageIndex": 1
}data 示例：
{
"answer": "...",
"finish_reason": "stop",
"is_complete": true,
"session_id": "d8f4...",
"user_id": "user-001",
"thinking_summary": "...",
"relevance_threshold": 1.2,
"threshold_relaxed": false,
"messages": [
{"role": "system", "content": "..."},
{"role": "user", "content": "..."},
{"role": "assistant", "content": "..."}
],
"results": [
{
"distance": 0.1023,
"filename": "account_guide.md",
"similarity": 0.9072,
"text": "命中分片全文...",
"preview_text": "命中分片预览（最多约 240 字）..."
}
]
}启用 stream=true 时，响应为 SSE，事件包含：
meta：包含results、session_id、user_idthinking_delta：思考过程增量文本，字段deltadelta：增量文本，字段deltadone：完成事件，包含answer、finish_reason、thinking、thinking_summary
当启用深度思考且模型提供摘要时，返回 thinking_summary；否则为空或不返回。
前端调用示例（SSE）：
fetch('/query?stream=1', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'text/event-stream',
},
body: JSON.stringify({
query: '如何重置密码？',
user_id: 'user-001',
session_id: '',
stream: true,
}),
});3. 文档管理
3.1 新增文本文档
POST/kb/document
请求体：
{
"filename": "guide.md",
"text": "文档内容"
}data 示例：
{
"ok": true,
"chunks_added": 3
}3.2 上传文件
POST/kb/file
Content-Type：
multipart/form-data字段：
file(file, 必填)filename(string, 可选)encoding(string, 可选)pageIndex(int, 可选)
也支持 JSON 方式：
{
"filename": "notes.txt",
"text": "..."
}返回结构与 POST /kb/document 类似。
3.3 批量上传文件
POST/kb/files
Content-Type：
multipart/form-data字段：
files(file, 必填，可多选)encoding(string, 可选)pageIndex(int, 可选)
3.4 删除单个文档
DELETE/kb/document/{filename}
data 示例：
{
"ok": true,
"chunks_removed": 5
}3.5 获取文档列表
GET/kb/documents
data 示例：
{
"ok": true,
"count": 2,
"documents": [
{
"filename": "guide.md",
"chunk_count": 3,
"char_count": 1200
}
]
}3.6 获取知识库统计
GET/stats
data 示例：
{
"ok": true,
"stats": {
"document_count": 2,
"chunk_count": 8,
"dimension": 1024,
"index_total": 8,
"embedding_model": "Qwen/Qwen3-Embedding-0.6B",
"reranker_model": "Qwen/Qwen3-Reranker-0.6B",
"chat_model": "gpt-oss-20b",
"use_lm_studio_chat": true
}
}3.7 清空知识库
DELETE/kb
data 示例：
{
"ok": true
}3.8 获取分片列表
GET/kb/chunks
参数（query string）：
pageIndex(int, 可选，默认1)pageSize(int, 可选，默认20)filename(string, 可选)q(string, 可选，关键词搜索)
data 示例：
{
"ok": true,
"count": 2,
"chunks": [
{
"id": 0,
"filename": "guide.md",
"text": "...",
"char_count": 320
}
]
}3.9 修改分片
PUT/kb/chunk/{id}
请求体（JSON）：
{
"text": "更新后的分片内容"
}data 示例：
{
"ok": true
}3.10 删除分片
DELETE/kb/chunk/{id}
data 示例：
{
"ok": true
}3.11 重建文件分片
POST/kb/chunks/rebuild
请求体（JSON）：
{
"filename": "guide.md"
}data 示例：
{
"ok": true,
"chunks_added": 3
}4. 历史记录
4.1 查询历史
GET/history
参数：
limit (int, 可选), action (string, 可选), group_by_session (bool, 可选), pageIndex (int, 可选)group_by_session=true 时返回 sessions，否则返回 history。
data 示例：
{
"ok": true,
"sessions": [
{
"session_id": "session-user-001-1",
"first_query": "如何重置密码？",
"timestamp": "2026-02-15T03:20:10+00:00",
"user_id": "user-001",
"count": 2,
"items": [
{
"id": 1,
"action": "query",
"request": {"query": "如何重置密码？"},
"response": {
"answer": "...",
"results": [
{
"filename": "account_guide.md",
"similarity": 0.91,
"text": "命中分片全文...",
"preview_text": "命中分片预览..."
}
]
}
}
]
}
]
}4.2 清空历史
DELETE/history
data 示例：
{
"ok": true,
"removed": 12
}4.3 删除单条历史
DELETE/history/{id}
data 示例：
{
"ok": true,
"removed": 1
}4.4 删除整个会话
DELETE/session/{session_id}
data 示例：
{
"ok": true,
"removed": 1
}5. 模型配置管理
以下接口依赖数据库后端；若未启用数据库，接口会返回不可用提示。
5.1 获取 Provider 列表
GET/model/providers
data 示例：
{
"ok": true,
"providers": [
{"name": "lm_studio", "base_url": "http://localhost:1234/v1", "requires_api_key": false},
{"name": "openai", "base_url": "https://api.openai.com/v1", "requires_api_key": true}
]
}5.2 查询配置列表
GET/model/configs
参数（query string）：
provider、is_active、model_type（均可选）5.3 新增配置
POST/model/config
必填字段：
name、provider、base_url、model_name5.4 查询单个配置
GET/model/config/{id_or_name}
5.5 更新配置
PUT/model/config/{id}
5.6 删除配置
DELETE/model/config/{id}
5.7 默认配置
GET/model/config/default
POST/model/config/{id}/default
5.8 测试配置与初始化预设
POST/model/config/test
POST/model/config/bootstrap
6. 前端与文档路由
GET /或GET /ui：前端页面GET /ui/app.css、GET /ui/app.js：前端静态资源GET /assets/*：图片等静态资源GET /api-docs或GET /docs：接口文档