docs(api): enhance agent and knowledge base documentation

This commit is contained in:
wizardchen
2026-04-02 19:28:23 +08:00
committed by lyingbug
parent 624e24ba49
commit d3c4992e01
6 changed files with 545 additions and 262 deletions
+176 -213
View File
@@ -9,11 +9,13 @@
| GET | `/sessions` | 获取租户的会话列表 |
| PUT | `/sessions/:id` | 更新会话 |
| DELETE | `/sessions/:id` | 删除会话 |
| DELETE | `/sessions/:id/messages` | 清空会话消息 |
| DELETE | `/sessions/batch` | 批量删除会话 |
| POST | `/sessions/:session_id/generate_title` | 生成会话标题 |
| POST | `/sessions/:session_id/stop` | 停止会话 |
| GET | `/sessions/continue-stream/:session_id` | 继续未完成的会话 |
| POST | `/sessions/:session_id/stop` | 停止生成 |
| GET | `/sessions/continue-stream/:session_id` | 继续未完成的流式响应 |
> **说明**:会话(Session)是纯粹的对话容器,仅存储基础信息(标题、描述)。所有与知识库、模型、检索策略相关的配置均在查询时由 Custom Agent 提供,不再存储在会话中。
## POST `/sessions` - 创建会话
@@ -21,83 +23,35 @@
```curl
curl --location 'http://localhost:8080/api/v1/sessions' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"knowledge_base_id": "kb-00000001",
"session_strategy": {
"max_rounds": 5,
"enable_rewrite": true,
"fallback_strategy": "FIXED_RESPONSE",
"fallback_response": "对不起,我无法回答这个问题",
"embedding_top_k": 10,
"keyword_threshold": 0.5,
"vector_threshold": 0.7,
"rerank_model_id": "排序模型ID",
"rerank_top_k": 3,
"rerank_threshold": 0.7,
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"summary_parameters": {
"max_tokens": 0,
"repeat_penalty": 1,
"top_k": 0,
"top_p": 0,
"frequency_penalty": 0,
"presence_penalty": 0,
"prompt": "这是用户和助手之间的对话。xxx",
"context_template": "你是一个专业的智能信息检索助手xxx",
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
"temperature": 0.3,
"seed": 0,
"max_completion_tokens": 2048
},
"no_match_prefix": "<think>\n</think>\nNO_MATCH"
}
"title": "我的新对话",
"description": "关于 AI 的讨论"
}'
```
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------- | ------ | ---- | ---------- |
| `title` | string | 否 | 会话标题 |
| `description` | string | 否 | 会话描述 |
**响应**:
```json
{
"success": true,
"data": {
"id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f",
"title": "",
"description": "",
"title": "我的新对话",
"description": "关于 AI 的讨论",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"max_rounds": 5,
"enable_rewrite": true,
"fallback_strategy": "FIXED_RESPONSE",
"fallback_response": "对不起,我无法回答这个问题",
"embedding_top_k": 10,
"keyword_threshold": 0.5,
"vector_threshold": 0.7,
"rerank_model_id": "排序模型ID",
"rerank_top_k": 3,
"rerank_threshold": 0.7,
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"summary_parameters": {
"max_tokens": 0,
"repeat_penalty": 1,
"top_k": 0,
"top_p": 0,
"frequency_penalty": 0,
"presence_penalty": 0,
"prompt": "这是用户和助手之间的对话。xxx",
"context_template": "你是一个专业的智能信息检索助手xxx",
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
"temperature": 0.3,
"seed": 0,
"max_completion_tokens": 2048
},
"agent_config": null,
"context_config": null,
"created_at": "2025-08-12T12:26:19.611616669+08:00",
"updated_at": "2025-08-12T12:26:19.611616919+08:00",
"created_at": "2026-03-27T12:26:19.611616+08:00",
"updated_at": "2026-03-27T12:26:19.611616+08:00",
"deleted_at": null
},
"success": true
}
}
```
@@ -107,52 +61,30 @@ curl --location 'http://localhost:8080/api/v1/sessions' \
```curl
curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------ |
| `id` | string | 是 | 会话ID |
**响应**:
```json
{
"success": true,
"data": {
"id": "ceb9babb-1e30-41d7-817d-fd584954304b",
"title": "模型优化策略",
"description": "",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"max_rounds": 5,
"enable_rewrite": true,
"fallback_strategy": "fixed",
"fallback_response": "抱歉,我无法回答这个问题。",
"embedding_top_k": 10,
"keyword_threshold": 0.3,
"vector_threshold": 0.5,
"rerank_model_id": "",
"rerank_top_k": 5,
"rerank_threshold": 0.7,
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"summary_parameters": {
"max_tokens": 0,
"repeat_penalty": 1,
"top_k": 0,
"top_p": 0,
"frequency_penalty": 0,
"presence_penalty": 0,
"prompt": "这是用户和助手之间的对话",
"context_template": "你是一个专业的智能信息检索助手",
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
"temperature": 0.3,
"seed": 0,
"max_completion_tokens": 2048
},
"agent_config": null,
"context_config": null,
"created_at": "2025-08-12T10:24:38.308596+08:00",
"updated_at": "2025-08-12T10:25:41.317761+08:00",
"created_at": "2026-03-27T10:24:38.308596+08:00",
"updated_at": "2026-03-27T10:25:41.317761+08:00",
"deleted_at": null
},
"success": true
}
}
```
@@ -161,56 +93,37 @@ curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-f
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions?page=1&page_size=1' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
curl --location 'http://localhost:8080/api/v1/sessions?page=1&page_size=10' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**查询参数**:
| 字段 | 类型 | 必填 | 描述 |
| ----------- | ---- | ---- | -------------------- |
| `page` | int | 否 | 页码(默认 1) |
| `page_size` | int | 否 | 每页数量(默认 10) |
**响应**:
```json
{
"success": true,
"data": [
{
"id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f",
"title": "",
"title": "我的新对话",
"description": "",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"max_rounds": 5,
"enable_rewrite": true,
"fallback_strategy": "FIXED_RESPONSE",
"fallback_response": "对不起,我无法回答这个问题",
"embedding_top_k": 10,
"keyword_threshold": 0.5,
"vector_threshold": 0.7,
"rerank_model_id": "排序模型ID",
"rerank_top_k": 3,
"rerank_threshold": 0.7,
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"summary_parameters": {
"max_tokens": 0,
"repeat_penalty": 1,
"top_k": 0,
"top_p": 0,
"frequency_penalty": 0,
"presence_penalty": 0,
"prompt": "这是用户和助手之间的对话。xxx",
"context_template": "你是一个专业的智能信息检索助手xxx",
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
"temperature": 0.3,
"seed": 0,
"max_completion_tokens": 2048
},
"created_at": "2025-08-12T12:26:19.611616+08:00",
"updated_at": "2025-08-12T12:26:19.611616+08:00",
"created_at": "2026-03-27T12:26:19.611616+08:00",
"updated_at": "2026-03-27T12:26:19.611616+08:00",
"deleted_at": null
}
],
"total": 1,
"page": 1,
"page_size": 1,
"success": true,
"total": 2
"page_size": 10
}
```
@@ -220,80 +133,41 @@ curl --location 'http://localhost:8080/api/v1/sessions?page=1&page_size=1' \
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/sessions/411d6b70-9a85-4d03-bb74-aab0fd8bd12f' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"title": "weknora",
"description": "weknora description",
"knowledge_base_id": "kb-00000001",
"max_rounds": 5,
"enable_rewrite": true,
"fallback_strategy": "FIXED_RESPONSE",
"fallback_response": "对不起,我无法回答这个问题",
"embedding_top_k": 10,
"keyword_threshold": 0.5,
"vector_threshold": 0.7,
"rerank_model_id": "排序模型ID",
"rerank_top_k": 3,
"rerank_threshold": 0.7,
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"summary_parameters": {
"max_tokens": 0,
"repeat_penalty": 1,
"top_k": 0,
"top_p": 0,
"frequency_penalty": 0,
"presence_penalty": 0,
"prompt": "这是用户和助手之间的对话。xxx",
"context_template": "你是一个专业的智能信息检索助手xxx",
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
"temperature": 0.3,
"seed": 0,
"max_completion_tokens": 2048
}
"title": "WeKnora 技术讨论",
"description": "关于 WeKnora 架构的讨论"
}'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------ |
| `id` | string | 是 | 会话ID |
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------- | ------ | ---- | -------- |
| `title` | string | 否 | 会话标题 |
| `description` | string | 否 | 会话描述 |
**响应**:
```json
{
"success": true,
"data": {
"id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f",
"title": "weknora",
"description": "weknora description",
"title": "WeKnora 技术讨论",
"description": "关于 WeKnora 架构的讨论",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"max_rounds": 5,
"enable_rewrite": true,
"fallback_strategy": "FIXED_RESPONSE",
"fallback_response": "对不起,我无法回答这个问题",
"embedding_top_k": 10,
"keyword_threshold": 0.5,
"vector_threshold": 0.7,
"rerank_model_id": "排序模型ID",
"rerank_top_k": 3,
"rerank_threshold": 0.7,
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"summary_parameters": {
"max_tokens": 0,
"repeat_penalty": 1,
"top_k": 0,
"top_p": 0,
"frequency_penalty": 0,
"presence_penalty": 0,
"prompt": "这是用户和助手之间的对话。xxx",
"context_template": "你是一个专业的智能信息检索助手xxx",
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
"temperature": 0.3,
"seed": 0,
"max_completion_tokens": 2048
},
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "2025-08-12T14:20:56.738424351+08:00",
"created_at": "2026-03-27T12:26:19.611616+08:00",
"updated_at": "2026-03-27T14:20:56.738424+08:00",
"deleted_at": null
},
"success": true
}
}
```
@@ -303,26 +177,61 @@ curl --location --request PUT 'http://localhost:8080/api/v1/sessions/411d6b70-9a
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/411d6b70-9a85-4d03-bb74-aab0fd8bd12f' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------ |
| `id` | string | 是 | 会话ID |
**响应**:
```json
{
"message": "Session deleted successfully",
"success": true
"success": true,
"message": "Session deleted successfully"
}
```
## DELETE `/sessions/:id/messages` - 清空会话消息
删除会话中的所有消息,同时清除 LLM 上下文和聊天历史知识库条目。会话本身保留。
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/messages' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------ |
| `id` | string | 是 | 会话ID |
**响应**:
```json
{
"success": true,
"message": "Session messages cleared successfully"
}
```
## DELETE `/sessions/batch` - 批量删除会话
**请求**:
支持两种模式:按 ID 列表批量删除,或删除当前租户的所有会话。
**请求 - 按 ID 列表删除**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/batch' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"ids": [
@@ -332,22 +241,42 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/batch' \
}'
```
**请求 - 删除所有会话**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/batch' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"delete_all": true
}'
```
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | -------- | ---- | -------------------------------------------------------- |
| `ids` | string[] | 否 | 要删除的会话 ID 列表(`delete_all` 为 false 时必填) |
| `delete_all` | bool | 否 | 设为 `true` 时删除当前租户的所有会话,忽略 `ids` 字段 |
**响应**:
```json
{
"message": "Sessions deleted successfully",
"success": true
"success": true,
"message": "Sessions deleted successfully"
}
```
## POST `/sessions/:session_id/generate_title` - 生成会话标题
根据消息内容自动生成会话标题。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/generate_title' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"messages": [
@@ -363,47 +292,81 @@ curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-f
}'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------ |
| `session_id` | string | 是 | 会话ID |
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---------- | --------- | ---- | ---------------------------- |
| `messages` | Message[] | 是 | 用作标题生成上下文的消息列表 |
**响应**:
```json
{
"data": "模型优化策略",
"success": true
"success": true,
"data": "人工智能基础知识"
}
```
## POST `/sessions/:session_id/stop` - 停止会话
## POST `/sessions/:session_id/stop` - 停止生成
停止当前正在进行的生成任务。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions/7c966c74-610e-4516-8d5b-05e14b2e4ee0/stop' \
--header 'X-API-Key: sk-An-W8T4tdZDbWKJgfwgdea5rS8ue_mRhCTZ8Smhnvku-bWEE' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{"message_id":"ebbf7e53-dfe6-44d5-882f-36a4104910b5"}'
--data '{
"message_id": "ebbf7e53-dfe6-44d5-882f-36a4104910b5"
}'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------ |
| `session_id` | string | 是 | 会话ID |
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------------------------ |
| `message_id` | string | 是 | 要停止生成的助手消息 ID |
**响应**:
```json
{
"message": "Session stopped successfully",
"success": true
"success": true,
"message": "Generation stopped"
}
```
## GET `/sessions/continue-stream/:session_id` - 继续未完成的会话
## GET `/sessions/continue-stream/:session_id` - 继续未完成的流式响应
重新连接正在进行的流式响应,先回放已有事件,再继续接收新事件。
**查询参数**:
- `message_id`: 从 `/messages/:session_id/load` 接口中获取的 `is_completed` 为 `false` 的消息 ID
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------------------------------------------------------------------------- |
| `message_id` | string | 是 | 从 `/messages/:session_id/load` 接口中获取的 `is_completed` 为 `false` 的消息 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions/continue-stream/ceb9babb-1e30-41d7-817d-fd584954304b?message_id=b8b90eeb-7dd5-4cf9-81c6-5ebcbd759451' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应格式**:
服务器端事件流(Server-Sent Events),与 `/knowledge-chat/:session_id` 返回结果一致
服务器端事件流(Server-Sent Events),与 `/knowledge-chat/:session_id` 返回结果一致。