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": "