From 5e16af8cf922c9b4141cd16ce25211cb6dcab974 Mon Sep 17 00:00:00 2001 From: wizardchen Date: Wed, 24 Dec 2025 15:45:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0API=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E9=93=BE=E6=8E=A5=E8=87=B3=E6=96=B0=E8=B7=AF=E5=BE=84=EF=BC=9B?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=E7=9F=A5=E8=AF=86=E6=90=9C=E7=B4=A2API?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9B=E5=A2=9E=E5=BC=BAFAQ=E5=92=8C?= =?UTF-8?q?=E6=A0=87=E7=AD=BE=E5=88=A0=E9=99=A4=E6=8E=A5=E5=8F=A3=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=EF=BC=9B=E7=A7=BB=E9=99=A4Swagger=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=B8=AD=E7=9A=84=E7=A1=AC=E7=BC=96=E7=A0=81=E4=B8=BB=E6=9C=BA?= =?UTF-8?q?=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- README_CN.md | 2 +- README_JA.md | 2 +- cmd/server/main.go | 1 - docs/API.md | 2587 ---------------------------------- docs/api/README.md | 1 + docs/api/faq.md | 21 +- docs/api/knowledge-search.md | 74 + docs/docs.go | 103 +- docs/swagger.json | 102 +- docs/swagger.yaml | 70 +- 11 files changed, 361 insertions(+), 2604 deletions(-) delete mode 100644 docs/API.md create mode 100644 docs/api/knowledge-search.md diff --git a/README.md b/README.md index 06af5d61..0f7ba67f 100644 --- a/README.md +++ b/README.md @@ -323,7 +323,7 @@ Please refer to the [MCP Configuration Guide](./mcp-server/MCP_CONFIG.md) for th Troubleshooting FAQ: [Troubleshooting FAQ](./docs/QA.md) -Detailed API documentation is available at: [API Docs](./docs/API.md) +Detailed API documentation is available at: [API Docs](./docs/api/README.md) ## 🧭 Developer Guide diff --git a/README_CN.md b/README_CN.md index 9b69b4fd..e6d4f17d 100644 --- a/README_CN.md +++ b/README_CN.md @@ -325,7 +325,7 @@ WeKnora 支持将文档转化为知识图谱，展示文档中不同段落之间 常见问题排查：[常见问题排查](./docs/QA.md) -详细接口说明请参考：[API 文档](./docs/API.md) +详细接口说明请参考：[API 文档](./docs/api/README.md) ## 🧭 开发指南 diff --git a/README_JA.md b/README_JA.md index f718315a..6d70ee5a 100644 --- a/README_JA.md +++ b/README_JA.md @@ -325,7 +325,7 @@ WeKnoraは文書をナレッジグラフに変換し、文書内の異なる段 よくある問題の解決：[よくある問題](./docs/QA.md) -詳細なAPIドキュメントは：[APIドキュメント](./docs/API.md)を参照してください +詳細なAPIドキュメントは：[APIドキュメント](./docs/api/README.md)を参照してください ## 🧭 開発ガイド diff --git a/cmd/server/main.go b/cmd/server/main.go index 23b5cd8e..e27f431e 100644 --- a/cmd/server/main.go +++ b/cmd/server/main.go @@ -9,7 +9,6 @@ // @contact.name WeKnora Github // @contact.url https://github.com/Tencent/WeKnora // -// @host localhost:8080 // @BasePath /api/v1 // // @securityDefinitions.apikey Bearer diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index 3dcef43c..00000000 --- a/docs/API.md +++ /dev/null @@ -1,2587 +0,0 @@ -# WeKnora API 文档 - -## 目录 - -- [概述](#概述) -- [基础信息](#基础信息) -- [认证机制](#认证机制) -- [错误处理](#错误处理) -- [API 概览](#api-概览) -- [API 详细说明](#api-详细说明) - - [租户管理 API](#租户管理api) - - [知识库管理 API](#知识库管理api) - - [知识管理 API](#知识管理api) - - [模型管理 API](#模型管理api) - - [分块管理 API](#分块管理api) - - [标签管理 API](#标签管理api) - - [FAQ管理 API](#faq管理api) - - [会话管理 API](#会话管理api) - - [聊天功能 API](#聊天功能api) - - [消息管理 API](#消息管理api) - - [评估功能 API](#评估功能api) - -## 概述 - -WeKnora 提供了一系列 RESTful API，用于创建和管理知识库、检索知识，以及进行基于知识的问答。本文档详细描述了这些 API 的使用方式。 - -## 基础信息 - -- **基础 URL**: `/api/v1` -- **响应格式**: JSON -- **认证方式**: API Key - -## 认证机制 - -所有 API 请求需要在 HTTP 请求头中包含 `X-API-Key` 进行身份认证： - -``` -X-API-Key: your_api_key -``` - -为便于问题追踪和调试，建议每个请求的 HTTP 请求头中添加 `X-Request-ID`： - -``` -X-Request-ID: unique_request_id -``` - -### 获取 API Key - -在 web 页面完成账户注册后，请前往账户信息页面获取您的 API Key。 - -请妥善保管您的 API Key，避免泄露。API Key 代表您的账户身份，拥有完整的 API 访问权限。 - -## 错误处理 - -所有 API 使用标准的 HTTP 状态码表示请求状态，并返回统一的错误响应格式： - -```json -{ - "success": false, - "error": { - "code": "错误代码", - "message": "错误信息", - "details": "错误详情" - } -} -``` - -## API 概览 - -WeKnora API 按功能分为以下几类： - -1. **租户管理**：创建和管理租户账户 -2. **知识库管理**：创建、查询和管理知识库 -3. **知识管理**：上传、检索和管理知识内容 -4. **模型管理**：配置和管理各种AI模型 -5. **分块管理**：管理知识的分块内容 -6. **标签管理**：管理知识库的标签分类 -7. **FAQ管理**：管理FAQ问答对 -8. **会话管理**：创建和管理对话会话 -9. **聊天功能**：基于知识库进行问答 -10. **消息管理**：获取和管理对话消息 -11. **评估功能**：评估模型性能 - -## API 详细说明 - -以下是每个API的详细说明和示例。 - -### 租户管理API - -| 方法 | 路径 | 描述 | -| ------ | -------------- | --------------------- | -| POST | `/tenants` | 创建新租户 | -| GET | `/tenants/:id` | 获取指定租户信息 | -| PUT | `/tenants/:id` | 更新租户信息 | -| DELETE | `/tenants/:id` | 删除租户 | -| GET | `/tenants` | 获取租户列表 | - -#### POST `/tenants` - 创建新租户 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/tenants' \ ---header 'Content-Type: application/json' \ ---data '{ - "name": "weknora", - "description": "weknora tenants", - "business": "wechat", - "retriever_engines": { - "engines": [ - { - "retriever_type": "keywords", - "retriever_engine_type": "postgres" - }, - { - "retriever_type": "vector", - "retriever_engine_type": "postgres" - } - ] - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": 10000, - "name": "weknora", - "description": "weknora tenants", - "api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240, - "storage_used": 0, - "created_at": "2025-08-11T20:37:28.396980093+08:00", - "updated_at": "2025-08-11T20:37:28.396980301+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/tenants/:id` - 获取指定租户信息 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/tenants/10000' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' -``` - -**响应**: - -```json -{ - "data": { - "id": 10000, - "name": "weknora", - "description": "weknora tenants", - "api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240, - "storage_used": 0, - "created_at": "2025-08-11T20:37:28.39698+08:00", - "updated_at": "2025-08-11T20:37:28.405693+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### PUT `/tenants/:id` - 更新租户信息 - -注意 API Key 会变更 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-KREi84yPtahKxMtIMOW-Cxx2dxb9xROpUuDSpi3vbiC1QVDe' \ ---data '{ - "name": "weknora new", - "description": "weknora tenants new", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240 -}' -``` - -**响应**: - -```json -{ - "data": { - "id": 10000, - "name": "weknora new", - "description": "weknora tenants new", - "api_key": "sk-IKtd9JGV4-aPGQ6RiL8YJu9Vzb3-ae4lgFkjFJZmhvUn2mLu", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240, - "storage_used": 0, - "created_at": "0001-01-01T00:00:00Z", - "updated_at": "2025-08-11T20:49:02.13421034+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### DELETE `/tenants/:id` - 删除租户 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/tenants/10000' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-IKtd9JGV4-aPGQ6RiL8YJu9Vzb3-ae4lgFkjFJZmhvUn2mLu' -``` - -**响应**: - -```json -{ - "message": "Tenant deleted successfully", - "success": true -} -``` - -#### GET `/tenants` - 获取租户列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/tenants' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA' -``` - -**响应**: - -```json -{ - "data": { - "items": [ - { - "id": 10002, - "name": "weknora", - "description": "weknora tenants", - "api_key": "sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240, - "storage_used": 0, - "created_at": "2025-08-11T20:52:58.05679+08:00", - "updated_at": "2025-08-11T20:52:58.060495+08:00", - "deleted_at": null - } - ] - }, - "success": true -} -``` - -
返回顶部 ↑
- -### 知识库管理API - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------ | ------------------------ | -| POST | `/knowledge-bases` | 创建知识库 | -| GET | `/knowledge-bases` | 获取知识库列表 | -| GET | `/knowledge-bases/:id` | 获取知识库详情 | -| PUT | `/knowledge-bases/:id` | 更新知识库 | -| DELETE | `/knowledge-bases/:id` | 删除知识库 | -| POST | `/knowledge-bases/copy` | 拷贝知识库 | -| GET | `/knowledge-bases/:id/hybrid-search` | 混合搜索（向量+关键词） | - -#### POST `/knowledge-bases` - 创建知识库 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "weknora", - "description": "weknora description", - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "." - ], - "enable_multimodal": true - }, - "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": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0", - "name": "weknora", - "description": "weknora description", - "tenant_id": 1, - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "." - ], - "enable_multimodal": true - }, - "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": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - }, - "created_at": "2025-08-12T11:30:09.206238645+08:00", - "updated_at": "2025-08-12T11:30:09.206238854+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/knowledge-bases` - 获取知识库列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "kb-00000001", - "name": "Default Knowledge Base", - "description": "System Default Knowledge Base", - "tenant_id": 1, - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "\n\n", - "\n", - "。", - "！", - "？", - ";", - "；" - ], - "enable_multimodal": true - }, - "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": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - }, - "created_at": "2025-08-11T20:10:41.817794+08:00", - "updated_at": "2025-08-12T11:23:00.593097+08:00", - "deleted_at": null - } - ], - "success": true -} -``` - -#### GET `/knowledge-bases/:id` - 获取知识库详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "data": { - "id": "kb-00000001", - "name": "Default Knowledge Base", - "description": "System Default Knowledge Base", - "tenant_id": 1, - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "\n\n", - "\n", - "。", - "！", - "？", - ";", - "；" - ], - "enable_multimodal": true - }, - "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": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - }, - "created_at": "2025-08-11T20:10:41.817794+08:00", - "updated_at": "2025-08-12T11:23:00.593097+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### PUT `/knowledge-bases/:id` - 更新知识库 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/b5829e4a-3845-4624-a7fb-ea3b35e843b0' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "weknora new", - "description": "weknora description new", - "config": { - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "\n\n", - "\n", - "。", - "！", - "？", - ";", - "；" - ], - "enable_multimodal": true - }, - "image_processing_config": { - "model_id": "" - } - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0", - "name": "weknora new", - "description": "weknora description new", - "tenant_id": 1, - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "\n\n", - "\n", - "。", - "！", - "？", - ";", - "；" - ], - "enable_multimodal": true - }, - "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": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - }, - "created_at": "2025-08-12T11:30:09.206238+08:00", - "updated_at": "2025-08-12T11:36:09.083577609+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### DELETE `/knowledge-bases/:id` - 删除知识库 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/b5829e4a-3845-4624-a7fb-ea3b35e843b0' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "message": "Knowledge base deleted successfully", - "success": true -} -``` - -#### GET `/knowledge-bases/:id/hybrid-search` - 混合搜索 - -执行向量搜索和关键词搜索的混合检索。 - -**注意**：此接口使用 GET 方法但需要 JSON 请求体。 - -**请求参数**： -- `query_text`: 搜索查询文本（必填） -- `vector_threshold`: 向量相似度阈值（0-1，可选） -- `keyword_threshold`: 关键词匹配阈值（可选） -- `match_count`: 返回结果数量（可选） -- `disable_keywords_match`: 是否禁用关键词匹配（可选） -- `disable_vector_match`: 是否禁用向量匹配（可选） - -**请求**: - -```curl -curl --location --request GET 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "query_text": "如何使用知识库", - "vector_threshold": 0.5, - "match_count": 10 -}' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "chunk-00000001", - "content": "知识库是用于存储和检索知识的系统...", - "knowledge_id": "knowledge-00000001", - "chunk_index": 0, - "knowledge_title": "知识库使用指南", - "start_at": 0, - "end_at": 500, - "seq": 1, - "score": 0.95, - "chunk_type": "text", - "image_info": "", - "metadata": {}, - "knowledge_filename": "guide.pdf", - "knowledge_source": "file" - } - ], - "success": true -} -``` - -
返回顶部 ↑
- -### 知识管理API - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------- | ------------------------ | -| POST | `/knowledge-bases/:id/knowledge/file` | 从文件创建知识 | -| POST | `/knowledge-bases/:id/knowledge/url` | 从 URL 创建知识 | -| POST | `/knowledge-bases/:id/knowledge/manual` | 创建手工 Markdown 知识 | -| GET | `/knowledge-bases/:id/knowledge` | 获取知识库下的知识列表 | -| GET | `/knowledge/:id` | 获取知识详情 | -| DELETE | `/knowledge/:id` | 删除知识 | -| GET | `/knowledge/:id/download` | 下载知识文件 | -| PUT | `/knowledge/:id` | 更新知识 | -| PUT | `/knowledge/manual/:id` | 更新手工 Markdown 知识 | -| PUT | `/knowledge/image/:id/:chunk_id` | 更新图像分块信息 | -| PUT | `/knowledge/tags` | 批量更新知识标签 | -| GET | `/knowledge/batch` | 批量获取知识 | - -#### POST `/knowledge-bases/:id/knowledge/file` - 从文件创建知识 - -**表单参数**： -- `file`: 上传的文件（必填） -- `metadata`: JSON 格式的元数据（可选） -- `enable_multimodel`: 是否启用多模态处理（可选，true/false） -- `fileName`: 自定义文件名，用于文件夹上传时保留路径（可选） - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/file' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---form 'file=@"/Users/xxxx/tests/彗星.txt"' \ ---form 'enable_multimodel="true"' -``` - -**响应**: - -```json -{ - "data": { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "", - "source": "", - "parse_status": "processing", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "file_hash": "d69476ddbba45223a5e97e786539952c", - "file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:52:36.168632288+08:00", - "updated_at": "2025-08-12T11:52:36.173612121+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -#### POST `/knowledge-bases/:id/knowledge/url` - 从 URL 创建知识 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/url' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "url":"https://github.com/Tencent/WeKnora", - "enable_multimodel":true -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "description": "", - "source": "https://github.com/Tencent/WeKnora", - "parse_status": "processing", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "file_type": "", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:55:05.709266776+08:00", - "updated_at": "2025-08-12T11:55:05.712918234+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/knowledge-bases/:id/knowledge` - 获取知识库下的知识列表 - -**查询参数**： -- `page`: 页码（默认 1） -- `page_size`: 每页条数（默认 20） -- `tag_id`: 按标签ID筛选（可选） - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge?page_size=1&page=1&tag_id=tag-00000001' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "description": "", - "source": "https://github.com/Tencent/WeKnora", - "parse_status": "pending", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "file_type": "", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:55:05.709266+08:00", - "updated_at": "2025-08-12T11:55:05.709266+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - } - ], - "page": 1, - "page_size": 1, - "success": true, - "total": 2 -} -``` - -注：parse_status 包含 `pending/processing/failed/completed` 四种状态 - -#### GET `/knowledge/:id` - 获取知识详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "彗星是由冰和尘埃构成的太阳系小天体，接近太阳时会形成彗发和彗尾。其轨道周期差异大，来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊，部分彗星已失去挥发物质，类似小行星。截至2019年，已知彗星超6600颗，数量庞大。彗星在古代被视为凶兆，现代研究揭示其复杂结构与起源。", - "source": "", - "parse_status": "completed", - "enable_status": "enabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "file_hash": "d69476ddbba45223a5e97e786539952c", - "file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt", - "storage_size": 33689, - "metadata": null, - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00", - "processed_at": "2025-08-12T11:52:53.376573+08:00", - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/knowledge/batch` - 批量获取知识 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/batch?ids=9c8af585-ae15-44ce-8f73-45ad18394651&ids=4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "description": "", - "source": "https://github.com/Tencent/WeKnora", - "parse_status": "pending", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "file_type": "", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:55:05.709266+08:00", - "updated_at": "2025-08-12T11:55:05.709266+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "彗星是由冰和尘埃构成的太阳系小天体，接近太阳时会形成彗发和彗尾。其轨道周期差异大，来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊，部分彗星已失去挥发物质，类似小行星。截至2019年，已知彗星超6600颗，数量庞大。彗星在古代被视为凶兆，现代研究揭示其复杂结构与起源。", - "source": "", - "parse_status": "completed", - "enable_status": "enabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "file_hash": "d69476ddbba45223a5e97e786539952c", - "file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt", - "storage_size": 33689, - "metadata": null, - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00", - "processed_at": "2025-08-12T11:52:53.376573+08:00", - "error_message": "", - "deleted_at": null - } - ], - "success": true -} -``` - -#### DELETE `/knowledge/:id` - 删除知识 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge/9c8af585-ae15-44ce-8f73-45ad18394651' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "Deleted successfully", - "success": true -} -``` - -#### GET `/knowledge/:id/download` - 下载知识文件 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/download' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -``` -attachment -``` - -
返回顶部 ↑
- -### 模型管理API - -| 方法 | 路径 | 描述 | -| ------ | --------------------- | --------------------- | -| POST | `/models` | 创建模型 | -| GET | `/models` | 获取模型列表 | -| GET | `/models/:id` | 获取模型详情 | -| PUT | `/models/:id` | 更新模型 | -| DELETE | `/models/:id` | 删除模型 | - -#### POST `/models` - 创建模型 - -创建对话模型（KnowledgeQA）请求体: - -```curl -curl --location 'http://localhost:8080/api/v1/models' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "qwen3:8b", - "type": "KnowledgeQA", - "source": "local", - "description": "LLM Model for Knowledge QA", - "parameters": { - "base_url": "", - "api_key": "" - }, - "is_default": false -}' -``` - -创建嵌入模型（Embedding）请求体: - -```curl -curl --location 'http://localhost:8080/api/v1/models' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "nomic-embed-text:latest", - "type": "Embedding", - "source": "local", - "description": "Embedding Model", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 768, - "truncate_prompt_tokens": 0 - } - }, - "is_default": false -}' -``` - -创建排序模型（Rerank）请求体: - -```curl -curl --location 'http://localhost:8080/api/v1/models' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "linux6200/bge-reranker-v2-m3:latest", - "type": "Rerank", - "source": "local", - "description": "Rerank Model for Knowledge QA", - "parameters": { - "base_url": "", - "api_key": "" - }, - "is_default": false -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "09c5a1d6-ee8b-4657-9a17-d3dcbd5c70cb", - "tenant_id": 1, - "name": "nomic-embed-text:latest3", - "type": "Embedding", - "source": "local", - "description": "Embedding Model", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 768, - "truncate_prompt_tokens": 0 - } - }, - "is_default": false, - "status": "downloading", - "created_at": "2025-08-12T10:39:01.454591766+08:00", - "updated_at": "2025-08-12T10:39:01.454591766+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/models` - 获取模型列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/models' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "tenant_id": 1, - "name": "nomic-embed-text:latest", - "type": "Embedding", - "source": "local", - "description": "Embedding Model", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 768, - "truncate_prompt_tokens": 0 - } - }, - "is_default": true, - "status": "active", - "created_at": "2025-08-11T20:10:41.813832+08:00", - "updated_at": "2025-08-11T20:10:41.822354+08:00", - "deleted_at": null - }, - { - "id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "tenant_id": 1, - "name": "qwen3:8b", - "type": "KnowledgeQA", - "source": "local", - "description": "LLM Model for Knowledge QA", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 0, - "truncate_prompt_tokens": 0 - } - }, - "is_default": true, - "status": "active", - "created_at": "2025-08-11T20:10:41.811761+08:00", - "updated_at": "2025-08-11T20:10:41.825381+08:00", - "deleted_at": null - } - ], - "success": true -} -``` - -#### GET `/models/:id` - 获取模型详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/models/dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "data": { - "id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "tenant_id": 1, - "name": "nomic-embed-text:latest", - "type": "Embedding", - "source": "local", - "description": "Embedding Model", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 768, - "truncate_prompt_tokens": 0 - } - }, - "is_default": true, - "status": "active", - "created_at": "2025-08-11T20:10:41.813832+08:00", - "updated_at": "2025-08-11T20:10:41.822354+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### PUT `/models/:id` - 更新模型 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/models/8fdc464d-8eaa-44d4-a85b-094b28af5330' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "linux6200/bge-reranker-v2-m3:latest", - "description": "Rerank Model for Knowledge QA new", - "parameters": { - "base_url": "", - "api_key": "" - }, - "is_default": false -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "8fdc464d-8eaa-44d4-a85b-094b28af5330", - "tenant_id": 1, - "name": "linux6200/bge-reranker-v2-m3:latest", - "type": "Rerank", - "source": "local", - "description": "Rerank Model for Knowledge QA new", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 0, - "truncate_prompt_tokens": 0 - } - }, - "is_default": false, - "status": "active", - "created_at": "2025-08-12T10:57:39.512681+08:00", - "updated_at": "2025-08-12T11:00:27.271678+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### DELETE `/models/:id` - 删除模型 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/models/8fdc464d-8eaa-44d4-a85b-094b28af5330' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "message": "Model deleted", - "success": true -} -``` - -
返回顶部 ↑
- -### 分块管理API - -| 方法 | 路径 | 描述 | -| ------ | --------------------------- | ------------------------ | -| GET | `/chunks/:knowledge_id` | 获取知识的分块列表 | -| DELETE | `/chunks/:knowledge_id/:id` | 删除分块 | -| DELETE | `/chunks/:knowledge_id` | 删除知识下的所有分块 | - -#### GET `/chunks/:knowledge_id?page=&page_size=` - 获取知识的分块列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5?page=1&page_size=1' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7", - "tenant_id": 1, - "knowledge_id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "knowledge_base_id": "kb-00000001", - "tag_id": "", - "content": "彗星xxxx", - "chunk_index": 0, - "is_enabled": true, - "status": 2, - "start_at": 0, - "end_at": 964, - "pre_chunk_id": "", - "next_chunk_id": "", - "chunk_type": "text", - "parent_chunk_id": "", - "relation_chunks": null, - "indirect_relation_chunks": null, - "metadata": null, - "content_hash": "", - "image_info": "", - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00", - "deleted_at": null - } - ], - "page": 1, - "page_size": 1, - "success": true, - "total": 5 -} -``` - -#### DELETE `/chunks/:knowledge_id/:id` - 删除分块 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "Chunk deleted", - "success": true -} -``` - -#### DELETE `/chunks/:knowledge_id` - 删除知识下的所有分块 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "All chunks under knowledge deleted", - "success": true -} -``` - -
返回顶部 ↑
- -### 标签管理API - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------- | ------------------------ | -| GET | `/knowledge-bases/:id/tags` | 获取知识库标签列表 | -| POST | `/knowledge-bases/:id/tags` | 创建标签 | -| PUT | `/knowledge-bases/:id/tags/:tag_id` | 更新标签 | -| DELETE | `/knowledge-bases/:id/tags/:tag_id` | 删除标签 | - -#### GET `/knowledge-bases/:id/tags` - 获取知识库标签列表 - -**查询参数**: -- `page`: 页码（默认 1） -- `page_size`: 每页条数（默认 20） -- `keyword`: 标签名称关键字搜索（可选） - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags?page=1&page_size=10' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "total": 2, - "page": 1, - "page_size": 10, - "data": [ - { - "id": "tag-00000001", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "name": "技术文档", - "color": "#1890ff", - "sort_order": 1, - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00", - "knowledge_count": 5, - "chunk_count": 120 - }, - { - "id": "tag-00000002", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "name": "常见问题", - "color": "#52c41a", - "sort_order": 2, - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00", - "knowledge_count": 3, - "chunk_count": 45 - } - ] - }, - "success": true -} -``` - -#### POST `/knowledge-bases/:id/tags` - 创建标签 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "name": "产品手册", - "color": "#faad14", - "sort_order": 3 -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "tag-00000003", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "name": "产品手册", - "color": "#faad14", - "sort_order": 3, - "created_at": "2025-08-12T11:00:00+08:00", - "updated_at": "2025-08-12T11:00:00+08:00" - }, - "success": true -} -``` - -#### PUT `/knowledge-bases/:id/tags/:tag_id` - 更新标签 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags/tag-00000003' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "name": "产品手册更新", - "color": "#ff4d4f" -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "tag-00000003", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "name": "产品手册更新", - "color": "#ff4d4f", - "sort_order": 3, - "created_at": "2025-08-12T11:00:00+08:00", - "updated_at": "2025-08-12T11:30:00+08:00" - }, - "success": true -} -``` - -#### DELETE `/knowledge-bases/:id/tags/:tag_id` - 删除标签 - -**查询参数**: -- `force`: 设置为 `true` 时强制删除（即使标签被引用） - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags/tag-00000003?force=true' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "success": true -} -``` - -
返回顶部 ↑
- -### FAQ管理API - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------------- | ------------------------ | -| GET | `/knowledge-bases/:id/faq/entries` | 获取FAQ条目列表 | -| POST | `/knowledge-bases/:id/faq/entries` | 批量导入FAQ条目 | -| POST | `/knowledge-bases/:id/faq/entry` | 创建单个FAQ条目 | -| PUT | `/knowledge-bases/:id/faq/entries/:entry_id`| 更新单个FAQ条目 | -| PUT | `/knowledge-bases/:id/faq/entries/status` | 批量更新FAQ启用状态 | -| PUT | `/knowledge-bases/:id/faq/entries/tags` | 批量更新FAQ标签 | -| DELETE | `/knowledge-bases/:id/faq/entries` | 批量删除FAQ条目 | -| POST | `/knowledge-bases/:id/faq/search` | 混合搜索FAQ | - -#### GET `/knowledge-bases/:id/faq/entries` - 获取FAQ条目列表 - -**查询参数**: -- `page`: 页码（默认 1） -- `page_size`: 每页条数（默认 20） -- `tag_id`: 按标签ID筛选（可选） -- `keyword`: 关键字搜索（可选） - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?page=1&page_size=10' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "total": 100, - "page": 1, - "page_size": 10, - "data": [ - { - "id": "faq-00000001", - "chunk_id": "chunk-00000001", - "knowledge_id": "knowledge-00000001", - "knowledge_base_id": "kb-00000001", - "tag_id": "tag-00000001", - "is_enabled": true, - "standard_question": "如何重置密码？", - "similar_questions": ["忘记密码怎么办", "密码找回"], - "negative_questions": ["如何修改用户名"], - "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"], - "index_mode": "hybrid", - "chunk_type": "faq", - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - } - ] - }, - "success": true -} -``` - -#### POST `/knowledge-bases/:id/faq/entries` - 批量导入FAQ条目 - -**请求参数**: -- `mode`: 导入模式，`append`（追加）或 `replace`（替换） -- `entries`: FAQ条目数组 -- `knowledge_id`: 关联的知识ID（可选） - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "mode": "append", - "entries": [ - { - "standard_question": "如何联系客服？", - "similar_questions": ["客服电话", "在线客服"], - "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"], - "tag_id": "tag-00000001" - }, - { - "standard_question": "退款政策是什么？", - "answers": ["我们提供7天无理由退款服务。"] - } - ] -}' -``` - -**响应**: - -```json -{ - "data": { - "task_id": "task-00000001" - }, - "success": true -} -``` - -注：批量导入为异步操作，返回任务ID用于追踪进度。 - -#### POST `/knowledge-bases/:id/faq/entry` - 创建单个FAQ条目 - -同步创建单个FAQ条目，适用于单条录入场景。会自动检查标准问和相似问是否与已有FAQ重复。 - -**请求参数**: -- `standard_question`: 标准问（必填） -- `similar_questions`: 相似问数组（可选） -- `negative_questions`: 反例问题数组（可选） -- `answers`: 答案数组（必填） -- `tag_id`: 标签ID（可选） -- `is_enabled`: 是否启用（可选，默认true） - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entry' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "standard_question": "如何联系客服？", - "similar_questions": ["客服电话", "在线客服"], - "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"], - "tag_id": "tag-00000001", - "is_enabled": true -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "faq-00000001", - "chunk_id": "chunk-00000001", - "knowledge_id": "knowledge-00000001", - "knowledge_base_id": "kb-00000001", - "tag_id": "tag-00000001", - "is_enabled": true, - "standard_question": "如何联系客服？", - "similar_questions": ["客服电话", "在线客服"], - "negative_questions": [], - "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"], - "index_mode": "hybrid", - "chunk_type": "faq", - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - }, - "success": true -} -``` - -**错误响应**（标准问或相似问重复时）: - -```json -{ - "success": false, - "error": { - "code": "BAD_REQUEST", - "message": "标准问与已有FAQ重复" - } -} -``` - -#### PUT `/knowledge-bases/:id/faq/entries/:entry_id` - 更新单个FAQ条目 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/faq-00000001' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "standard_question": "如何重置账户密码？", - "similar_questions": ["忘记密码怎么办", "密码找回", "重置密码"], - "answers": ["您可以通过以下步骤重置密码：1. 点击登录页面的"忘记密码" 2. 输入注册邮箱 3. 查收重置邮件"], - "is_enabled": true -}' -``` - -**响应**: - -```json -{ - "success": true -} -``` - -#### PUT `/knowledge-bases/:id/faq/entries/status` - 批量更新FAQ启用状态 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/status' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "updates": { - "faq-00000001": true, - "faq-00000002": false, - "faq-00000003": true - } -}' -``` - -**响应**: - -```json -{ - "success": true -} -``` - -#### PUT `/knowledge-bases/:id/faq/entries/tags` - 批量更新FAQ标签 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/tags' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "updates": { - "faq-00000001": "tag-00000001", - "faq-00000002": "tag-00000002", - "faq-00000003": null - } -}' -``` - -注：设置为 `null` 可清除标签关联。 - -**响应**: - -```json -{ - "success": true -} -``` - -#### DELETE `/knowledge-bases/:id/faq/entries` - 批量删除FAQ条目 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "ids": ["faq-00000001", "faq-00000002"] -}' -``` - -**响应**: - -```json -{ - "success": true -} -``` - -#### POST `/knowledge-bases/:id/faq/search` - 混合搜索FAQ - -**请求参数**: -- `query_text`: 搜索查询文本 -- `vector_threshold`: 向量相似度阈值（0-1） -- `match_count`: 返回结果数量（最大200） - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/search' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "query_text": "如何重置密码", - "vector_threshold": 0.5, - "match_count": 10 -}' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "faq-00000001", - "chunk_id": "chunk-00000001", - "knowledge_id": "knowledge-00000001", - "knowledge_base_id": "kb-00000001", - "tag_id": "tag-00000001", - "is_enabled": true, - "standard_question": "如何重置密码？", - "similar_questions": ["忘记密码怎么办", "密码找回"], - "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"], - "chunk_type": "faq", - "score": 0.95, - "match_type": "vector", - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - } - ], - "success": true -} -``` - -
返回顶部 ↑
- -### 会话管理API - -| 方法 | 路径 | 描述 | -| ------ | --------------------------------------- | --------------------- | -| POST | `/sessions` | 创建会话 | -| GET | `/sessions/:id` | 获取会话详情 | -| GET | `/sessions` | 获取租户的会话列表 | -| PUT | `/sessions/:id` | 更新会话 | -| DELETE | `/sessions/:id` | 删除会话 | -| POST | `/sessions/:session_id/generate_title` | 生成会话标题 | -| GET | `/sessions/continue-stream/:session_id` | 继续未完成的会话 | - -#### POST `/sessions` - 创建会话 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/sessions' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---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" - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f", - "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 - }, - "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", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/sessions/:id` - 获取会话详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "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", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/sessions?page=&page_size=` - 获取租户的会话列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/sessions?page=1&page_size=1' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f", - "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", - "deleted_at": null - } - ], - "page": 1, - "page_size": 1, - "success": true, - "total": 2 -} -``` - -#### PUT `/sessions/:id` - 更新会话 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/sessions/411d6b70-9a85-4d03-bb74-aab0fd8bd12f' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---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 - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f", - "title": "weknora", - "description": "weknora 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": "0001-01-01T00:00:00Z", - "updated_at": "2025-08-12T14:20:56.738424351+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### DELETE `/sessions/:id` - 删除会话 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/411d6b70-9a85-4d03-bb74-aab0fd8bd12f' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "Session deleted successfully", - "success": true -} -``` - -#### 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 'Content-Type: application/json' \ ---data '{ - "messages": [ - { - "role": "user", - "content": "你好，我想了解关于人工智能的知识" - }, - { - "role": "assistant", - "content": "人工智能是计算机科学的一个分支..." - } - ] -}' -``` - -**响应**: - -```json -{ - "data": "模型优化策略", - "success": true -} -``` - -#### GET `/sessions/continue-stream/:session_id` - 继续未完成的会话 - -**查询参数**: -- `message_id`: 从 `/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 'Content-Type: application/json' -``` - -**响应格式**: -服务器端事件流（Server-Sent Events），与 `/knowledge-chat/:session_id` 返回结果一致 - -
返回顶部 ↑
- -### 聊天功能API - -| 方法 | 路径 | 描述 | -| ---- | ----------------------------- | ------------------------ | -| POST | `/knowledge-chat/:session_id` | 基于知识库的问答 | -| POST | `/knowledge-search` | 基于知识库的搜索知识 | - -#### POST `/knowledge-chat/:session_id` - 基于知识库的问答 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-chat/ceb9babb-1e30-41d7-817d-fd584954304b' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "query": "彗尾的形状" -}' -``` - -**响应格式**: -服务器端事件流（Server-Sent Events，Content-Type: text/event-stream） - -**响应**: - -``` -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":""}]} - -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} - -event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"","done":true,"knowledge_references":null} -``` - -
返回顶部 ↑
- -### 消息管理API - -| 方法 | 路径 | 描述 | -| ------ | ---------------------------- | ------------------------ | -| GET | `/messages/:session_id/load` | 获取最近的会话消息列表 | -| DELETE | `/messages/:session_id/:id` | 删除消息 | - -#### GET `/messages/:session_id/load?before_time=2025-04-18T11:57:31.310671+08:00&limit=20` - 获取最近的会话消息列表 - -**查询参数**: - -- `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-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---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": "\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, - "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, - "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": "\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, - "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-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "Message deleted successfully", - "success": true -} -``` - -
返回顶部 ↑
- -### 评估功能API - -| 方法 | 路径 | 描述 | -| ---- | ------------- | --------------------- | -| GET | `/evaluation` | 获取评估任务 | -| POST | `/evaluation` | 创建评估任务 | - -#### GET `/evaluation` - 获取评估任务 - -**请求参数**: -- `task_id`: 从 `POST /evaluation` 接口中获取到的任务 ID -- `X-API-Key`: 用户 API Key - -**请求**: - -```bash -curl --location 'http://localhost:8080/api/v1/evaluation?task_id=c34563ad-b09f-4858-b72e-e92beb80becb' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "task": { - "id": "c34563ad-b09f-4858-b72e-e92beb80becb", - "tenant_id": 1, - "dataset_id": "default", - "start_time": "2025-08-12T14:54:26.221804768+08:00", - "status": 2, - "total": 1, - "finished": 1 - }, - "params": { - "session_id": "", - "knowledge_base_id": "2ef57434-8c8d-4442-b967-2f7fc578a2fc", - "vector_threshold": 0.5, - "keyword_threshold": 0.3, - "embedding_top_k": 10, - "vector_database": "", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "rerank_top_k": 5, - "rerank_threshold": 0.7, - "chat_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_config": { - "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 - }, - "fallback_strategy": "", - "fallback_response": "抱歉，我无法回答这个问题。" - }, - "metric": { - "retrieval_metrics": { - "precision": 0, - "recall": 0, - "ndcg3": 0, - "ndcg10": 0, - "mrr": 0, - "map": 0 - }, - "generation_metrics": { - "bleu1": 0.037656734016532384, - "bleu2": 0.04067392145167686, - "bleu4": 0.048963321289052536, - "rouge1": 0, - "rouge2": 0, - "rougel": 0 - } - } - }, - "success": true -} -``` - -#### POST `/evaluation` - 创建评估任务 - -**请求参数**: -- `dataset_id`: 评估使用的数据集，暂时只支持官方测试数据集 `default` -- `knowledge_base_id`: 评估使用的知识库 -- `chat_id`: 评估使用的对话模型 -- `rerank_id`: 评估使用的重排序模型 - -**请求**: - -```bash -curl --location 'http://localhost:8080/api/v1/evaluation' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "dataset_id": "default", - "knowledge_base_id": "kb-00000001", - "chat_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_id": "b30171a1-787b-426e-a293-735cd5ac16c0" -}' -``` - -**响应**: - -```json -{ - "data": { - "task": { - "id": "c34563ad-b09f-4858-b72e-e92beb80becb", - "tenant_id": 1, - "dataset_id": "default", - "start_time": "2025-08-12T14:54:26.221804768+08:00", - "status": 1 - }, - "params": { - "session_id": "", - "knowledge_base_id": "2ef57434-8c8d-4442-b967-2f7fc578a2fc", - "vector_threshold": 0.5, - "keyword_threshold": 0.3, - "embedding_top_k": 10, - "vector_database": "", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "rerank_top_k": 5, - "rerank_threshold": 0.7, - "chat_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_config": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话。", - "context_template": "你是一个专业的智能信息检索助手，xxx", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "fallback_strategy": "", - "fallback_response": "抱歉，我无法回答这个问题。" - } - }, - "success": true -} -``` - -
返回顶部 ↑
\ No newline at end of file diff --git a/docs/api/README.md b/docs/api/README.md index 7803030d..ee968ede 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -67,6 +67,7 @@ WeKnora API 按功能分为以下几类： | 标签管理 | 管理知识库的标签分类 | [tag.md](./tag.md) | | FAQ管理 | 管理FAQ问答对 | [faq.md](./faq.md) | | 会话管理 | 创建和管理对话会话 | [session.md](./session.md) | +| 知识搜索 | 在知识库中搜索内容 | [knowledge-search.md](./knowledge-search.md) | | 聊天功能 | 基于知识库和 Agent 进行问答 | [chat.md](./chat.md) | | 消息管理 | 获取和管理对话消息 | [message.md](./message.md) | | 评估功能 | 评估模型性能 | [evaluation.md](./evaluation.md) | diff --git a/docs/api/faq.md b/docs/api/faq.md index 993a06e0..7aa141c1 100644 --- a/docs/api/faq.md +++ b/docs/api/faq.md @@ -20,13 +20,32 @@ - `page_size`: 每页条数（默认 20） - `tag_id`: 按标签ID筛选（可选） - `keyword`: 关键字搜索（可选） +- `search_field`: 搜索字段（可选），可选值： + - `standard_question`: 只搜索标准问题 + - `similar_questions`: 只搜索相似问法 + - `answers`: 只搜索答案 + - 留空或不传：搜索全部字段 +- `sort_order`: 排序方式（可选），`asc` 表示按更新时间正序，默认按更新时间倒序 **请求**: ```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?page=1&page_size=10' \ +# 搜索全部字段 +curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?page=1&page_size=10&keyword=密码' \ --header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ --header 'Content-Type: application/json' + +# 只搜索标准问题 +curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=密码&search_field=standard_question' \ +--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' + +# 只搜索相似问法 +curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=忘记&search_field=similar_questions' \ +--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' + +# 只搜索答案 +curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=点击&search_field=answers' \ +--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' ``` **响应**: diff --git a/docs/api/knowledge-search.md b/docs/api/knowledge-search.md new file mode 100644 index 00000000..2ca7afc7 --- /dev/null +++ b/docs/api/knowledge-search.md @@ -0,0 +1,74 @@ +# 知识搜索 API + +[返回目录](./README.md) + +| 方法 | 路径 | 描述 | +| ---- | ------------------ | -------- | +| POST | `/knowledge-search` | 知识搜索 | + +## POST `/knowledge-search` - 知识搜索 + +在知识库中搜索相关内容（不使用 LLM 总结），直接返回检索结果。 + +**请求参数**: +- `query`: 搜索查询文本（必填） +- `knowledge_base_id`: 单个知识库ID（向后兼容） +- `knowledge_base_ids`: 知识库ID列表（支持多知识库搜索） +- `knowledge_ids`: 指定知识（文件）ID列表 + +**请求**: + +```curl +# 搜索单个知识库 +curl --location 'http://localhost:8080/api/v1/knowledge-search' \ +--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ +--header 'Content-Type: application/json' \ +--data '{ + "query": "如何使用知识库", + "knowledge_base_id": "kb-00000001" +}' + +# 搜索多个知识库 +curl --location 'http://localhost:8080/api/v1/knowledge-search' \ +--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ +--header 'Content-Type: application/json' \ +--data '{ + "query": "如何使用知识库", + "knowledge_base_ids": ["kb-00000001", "kb-00000002"] +}' + +# 搜索指定文件 +curl --location 'http://localhost:8080/api/v1/knowledge-search' \ +--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ +--header 'Content-Type: application/json' \ +--data '{ + "query": "如何使用知识库", + "knowledge_ids": ["4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5"] +}' +``` + +**响应**: + +```json +{ + "data": [ + { + "id": "chunk-00000001", + "content": "知识库是用于存储和检索知识的系统...", + "knowledge_id": "knowledge-00000001", + "chunk_index": 0, + "knowledge_title": "知识库使用指南", + "start_at": 0, + "end_at": 500, + "seq": 1, + "score": 0.95, + "chunk_type": "text", + "image_info": "", + "metadata": {}, + "knowledge_filename": "guide.pdf", + "knowledge_source": "file" + } + ], + "success": true +} +``` diff --git a/docs/docs.go b/docs/docs.go index 037808a1..819434e0 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -265,6 +265,12 @@ const docTemplate = `{ "schema": { "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" } + }, + "403": { + "description": "注册功能已禁用", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } } } } @@ -1947,6 +1953,18 @@ const docTemplate = `{ "description": "关键词搜索", "name": "keyword", "in": "query" + }, + { + "type": "string", + "description": "搜索字段: standard_question(标准问题), similar_questions(相似问法), answers(答案), 默认搜索全部", + "name": "search_field", + "in": "query" + }, + { + "type": "string", + "description": "排序方式: asc(按更新时间正序), 默认按更新时间倒序", + "name": "sort_order", + "in": "query" } ], "responses": { @@ -2241,6 +2259,64 @@ const docTemplate = `{ } }, "/knowledge-bases/{id}/faq/entries/{entry_id}": { + "get": { + "security": [ + { + "Bearer": [] + }, + { + "ApiKeyAuth": [] + } + ], + "description": "根据ID获取单个FAQ条目的详情", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "FAQ管理" + ], + "summary": "获取FAQ条目详情", + "parameters": [ + { + "type": "string", + "description": "知识库ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "FAQ条目ID", + "name": "entry_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "FAQ条目详情", + "schema": { + "type": "object", + "additionalProperties": true + } + }, + "400": { + "description": "请求参数错误", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "404": { + "description": "条目不存在", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + } + } + }, "put": { "security": [ { @@ -2958,7 +3034,7 @@ const docTemplate = `{ "ApiKeyAuth": [] } ], - "description": "删除标签，可使用force=true强制删除被引用的标签", + "description": "删除标签，可使用force=true强制删除被引用的标签，content_only=true仅删除标签下的内容而保留标签本身", "consumes": [ "application/json" ], @@ -2989,6 +3065,12 @@ const docTemplate = `{ "description": "强制删除", "name": "force", "in": "query" + }, + { + "type": "boolean", + "description": "仅删除内容，保留标签", + "name": "content_only", + "in": "query" } ], "responses": { @@ -7796,14 +7878,27 @@ const docTemplate = `{ "internal_handler_session.SearchKnowledgeRequest": { "type": "object", "required": [ - "knowledge_base_id", "query" ], "properties": { "knowledge_base_id": { - "description": "ID of the knowledge base to search", + "description": "Single knowledge base ID (for backward compatibility)", "type": "string" }, + "knowledge_base_ids": { + "description": "IDs of knowledge bases to search (multi-KB support)", + "type": "array", + "items": { + "type": "string" + } + }, + "knowledge_ids": { + "description": "IDs of specific knowledge (files) to search", + "type": "array", + "items": { + "type": "string" + } + }, "query": { "description": "Query text to search for", "type": "string" @@ -7906,7 +8001,7 @@ const docTemplate = `{ // SwaggerInfo holds exported Swagger Info so clients can modify it var SwaggerInfo = &swag.Spec{ Version: "1.0", - Host: "localhost:8080", + Host: "", BasePath: "/api/v1", Schemes: []string{}, Title: "WeKnora API", diff --git a/docs/swagger.json b/docs/swagger.json index 757c1348..6fd8f2b9 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -10,7 +10,6 @@ }, "version": "1.0" }, - "host": "localhost:8080", "basePath": "/api/v1", "paths": { "/auth/change-password": { @@ -259,6 +258,12 @@ "schema": { "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" } + }, + "403": { + "description": "注册功能已禁用", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } } } } @@ -1941,6 +1946,18 @@ "description": "关键词搜索", "name": "keyword", "in": "query" + }, + { + "type": "string", + "description": "搜索字段: standard_question(标准问题), similar_questions(相似问法), answers(答案), 默认搜索全部", + "name": "search_field", + "in": "query" + }, + { + "type": "string", + "description": "排序方式: asc(按更新时间正序), 默认按更新时间倒序", + "name": "sort_order", + "in": "query" } ], "responses": { @@ -2235,6 +2252,64 @@ } }, "/knowledge-bases/{id}/faq/entries/{entry_id}": { + "get": { + "security": [ + { + "Bearer": [] + }, + { + "ApiKeyAuth": [] + } + ], + "description": "根据ID获取单个FAQ条目的详情", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "FAQ管理" + ], + "summary": "获取FAQ条目详情", + "parameters": [ + { + "type": "string", + "description": "知识库ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "FAQ条目ID", + "name": "entry_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "FAQ条目详情", + "schema": { + "type": "object", + "additionalProperties": true + } + }, + "400": { + "description": "请求参数错误", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "404": { + "description": "条目不存在", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + } + } + }, "put": { "security": [ { @@ -2952,7 +3027,7 @@ "ApiKeyAuth": [] } ], - "description": "删除标签，可使用force=true强制删除被引用的标签", + "description": "删除标签，可使用force=true强制删除被引用的标签，content_only=true仅删除标签下的内容而保留标签本身", "consumes": [ "application/json" ], @@ -2983,6 +3058,12 @@ "description": "强制删除", "name": "force", "in": "query" + }, + { + "type": "boolean", + "description": "仅删除内容，保留标签", + "name": "content_only", + "in": "query" } ], "responses": { @@ -7790,14 +7871,27 @@ "internal_handler_session.SearchKnowledgeRequest": { "type": "object", "required": [ - "knowledge_base_id", "query" ], "properties": { "knowledge_base_id": { - "description": "ID of the knowledge base to search", + "description": "Single knowledge base ID (for backward compatibility)", "type": "string" }, + "knowledge_base_ids": { + "description": "IDs of knowledge bases to search (multi-KB support)", + "type": "array", + "items": { + "type": "string" + } + }, + "knowledge_ids": { + "description": "IDs of specific knowledge (files) to search", + "type": "array", + "items": { + "type": "string" + } + }, "query": { "description": "Query text to search for", "type": "string" diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 5025deb1..301cba7f 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1690,13 +1690,22 @@ definitions: internal_handler_session.SearchKnowledgeRequest: properties: knowledge_base_id: - description: ID of the knowledge base to search + description: Single knowledge base ID (for backward compatibility) type: string + knowledge_base_ids: + description: IDs of knowledge bases to search (multi-KB support) + items: + type: string + type: array + knowledge_ids: + description: IDs of specific knowledge (files) to search + items: + type: string + type: array query: description: Query text to search for type: string required: - - knowledge_base_id - query type: object internal_handler_session.SessionStrategy: @@ -1750,7 +1759,6 @@ definitions: required: - message_id type: object -host: localhost:8080 info: contact: name: WeKnora Github @@ -1917,6 +1925,10 @@ paths: description: 请求参数错误 schema: $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + "403": + description: 注册功能已禁用 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' summary: 用户注册 tags: - 认证 @@ -2940,6 +2952,15 @@ paths: in: query name: keyword type: string + - description: '搜索字段: standard_question(标准问题), similar_questions(相似问法), answers(答案), + 默认搜索全部' + in: query + name: search_field + type: string + - description: '排序方式: asc(按更新时间正序), 默认按更新时间倒序' + in: query + name: sort_order + type: string produces: - application/json responses: @@ -2993,6 +3014,43 @@ paths: tags: - FAQ管理 /knowledge-bases/{id}/faq/entries/{entry_id}: + get: + consumes: + - application/json + description: 根据ID获取单个FAQ条目的详情 + parameters: + - description: 知识库ID + in: path + name: id + required: true + type: string + - description: FAQ条目ID + in: path + name: entry_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: FAQ条目详情 + schema: + additionalProperties: true + type: object + "400": + description: 请求参数错误 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + "404": + description: 条目不存在 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + security: + - Bearer: [] + - ApiKeyAuth: [] + summary: 获取FAQ条目详情 + tags: + - FAQ管理 put: consumes: - application/json @@ -3503,7 +3561,7 @@ paths: delete: consumes: - application/json - description: 删除标签，可使用force=true强制删除被引用的标签 + description: 删除标签，可使用force=true强制删除被引用的标签，content_only=true仅删除标签下的内容而保留标签本身 parameters: - description: 知识库ID in: path @@ -3519,6 +3577,10 @@ paths: in: query name: force type: boolean + - description: 仅删除内容，保留标签 + in: query + name: content_only + type: boolean produces: - application/json responses: