PoJie/ruoyi-modules/ruoyi-knowledge

RuoYi Knowledge 模块

概述

RuoYi Knowledge 模块是一个智能知识库管理系统，提供知识库的创建、管理、向量化处理和智能检索功能。该模块支持多种文档格式，具备强大的向量搜索能力，为AI问答系统提供知识基础。

目录结构

ruoyi-knowledge/
├─ src/main/java/org/dromara/knowledge/
│  ├─ data/           # 文档解析与数据清洗（PDF/Word/Excel等）
│  ├─ embedding/      # 文本向量化引擎接口（多模型可插拔）
│  ├─ retrieval/      # 检索器与索引更新（支持多后端）
│  ├─ generation/     # 响应生成（LLM集成与后处理）
│  ├─ version/        # 版本管理与回滚接口
│  └─ config/         # RAG 配置属性（rag.*）
├─ docs/              # API/设计/配置文档
└─ src/test/java/org/dromara/knowledge/
   ├─ unit/           # 单元测试
   ├─ integration/    # 集成测试
   └─ mock/           # 测试用 Mock 数据

核心特性

📚 知识库管理

• ✅ 知识库创建和配置（名称、描述、向量模型、分片参数等）
• ✅ 知识库列表查询（分页、筛选）
• ✅ 知识库信息更新和删除
• ✅ 知识库状态查询
• ✅ 用户知识库列表查询
• ✅ 知识库公开/私有设置

📄 文档处理

• ✅ 文档上传（单文件、批量上传）
• ✅ 多格式文档支持（PDF、Word、TXT、Markdown、Excel、CSV、HTML等）
• ✅ 自动文档解析（通过DocumentParser接口，支持多种格式）
• ✅ 智能分片处理（可配置分片大小、重叠字符数）
• ✅ 文档解析状态跟踪（拆解图片状态、分析图片状态、向量化状态）
• ✅ 文档列表查询和管理

📑 知识片段管理

• ✅ 片段列表查询（分页、筛选）
• ✅ 片段信息查询和管理
• ✅ 片段创建、更新、删除
• ✅ 根据知识库/文档ID查询片段列表

⚡ 向量化处理

• ✅ 向量生成（单片段、批量生成）
• ✅ 多种嵌入模型支持（通过EmbeddingEngine接口，支持模型扩展）
• ✅ 文档批量向量化
• ✅ 向量列表查询和管理
• ✅ 向量索引重建
• ✅ 向量统计信息查询

🔍 智能检索

• ✅ 基于向量的语义搜索（向量相似度搜索）
• ✅ 相似度排序
• ✅ 检索结果过滤（按文档去重）
• ✅ 检索器接口可插拔（Retriever），默认实现调用向量服务
• ✅ 检索命中日志记录和分析

📊 任务管理

• ✅ 任务创建和查询（支持多种任务类型：upload、process、delete、export、embedding、sync）
• ✅ 任务状态跟踪（等待、进行中、成功、失败、暂停）
• ✅ 任务进度管理（进度百分比、总项目数、已处理项目数等）
• ✅ 任务重试机制（重试次数、最大重试次数）
• ✅ 任务错误信息记录
• ✅ 任务通知机制（通知URL、通知状态）

💡 提示词模板管理

• ✅ 模板创建和配置
• ✅ 模板列表查询（分页、筛选）
• ✅ 模板更新和删除
• ✅ 按分类查询模板（knowledge、chat、draw）
• ✅ 按模板名称查询

🎯 数据模型管理

• ✅ 模型分组管理（分组创建、查询、更新、删除）
• ✅ 数据模型管理（模型创建、查询、更新、删除）
• ✅ 模型字段管理（字段创建、查询、更新、删除）
• ✅ 灵活的Schema定义（字段类型、属性配置）
• ✅ 字段类型支持（文本、数字、日期等）
• ✅ 字段属性配置（是否主键、是否必填、是否唯一、默认值、长度等）
• ✅ 字段显示配置（是否列表显示、是否查询字段、是否插入字段、是否编辑字段）
• ✅ 查询方式配置（EQ、NE、GT、LT、LIKE、BETWEEN）
• ✅ 显示类型配置（input、textarea、select、checkbox、radio、datetime、image、upload、editor）
• ✅ 字典类型支持

👥 角色与权限管理

• ✅ 角色组管理（Service层已实现）
• ✅ 角色管理（Service层已实现）
• ✅ 角色与知识库关联管理（Service层已实现）
• ⚠️ 角色管理Controller（待实现，目前只有Service层）

📈 检索日志与分析

• ✅ 命中日志记录（记录每次检索的详细信息）
• ✅ 命中日志查询（按知识库、会话、片段、查询文本筛选）
• ✅ 热门查询统计
• ✅ 平均响应时间分析
• ✅ 日志导出功能

🔧 RAG架构组件

• ✅ 文档解析器接口（DocumentParser）及多种实现（PDF、Word、Excel、Text、Markdown、CSV、HTML）
• ✅ 向量化引擎接口（EmbeddingEngine）及HTTP实现（HttpEmbeddingService）
• ✅ 检索器接口（Retriever）及默认实现（DefaultRetriever）
• ✅ 索引更新器接口（IndexUpdater）及默认实现（DefaultIndexUpdater）
• ✅ 响应生成器接口（Generator）及默认实现（DefaultGenerator）
• ✅ 版本管理器接口（VersionManager）及默认实现（DefaultVersionManager）
• ✅ 向量存储服务接口（VectorStoreService）及多种实现（DbVectorStoreService、QdrantVectorStoreService、WeaviateVectorStoreService）

架构设计

┌─────────────────────────────────────────────────────────────┐
│                  Knowledge Controller Layer                 │
├─────────────────────────────────────────────────────────────┤
│  KnowledgeInfoController   │ KnowledgeAttachController      │
│  KnowledgeFragmentController │ KnowledgeSchemaController    │
│  KnowledgeRoleController   │ KnowledgeVectorController      │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                    Service Layer                            │
├─────────────────────────────────────────────────────────────┤
│  KnowledgeInfoService      │ KnowledgeAttachService         │
│  KnowledgeFragmentService  │ KnowledgeSchemaService         │
│  KnowledgeVectorService    │ KnowledgeRoleService           │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                 Processing Layer                            │
├─────────────────────────────────────────────────────────────┤
│  Document Parser   │ Vector Processor │ Search Engine       │
│  Embedding Models  │ Index Manager    │ Cache Manager       │
└─────────────────────────────────────────────────────────────┘

主要组件

控制器 (Controllers)

KnowledgeInfoController

知识库信息管理控制器，路径：/knowledge/info

主要接口：

