105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
# 知识库模块使用说明
|
||
|
||
## 已实现功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 文档上传 | 支持 PDF / Word(.docx/.doc) / TXT / Markdown / Excel(.xlsx/.xls) 拖拽上传 |
|
||
| 文本解析 | Apache Tika 自动提取 PDF/Word，Apache POI 提取 Excel |
|
||
| 文本切片 | 按 200 Token 切片，40 Token 重叠 |
|
||
| 向量化 | 调用 Ollama 或 DeepSeek Embedding API 转为向量 |
|
||
| 向量存储 | PostgreSQL pgvector |
|
||
| 语义检索 | 余弦相似度检索，按相关性排序返回 Top 5 |
|
||
| 文档管理 | 列表查看、删除、重新索引 |
|
||
| 检索审计 | 记录每次检索的关键词、耗时、命中数 |
|
||
| Embedding 配置 | 前端可切换 Ollama / DeepSeek，可修改模型名和 API Key |
|
||
|
||
## 功能界面位置
|
||
|
||
左侧菜单 → **知识库管理**（路径 `/knowledge-base`）
|
||
|
||
页面分两个 Tab：
|
||
|
||
- **文档管理** — 上传、搜索、文档列表
|
||
- **检索审计** — 检索日志和统计
|
||
|
||
## 操作步骤
|
||
|
||
### 上传文档
|
||
|
||
1. 打开知识库管理页面
|
||
2. 在虚线区域**拖拽文件**或**点击选择文件**
|
||
3. 系统自动处理：解析 → 切片 → 向量化 → 入库
|
||
4. 文档列表中状态变为 `completed` 即完成
|
||
|
||
支持格式：`.pdf` `.docx` `.doc` `.txt` `.md` `.xlsx` `.xls`，单文件不超过 50MB
|
||
|
||
### 检索知识库
|
||
|
||
1. 在文档管理页的搜索框中输入关键词或自然语言问题
|
||
2. 按回车搜索
|
||
3. 下方显示匹配结果、来源文件名和相似度百分比（越高越匹配）
|
||
4. 注意：即使搜索词与文档用词不完全一致，语义相近也能搜到
|
||
|
||
> 相似度低于 50% 的结果通常不相关，因为搜索始终返回 Top 5，没有相关结果时也会"矮子里拔将军"。
|
||
|
||
### 切换 Embedding 模型
|
||
|
||
1. 点击页面右上角 **"Embedding 配置"** 按钮
|
||
2. 在弹出的窗口中：
|
||
- 选择 AI 提供商（Ollama / DeepSeek）
|
||
- Ollama：填入 Ollama 地址和模型名（默认 `nomic-embed-text`）
|
||
- DeepSeek：填入模型名（默认 `text-embedding-3-small`）和 API Key
|
||
3. 点击保存
|
||
|
||
> 配置保存在 Redis 中，有效期 24 小时。未配置时使用 `application.yml` 的默认值。
|
||
|
||
### 删除文档
|
||
|
||
1. 在文档列表中点击对应行的 **"删除"** 按钮
|
||
2. 确认后删除文档及其向量数据
|
||
|
||
### 重新索引
|
||
|
||
1. 在文档列表中点击对应行的 **"重新索引"** 按钮
|
||
2. 系统重新执行解析 → 切片 → 向量化流程
|
||
|
||
## 前提条件
|
||
|
||
| 组件 | 状态要求 |
|
||
|------|---------|
|
||
| PostgreSQL + pgvector | 已运行（`docker compose up -d`） |
|
||
| MinIO | 已运行，`ims-attachments` bucket 已创建 |
|
||
| Ollama 或 DeepSeek | 至少一个可用（Ollama 需已拉取 `nomic-embed-text`） |
|
||
| 后端 | 已启动（端口 8080） |
|
||
| 前端 | 已启动（端口 5173） |
|
||
|
||
## 验证流程
|
||
|
||
1. 打开 `http://localhost:5173`，用 `admin / Admin@2026` 登录
|
||
2. 左侧菜单 → 知识库管理
|
||
3. 点击右上角 **"Embedding 配置"**，确认提供商已正确配置
|
||
4. 上传一个 `.txt` 文件
|
||
5. 等待状态变为 `completed`
|
||
6. 在搜索框输入关键词，验证是否能匹配到文档内容
|
||
|
||
## 常见问题
|
||
|
||
| 问题 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| 上传失败：bucket 不存在 | MinIO 未创建 bucket | 打开 `http://localhost:9001` 登录 minioadmin 创建 `ims-attachments` |
|
||
| 上传失败：Ollama 连接拒绝 | Ollama 地址配置不对 | 见下方"Ollama 地址怎么配" |
|
||
| 上传失败：状态显示 `failed` | 解析或向量化出错 | 鼠标悬停查看错误信息，根据提示处理 |
|
||
| 上传失败：HTTP 500 | 后端异常 | 检查后端终端日志，常见原因：依赖版本冲突（执行 `mvn install -DskipTests -U` 后重启） |
|
||
| 检索返回空 | 文档状态不是 `completed` | 等待文档处理完成 |
|
||
| 检索结果乱码或相似度低 | 之前失败时存入了二进制乱码 | 删除该文档，重新上传 |
|
||
| Token 过期跳登录 | 超过 30 分钟未操作 | 重新登录即可（已配置自动刷新） |
|
||
|
||
### Ollama 地址怎么配？
|
||
|
||
Ollama 已集成在 Docker Compose 中，地址固定为 `http://localhost:11434`。
|
||
|
||
如果在前端 Embedding 配置中手动填写，填此地址即可。默认 `application.yml` 中已配置为 `localhost:11434`，一般无需修改。
|
||
|
||
> 如果地址不对，上传任何文件都会在 Embedding 步骤报错，日志中显示 `Ollama embedding failed`。
|