opensource/WeKnora
3
0
Fork 0
mirror of https://github.com/Tencent/WeKnora.git synced 2026-09-24 16:29:01 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d4edd374dfd14bb475eb430f0ae4d8f2bcb8a2aa
WeKnora/docs/api/knowledge-base.md
T

729 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 知识库管理 API
[返回目录](./README.md)
**字段说明（知识库对象）**
- 知识库类型 `type` 为 `document`（文档）或 `faq`（FAQ），默认 `document`。
- JSON 中对象存储相关字段：**`storage_config`** 为序列化字段名（对应数据库列 `cos_config`，兼容旧数据）。旧客户端若仍发送或接收 `cos_config`，服务端会兼容解析；新集成请使用 **`storage_config`**。
- **`storage_provider_config`** 为新版存储提供者选择（如 `{"provider": "local"}`），与租户级存储引擎凭证配合使用；无配置时可为 `null`。
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------ | ------------------------ |
| POST | `/knowledge-bases` | 创建知识库 |
| GET | `/knowledge-bases` | 获取知识库列表 |
| GET | `/knowledge-bases/:id` | 获取知识库详情 |
| PUT | `/knowledge-bases/:id` | 更新知识库 |
| DELETE | `/knowledge-bases/:id` | 删除知识库 |
| POST | `/knowledge-bases/copy` | 拷贝知识库 |
| GET | `/knowledge-bases/copy/progress/:task_id` | 获取拷贝进度 |
| GET | `/knowledge-bases/:id/hybrid-search` | 混合搜索（向量+关键词） |
| PUT | `/knowledge-bases/:id/pin` | 置顶/取消置顶知识库 |
| GET | `/knowledge-bases/:id/move-targets` | 获取可迁移目标知识库列表 |
## 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",
"type": "document",
"is_temporary": false,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"."
],
"enable_multimodal": true,
"parser_engine_rules": [
{
"file_types": [".pdf", ".docx"],
"engine": "builtin"
}
],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": true,
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": {
"enabled": false,
"question_count": 3
}
}'
```
**响应**:
```json
{
"data": {
"id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0",
"name": "weknora",
"description": "weknora description",
"type": "document",
"is_temporary": false,
"tenant_id": 1,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"."
],
"enable_multimodal": true,
"parser_engine_rules": [
{
"file_types": [".pdf", ".docx"],
"engine": "builtin"
}
],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": true,
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": {
"enabled": false,
"question_count": 3
},
"is_pinned": false,
"pinned_at": null,
"knowledge_count": 0,
"chunk_count": 0,
"processing_count": 0,
"created_at": "2025-08-12T11:30:09.206238645+08:00",
"updated_at": "2025-08-12T11:30:09.206238854+08:00",
"deleted_at": null
},
"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",
"type": "document",
"is_temporary": false,
"tenant_id": 1,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"\n\n",
"\n",
"。",
"！",
"？",
";",
"；"
],
"enable_multimodal": true,
"parser_engine_rules": [],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": ""
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": true,
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": null,
"is_pinned": false,
"pinned_at": null,
"knowledge_count": 12,
"chunk_count": 340,
"processing_count": 0,
"created_at": "2025-08-11T20:10:41.817794+08:00",
"updated_at": "2025-08-12T11:23:00.593097+08:00",
"deleted_at": null
}
],
"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",
"type": "document",
"is_temporary": false,
"tenant_id": 1,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"\n\n",
"\n",
"。",
"！",
"？",
";",
"；"
],
"enable_multimodal": true,
"parser_engine_rules": [],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": ""
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": true,
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": {
"enabled": false,
"text": "",
"tags": [],
"nodes": [],
"relations": []
},
"faq_config": null,
"question_generation_config": null,
"is_pinned": false,
"pinned_at": null,
"knowledge_count": 12,
"chunk_count": 340,
"processing_count": 0,
"created_at": "2025-08-11T20:10:41.817794+08:00",
"updated_at": "2025-08-12T11:23:00.593097+08:00",
"deleted_at": null
},
"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,
"parser_engine_rules": [
{
"file_types": [".md", ".txt"],
"engine": "builtin"
}
],
"enable_parent_child": true,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": ""
}
}
}'
```
**响应**:
```json
{
"data": {
"id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0",
"name": "weknora new",
"description": "weknora description new",
"type": "document",
"is_temporary": false,
"tenant_id": 1,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"\n\n",
"\n",
"。",
"！",
"？",
";",
"；"
],
"enable_multimodal": true,
"parser_engine_rules": [
{
"file_types": [".md", ".txt"],
"engine": "builtin"
}
],
"enable_parent_child": true,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": ""
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": true,
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": null,
"is_pinned": false,
"pinned_at": null,
"knowledge_count": 3,
"chunk_count": 48,
"processing_count": 1,
"created_at": "2025-08-12T11:30:09.206238+08:00",
"updated_at": "2025-08-12T11:36:09.083577609+08:00",
"deleted_at": null
},
"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
}
```
## POST `/knowledge-bases/copy` - 拷贝知识库
异步拷贝一个知识库，包括知识库配置和所有知识内容。返回任务ID用于查询拷贝进度。
**请求参数**:
- `source_id`: 源知识库ID（必填）
- `name`: 新知识库名称（可选，默认使用原名称加"(副本)"后缀）
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/copy' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json' \
--data '{
"source_id": "kb-00000001",
"name": "知识库副本"
}'
```
**响应**:
```json
{
"data": {
"task_id": "task-copy-00000001",
"target_id": "kb-00000002"
},
"success": true
}
```
## GET `/knowledge-bases/copy/progress/:task_id` - 获取拷贝进度
查询知识库拷贝任务的执行进度。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/copy/progress/task-copy-00000001' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"task_id": "task-copy-00000001",
"status": "completed",
"total": 10,
"finished": 10,
"source_id": "kb-00000001",
"target_id": "kb-00000002"
},
"success": true
}
```
注：`status` 可能的值为 `pending`、`processing`、`completed`、`failed`。
## 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
}
```
## PUT `/knowledge-bases/:id/pin` - 置顶/取消置顶知识库
切换知识库的置顶状态。无需请求体，每次调用会自动切换当前置顶状态。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/pin' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"id": "kb-00000001",
"name": "Default Knowledge Base",
"description": "System Default Knowledge Base",
"type": "document",
"is_temporary": false,
"tenant_id": 1,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": ["\n\n", "\n", "。", "！", "？", ";", "；"],
"enable_multimodal": true,
"parser_engine_rules": [],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": ""
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": true,
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": null,
"is_pinned": true,
"pinned_at": "2025-08-12T15:00:00.000000+08:00",
"knowledge_count": 12,
"chunk_count": 340,
"processing_count": 0,
"created_at": "2025-08-11T20:10:41.817794+08:00",
"updated_at": "2025-08-12T15:00:00.000000+08:00",
"deleted_at": null
},
"success": true
}
```
## GET `/knowledge-bases/:id/move-targets` - 获取可迁移目标知识库列表
获取当前知识库可以迁移知识到的目标知识库列表。返回结果会排除当前知识库本身。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/move-targets' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"id": "kb-00000002",
"name": "技术文档知识库",
"description": "技术文档相关知识",
"type": "document",
"is_temporary": false,
"tenant_id": 1,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": ["\n\n", "\n"],
"enable_multimodal": true,
"parser_engine_rules": [],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": ""
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": false,
"model_id": ""
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": null,
"is_pinned": false,
"pinned_at": null,
"knowledge_count": 8,
"chunk_count": 210,
"processing_count": 0,
"created_at": "2025-08-12T11:30:09.206238+08:00",
"updated_at": "2025-08-12T11:30:09.206238+08:00",
"deleted_at": null
}
],
"success": true
}
```
Reference in New Issue View Git Blame Copy Permalink