# 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

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

**主要方法：**

```java
// 查询知识库列表
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

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

**主要方法：**

```java
// 查询向量列表
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

知识片段管理服务。

**主要方法：**

```java
// 查询知识片段列表
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

知识库附件管理服务。

**主要方法：**

```java
// 查询附件列表
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

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

**主要方法：**

```java
// 上传文档并处理
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

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

**主要方法：**

```java
// 查询任务列表
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

提示词模板管理服务。

**主要方法：**

```java
// 查询模板列表
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

数据模型管理服务。

**主要方法：**

```java
// 查询模型列表
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

数据模型分组管理服务。

**主要方法：**

```java
// 查询分组列表
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

数据模型字段管理服务。

**主要方法：**

```java
// 查询字段列表
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

命中日志管理服务。

**主要方法：**

```java
// 查询日志列表
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层待实现）。

**主要方法：**

```java
// 查询角色列表
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层待实现）。

**主要方法：**

```java
// 查询角色组列表
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层待实现）。

**主要方法：**

```java
// 查询关联列表
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. 创建知识库

```bash
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. 上传文档

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

### 3. 批量上传文档

```bash
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. 搜索知识库

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

### 5. 向量搜索

```bash
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. 生成向量

```bash
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. 文档批量向量化

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

### 8. 获取向量统计

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

### 9. 重建向量索引

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

### 10. 获取知识库状态

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

### 11. 查询知识库列表

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

### 12. 查询附件列表

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

### 13. 查询片段列表

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

### 14. 查询任务列表

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

### 15. 获取热门查询列表

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

### 16. 获取平均响应时间

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

### 17. 查询命中日志

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

### 18. 创建提示词模板

```bash
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. 创建数据模型分组

```bash
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. 创建数据模型

```bash
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"
  }'
```

## 配置说明

### 应用配置

```yaml
# 知识库模块配置
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 等
```

### 文件存储配置

```yaml
# 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. 添加单元测试

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

### 集成新的嵌入模型

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

```java
@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. 文档化搜索算法

```java
@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. **分库分表**
    - 按知识库分表
    - 向量数据分片
    - 读写分离

## 监控和运维

### 关键指标

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

### 日志配置

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

### 健康检查

```bash
# 检查知识库状态
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
- 发送邮件至技术支持
- 参与社区讨论