知识库管理

架构概述

知识库管理系统基于多层架构构建，区分了API端点、业务逻辑、数据持久化和存储后端之间的关注点。

知识库管理架构

来源：api/apps/kb_app.py1-358 api/apps/sdk/doc.py1-2269 api/db/services/knowledgebase_service.py1-439 rag/utils/es_conn.py1-564 rag/utils/infinity_conn.py1-704 rag/utils/minio_conn.py1-131

知识库CRUD操作

核心知识库管理

KnowledgebaseService提供了知识库操作的主要接口，负责创建、更新、访问控制和删除。

操作	端点	服务方法	描述
创建	`POST /v1/kb/create`	`KnowledgebaseService.save()`	创建新的知识库
读取	`GET /v1/kb/detail`	`KnowledgebaseService.get_detail()`	检索KB详情
更新	`POST /v1/kb/update`	`KnowledgebaseService.update_by_id()`	更新KB配置
删除	`POST /v1/kb/rm`	`KnowledgebaseService.delete_by_id()`	删除KB和文档
列表	`POST /v1/kb/list`	`KnowledgebaseService.get_by_tenant_ids()`	列出用户的KB

知识库配置

知识库支持各种配置选项

解析器配置：通过parser_config字段进行文档解析设置
嵌入模型：通过embd_id字段配置
语言设置：文档处理的语言偏好
访问权限：团队与个人访问控制
PageRank设置：搜索排名配置

访问控制和多租户

系统实现基于租户的访问控制，用户只能访问其授权租户内的知识库

来源：api/apps/kb_app.py40-74 api/db/services/knowledgebase_service.py45-78 api/db/services/knowledgebase_service.py360-374

文档管理

文档上传和存储

文档管理遵循一个涉及文件存储、元数据跟踪和内容索引的多阶段过程

来源：api/apps/sdk/doc.py67-171 api/db/services/file_service.py1-50 api/db/services/document_service.py1-50

文档生命周期管理

文档在处理过程中会经历几个状态

状态	代码	描述
UNSTART	0	文档已上传，尚未解析
RUNNING	1	正在处理中
CANCEL	2	处理已取消
DONE	3	成功处理
FAIL	4	处理失败

系统会跟踪解析进度，并通过progress字段（0.0到1.0）提供实时状态更新。

分块管理

文档被处理成可搜索的块，操作如下

解析文档：POST /datasets/{id}/chunks - 启动文档解析
停止解析：DELETE /datasets/{id}/chunks - 取消正在进行的解析
列出块：GET /datasets/{id}/documents/{doc_id}/chunks - 检索文档块
添加块：POST /datasets/{id}/documents/{doc_id}/chunks - 手动添加块
更新块：PUT /datasets/{id}/documents/{doc_id}/chunks/{chunk_id} - 修改块内容

来源：api/apps/sdk/doc.py657-809 api/apps/sdk/doc.py811-976

文件存储集成

多后端存储架构

系统集成多个存储后端以处理不同类型的数据

存储后端配置

系统支持可配置的文档存储引擎

Elasticsearch：具有向量功能的传统全文搜索
Infinity：专用于高性能相似性搜索的向量数据库
MinIO：S3兼容的对象存储，用于文件内容

后端选择通过环境变量配置控制，支持自动模式迁移和索引管理。

来源：rag/utils/minio_conn.py26-131 rag/utils/es_conn.py40-564 rag/utils/infinity_conn.py127-704

数据模型和服务

核心数据模型

知识库系统使用几个相互关联的模型

模型	目的	关键字段
`Knowledgebase`	KB元数据和配置	`id`, `name`, `tenant_id`, `parser_id`, `embd_id`
`文档`	文档元数据和状态	`id`, `kb_id`, `name`, `chunk_num`, `token_num`, `progress`
`文件`	文件存储信息	`id`, `name`, `location`, `size`, `type`
`File2Document`	文件到文档的映射	`file_id`, `document_id`

服务层架构

服务实现业务逻辑，并协调API端点和数据模型之间的关系

KnowledgebaseService：KB生命周期、权限、配置管理
DocumentService：文档CRUD、状态跟踪、元数据管理
FileService：文件上传、存储、检索操作
File2DocumentService：维护文件-文档关系

索引管理

系统自动管理搜索索引，并提供可配置的模式

索引创建：createIdx() - 创建具有正确映射的索引
模式迁移：为新功能自动添加字段
向量配置：基于嵌入模型的动态向量维度
清理：deleteIdx() - 在删除知识库时删除索引

来源： api/db/services/knowledgebase_service.py26-439 conf/infinity_mapping.json1-45 conf/mapping.json1-212

API 端点

知识库 API 路由

知识库管理系统通过 Flask Blueprint 管理器公开 REST 端点

方法	路由	处理器	描述
POST	`/v1/kb/create`	`create()`	创建知识库
POST	`/v1/kb/update`	`update()`	更新知识库
GET	`/v1/kb/detail`	`detail()`	获取 KB 详情
POST	`/v1/kb/list`	`list_kbs()`	列出知识库
POST	`/v1/kb/rm`	`rm()`	删除知识库
GET	`/v1/kb/{kb_id}/tags`	`list_tags()`	获取 KB 标签
POST	`/v1/kb/{kb_id}/rm_tags`	`rm_tags()`	移除标签
GET	`/v1/kb/{kb_id}/knowledge_graph`	`knowledge_graph()`	获取知识图谱

文档 API 路由

文档管理提供全面的 CRUD 操作

方法	路由	处理器	描述
POST	`/datasets/{dataset_id}/documents`	`upload()`	上传文档
GET	`/datasets/{dataset_id}/documents`	`list_docs()`	列出文档
PUT	`/datasets/{dataset_id}/documents/{document_id}`	`update_doc()`	更新文档
GET	`/datasets/{dataset_id}/documents/{document_id}`	`download()`	下载文档
DELETE	`/datasets/{dataset_id}/documents`	`delete()`	删除文档
POST	`/datasets/{dataset_id}/chunks`	`parse()`	开始解析
DELETE	`/datasets/{dataset_id}/chunks`	`stop_parsing()`	停止解析

SDK 集成

该系统提供 Python SDK 集成以实现程序化访问，可以通过 SDK 方法访问相同的 REST 端点，用于自动化知识库管理。

来源： api/apps/kb_app.py40-358 api/apps/sdk/doc.py67-2269