2026Technology-Competition/docs/knowledge-base-usage.md

知识库模块使用说明

已实现功能

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