• GET /knowledge/info/list - 查询知识库信息列表（分页，支持筛选）
• POST /knowledge/info/export - 导出知识库信息列表（需要权限 knowledge:info:export）
• GET /knowledge/info/{knowledgeId} - 获取知识库信息详细信息（需要权限 knowledge:info:query）
• POST /knowledge/info - 新增知识库信息（需要权限 knowledge:info:add）
• PUT /knowledge/info - 修改知识库信息（需要权限 knowledge:info:edit）
• DELETE /knowledge/info/{knowledgeIds} - 删除知识库信息（需要权限 knowledge:info:remove）
• GET /knowledge/info/user/{userId} - 根据用户ID查询知识库信息列表（需要权限 knowledge:info:query）
• GET /knowledge/info/knowledge/{knowledgeId} - 根据知识库ID查询知识库信息（需要权限 knowledge:info:query）
• POST /knowledge/info/{knowledgeId}/upload - 上传文档到知识库（需要权限 knowledge:info:upload）
• POST /knowledge/info/{knowledgeId}/batch-upload - 批量上传文档到知识库（需要权限 knowledge:info:upload）
• POST /knowledge/info/{knowledgeId}/search - 检索知识库（需要权限 knowledge:info:search）
• GET /knowledge/info/{knowledgeId}/status - 获取知识库处理状态（需要权限 knowledge:info:query）

KnowledgeAttachController

知识库附件管理控制器，路径：/knowledge/attach

主要接口：

• GET /knowledge/attach/list - 查询知识库附件列表（分页，需要权限 knowledge:attach:list）
• POST /knowledge/attach/export - 导出知识库附件列表（需要权限 knowledge:attach:export）
• GET /knowledge/attach/{attachId} - 获取知识库附件详细信息（需要权限 knowledge:attach:query）
• POST /knowledge/attach - 新增知识库附件（需要权限 knowledge:attach:add）
• PUT /knowledge/attach - 修改知识库附件（需要权限 knowledge:attach:edit）
• DELETE /knowledge/attach/{attachIds} - 删除知识库附件（需要权限 knowledge:attach:remove）
• GET /knowledge/attach/knowledge/{knowledgeId} - 根据知识库ID查询附件列表（需要权限 knowledge:attach:query）
• GET /knowledge/attach/document/{documentId} - 根据文档ID查询附件信息（需要权限 knowledge:attach:query）

KnowledgeFragmentController

知识库片段管理控制器，路径：/knowledge/fragment

主要接口：

• GET /knowledge/fragment/list - 查询知识库片段列表（分页，需要权限 knowledge:fragment:list）
• POST /knowledge/fragment/export - 导出知识库片段列表（需要权限 knowledge:fragment:export）
• GET /knowledge/fragment/{fragmentId} - 获取知识库片段详细信息（需要权限 knowledge:fragment:query）
• POST /knowledge/fragment - 新增知识库片段（需要权限 knowledge:fragment:add）
• PUT /knowledge/fragment - 修改知识库片段（需要权限 knowledge:fragment:edit）
• DELETE /knowledge/fragment/{fragmentIds} - 删除知识库片段（需要权限 knowledge:fragment:remove）
• GET /knowledge/fragment/knowledge/{knowledgeId} - 根据知识库ID查询片段列表（需要权限 knowledge:fragment:query）
• GET /knowledge/fragment/document/{documentId} - 根据文档ID查询片段列表（需要权限 knowledge:fragment:query）
• GET /knowledge/fragment/fragment/{fragmentId} - 根据片段ID查询片段信息（需要权限 knowledge:fragment:query）

KnowledgeVectorController

向量管理控制器，路径：/knowledge/vector

主要接口：

• POST /knowledge/vector/generate - 生成向量（批量生成片段向量）
• POST /knowledge/vector/search - 向量搜索（向量相似度搜索，支持按文档去重）
• GET /knowledge/vector/stats/{knowledgeId} - 向量统计（获取向量统计信息）
• POST /knowledge/vector/rebuild/{knowledgeId} - 重建索引（重建向量索引）
• POST /knowledge/vector/vectorize-doc - 文档批量向量化（对文档的所有片段进行向量化）
• GET /knowledge/vector/list - 查询知识库向量列表（分页，需要权限 knowledge:vector:list）
• POST /knowledge/vector/export - 导出知识库向量列表（需要权限 knowledge:vector:export）
• GET /knowledge/vector/{vectorId} - 获取知识库向量详细信息（需要权限 knowledge:vector:query）
• POST /knowledge/vector - 新增知识库向量（需要权限 knowledge:vector:add）
• PUT /knowledge/vector - 修改知识库向量（需要权限 knowledge:vector:edit）
• DELETE /knowledge/vector/{vectorIds} - 删除知识库向量（需要权限 knowledge:vector:remove）
• GET /knowledge/vector/fragment/{fragmentId} - 根据片段ID查询向量列表（需要权限 knowledge:vector:query）
• GET /knowledge/vector/knowledge/{knowledgeId} - 根据知识库ID查询向量列表（需要权限 knowledge:vector:query）

KnowledgeHitLogController

知识库命中日志控制器，路径：/knowledge/hitlog

主要接口：

• GET /knowledge/hitlog/list - 查询命中日志列表（分页，需要权限 knowledge:hitlog:list）
• POST /knowledge/hitlog/export - 导出命中日志列表（需要权限 knowledge:hitlog:export）
• GET /knowledge/hitlog/{logId} - 获取命中日志详细信息（需要权限 knowledge:hitlog:query）
• POST /knowledge/hitlog - 新增命中日志（需要权限 knowledge:hitlog:add）
• PUT /knowledge/hitlog - 修改命中日志（需要权限 knowledge:hitlog:edit）
• DELETE /knowledge/hitlog/{logIds} - 删除命中日志（需要权限 knowledge:hitlog:remove）
• GET /knowledge/hitlog/knowledge/{knowledgeId} - 根据知识库ID查询命中日志列表（需要权限 knowledge:hitlog:query）
• GET /knowledge/hitlog/session/{sessionId} - 根据会话ID查询命中日志列表（需要权限 knowledge:hitlog:query）
• GET /knowledge/hitlog/fragment/{fragmentId} - 根据片段ID查询命中日志列表（需要权限 knowledge:hitlog:query）
• GET /knowledge/hitlog/query/{queryText} - 根据查询文本查询命中日志列表（需要权限 knowledge:hitlog:query）
• GET /knowledge/hitlog/popular - 获取热门查询列表（需要权限 knowledge:hitlog:query，参数：knowledgeId（可选）、limit（默认10））
• GET /knowledge/hitlog/avg-response-time - 获取平均响应时间（需要权限 knowledge:hitlog:query，参数：knowledgeId（可选））

KnowledgeJobController

知识库任务管理控制器，路径：/knowledge/job

主要接口：

