diff --git a/docs/api/agent.md b/docs/api/agent.md index 45315c44..02640f58 100644 --- a/docs/api/agent.md +++ b/docs/api/agent.md @@ -418,7 +418,9 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \ |------|------|--------|------| | `agent_mode` | string | - | 智能体模式:`quick-answer`(RAG)或 `smart-reasoning`(ReAct) | | `system_prompt` | string | - | 系统提示词,支持使用占位符 | +| `system_prompt_id` | string | - | 系统提示词模板 ID(引用 `prompt_templates/` YAML 文件中的模板) | | `context_template` | string | - | 上下文模板(仅 quick-answer 模式使用) | +| `context_template_id` | string | - | 上下文模板 ID(引用 `prompt_templates/` YAML 文件中的模板) | ### 模型设置 @@ -428,6 +430,7 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \ | `rerank_model_id` | string | - | 重排序模型 ID | | `temperature` | float | 0.7 | 温度参数(0-1) | | `max_completion_tokens` | int | 2048 | 最大生成 token 数 | +| `thinking` | *bool | nil | 是否启用思考模式(适用于支持扩展思考的模型) | ### Agent 模式设置 @@ -435,9 +438,10 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \ |------|------|--------|------| | `max_iterations` | int | 10 | ReAct 最大迭代次数 | | `allowed_tools` | []string | - | 允许使用的工具列表 | -| `reflection_enabled` | bool | false | 是否启用反思 | | `mcp_selection_mode` | string | - | MCP 服务选择模式:`all`/`selected`/`none` | | `mcp_services` | []string | - | 选中的 MCP 服务 ID 列表 | +| `skills_selection_mode` | string | - | Skills 选择模式:`all`/`selected`/`none` | +| `selected_skills` | []string | - | 选中的 Skill 名称列表(mode 为 `selected` 时) | ### 知识库设置 @@ -445,8 +449,17 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \ |------|------|--------|------| | `kb_selection_mode` | string | - | 知识库选择模式:`all`/`selected`/`none` | | `knowledge_bases` | []string | - | 关联的知识库 ID 列表 | +| `retrieve_kb_only_when_mentioned` | bool | false | 仅在用户通过 @ 显式提及时才检索知识库 | | `supported_file_types` | []string | - | 支持的文件类型(如 `["csv", "xlsx"]`) | +### 图片上传 / 多模态设置 + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `image_upload_enabled` | bool | false | 是否允许上传图片 | +| `vlm_model_id` | string | - | 图片分析所用的 VLM 模型 ID | +| `image_storage_provider` | string | - | 图片存储提供者:`local`/`minio`/`cos`/`tos`,为空使用全局默认 | + ### FAQ 策略设置 | 参数 | 类型 | 默认值 | 说明 | @@ -461,6 +474,9 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \ |------|------|--------|------| | `web_search_enabled` | bool | true | 是否启用网络搜索 | | `web_search_max_results` | int | 5 | 网络搜索最大结果数 | +| `web_search_provider_id` | string | - | 网络搜索提供者 ID,为空使用租户默认提供者 | +| `web_fetch_enabled` | bool | false | 是否自动获取重排后的搜索结果页面全文 | +| `web_fetch_top_n` | int | 3 | 重排后获取全文的最大页面数 | ### 多轮对话设置 @@ -479,6 +495,12 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \ | `rerank_top_k` | int | 5 | 重排序 TopK | | `rerank_threshold` | float | 0.5 | 重排序阈值 | +### 推荐问题设置 + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `suggested_prompts` | []string | - | 推荐问题列表,用于在前端对话面板展示快捷提问 | + ### 高级设置 | 参数 | 类型 | 默认值 | 说明 | @@ -487,7 +509,7 @@ curl --location 'http://localhost:8080/api/v1/agents/placeholders' \ | `enable_rewrite` | bool | true | 是否启用多轮对话查询改写 | | `rewrite_prompt_system` | string | - | 改写系统提示词 | | `rewrite_prompt_user` | string | - | 改写用户提示词模板 | -| `fallback_strategy` | string | model | 回退策略:`fixed`(固定回复)或 `model`(模型生成) | +| `fallback_strategy` | string | `model` | 回退策略:`fixed`(固定回复)或 `model`(模型生成);未设置时在服务端默认为 `model` | | `fallback_response` | string | - | 固定回退回复(`fallback_strategy` 为 `fixed` 时使用) | | `fallback_prompt` | string | - | 回退提示词(`fallback_strategy` 为 `model` 时使用) | diff --git a/docs/api/chat.md b/docs/api/chat.md index 4c909627..c334c3d6 100644 --- a/docs/api/chat.md +++ b/docs/api/chat.md @@ -10,14 +10,33 @@ ## POST `/knowledge-chat/:session_id` - 基于知识库的问答 +基于知识库的 RAG 问答,支持 SSE 流式响应。 + +**请求参数**: + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `query` | string | 是 | 查询文本 | +| `knowledge_base_ids` | string[] | 否 | 知识库 ID 列表 | +| `knowledge_ids` | string[] | 否 | 知识文件 ID 列表,指定具体文件进行检索 | +| `agent_id` | string | 否 | 自定义 Agent ID,指定使用的智能体 | +| `summary_model_id` | string | 否 | 覆盖默认的摘要模型 ID | +| `mentioned_items` | object[] | 否 | @提及的知识库和文件列表 | +| `disable_title` | bool | 否 | 是否禁用自动标题生成(默认 false) | +| `enable_memory` | bool | 否 | 是否启用记忆功能 | +| `images` | object[] | 否 | 附带的图片(base64 格式),需要 Agent 启用图片上传 | +| `channel` | string | 否 | 来源渠道标识:`web`、`api`、`im`、`browser_extension` | + **请求**: ```curl curl --location 'http://localhost:8080/api/v1/knowledge-chat/ceb9babb-1e30-41d7-817d-fd584954304b' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ +--header 'X-API-Key: sk-xxxxx' \ --header 'Content-Type: application/json' \ --data '{ - "query": "彗尾的形状" + "query": "彗尾的形状", + "knowledge_base_ids": ["kb-00000001"], + "agent_id": "builtin-quick-answer" }' ``` @@ -28,16 +47,10 @@ curl --location 'http://localhost:8080/api/v1/knowledge-chat/ceb9babb-1e30-41d7- ``` event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"references","content":"","done":false,"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":""}]} +data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"references","content":"","done":false,"knowledge_references":[{"id":"c8347bef-...","content":"彗星xxx。","knowledge_id":"a6790b93-...","chunk_index":0,"knowledge_title":"彗星.txt","score":4.04,"match_type":3,"chunk_type":"text","knowledge_filename":"彗星.txt"}]} event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"表现为","done":false,"knowledge_references":null} - -event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"结构","done":false,"knowledge_references":null} - -event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"。","done":false,"knowledge_references":null} +data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"彗尾的形状主要表现为...","done":false,"knowledge_references":null} event: message data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"","done":true,"knowledge_references":null} @@ -48,29 +61,49 @@ data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","con Agent 模式支持更智能的问答,包括工具调用、网络搜索、多知识库检索等能力。 **请求参数**: -- `query`: 查询文本(必填) -- `knowledge_base_ids`: 知识库 ID 数组,可动态指定本次查询使用的知识库(可选) -- `knowledge_ids`: 知识文件 ID 数组,可动态指定本次查询使用的具体知识文件(可选) -- `agent_enabled`: 是否启用 Agent 模式(可选,默认 false) -- `agent_id`: 自定义 Agent ID,指定使用的自定义智能体(可选) -- `web_search_enabled`: 是否启用网络搜索(可选,默认 false) -- `summary_model_id`: 覆盖会话默认的摘要模型 ID(可选) -- `mentioned_items`: @提及的知识库和文件列表(可选) -- `disable_title`: 是否禁用自动标题生成(可选,默认 false) -- `mcp_service_ids`: MCP 服务白名单(可选,已废弃) + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `query` | string | 是 | 查询文本 | +| `knowledge_base_ids` | string[] | 否 | 知识库 ID 列表,可动态指定本次查询使用的知识库 | +| `knowledge_ids` | string[] | 否 | 知识文件 ID 列表,可动态指定本次查询使用的具体文件 | +| `agent_enabled` | bool | 否 | 是否启用 Agent 模式(默认 false,优先使用 Agent 配置) | +| `agent_id` | string | 否 | 自定义 Agent ID,指定使用的智能体(支持共享 Agent) | +| `web_search_enabled` | bool | 否 | 是否启用网络搜索(默认 false) | +| `summary_model_id` | string | 否 | 覆盖默认的摘要模型 ID | +| `mentioned_items` | object[] | 否 | @提及的知识库和文件列表 | +| `disable_title` | bool | 否 | 是否禁用自动标题生成(默认 false) | +| `enable_memory` | bool | 否 | 是否启用记忆功能 | +| `images` | object[] | 否 | 附带的图片(base64 格式),需要 Agent 启用图片上传 | +| `channel` | string | 否 | 来源渠道标识:`web`、`api`、`im`、`browser_extension` | + +**mentioned_items 结构**: + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | string | 知识库或文件 ID | +| `name` | string | 显示名称 | +| `type` | string | 类型:`kb`(知识库)或 `file`(文件) | +| `kb_type` | string | 知识库类型:`document` 或 `faq`(仅 `type=kb` 时) | + +**images 结构**: + +| 字段 | 类型 | 说明 | +|------|------|------| +| `data` | string | base64 编码的图片数据(`data:image/png;base64,...`) | **请求**: ```curl curl --location 'http://localhost:8080/api/v1/agent-chat/ceb9babb-1e30-41d7-817d-fd584954304b' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ +--header 'X-API-Key: sk-xxxxx' \ --header 'Content-Type: application/json' \ --data '{ "query": "帮我查询今天的天气", "agent_enabled": true, "web_search_enabled": true, "knowledge_base_ids": ["kb-00000001"], - "agent_id": "agent-001", + "agent_id": "builtin-smart-reasoning", "mentioned_items": [ { "id": "kb-00000001", @@ -89,29 +122,31 @@ curl --location 'http://localhost:8080/api/v1/agent-chat/ceb9babb-1e30-41d7-817d | response_type | 描述 | |---------------|------| +| `agent_query` | Agent 开始处理查询 | | `thinking` | Agent 思考过程 | | `tool_call` | 工具调用信息 | | `tool_result` | 工具调用结果 | | `references` | 知识库检索引用 | | `answer` | 最终回答内容 | | `reflection` | Agent 反思内容 | +| `session_title` | 自动生成的会话标题 | | `error` | 错误信息 | **响应示例**: ``` event: message -data: {"id":"agent-001","response_type":"thinking","content":"用户想查询天气,我需要使用网络搜索工具...","done":false,"knowledge_references":null} +data: {"id":"req-001","response_type":"thinking","content":"用户想查询天气,我需要使用网络搜索工具...","done":false} event: message -data: {"id":"agent-001","response_type":"tool_call","content":"","done":false,"knowledge_references":null,"data":{"tool_name":"web_search","arguments":{"query":"今天天气"}}} +data: {"id":"req-001","response_type":"tool_call","content":"","done":false,"data":{"tool_name":"web_search","arguments":{"query":"今天天气"}}} event: message -data: {"id":"agent-001","response_type":"tool_result","content":"搜索结果:今天晴,气温25°C...","done":false,"knowledge_references":null} +data: {"id":"req-001","response_type":"tool_result","content":"搜索结果:今天晴,气温25°C...","done":false} event: message -data: {"id":"agent-001","response_type":"answer","content":"根据查询结果,今天天气晴朗,气温约25°C。","done":false,"knowledge_references":null} +data: {"id":"req-001","response_type":"answer","content":"根据查询结果,今天天气晴朗,气温约25°C。","done":false} event: message -data: {"id":"agent-001","response_type":"answer","content":"","done":true,"knowledge_references":null} +data: {"id":"req-001","response_type":"answer","content":"","done":true} ``` diff --git a/docs/api/knowledge-base.md b/docs/api/knowledge-base.md index 82581b04..ac901a0f 100644 --- a/docs/api/knowledge-base.md +++ b/docs/api/knowledge-base.md @@ -2,6 +2,13 @@ [返回目录](./README.md) +**字段说明(知识库对象)** + +- 知识库类型 `type` 为 `document`(文档)或 `faq`(FAQ),默认 `document`。 +- JSON 中对象存储相关字段:**`storage_config`** 为序列化字段名(对应数据库列 `cos_config`,兼容旧数据)。旧客户端若仍发送或接收 `cos_config`,服务端会兼容解析;新集成请使用 **`storage_config`**。 +- **`storage_provider_config`** 为新版存储提供者选择(如 `{"provider": "local"}`),与租户级存储引擎凭证配合使用;无配置时可为 `null`。 + + | 方法 | 路径 | 描述 | | ------ | ------------------------------------ | ------------------------ | | POST | `/knowledge-bases` | 创建知识库 | @@ -12,7 +19,7 @@ | POST | `/knowledge-bases/copy` | 拷贝知识库 | | GET | `/knowledge-bases/copy/progress/:task_id` | 获取拷贝进度 | | GET | `/knowledge-bases/:id/hybrid-search` | 混合搜索(向量+关键词) | -| POST | `/knowledge-bases/:id/pin` | 置顶/取消置顶知识库 | +| PUT | `/knowledge-bases/:id/pin` | 置顶/取消置顶知识库 | | GET | `/knowledge-bases/:id/move-targets` | 获取可迁移目标知识库列表 | ## POST `/knowledge-bases` - 创建知识库 @@ -26,31 +33,55 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ --data '{ "name": "weknora", "description": "weknora description", + "type": "document", + "is_temporary": false, "chunking_config": { "chunk_size": 1000, "chunk_overlap": 200, "separators": [ "." ], - "enable_multimodal": true + "enable_multimodal": true, + "parser_engine_rules": [ + { + "file_types": [".pdf", ".docx"], + "engine": "builtin" + } + ], + "enable_parent_child": false, + "parent_chunk_size": 4096, + "child_chunk_size": 384 }, "image_processing_config": { "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" }, "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", "vlm_config": { "enabled": true, "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" }, - "cos_config": { + "asr_config": { + "enabled": false, + "model_id": "", + "language": "" + }, + "storage_provider_config": { + "provider": "local" + }, + "storage_config": { "secret_id": "", "secret_key": "", "region": "", "bucket_name": "", "app_id": "", "path_prefix": "" + }, + "extract_config": null, + "faq_config": null, + "question_generation_config": { + "enabled": false, + "question_count": 3 } }' ``` @@ -63,6 +94,8 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ "id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0", "name": "weknora", "description": "weknora description", + "type": "document", + "is_temporary": false, "tenant_id": 1, "chunking_config": { "chunk_size": 1000, @@ -70,19 +103,35 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ "separators": [ "." ], - "enable_multimodal": true + "enable_multimodal": true, + "parser_engine_rules": [ + { + "file_types": [".pdf", ".docx"], + "engine": "builtin" + } + ], + "enable_parent_child": false, + "parent_chunk_size": 4096, + "child_chunk_size": 384 }, "image_processing_config": { "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" }, "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", "vlm_config": { "enabled": true, "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" }, - "cos_config": { + "asr_config": { + "enabled": false, + "model_id": "", + "language": "" + }, + "storage_provider_config": { + "provider": "local" + }, + "storage_config": { "secret_id": "", "secret_key": "", "region": "", @@ -90,6 +139,17 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ "app_id": "", "path_prefix": "" }, + "extract_config": null, + "faq_config": null, + "question_generation_config": { + "enabled": false, + "question_count": 3 + }, + "is_pinned": false, + "pinned_at": null, + "knowledge_count": 0, + "chunk_count": 0, + "processing_count": 0, "created_at": "2025-08-12T11:30:09.206238645+08:00", "updated_at": "2025-08-12T11:30:09.206238854+08:00", "deleted_at": null @@ -117,6 +177,8 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ "id": "kb-00000001", "name": "Default Knowledge Base", "description": "System Default Knowledge Base", + "type": "document", + "is_temporary": false, "tenant_id": 1, "chunking_config": { "chunk_size": 1000, @@ -130,19 +192,30 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ ";", ";" ], - "enable_multimodal": true + "enable_multimodal": true, + "parser_engine_rules": [], + "enable_parent_child": false, + "parent_chunk_size": 4096, + "child_chunk_size": 384 }, "image_processing_config": { "model_id": "" }, "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", "vlm_config": { "enabled": true, "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" }, - "cos_config": { + "asr_config": { + "enabled": false, + "model_id": "", + "language": "" + }, + "storage_provider_config": { + "provider": "local" + }, + "storage_config": { "secret_id": "", "secret_key": "", "region": "", @@ -150,6 +223,14 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ "app_id": "", "path_prefix": "" }, + "extract_config": null, + "faq_config": null, + "question_generation_config": null, + "is_pinned": false, + "pinned_at": null, + "knowledge_count": 12, + "chunk_count": 340, + "processing_count": 0, "created_at": "2025-08-11T20:10:41.817794+08:00", "updated_at": "2025-08-12T11:23:00.593097+08:00", "deleted_at": null @@ -177,6 +258,8 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001' \ "id": "kb-00000001", "name": "Default Knowledge Base", "description": "System Default Knowledge Base", + "type": "document", + "is_temporary": false, "tenant_id": 1, "chunking_config": { "chunk_size": 1000, @@ -190,19 +273,30 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001' \ ";", ";" ], - "enable_multimodal": true + "enable_multimodal": true, + "parser_engine_rules": [], + "enable_parent_child": false, + "parent_chunk_size": 4096, + "child_chunk_size": 384 }, "image_processing_config": { "model_id": "" }, "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", "vlm_config": { "enabled": true, "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" }, - "cos_config": { + "asr_config": { + "enabled": false, + "model_id": "", + "language": "" + }, + "storage_provider_config": { + "provider": "local" + }, + "storage_config": { "secret_id": "", "secret_key": "", "region": "", @@ -210,6 +304,20 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001' \ "app_id": "", "path_prefix": "" }, + "extract_config": { + "enabled": false, + "text": "", + "tags": [], + "nodes": [], + "relations": [] + }, + "faq_config": null, + "question_generation_config": null, + "is_pinned": false, + "pinned_at": null, + "knowledge_count": 12, + "chunk_count": 340, + "processing_count": 0, "created_at": "2025-08-11T20:10:41.817794+08:00", "updated_at": "2025-08-12T11:23:00.593097+08:00", "deleted_at": null @@ -242,7 +350,16 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/b582 ";", ";" ], - "enable_multimodal": true + "enable_multimodal": true, + "parser_engine_rules": [ + { + "file_types": [".md", ".txt"], + "engine": "builtin" + } + ], + "enable_parent_child": true, + "parent_chunk_size": 4096, + "child_chunk_size": 384 }, "image_processing_config": { "model_id": "" @@ -259,6 +376,8 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/b582 "id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0", "name": "weknora new", "description": "weknora description new", + "type": "document", + "is_temporary": false, "tenant_id": 1, "chunking_config": { "chunk_size": 1000, @@ -272,19 +391,35 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/b582 ";", ";" ], - "enable_multimodal": true + "enable_multimodal": true, + "parser_engine_rules": [ + { + "file_types": [".md", ".txt"], + "engine": "builtin" + } + ], + "enable_parent_child": true, + "parent_chunk_size": 4096, + "child_chunk_size": 384 }, "image_processing_config": { "model_id": "" }, "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", "vlm_config": { "enabled": true, "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" }, - "cos_config": { + "asr_config": { + "enabled": false, + "model_id": "", + "language": "" + }, + "storage_provider_config": { + "provider": "local" + }, + "storage_config": { "secret_id": "", "secret_key": "", "region": "", @@ -292,6 +427,14 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/b582 "app_id": "", "path_prefix": "" }, + "extract_config": null, + "faq_config": null, + "question_generation_config": null, + "is_pinned": false, + "pinned_at": null, + "knowledge_count": 3, + "chunk_count": 48, + "processing_count": 1, "created_at": "2025-08-12T11:30:09.206238+08:00", "updated_at": "2025-08-12T11:36:09.083577609+08:00", "deleted_at": null @@ -434,14 +577,14 @@ curl --location --request GET 'http://localhost:8080/api/v1/knowledge-bases/kb-0 } ``` -## POST `/knowledge-bases/:id/pin` - 置顶/取消置顶知识库 +## PUT `/knowledge-bases/:id/pin` - 置顶/取消置顶知识库 切换知识库的置顶状态。无需请求体,每次调用会自动切换当前置顶状态。 **请求**: ```curl -curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/pin' \ +curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/pin' \ --header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ --header 'Content-Type: application/json' ``` @@ -454,8 +597,52 @@ curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb- "id": "kb-00000001", "name": "Default Knowledge Base", "description": "System Default Knowledge Base", + "type": "document", + "is_temporary": false, "tenant_id": 1, + "chunking_config": { + "chunk_size": 1000, + "chunk_overlap": 200, + "separators": ["\n\n", "\n", "。", "!", "?", ";", ";"], + "enable_multimodal": true, + "parser_engine_rules": [], + "enable_parent_child": false, + "parent_chunk_size": 4096, + "child_chunk_size": 384 + }, + "image_processing_config": { + "model_id": "" + }, + "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", + "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", + "vlm_config": { + "enabled": true, + "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" + }, + "asr_config": { + "enabled": false, + "model_id": "", + "language": "" + }, + "storage_provider_config": { + "provider": "local" + }, + "storage_config": { + "secret_id": "", + "secret_key": "", + "region": "", + "bucket_name": "", + "app_id": "", + "path_prefix": "" + }, + "extract_config": null, + "faq_config": null, + "question_generation_config": null, "is_pinned": true, + "pinned_at": "2025-08-12T15:00:00.000000+08:00", + "knowledge_count": 12, + "chunk_count": 340, + "processing_count": 0, "created_at": "2025-08-11T20:10:41.817794+08:00", "updated_at": "2025-08-12T15:00:00.000000+08:00", "deleted_at": null @@ -485,9 +672,55 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/move-t "id": "kb-00000002", "name": "技术文档知识库", "description": "技术文档相关知识", + "type": "document", + "is_temporary": false, + "tenant_id": 1, + "chunking_config": { + "chunk_size": 1000, + "chunk_overlap": 200, + "separators": ["\n\n", "\n"], + "enable_multimodal": true, + "parser_engine_rules": [], + "enable_parent_child": false, + "parent_chunk_size": 4096, + "child_chunk_size": 384 + }, + "image_processing_config": { + "model_id": "" + }, "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", + "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", + "vlm_config": { + "enabled": false, + "model_id": "" + }, + "asr_config": { + "enabled": false, + "model_id": "", + "language": "" + }, + "storage_provider_config": { + "provider": "local" + }, + "storage_config": { + "secret_id": "", + "secret_key": "", + "region": "", + "bucket_name": "", + "app_id": "", + "path_prefix": "" + }, + "extract_config": null, + "faq_config": null, + "question_generation_config": null, + "is_pinned": false, + "pinned_at": null, + "knowledge_count": 8, + "chunk_count": 210, + "processing_count": 0, "created_at": "2025-08-12T11:30:09.206238+08:00", - "updated_at": "2025-08-12T11:30:09.206238+08:00" + "updated_at": "2025-08-12T11:30:09.206238+08:00", + "deleted_at": null } ], "success": true diff --git a/docs/api/knowledge.md b/docs/api/knowledge.md index 2c1bd005..50f639b1 100644 --- a/docs/api/knowledge.md +++ b/docs/api/knowledge.md @@ -52,6 +52,9 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowle "title": "彗星.txt", "description": "", "source": "", + "channel": "web", + "tag_id": "", + "summary_status": "none", "parse_status": "processing", "enable_status": "disabled", "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", @@ -98,6 +101,9 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowle "title": "", "description": "", "source": "https://github.com/Tencent/WeKnora", + "channel": "web", + "tag_id": "", + "summary_status": "none", "parse_status": "processing", "enable_status": "disabled", "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", @@ -146,6 +152,9 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowle "title": "", "description": "", "source": "https://github.com/Tencent/WeKnora", + "channel": "web", + "tag_id": "", + "summary_status": "none", "parse_status": "pending", "enable_status": "disabled", "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", @@ -194,6 +203,9 @@ curl --location 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5- "title": "彗星.txt", "description": "彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。截至2019年,已知彗星超6600颗,数量庞大。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。", "source": "", + "channel": "web", + "tag_id": "", + "summary_status": "none", "parse_status": "completed", "enable_status": "enabled", "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", @@ -237,6 +249,9 @@ curl --location 'http://localhost:8080/api/v1/knowledge/batch?ids=9c8af585-ae15- "title": "", "description": "", "source": "https://github.com/Tencent/WeKnora", + "channel": "web", + "tag_id": "", + "summary_status": "none", "parse_status": "pending", "enable_status": "disabled", "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", @@ -261,6 +276,9 @@ curl --location 'http://localhost:8080/api/v1/knowledge/batch?ids=9c8af585-ae15- "title": "彗星.txt", "description": "彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。截至2019年,已知彗星超6600颗,数量庞大。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。", "source": "", + "channel": "web", + "tag_id": "", + "summary_status": "none", "parse_status": "completed", "enable_status": "enabled", "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", @@ -375,6 +393,9 @@ curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowle "title": "产品使用指南", "description": "", "source": "", + "channel": "web", + "tag_id": "", + "summary_status": "none", "parse_status": "processing", "enable_status": "disabled", "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", diff --git a/docs/api/message.md b/docs/api/message.md index 9b9f59a4..a8a7e8bd 100644 --- a/docs/api/message.md +++ b/docs/api/message.md @@ -84,6 +84,9 @@ curl --location --request GET 'http://localhost:8080/api/v1/messages/ceb9babb-1e ], "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 @@ -97,6 +100,9 @@ curl --location --request GET 'http://localhost:8080/api/v1/messages/ceb9babb-1e "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 @@ -153,6 +159,9 @@ curl --location --request GET 'http://localhost:8080/api/v1/messages/ceb9babb-1e ], "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 diff --git a/docs/api/session.md b/docs/api/session.md index 3d116b9c..3123a553 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -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": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "no_match_prefix": "\n\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": "\n\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": "\n\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": "\n\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": "\n\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": "\n\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` 返回结果一致。