# 知识库模块使用说明

## 已实现功能

| 功能 | 说明 |
|------|------|
| 文档上传 | 支持 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`。