• GET /knowledge/job/list - 查询知识库任务列表（分页，需要权限 knowledge:job:list）
• POST /knowledge/job/export - 导出知识库任务列表（需要权限 knowledge:job:export）
• GET /knowledge/job/{jobId} - 获取知识库任务详细信息（需要权限 knowledge:job:query）
• POST /knowledge/job - 新增知识库任务（需要权限 knowledge:job:add）
• PUT /knowledge/job - 修改知识库任务（需要权限 knowledge:job:edit）
• DELETE /knowledge/job/{jobIds} - 删除知识库任务（需要权限 knowledge:job:remove）
• GET /knowledge/job/knowledge/{knowledgeId} - 根据知识库ID查询任务列表（需要权限 knowledge:job:query）
• GET /knowledge/job/status/{status} - 根据任务状态查询任务列表（需要权限 knowledge:job:query）
• GET /knowledge/job/type/{jobType} - 根据任务类型查询任务列表（需要权限 knowledge:job:query）

KnowledgePromptTemplateController

知识库提示词模板管理控制器，路径：/knowledge/prompt

主要接口：

• GET /knowledge/prompt/list - 查询知识库提示模板列表（分页，需要权限 knowledge:prompt:list）
• POST /knowledge/prompt/export - 导出知识库提示模板列表（需要权限 knowledge:prompt:export）
• GET /knowledge/prompt/{templateId} - 获取知识库提示模板详细信息（需要权限 knowledge:prompt:query）
• POST /knowledge/prompt - 新增知识库提示模板（需要权限 knowledge:prompt:add）
• PUT /knowledge/prompt - 修改知识库提示模板（需要权限 knowledge:prompt:edit）
• DELETE /knowledge/prompt/{templateIds} - 删除知识库提示模板（需要权限 knowledge:prompt:remove）
• GET /knowledge/prompt/category/{category} - 根据分类查询提示模板列表（需要权限 knowledge:prompt:query）
• GET /knowledge/prompt/name/{templateName} - 根据模板名称查询提示模板（需要权限 knowledge:prompt:query）

KnowledgeSchemaController

知识库数据模型管理控制器，路径：/knowledge/schema

主要接口：

• GET /knowledge/schema/list - 查询知识库模式列表（分页，需要权限 knowledge:schema:list）
• POST /knowledge/schema/export - 导出知识库模式列表（需要权限 knowledge:schema:export）
• GET /knowledge/schema/{schemaId} - 获取知识库模式详细信息（需要权限 knowledge:schema:query）
• POST /knowledge/schema - 新增知识库模式（需要权限 knowledge:schema:add）
• PUT /knowledge/schema - 修改知识库模式（需要权限 knowledge:schema:edit）
• DELETE /knowledge/schema/{schemaIds} - 删除知识库模式（需要权限 knowledge:schema:remove）
• GET /knowledge/schema/id/{id} - 根据ID查询模式信息（需要权限 knowledge:schema:query）
• GET /knowledge/schema/group/{schemaGroupId} - 根据模式组ID查询模式列表（需要权限 knowledge:schema:query）
• GET /knowledge/schema/code/{code} - 根据编码查询模式信息（需要权限 knowledge:schema:query）
• GET /knowledge/schema/table/{tableName} - 根据表名查询模式信息（需要权限 knowledge:schema:query）

KnowledgeSchemaGroupController

知识库数据模型分组管理控制器，路径：/knowledge/schema/group

主要接口：

• GET /knowledge/schema/group/list - 查询知识库模式组列表（分页，需要权限 knowledge:schema:group:list）
• POST /knowledge/schema/group/export - 导出知识库模式组列表（需要权限 knowledge:schema:group:export）
• GET /knowledge/schema/group/{groupId} - 获取知识库模式组详细信息（需要权限 knowledge:schema:group:query）
• POST /knowledge/schema/group - 新增知识库模式组（需要权限 knowledge:schema:group:add）
• PUT /knowledge/schema/group - 修改知识库模式组（需要权限 knowledge:schema:group:edit）
• DELETE /knowledge/schema/group/{groupIds} - 删除知识库模式组（需要权限 knowledge:schema:group:remove）
• GET /knowledge/schema/group/id/{id} - 根据ID查询模式组信息（需要权限 knowledge:schema:group:query）
• GET /knowledge/schema/group/code/{code} - 根据编码查询模式组信息（需要权限 knowledge:schema:group:query）
• GET /knowledge/schema/group/name/{name} - 根据名称查询模式组信息（需要权限 knowledge:schema:group:query）

KnowledgeSchemaFieldController

知识库数据模型字段管理控制器，路径：/knowledge/schema/field

主要接口：

• GET /knowledge/schema/field/list - 查询知识库模式字段列表（分页，需要权限 knowledge:schema:field:list）
• POST /knowledge/schema/field/export - 导出知识库模式字段列表（需要权限 knowledge:schema:field:export）
• GET /knowledge/schema/field/{fieldId} - 获取知识库模式字段详细信息（需要权限 knowledge:schema:field:query）
• POST /knowledge/schema/field - 新增知识库模式字段（需要权限 knowledge:schema:field:add）
• PUT /knowledge/schema/field - 修改知识库模式字段（需要权限 knowledge:schema:field:edit）
• DELETE /knowledge/schema/field/{fieldIds} - 删除知识库模式字段（需要权限 knowledge:schema:field:remove）
• GET /knowledge/schema/field/id/{id} - 根据ID查询字段信息（需要权限 knowledge:schema:field:query）
• GET /knowledge/schema/field/schema/{schemaId} - 根据模式ID查询字段列表（需要权限 knowledge:schema:field:query）
• GET /knowledge/schema/field/code/{code} - 根据编码查询字段信息（需要权限 knowledge:schema:field:query）
• GET /knowledge/schema/field/schema/{schemaId}/code/{code} - 根据模式ID和编码查询字段信息（需要权限 knowledge:schema:field:query）

服务层 (Services)

KnowledgeInfoService

知识库信息服务，核心业务逻辑实现。

主要方法：

// 查询知识库列表
TableDataInfo<KnowledgeInfoVo> queryPageList(KnowledgeInfoBo bo, PageQuery pageQuery);
List<KnowledgeInfoVo> queryList(KnowledgeInfoBo bo);

// 查询知识库
KnowledgeInfoVo queryById(Long id);
KnowledgeInfoVo queryByKnowledgeId(Long knowledgeId);

