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

知识库模块实施计划

技术选型

项目	选择
文档解析	Apache Tika（一个依赖支持 PDF/Word/TXT/MD）
向量化引擎	Ollama（默认 nomic-embed-text）或 DeepSeek（text-embedding-3-small），前端可切换
向量存储	PostgreSQL + pgvector（已有）
文件存储	MinIO（已有）
切片策略	500 Token，10% 重叠

实施步骤

Step 0：AI 配置管理（前置）

端	内容
后端新增	AiConfigService — 读取/写入 AI 配置（provider、模型名、API Key），存入 Redis
后端实现	AiConfigController 的 get/put/test 三个方法
后端改动	EmbeddingService 每次调用前查配置，根据 provider 路由到 Ollama 或 DeepSeek
前端新增	知识库页内加"Embedding 配置"区域：Provider 下拉框（Ollama / DeepSeek）+ 模型名输入框

Step 1：添加依赖

修改 ims-service/pom.xml，新增依赖：

依赖	用途
org.apache.tika:tika-core	文档解析
org.springframework.ai:spring-ai-ollama-spring-boot-starter	Ollama Embedding 调用

Step 2：创建 Service 接口 + 实现（8 个新文件）

文件	包路径	说明
EmbeddingService.java	com.ims.service.knowledge	接口：embed(text) + search(query, topK)
AiConfigService.java	com.ims.service.knowledge	AI 配置读写，存入 Redis
OllamaEmbeddingService.java	com.ims.service.knowledge	调用 Ollama 实现 Embedding
DeepSeekEmbeddingService.java	com.ims.service.knowledge	调用 DeepSeek API 实现 Embedding
DocumentParserService.java	com.ims.service.knowledge	Tika 解析 + 500 Token 切片
KnowledgeService.java	com.ims.service.knowledge	上传→MinIO→DB、列表、删除、重新索引
SearchService.java	com.ims.service.knowledge	pgvector 余弦相似度检索
SearchLogService.java	com.ims.service.knowledge	检索审计日志记录

Step 3：实现 Controller

Controller	方法	功能
AiConfigController	GET /api/v1/ai/config	读取 AI 配置
	PUT /api/v1/ai/config	更新 AI 配置
	POST /api/v1/ai/config/test	测试连接
KnowledgeController	GET /documents	文档列表（分页）
	POST /documents	上传文档 → 解析 → 切片 → 向量化 → 入库
	DELETE /documents/{id}	删除文档 + MinIO 文件 + 向量
	POST /documents/{id}/reindex	重新向量化
	GET /search	检索接口
	GET /logs	检索日志列表

Step 4：前端知识库页面

修改 frontend/src/pages/knowledge-base/index.tsx：

组件	参考设计
Tab 切换	文档管理 / 检索审计
Embedding 配置区	Provider 下拉框（Ollama / DeepSeek）+ 模型名输入框
上传拖拽区	Ant Design Upload.Dragger
文档表格	Ant Design Table（文件名/上传人/时间/状态/分块数/操作）
搜索框	Ant Design Input.Search
检索日志表格	Ant Design Table
统计卡片	Ant Design Card + Statistic

Step 5：配置

项目	操作
Ollama 模型	ollama pull nomic-embed-text
MinIO bucket	管理后台创建 ims-attachments

文件清单

修改：
  backend/ims-service/pom.xml                              +2 依赖
  backend/ims-api/src/main/java/.../AiConfigController.java    填充 3 个方法
  backend/ims-api/src/main/java/.../KnowledgeController.java   填充 6 个方法
  frontend/src/pages/knowledge-base/index.tsx              重写

新增（后端）：
  backend/ims-service/src/main/java/com/ims/service/knowledge/
    ├── EmbeddingService.java
    ├── AiConfigService.java
    ├── OllamaEmbeddingService.java
    ├── DeepSeekEmbeddingService.java
    ├── DocumentParserService.java
    ├── KnowledgeService.java
    ├── SearchService.java
    └── SearchLogService.java

新增（前端）：
  frontend/src/pages/knowledge-base/services.ts            API 封装

实施顺序

前置条件（你手动执行）
  ① ollama pull nomic-embed-text（如果用 DeepSeek 则跳过）
  ② MinIO 创建 ims-attachments bucket
  ③ 如需 DeepSeek 则准备 API Key
        ↓
代码实施（我写）
  Step 0: AiConfigService + AiConfigController + 前端配置区
  Step 1: pom.xml 加依赖 → mvn install 验证
  Step 2: 8 个 Service 文件
  Step 3: 填充 Controller
  Step 4: 前端页面 + services.ts
        ↓
验证
  ① 启动后端 + 前端
  ② 配置页选择 Ollama + nomic-embed-text → 保存
  ③ 上传一个 PDF → 检查是否解析/切片/向量化成功
  ④ 检索 → 检查返回结果
  ⑤ 查看审计日志
  ⑥ 切到 DeepSeek 重新索引 → 验证 DeepSeek 向量化