mirror of
https://github.com/Tencent/WeKnora.git
synced 2026-09-19 10:28:49 +08:00
nullkey
1c7171b2c6
Refs #890 #1049 #1168. 按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go 对齐。每个端点新增参数说明小节（path/query/body 字段含义）和响应字段 含义说明（#1168 的核心诉求）。 【与代码对齐】 - 删除已下线端点：system.md 中的 /system/minio/buckets（代码中已无对 应路由）。 - 修正路径错误：chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id； /chunks/:id/delete-question → /chunks/by-id/:id/questions； organization.md 中 /organizations/preview/:invite_code → :code。 - 修正字段类型：faq tag_id / entry_id 由 string 改为 int64； knowledge.search 响应结构纠正。 - 补齐缺失端点（move-targets、batch-delete、move/progress、pin/unpin/ stop/continue-stream、tool-approvals、organization agent-shares 等 30+ 条）。 【精简】 - knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例 收敛为指向首次出现（"字段结构同 POST /xxx 响应"），节省约 400 行 而不损失信息（仅去重，原作者写的每个字段定义都保留可达）。 - 示例 X-API-Key 统一为 sk-xxxxx（避免读者复制看似真实的 key）。 【清理】 - 删除内部实现细节引用：mcp-service.md 中 6 处 "issue #1173"、 organization.md 中 "RegisterOrganizationRoutes" 等。 不动 initialization.md：其中端点（KB 配置、模型连通性测试、Ollama 管理） 对集成方有实用价值，保留原作者写好的内容不删。 格式统一遵循 web-search.md 重写后的范式（路由表 + 每端点方法/路径 + 参数表 + curl + 响应 JSON + 字段说明）。
267 lines
9.7 KiB
Markdown
267 lines
9.7 KiB
Markdown
# 消息管理 API
|
||
|
||
[返回目录](./README.md)
|
||
|
||
| 方法 | 路径 | 描述 |
|
||
| ------ | ---------------------------- | ------------------------ |
|
||
| GET | `/messages/:session_id/load` | 获取最近的会话消息列表 |
|
||
| DELETE | `/messages/:session_id/:id` | 删除消息 |
|
||
| POST | `/messages/search` | 搜索历史对话 |
|
||
| GET | `/messages/chat-history-stats` | 获取聊天历史知识库统计 |
|
||
|
||
## GET `/messages/:session_id/load` - 获取最近的会话消息列表
|
||
|
||
**查询参数**:
|
||
|
||
- `before_time`: 上一次拉取的最早一条消息的 created_at 字段，为空拉取最近的消息
|
||
- `limit`: 每页条数(默认 20)
|
||
|
||
**请求**:
|
||
|
||
```curl
|
||
curl --location --request GET 'http://localhost:8080/api/v1/messages/ceb9babb-1e30-41d7-817d-fd584954304b/load?limit=3&before_time=2030-08-12T14%3A35%3A42.123456789Z' \
|
||
--header 'X-API-Key: sk-xxxxx' \
|
||
--header 'Content-Type: application/json' \
|
||
--data '{
|
||
"query": "彗尾的形状"
|
||
}'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "b8b90eeb-7dd5-4cf9-81c6-5ebcbd759451",
|
||
"session_id": "ceb9babb-1e30-41d7-817d-fd584954304b",
|
||
"request_id": "hCA8SDjxcAvv",
|
||
"content": "<think>\n好的",
|
||
"role": "assistant",
|
||
"knowledge_references": [
|
||
{
|
||
"id": "c8347bef-127f-4a22-b962-edf5a75386ec",
|
||
"content": "彗星xxx",
|
||
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
|
||
"chunk_index": 0,
|
||
"knowledge_title": "彗星.txt",
|
||
"start_at": 0,
|
||
"end_at": 2760,
|
||
"seq": 0,
|
||
"score": 4.038836479187012,
|
||
"match_type": 4,
|
||
"sub_chunk_id": [
|
||
"688821f0-40bf-428e-8cb6-541531ebeb76",
|
||
"c1e9903e-2b4d-4281-be15-0149288d45c2",
|
||
"7d955251-3f79-4fd5-a6aa-02f81e044091"
|
||
],
|
||
"metadata": {},
|
||
"chunk_type": "text",
|
||
"parent_chunk_id": "",
|
||
"image_info": "",
|
||
"knowledge_filename": "彗星.txt",
|
||
"knowledge_source": ""
|
||
},
|
||
{
|
||
"id": "fa3aadee-cadb-4a84-9941-c839edc3e626",
|
||
"content": "# 文档名称\n彗星.txt\n\n# 摘要\n彗星是由冰和尘埃构成的太阳系小天体，接近太阳时会释放气体形成彗发和彗尾。其轨道周期差异大，来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊，部分彗星已失去挥发物质，类似小行星。目前已知彗星数量众多，且存在系外彗星。彗星在古代被视为凶兆，现代研究揭示其复杂结构与起源。",
|
||
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
|
||
"chunk_index": 6,
|
||
"knowledge_title": "彗星.txt",
|
||
"start_at": 0,
|
||
"end_at": 0,
|
||
"seq": 6,
|
||
"score": 0.6131043121858466,
|
||
"match_type": 0,
|
||
"sub_chunk_id": null,
|
||
"metadata": {},
|
||
"chunk_type": "summary",
|
||
"parent_chunk_id": "c8347bef-127f-4a22-b962-edf5a75386ec",
|
||
"image_info": "",
|
||
"knowledge_filename": "彗星.txt",
|
||
"knowledge_source": ""
|
||
}
|
||
],
|
||
"agent_steps": [],
|
||
"is_completed": true,
|
||
"is_fallback": false,
|
||
"agent_duration_ms": 2500,
|
||
"channel": "web",
|
||
"created_at": "2025-08-12T10:24:38.370548+08:00",
|
||
"updated_at": "2025-08-12T10:25:40.416382+08:00",
|
||
"deleted_at": null
|
||
},
|
||
{
|
||
"id": "7fa136ae-a045-424e-baac-52113d92ae94",
|
||
"session_id": "ceb9babb-1e30-41d7-817d-fd584954304b",
|
||
"request_id": "3475c004-0ada-4306-9d30-d7f5efce50d2",
|
||
"content": "彗尾的形状",
|
||
"role": "user",
|
||
"knowledge_references": [],
|
||
"agent_steps": [],
|
||
"is_completed": true,
|
||
"mentioned_items": [],
|
||
"images": [],
|
||
"channel": "web",
|
||
"created_at": "2025-08-12T14:30:39.732246+08:00",
|
||
"updated_at": "2025-08-12T14:30:39.733277+08:00",
|
||
"deleted_at": null
|
||
},
|
||
{
|
||
"id": "9bcafbcf-a758-40af-a9a3-c4d8e0f49439",
|
||
"session_id": "ceb9babb-1e30-41d7-817d-fd584954304b",
|
||
"request_id": "3475c004-0ada-4306-9d30-d7f5efce50d2",
|
||
"content": "<think>\n好的",
|
||
"role": "assistant",
|
||
"knowledge_references": [
|
||
{
|
||
"id": "c8347bef-127f-4a22-b962-edf5a75386ec",
|
||
"content": "彗星xxx",
|
||
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
|
||
"chunk_index": 0,
|
||
"knowledge_title": "彗星.txt",
|
||
"start_at": 0,
|
||
"end_at": 2760,
|
||
"seq": 0,
|
||
"score": 4.038836479187012,
|
||
"match_type": 3,
|
||
"sub_chunk_id": [
|
||
"688821f0-40bf-428e-8cb6-541531ebeb76",
|
||
"c1e9903e-2b4d-4281-be15-0149288d45c2",
|
||
"7d955251-3f79-4fd5-a6aa-02f81e044091"
|
||
],
|
||
"metadata": {},
|
||
"chunk_type": "text",
|
||
"parent_chunk_id": "",
|
||
"image_info": "",
|
||
"knowledge_filename": "彗星.txt",
|
||
"knowledge_source": ""
|
||
},
|
||
{
|
||
"id": "fa3aadee-cadb-4a84-9941-c839edc3e626",
|
||
"content": "# 文档名称\n彗星.txt\n\n# 摘要\n彗星是由冰和尘埃构成的太阳系小天体，接近太阳时会释放气体形成彗发和彗尾。其轨道周期差异大，来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊，部分彗星已失去挥发物质，类似小行星。目前已知彗星数量众多，且存在系外彗星。彗星在古代被视为凶兆，现代研究揭示其复杂结构与起源。",
|
||
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
|
||
"chunk_index": 6,
|
||
"knowledge_title": "彗星.txt",
|
||
"start_at": 0,
|
||
"end_at": 0,
|
||
"seq": 6,
|
||
"score": 0.6131043121858466,
|
||
"match_type": 3,
|
||
"sub_chunk_id": null,
|
||
"metadata": {},
|
||
"chunk_type": "summary",
|
||
"parent_chunk_id": "c8347bef-127f-4a22-b962-edf5a75386ec",
|
||
"image_info": "",
|
||
"knowledge_filename": "彗星.txt",
|
||
"knowledge_source": ""
|
||
}
|
||
],
|
||
"agent_steps": [],
|
||
"is_completed": true,
|
||
"is_fallback": false,
|
||
"agent_duration_ms": 2500,
|
||
"channel": "web",
|
||
"created_at": "2025-08-12T14:30:39.735108+08:00",
|
||
"updated_at": "2025-08-12T14:31:17.829926+08:00",
|
||
"deleted_at": null
|
||
}
|
||
],
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
## DELETE `/messages/:session_id/:id` - 删除消息
|
||
|
||
**请求**:
|
||
|
||
```curl
|
||
curl --location --request DELETE 'http://localhost:8080/api/v1/messages/ceb9babb-1e30-41d7-817d-fd584954304b/9bcafbcf-a758-40af-a9a3-c4d8e0f49439' \
|
||
--header 'X-API-Key: sk-xxxxx' \
|
||
--header 'Content-Type: application/json'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"message": "Message deleted successfully",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
## POST `/messages/search` - 搜索历史对话
|
||
|
||
搜索历史对话消息，支持混合搜索、关键词搜索和向量搜索模式。
|
||
|
||
**请求参数**:
|
||
- `query`: 搜索关键词（必填）
|
||
- `mode`: 搜索模式，可选 `hybrid`、`keyword`、`vector`（可选，默认 `hybrid`）
|
||
- `limit`: 返回结果数量（可选，默认 20）
|
||
- `session_ids`: 限定搜索的会话ID列表（可选）
|
||
|
||
**请求**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/messages/search' \
|
||
--header 'X-API-Key: sk-xxxxx' \
|
||
--header 'Content-Type: application/json' \
|
||
--data '{
|
||
"query": "彗星的结构",
|
||
"mode": "hybrid",
|
||
"limit": 20,
|
||
"session_ids": []
|
||
}'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"request_id": "3475c004-0ada-4306-9d30-d7f5efce50d2",
|
||
"session_id": "ceb9babb-1e30-41d7-817d-fd584954304b",
|
||
"session_title": "彗星知识问答",
|
||
"query_content": "彗尾的形状",
|
||
"answer_content": "彗尾的形状主要取决于...",
|
||
"score": 0.85,
|
||
"match_type": "hybrid",
|
||
"created_at": "2025-08-12T14:30:39.732246+08:00"
|
||
}
|
||
],
|
||
"total": 1
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
## GET `/messages/chat-history-stats` - 获取聊天历史知识库统计
|
||
|
||
获取当前租户的聊天历史知识库索引统计信息。
|
||
|
||
**请求**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/messages/chat-history-stats' \
|
||
--header 'X-API-Key: sk-xxxxx' \
|
||
--header 'Content-Type: application/json'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"enabled": true,
|
||
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
|
||
"knowledge_base_id": "kb-chat-00000001",
|
||
"knowledge_base_name": "聊天历史知识库",
|
||
"indexed_message_count": 1024,
|
||
"has_indexed_messages": true
|
||
},
|
||
"success": true
|
||
}
|
||
```
|