// 创建/更新/删除知识库
Boolean insertByBo(KnowledgeInfoBo bo);
Boolean updateByBo(KnowledgeInfoBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据用户ID查询知识库列表
List<KnowledgeInfoVo> queryListByUserId(Long userId);

// 上传文档
String uploadDocument(String knowledgeId, MultipartFile file);

// 批量上传文档
List<String> batchUploadDocuments(String knowledgeId, MultipartFile[] files);

// 搜索知识库
List<KnowledgeSearchResultVo> searchKnowledge(String knowledgeId, String query, Integer limit);

// 获取知识库处理状态
KnowledgeStatusVo getKnowledgeStatus(String knowledgeId);

// 处理文档并生成知识片段
String processDocument(String knowledgeId, String docId, String content);

// 对知识片段进行向量化
String vectorizeFragment(String knowledgeId, String fragmentId);

KnowledgeVectorService

向量化服务，处理文档向量化和搜索。

主要方法：

// 查询向量列表
TableDataInfo<KnowledgeVectorVo> queryPageList(KnowledgeVectorBo bo, PageQuery pageQuery);
List<KnowledgeVectorVo> queryList(KnowledgeVectorBo bo);

// 查询向量
KnowledgeVectorVo queryById(Long vectorId);

// 创建/更新/删除向量
Boolean insertByBo(KnowledgeVectorBo bo);
Boolean updateByBo(KnowledgeVectorBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 向量相似度搜索
List<KnowledgeSearchResultVo> vectorSimilaritySearch(String knowledgeId, String queryText,
    String modelName, Integer topK, Double threshold);

// 单片段向量生成
String generateVector(String knowledgeId, String docId, String fragmentId, String content, String modelName);

// 批量向量生成
List<String> batchGenerateVectors(String knowledgeId, String docId, 
    Map<String, String> fragmentContents, String modelName);

// 统计与可用性
Map<String, Object> getVectorStatistics(String knowledgeId);
boolean isModelAvailable(String modelName);
List<String> getAvailableModels();

// 根据片段ID/知识库ID/文档ID/模型名称/状态查询向量列表
List<KnowledgeVectorVo> queryByFragmentId(String fragmentId);
List<KnowledgeVectorVo> queryByKnowledgeId(String knowledgeId);
List<KnowledgeVectorVo> queryByDocId(String docId);
List<KnowledgeVectorVo> queryByModelName(String modelName);
List<KnowledgeVectorVo> queryByStatus(Integer status);
List<KnowledgeVectorVo> queryByKnowledgeIdAndStatus(String knowledgeId, Integer status);

// 根据向量ID查询向量
KnowledgeVectorVo queryByVectorId(String vectorId);

// 批量更新向量状态
Boolean updateStatusByIds(Collection<Long> ids, Integer status);

// 文本转向量和相似度计算
double[] textToVector(String text, String modelName);
double calculateSimilarity(double[] vector1, double[] vector2);

// 批量删除向量
int deleteVectorsByKnowledgeId(String knowledgeId);
int deleteVectorsByDocId(String docId);

KnowledgeFragmentService

知识片段管理服务。

主要方法：

// 查询知识片段列表
TableDataInfo<KnowledgeFragmentVo> queryPageList(KnowledgeFragmentBo bo, PageQuery pageQuery);
List<KnowledgeFragmentVo> queryList(KnowledgeFragmentBo bo);

// 查询知识片段
KnowledgeFragmentVo queryById(Long fragmentId);
KnowledgeFragmentVo queryByFid(String fid);

// 创建/更新/删除知识片段
Boolean insertByBo(KnowledgeFragmentBo bo);
Boolean updateByBo(KnowledgeFragmentBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据知识库ID/文档ID查询片段列表
List<KnowledgeFragmentVo> queryListByKnowledgeId(Long knowledgeId);
List<KnowledgeFragmentVo> queryListByDocId(String docId);

KnowledgeAttachService

知识库附件管理服务。

主要方法：

// 查询附件列表
TableDataInfo<KnowledgeAttachVo> queryPageList(KnowledgeAttachBo bo, PageQuery pageQuery);
List<KnowledgeAttachVo> queryList(KnowledgeAttachBo bo);

// 查询附件
KnowledgeAttachVo queryById(Long attachId);
KnowledgeAttachVo queryByDocId(String docId);

// 创建/更新/删除附件
Boolean insertByBo(KnowledgeAttachBo bo);
Boolean updateByBo(KnowledgeAttachBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据知识库ID查询附件列表
List<KnowledgeAttachVo> queryListByKnowledgeId(String knowledgeId);

KnowledgeDocumentService

文档处理服务，处理文档上传、解析和分片。

主要方法：

// 上传文档并处理
String uploadDocument(String knowledgeId, MultipartFile file);

// 批量上传文档
List<String> batchUploadDocuments(String knowledgeId, MultipartFile[] files);

// 分割文档为片段
List<String> splitDocumentIntoFragments(String knowledgeId, String docId, 
    String content, Integer chunkSize, Integer overlapSize);

KnowledgeJobService

任务管理服务，处理知识库处理任务的创建、查询和状态管理。

主要方法：

// 查询任务列表
TableDataInfo<KnowledgeJobVo> queryPageList(KnowledgeJobBo bo, PageQuery pageQuery);
List<KnowledgeJobVo> queryList(KnowledgeJobBo bo);

// 查询任务
KnowledgeJobVo queryById(Long jobId);

// 创建/更新/删除任务
Boolean insertByBo(KnowledgeJobBo bo);
Boolean updateByBo(KnowledgeJobBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据知识库ID/状态/类型查询任务
List<KnowledgeJobVo> queryByKnowledgeId(String knowledgeId);
List<KnowledgeJobVo> queryByStatus(Integer status);
List<KnowledgeJobVo> queryByJobType(String jobType);

KnowledgePromptTemplateService

提示词模板管理服务。

主要方法：

// 查询模板列表
TableDataInfo<KnowledgePromptTemplateVo> queryPageList(KnowledgePromptTemplateBo bo, PageQuery pageQuery);
List<KnowledgePromptTemplateVo> queryList(KnowledgePromptTemplateBo bo);

// 查询模板
KnowledgePromptTemplateVo queryById(Long templateId);
KnowledgePromptTemplateVo queryByTemplateName(String templateName);

// 创建/更新/删除模板
Boolean insertByBo(KnowledgePromptTemplateBo bo);
Boolean updateByBo(KnowledgePromptTemplateBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据分类查询模板列表
List<KnowledgePromptTemplateVo> queryListByCategory(String category);

KnowledgeSchemaService

数据模型管理服务。

主要方法：

// 查询模型列表
TableDataInfo<KnowledgeSchemaVo> queryPageList(KnowledgeSchemaBo bo, PageQuery pageQuery);
List<KnowledgeSchemaVo> queryList(KnowledgeSchemaBo bo);

// 查询模型
KnowledgeSchemaVo queryById(Long schemaId);
KnowledgeSchemaVo queryByCode(String code);
KnowledgeSchemaVo queryByTableName(String tableName);

// 创建/更新/删除模型
Boolean insertByBo(KnowledgeSchemaBo bo);
Boolean updateByBo(KnowledgeSchemaBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据分组ID查询模型列表
List<KnowledgeSchemaVo> queryListBySchemaGroupId(Long schemaGroupId);

KnowledgeSchemaGroupService

数据模型分组管理服务。

主要方法：

// 查询分组列表
TableDataInfo<KnowledgeSchemaGroupVo> queryPageList(KnowledgeSchemaGroupBo bo, PageQuery pageQuery);
List<KnowledgeSchemaGroupVo> queryList(KnowledgeSchemaGroupBo bo);

// 查询分组
KnowledgeSchemaGroupVo queryById(Long groupId);
KnowledgeSchemaGroupVo queryByCode(String code);
KnowledgeSchemaGroupVo queryByName(String name);

// 创建/更新/删除分组
Boolean insertByBo(KnowledgeSchemaGroupBo bo);
Boolean updateByBo(KnowledgeSchemaGroupBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

KnowledgeSchemaFieldService

数据模型字段管理服务。

主要方法：

// 查询字段列表
TableDataInfo<KnowledgeSchemaFieldVo> queryPageList(KnowledgeSchemaFieldBo bo, PageQuery pageQuery);
List<KnowledgeSchemaFieldVo> queryList(KnowledgeSchemaFieldBo bo);

// 查询字段
KnowledgeSchemaFieldVo queryById(Long fieldId);
KnowledgeSchemaFieldVo queryByCode(String code);
KnowledgeSchemaFieldVo queryBySchemaIdAndCode(Long schemaId, String code);

// 创建/更新/删除字段
Boolean insertByBo(KnowledgeSchemaFieldBo bo);
Boolean updateByBo(KnowledgeSchemaFieldBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据模式ID查询字段列表
List<KnowledgeSchemaFieldVo> queryListBySchemaId(Long schemaId);

KnowledgeHitLogService

命中日志管理服务。

主要方法：

// 查询日志列表
TableDataInfo<KnowledgeHitLogVo> queryPageList(KnowledgeHitLogBo bo, PageQuery pageQuery);
List<KnowledgeHitLogVo> queryList(KnowledgeHitLogBo bo);

// 查询日志
KnowledgeHitLogVo queryById(Long logId);

// 创建/更新/删除日志
Boolean insertByBo(KnowledgeHitLogBo bo);
Boolean updateByBo(KnowledgeHitLogBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据知识库ID/会话ID/片段ID/查询文本查询日志
List<KnowledgeHitLogVo> queryByKnowledgeId(String knowledgeId);
List<KnowledgeHitLogVo> queryBySessionId(String sessionId);
List<KnowledgeHitLogVo> queryByFragmentId(String fragmentId);
List<KnowledgeHitLogVo> queryByQueryText(String queryText);

// 统计分析
List<Map<String, Object>> getPopularQueries(String knowledgeId, Integer limit);
Double getAverageResponseTime(String knowledgeId);

KnowledgeRoleService

角色管理服务（Service层已实现，Controller层待实现）。

主要方法：

// 查询角色列表
TableDataInfo<KnowledgeRoleVo> queryPageList(KnowledgeRoleBo bo, PageQuery pageQuery);
List<KnowledgeRoleVo> queryList(KnowledgeRoleBo bo);
List<KnowledgeRoleVo> queryEnabledList(); // 查询启用状态的角色列表

// 查询角色
KnowledgeRoleVo queryById(Long id);
KnowledgeRoleVo queryByRoleCode(String roleCode);

// 创建/更新/删除角色
Boolean insertByBo(KnowledgeRoleBo bo);
Boolean updateByBo(KnowledgeRoleBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

KnowledgeRoleGroupService

角色组管理服务（Service层已实现，Controller层待实现）。

主要方法：

// 查询角色组列表
TableDataInfo<KnowledgeRoleGroupVo> queryPageList(KnowledgeRoleGroupBo bo, PageQuery pageQuery);
List<KnowledgeRoleGroupVo> queryList(KnowledgeRoleGroupBo bo);

// 查询角色组
KnowledgeRoleGroupVo queryById(Long groupId);

// 创建/更新/删除角色组
Boolean insertByBo(KnowledgeRoleGroupBo bo);
Boolean updateByBo(KnowledgeRoleGroupBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

KnowledgeRoleRelationService

角色关联管理服务（Service层已实现，Controller层待实现）。

主要方法：

// 查询关联列表
TableDataInfo<KnowledgeRoleRelationVo> queryPageList(KnowledgeRoleRelationBo bo, PageQuery pageQuery);
List<KnowledgeRoleRelationVo> queryList(KnowledgeRoleRelationBo bo);

// 查询关联
KnowledgeRoleRelationVo queryById(Long id);
KnowledgeRoleRelationVo queryByRoleIdAndGroupId(Long roleId, Long groupId);

// 创建/更新/删除关联
Boolean insertByBo(KnowledgeRoleRelationBo bo);
Boolean updateByBo(KnowledgeRoleRelationBo bo);
Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

// 根据角色ID/分组ID查询关联列表
List<KnowledgeRoleRelationVo> queryByRoleId(Long roleId);
List<KnowledgeRoleRelationVo> queryByGroupId(Long groupId);

数据库表结构

知识库模块包含以下数据表（详细SQL请参考 script/sql/ry_knowledge.sql）：

数据库表清单

1. knowledge_info - 知识库信息表
2. knowledge_attach - 知识库附件表
3. knowledge_fragment - 知识库片段表
4. knowledge_vector - 知识片段向量表
5. knowledge_prompt_template - 知识库提示词模板表
6. knowledge_schema_group - 知识库数据模型分组表
7. knowledge_schema - 知识库数据模型表
8. knowledge_schema_field - 知识库数据模型字段表
9. knowledge_role - 知识库角色表
10. knowledge_role_group - 知识库角色组表
11. knowledge_role_relation - 知识库角色与知识库关联表
12. knowledge_job - 知识库任务进度表
13. knowledge_hit_log - 知识检索命中日志表

主要数据表说明

1. knowledge_info (知识库信息表)

存储知识库的基本信息和配置。

主要字段：

• id - 主键ID
• user_id - 用户ID
• knowledge_id - 知识库ID（唯一标识）
• knowledge_name - 知识库名称
• share - 是否公开知识库（0否,1是）
• description - 描述
• knowledge_separator - 知识分隔符
• question_separator - 提问分隔符
• overlap_char - 重叠字符数
• retrieve_limit - 知识库中检索的条数
• text_block_size - 文本块大小
• vector_model_name - 向量库
• embedding_model_name - 向量模型
• system_prompt - 系统提示词
• del_flag - 删除标志（0存在,1删除）

2. knowledge_attach (知识库附件表)

存储上传到知识库的文档文件信息。

主要字段：

• id - 主键ID
• knowledge_id - 知识库ID
• doc_id - 文档ID（唯一标识）
• doc_name - 文档名称
• doc_type - 文档类型（pdf/docx/txt/md等）
• oss_id - 对象存储ID
• pic_status - 拆解图片状态（10未开始,20进行中,30已完成）
• pic_anys_status - 分析图片状态（10未开始,20进行中,30已完成）
• vector_status - 写入向量数据库状态（10未开始,20进行中,30已完成）
• content - 文档内容（长文本）

3. knowledge_fragment (知识库片段表)

存储文档分割后的知识片段。

主要字段：

• id - 主键ID
• knowledge_id - 知识库ID
• doc_id - 文档ID
• fid - 知识片段ID（唯一标识）
• idx - 片段索引下标
• content - 文档内容（文本）

4. knowledge_vector (知识片段向量表)

存储知识片段的向量化数据。

主要字段：

• id - 主键ID
• knowledge_id - 知识库ID
• doc_id - 文档ID
• fragment_id - 知识片段ID
• vector_id - 向量唯一标识
• vector_data - 向量数据（BLOB）
• dimension - 向量维度
• model_name - 向量模型名称
• status - 状态（0启用,1禁用）

5. knowledge_prompt_template (知识库提示词模板表)

存储提示词模板信息。

主要字段：

• id - 主键ID
• template_name - 提示词模板名称
• template_content - 提示词模板内容
• category - 提示词分类（knowledge知识库类型,chat对话类型,draw绘画类型）
• del_flag - 删除标志（0存在,1删除）

6. knowledge_schema_group (知识库数据模型分组表)

存储数据模型分组信息。

主要字段：

• id - 主键ID
• name - 分组名称
• code - 分组编码（唯一）
• icon - 图标
• del_flag - 删除标志（0存在,1删除）

7. knowledge_schema (知识库数据模型表)

存储数据模型定义信息。

主要字段：

• id - 主键ID
• schema_group_id - 分组ID
• name - 模型名称
• code - 模型编码（唯一）
• table_name - 表名（唯一）
• del_flag - 删除标志（0存在,1删除）

8. knowledge_schema_field (知识库数据模型字段表)

存储数据模型的字段定义信息。

主要字段：

• id - 主键ID
• schema_id - 模型ID
• schema_name - 模型名称
• name - 字段名称
• code - 字段编码
• type - 字段类型
• comment - 字段注释
• is_pk - 是否主键（0否,1是）
• is_required - 是否必填（0否,1是）
• is_unique - 是否唯一（0否,1是）
• default_value - 默认值
• length - 字段长度
• scale - 小数位数
• is_list - 是否列表显示（0否,1是）
• is_query - 是否查询字段（0否,1是）
• is_insert - 是否插入字段（0否,1是）
• is_edit - 是否编辑字段（0否,1是）
• query_type - 查询方式（EQ,NE,GT,LT,LIKE,BETWEEN）
• html_type - 显示类型（input,textarea,select,checkbox,radio,datetime,image,upload,editor）
• dict_type - 字典类型
• sort - 排序
• del_flag - 删除标志（0存在,1删除）

9. knowledge_role (知识库角色表)

存储知识库角色信息。

主要字段：

• id - 知识库角色id（主键）
• name - 知识库角色名称（注意：SQL建表语句中字段名为name，但Java实体类中通过MyBatis-Plus字段映射使用roleName、roleCode、roleDesc等字段，实际运行时通过字段映射或XML映射处理）
• group_id - 知识库角色组id
• remark - 备注
• del_flag - 删除标志（0存在,1删除）
• create_by - 创建者
• create_time - 创建时间
• update_by - 更新者
• update_time - 更新时间

注意：

1. SQL建表语句与Java实体类字段可能存在不一致（SQL中仅定义了name字段，但Java实体类中有roleName、roleCode、roleDesc、status、sort等字段），实际使用时会通过MyBatis-Plus的字段映射或XML映射处理。
2. 角色管理功能的Service层已实现（KnowledgeRoleService、KnowledgeRoleGroupService、KnowledgeRoleRelationService），但Controller层尚未实现，可通过Service层调用或后续补充Controller。

10. knowledge_role_group (知识库角色组表)

存储知识库角色组信息。

主要字段（基于SQL建表语句）：

• id - 知识库角色组id（主键）
• name - 知识库角色组名称（在Java实体类中映射为groupName）
• remark - 备注
• del_flag - 删除标志（0存在,1删除）
• create_by - 创建者
• create_time - 创建时间
• update_by - 更新者
• update_time - 更新时间

注意：SQL建表语句仅定义了基本字段，但Java实体类（KnowledgeRoleGroup）中还包含groupCode、groupDesc、status、sort等字段。这些字段可能在SQL中未定义或通过后续ALTER TABLE添加，实际使用时会通过MyBatis-Plus的字段映射或XML映射处理。

11. knowledge_role_relation (知识库角色与知识库关联表)

存储角色与知识库的关联关系。

主要字段（基于SQL建表语句和XML映射）：

• id - 主键ID
• knowledge_role_id - 知识库角色id（在Java实体类中映射为knowledgeRoleId，通过XML映射）
• knowledge_id - 知识库id（在Java实体类中映射为knowledgeId，通过XML映射）
• remark - 备注
• del_flag - 删除标志（0存在,1删除）
• create_by - 创建者
• create_time - 创建时间
• update_by - 更新者
• update_time - 更新时间
• 唯一索引：uk_role_knowledge (knowledge_role_id, knowledge_id)

注意：SQL建表语句仅定义了基本字段（knowledge_role_id和knowledge_id），但Java实体类（KnowledgeRoleRelation）中还包含roleId、groupId、relationType、status、sort等字段。XML映射文件（KnowledgeRoleRelationMapper.xml）中只映射了knowledgeRoleId和knowledgeId字段，其他字段（roleId、groupId、relationType、status、sort）可能在SQL中未定义或通过后续ALTER TABLE添加，实际使用时会通过MyBatis-Plus的字段映射处理。

12. knowledge_job (知识库任务进度表)

存储知识库处理任务的进度和状态信息。

主要字段：

• id - 任务ID
• job_id - 任务唯一标识
• job_type - 任务类型（upload,process,delete,export,embedding,sync）
• job_sub_type - 任务子类型
• knowledge_id - 知识库ID
• doc_id - 文档ID
• user_id - 用户ID
• status - 任务状态（0等待,1进行中,2成功,3失败,4暂停）
• progress - 进度（0-100）
• total_items - 总项目数
• processed_items - 已处理项目数
• success_items - 成功项目数
• failed_items - 失败项目数
• priority - 优先级（1低,2中,3高）
• retry_count - 重试次数
• max_retry - 最大重试次数
• start_time - 开始时间
• end_time - 结束时间
• timeout - 超时时间（秒）
• error_message - 错误信息
• error_stack - 错误堆栈
• result_data - 结果数据（JSON格式）
• notify_url - 通知URL
• notify_status - 通知状态（0未通知,1已通知）

13. knowledge_hit_log (知识检索命中日志表)

存储知识检索的命中日志，用于分析检索效果和热门查询。

主要字段：

• id - 主键ID
• session_id - 会话ID
• knowledge_id - 知识库ID
• doc_id - 文档ID
• fragment_id - 知识片段ID
• query_text - 查询文本
• query_vector - 查询向量（BLOB）
• similarity_score - 相似度分数
• ranking - 排名位置
• model_name - 向量模型名称
• search_params - 搜索参数（JSON格式）
• response_time - 响应时间（毫秒）
• hit_count - 命中次数

使用示例

1. 创建知识库

curl -X POST "http://localhost:8080/knowledge/info" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "knowledgeName": "技术文档库",
    "description": "存储技术相关文档",
    "share": 0,
    "textBlockSize": 1000,
    "overlapChar": 200,
    "retrieveLimit": 5,
    "embeddingModelName": "bge-large-zh",
    "vectorModelName": "db"
  }'

2. 上传文档

curl -X POST "http://localhost:8080/knowledge/info/kb123/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf"

3. 批量上传文档

curl -X POST "http://localhost:8080/knowledge/info/kb123/batch-upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@document1.pdf" \
  -F "files=@document2.docx"

4. 搜索知识库

curl -X POST "http://localhost:8080/knowledge/info/kb123/search?query=Spring Boot&limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

5. 向量搜索

curl -X POST "http://localhost:8080/knowledge/vector/search?knowledgeId=kb123&query=什么是微服务架构？&model=bge-large-zh&topK=5&threshold=0.7" \
  -H "Authorization: Bearer YOUR_TOKEN"

6. 生成向量

curl -X POST "http://localhost:8080/knowledge/vector/generate?knowledgeId=kb123&docId=doc456&model=bge-large-zh" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '[
    {
      "fid": "fragment1",
      "content": "这是第一个片段的内容..."
    },
    {
      "fid": "fragment2",
      "content": "这是第二个片段的内容..."
    }
  ]'

7. 文档批量向量化

curl -X POST "http://localhost:8080/knowledge/vector/vectorize-doc?knowledgeId=kb123&docId=doc456&model=bge-large-zh" \
  -H "Authorization: Bearer YOUR_TOKEN"

8. 获取向量统计

curl -X GET "http://localhost:8080/knowledge/vector/stats/kb123" \
  -H "Authorization: Bearer YOUR_TOKEN"

9. 重建向量索引

curl -X POST "http://localhost:8080/knowledge/vector/rebuild/kb123" \
  -H "Authorization: Bearer YOUR_TOKEN"

10. 获取知识库状态

curl -X GET "http://localhost:8080/knowledge/info/kb123/status" \
  -H "Authorization: Bearer YOUR_TOKEN"

11. 查询知识库列表

curl -X GET "http://localhost:8080/knowledge/info/list?pageNum=1&pageSize=10&knowledgeName=技术" \
  -H "Authorization: Bearer YOUR_TOKEN"

12. 查询附件列表

curl -X GET "http://localhost:8080/knowledge/attach/list?knowledgeId=kb123&pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

13. 查询片段列表

curl -X GET "http://localhost:8080/knowledge/fragment/list?knowledgeId=kb123&pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

14. 查询任务列表

curl -X GET "http://localhost:8080/knowledge/job/list?knowledgeId=kb123&status=1&pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

15. 获取热门查询列表

curl -X GET "http://localhost:8080/knowledge/hitlog/popular?knowledgeId=kb123&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

16. 获取平均响应时间

curl -X GET "http://localhost:8080/knowledge/hitlog/avg-response-time?knowledgeId=kb123" \
  -H "Authorization: Bearer YOUR_TOKEN"

17. 查询命中日志

curl -X GET "http://localhost:8080/knowledge/hitlog/list?knowledgeId=kb123&pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

18. 创建提示词模板

curl -X POST "http://localhost:8080/knowledge/prompt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "templateName": "技术问答模板",
    "templateContent": "你是一个专业的技术助手，请基于以下知识回答问题：\n{knowledge}\n\n问题：{question}",
    "category": "knowledge"
  }'

19. 创建数据模型分组

curl -X POST "http://localhost:8080/knowledge/schema/group" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "业务模型组",
    "code": "business_models",
    "icon": "icon-business"
  }'

20. 创建数据模型

curl -X POST "http://localhost:8080/knowledge/schema" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "schemaGroupId": 1,
    "name": "产品模型",
    "code": "product_model",
    "tableName": "product_data"
  }'

配置说明

应用配置

# 知识库模块配置
knowledge:
  # 默认嵌入模型
  default-embedding-model: text-embedding-ada-002
  # 默认分片大小
  default-chunk-size: 1000
  # 默认分片重叠
  default-chunk-overlap: 200
  # 支持的文件类型
  supported-file-types:
    - pdf
    - docx
    - txt
    - md
  # 最大文件大小（MB）
  max-file-size: 50
  # 向量搜索配置
  vector-search:
    # 默认返回数量
    default-top-k: 5
    # 默认相似度阈值
    default-threshold: 0.7
    # 缓存过期时间（秒）
    cache-expire-time: 3600

# RAG 配置（统一前缀 rag.*）
rag:
  enabled: true
  default-embedding-model: text-embedding
  default-vector-backend: db   # 可扩展 qdrant/weaviate 等

文件存储配置

# OSS配置
oss:
  # 知识库文件存储桶
  knowledge-bucket: knowledge-files
  # 文件访问路径前缀
  file-url-prefix: /knowledge/files/

支持的文档格式

文本格式

• TXT: 纯文本文件
• MD: Markdown文档
• CSV: 逗号分隔值文件

办公文档

• PDF: Adobe PDF文档
• DOCX: Microsoft Word文档
• PPTX: Microsoft PowerPoint文档
• XLSX: Microsoft Excel文档

网页格式

• HTML: 网页文档
• XML: 结构化文档

嵌入模型支持

OpenAI模型

• text-embedding-ada-002
• text-embedding-3-small
• text-embedding-3-large

其他模型

• sentence-transformers/all-MiniLM-L6-v2
• sentence-transformers/all-mpnet-base-v2
• text2vec-chinese

开发指南

添加新的文档解析器

1. 实现 DocumentParser 接口（签名：String parse(byte[] bytes, String filename)）
2. 注册解析器到Spring容器
3. 配置文件类型映射
4. 添加单元测试

@Component
public class CustomDocumentParser implements DocumentParser {
    @Override
    public String parse(byte[] bytes, String filename) {
        // 实现解析逻辑并返回纯文本
        return new String(bytes);
    }
}

集成新的嵌入模型

1. 实现 EmbeddingEngine 接口
2. 配置模型参数
3. 添加模型验证
4. 更新配置文档

@Component
public class CustomEmbeddingEngine implements EmbeddingEngine {
    @Override
    public double[] embed(String text, String model) {
        // 实现嵌入逻辑
        return new double[]{0.1, 0.2, 0.3};
    }
}

自定义搜索策略

1. 实现 Retriever 接口
2. 配置搜索权重
3. 添加性能测试
4. 文档化搜索算法

@Component
public class HybridRetriever implements Retriever {
    public List<KnowledgeSearchResultVo> search(String knowledgeId, String query, String model, int topK, double threshold) {
        // 实现混合搜索逻辑：关键词 + 向量
        return java.util.Collections.emptyList();
    }
}

增量索引与版本控制

• 索引更新：IndexUpdater 接口，默认实现 DefaultIndexUpdater 触发分片重建与任务追踪
• 版本管理：VersionManager 接口，默认实现 DefaultVersionManager（创建版本与回滚占位）
• 推荐将版本信息与片段/向量表做快照/变更日志以支持精准回滚

性能优化

向量索引优化

1. 索引策略

   • 使用适当的向量索引算法（HNSW、IVF等）
   • 定期重建索引
   • 增量索引更新

2. 内存管理

   • 向量数据分页加载
   • LRU缓存策略
   • 内存使用监控

搜索性能

1. 缓存策略

   • 热门查询结果缓存
   • 向量计算结果缓存
   • 分布式缓存支持

2. 并发处理

   • 异步向量化处理
   • 并行搜索执行
   • 线程池优化

存储优化

1. 数据压缩

   • 向量数据压缩
   • 文档内容压缩
   • 索引数据优化

2. 分库分表

   • 按知识库分表
   • 向量数据分片
   • 读写分离

监控和运维

关键指标

• 知识库数量和大小
• 文档处理成功率
• 向量化处理时间
• 搜索响应时间
• 搜索准确率
• 存储使用量

日志配置

logging:
  level:
    org.dromara.knowledge: DEBUG
    org.dromara.knowledge.service.impl.KnowledgeVectorServiceImpl: INFO

健康检查

# 检查知识库状态
curl -X GET "http://localhost:8080/knowledge/health"

# 检查向量服务状态
curl -X GET "http://localhost:8080/knowledge/vector/health"

故障排除

常见问题

1. 文档上传失败

   • 检查文件格式支持
   • 验证文件大小限制
   • 查看存储空间

2. 向量化处理失败

   • 检查嵌入模型配置
   • 验证API密钥
   • 查看网络连接

3. 搜索结果不准确

   • 调整相似度阈值
   • 优化分片策略
   • 重建向量索引

4. 性能问题

   • 检查索引状态
   • 优化查询条件
   • 增加缓存配置

数据恢复

1. 备份策略

   • 定期备份知识库数据
   • 向量索引备份
   • 配置文件备份

2. 恢复流程

   • 恢复数据库数据
   • 重建向量索引
   • 验证数据完整性

API文档

完整的API文档可通过Swagger UI访问： http://localhost:8080/doc.html#/knowledge

功能清单

已实现功能 ✅

知识库管理

• ✅ 知识库创建和配置
• ✅ 知识库列表查询（分页、筛选）
• ✅ 知识库信息更新和删除
• ✅ 知识库状态查询
• ✅ 用户知识库列表查询

文档管理

• ✅ 文档上传（单文件）
• ✅ 文档批量上传
• ✅ 文档列表查询
• ✅ 文档信息查询
• ✅ 文档删除
• ✅ 多格式文档支持（PDF、Word、TXT、Markdown、Excel、CSV、HTML等）
• ✅ 文档解析状态跟踪（拆解图片状态、分析图片状态、向量化状态）

知识片段管理

• ✅ 片段列表查询（分页、筛选）
• ✅ 片段信息查询
• ✅ 片段创建、更新、删除
• ✅ 根据知识库ID查询片段列表
• ✅ 根据文档ID查询片段列表
• ✅ 片段内容管理

向量化处理

• ✅ 向量生成（单片段、批量）
• ✅ 向量搜索（相似度搜索）
• ✅ 向量列表查询
• ✅ 向量统计
• ✅ 向量索引重建
• ✅ 文档批量向量化
• ✅ 多向量模型支持

智能检索

• ✅ 基于向量的语义搜索
• ✅ 相似度排序
• ✅ 检索结果过滤
• ✅ 检索命中日志记录

任务管理

• ✅ 任务创建和查询
• ✅ 任务状态跟踪（等待、进行中、成功、失败、暂停）
• ✅ 任务进度管理
• ✅ 任务重试机制
• ✅ 根据知识库ID查询任务
• ✅ 根据任务状态/类型查询任务

提示词模板管理

• ✅ 模板创建和配置
• ✅ 模板列表查询
• ✅ 模板更新和删除
• ✅ 按分类查询模板
• ✅ 按模板名称查询

数据模型管理

• ✅ 模型分组管理（分组创建、查询、更新、删除）
• ✅ 数据模型管理（模型创建、查询、更新、删除）
• ✅ 模型字段管理（字段创建、查询、更新、删除）
• ✅ 模型与分组的关联管理
• ✅ 字段类型和属性配置

角色与权限管理

• ✅ 角色组管理（Service层已实现）
• ✅ 角色管理（Service层已实现）
• ✅ 角色与知识库关联管理（Service层已实现）

检索日志与分析

• ✅ 命中日志记录
• ✅ 命中日志查询（按知识库、会话、片段、查询文本）
• ✅ 热门查询统计
• ✅ 平均响应时间分析
• ✅ 日志导出

RAG架构组件

• ✅ 文档解析器接口（DocumentParser）及多种实现
• ✅ 向量化引擎接口（EmbeddingEngine）及HTTP实现
• ✅ 检索器接口（Retriever）及默认实现
• ✅ 索引更新器接口（IndexUpdater）及默认实现
• ✅ 响应生成器接口（Generator）及默认实现
• ✅ 版本管理器接口（VersionManager）及默认实现
• ✅ 向量存储服务接口（VectorStoreService）及多种实现（DB、Qdrant、Weaviate）

待实现功能

文档处理增强

• 文档版本管理（版本对比、回滚）
• 文档预览功能（PDF预览、图片预览）
• 文档在线编辑
• 文档标签和分类管理
• 文档批量操作（批量删除、批量导出）

检索功能增强

• 关键词搜索（全文检索）
• 混合搜索策略（关键词+向量）
• 检索结果排序优化（多种排序策略）
• 检索结果高亮显示
• 检索历史记录

权限控制增强

• 角色管理Controller（目前只有Service层）
• 知识库访问权限控制（读写权限、分享权限）
• 用户权限验证和拦截
• 权限审计日志

数据分析与统计

• 知识库使用统计（文档数量、检索次数、用户数等）
• 检索效果分析（准确率、召回率）
• 热门知识库统计
• 用户行为分析

性能优化

• 向量索引优化（HNSW、IVF等算法）
• 检索结果缓存
• 批量处理优化
• 异步任务队列优化

集成功能

• 与AI模块深度集成（RAG问答优化）
• 与聊天模块集成（知识库聊天增强）
• 知识库导入导出（批量导入、格式转换）

版本历史

• v1.0.0: 初始版本，基础知识库功能
• v1.1.0: 添加向量搜索支持
• v1.2.0: 支持多种文档格式
• v1.3.0: 增加批量处理功能
• v1.4.0: 引入 RAG 模块化目录、解析/检索接口与增量索引/版本控制
• v1.5.0: 完善命中日志功能，新增热门查询统计和平均响应时间分析
• v1.6.0: 完善文档，补充完整的API接口列表、数据库表结构说明、Service层方法说明和使用示例（2025-01-09）

贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交代码变更 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

技术支持

如有问题或建议，请通过以下方式联系：

• 提交 Issue
• 发送邮件至技术支持
• 参与社区讨论