一、项目简介

基于 Spring Boot + Qdrant + 通义千问 构建的企业级知识库问答系统，支持文档上传、智能检索、知识图谱可视化等功能。

核心特点：

• RAG技术：向量检索 + 大模型生成
• 多格式支持：Word、PDF、TXT文档
• 知识图谱：自动提取实体和关系
• 智能问答：根据匹配度动态调整回答策略
• 开箱即用：提供一键启动脚本

二、项目地址

Gitee仓库：https://gitee.com/mobuhan/knowledge-base

克隆命令：

git clone https://gitee.com/mobuhan/knowledge-base.git
cd knowledge-base

三、运行环境要求

3.1 必需软件

软件	版本	说明
JDK	17+	Java开发环境
Maven	3.8+	项目构建工具
Qdrant	1.17.1+	向量数据库（已内置qdrant.exe）

3.2 可选软件

IDE：IntelliJ IDEA / VS Code（推荐）

浏览器：Chrome / Edge（用于访问前端页面）

3.3 环境检查

双击运行 verify-env.bat 检查环境是否就绪。

四、快速启动

方式一：一键启动（推荐）

步骤：

1. 配置API Key
编辑 src/main/resources/application.yml，修改第4行：
qianwen:
  api-key: ${QIANWEN_API_KEY:你的sk}  # 替换为你的通义千问API Key

获取API Key：https://dashscope.aliyun.com/

2. 启动Qdrant
双击运行 start-qdrant.bat

等待看到类似输出表示启动成功：
Qdrant HTTP server is listening on 0.0.0.0:6333

3. 启动后端服务
双击运行 run.bat

等待看到以下日志表示启动成功：
Started KnowledgeBaseApplication in X.XXX seconds
Tomcat started on port 8080 (http)

4. 访问应用
浏览器打开：http://localhost:8080

方式二：命令行启动

# 1. 进入项目目录
cd knowledge-base

# 2. 启动Qdrant（后台运行）
start /B qdrant.exe

# 3. 等待3秒后启动后端
timeout /t 3
mvn spring-boot:run

# 4. 访问 http://localhost:8080

方式三：IDE启动

1. 使用 IntelliJ IDEA 打开项目
2. 等待Maven依赖下载完成
3. 找到 KnowledgeBaseApplication.java
4. 右键 → Run 'KnowledgeBaseApplication'
5. 访问 http://localhost:8080

注意：需要先手动启动Qdrant（运行 start-qdrant.bat）

五、项目结构说明

knowledge-base/
│
├── src/                          # 源代码目录
│   ├── main/
│   │   ├── java/com/knowledge/
│   │   │   ├── config/           # 配置类（6个文件）
│   │   │   │   ├── AppConfig.java
│   │   │   │   ├── ApplicationInitializer.java
│   │   │   │   ├── AsyncConfig.java
│   │   │   │   ├── CorsConfig.java
│   │   │   │   ├── QdrantConfig.java
│   │   │   │   └── QianwenConfig.java
│   │   │   │
│   │   │   ├── controller/       # 控制器层（3个文件）
│   │   │   │   ├── ChatController.java
│   │   │   │   ├── DocumentController.java
│   │   │   │   └── KnowledgeGraphController.java
│   │   │   │
│   │   │   ├── model/            # 数据模型（4个实体类）
│   │   │   │   ├── ChatHistory.java
│   │   │   │   ├── Document.java
│   │   │   │   ├── EntityRelation.java
│   │   │   │   └── KnowledgeEntity.java
│   │   │   │
│   │   │   ├── repository/       # 数据访问层（4个Repository）
│   │   │   │
│   │   │   ├── service/          # 业务逻辑层（5个Service）
│   │   │   │   ├── ChatService.java            # ⭐核心
│   │   │   │   ├── DocumentService.java
│   │   │   │   ├── KnowledgeGraphService.java
│   │   │   │   ├── QdrantService.java
│   │   │   │   └── QianwenService.java
│   │   │   │
│   │   │   ├── util/             # 工具类（2个文件）
│   │   │   │   ├── DocumentParser.java
│   │   │   │   └── TextChunker.java
│   │   │   │
│   │   │   └── KnowledgeBaseApplication.java   # 主启动类
│   │   │
│   │   └── resources/
│   │       ├── application.yml                 # ⭐重要
│   │       └── static/
│   │           └── index.html                  # ⭐唯一页面
│   │
│   └── test/java/                # 单元测试（4个测试类）
│
├── data/                         # H2数据库文件（运行时自动生成）
├── uploads/                      # 上传的文档文件（运行时自动生成）
├── storage/                      # Qdrant数据存储（运行时自动生成）
│
├── pom.xml                       # Maven配置文件 ⭐重要
├── README.md                     # 项目说明文档
├── QUICKSTART.md                 # 快速开始指南
├── setup-env.bat                 # 环境设置脚本
├── verify-env.bat                # 环境检查脚本
├── start-qdrant.bat              # Qdrant启动脚本
├── run.bat                       # 后端服务启动脚本 ⭐常用
├── smart-start.bat               # 智能启动脚本
└── CSDN发布-知识库系统完整开发指南.md  # CSDN博客文章

六、核心功能使用

6.1 上传文档

1. 点击顶部导航栏的 "文档管理" 标签
2. 点击 "选择文件" 按钮
3. 选择 Word(.docx)、PDF(.pdf) 或 TXT(.txt) 文件
4. 点击 "上传并同步" 按钮
5. 等待同步完成（可在控制台查看进度）

提示：大文档（>10MB）同步可能需要几分钟，请耐心等待

6.2 查看知识图谱

1. 点击顶部导航栏的 "知识图谱" 标签
2. 点击 "刷新图谱" 按钮
3. 鼠标悬停节点可查看详细信息
4. 不同颜色代表不同类型的实体：

• 蓝色：人物
• 绿色：地点
• 黄色：组织
• 红色：术语

6.3 智能问答

1. 点击顶部导航栏的 "智能问答" 标签
2. 在输入框中输入问题，例如：

• "郑克俊的技术栈有哪些？"
• "项目中使用了哪些设计模式？"

1. 按回车或点击发送按钮
2. 查看AI回答，包括：

• �� 回答内容
• �� 来源文件
• �� 引用原文（如有）
• �� 匹配度和召回率

七、常见问题

Q1：启动时报错 "Connection refused: localhost:6334"

解决：Qdrant未启动或端口被占用

# 1. 检查Qdrant是否运行
netstat -ano | findstr :6333

# 2. 如果未运行，启动Qdrant
start-qdrant.bat

# 3. 如果端口被占用，结束进程后重启
taskkill /F /PID <进程ID>

Q2：向量搜索返回空结果

解决：相似度阈值过高
1. 编辑 src/main/resources/application.yml
2. 修改 similarity-threshold: 0.05（建议值：0.05-0.15）
3. 重启应用

Q3：API调用失败 "401 Unauthorized"

解决：API Key配置错误
1. 检查 application.yml 中的 api-key 是否正确
2. 确认使用的是通义千问DashScope API Key
3. 检查网络连接（需要访问外网）

Q4：H2数据库锁定 "Database is already in use"

解决：Java进程未正常关闭

# 1. 结束所有Java进程
Get-Process java | Stop-Process -Force

# 2. 删除锁文件（如果有）
del data\knowledge_db.lock.db

# 3. 重新启动应用
run.bat

Q5：文档解析乱码

解决：
1. 确认文件编码为UTF-8
2. PDF扫描件无法解析（需要有文本层）
3. 尝试转换为TXT后重新上传

八、配置说明

application.yml 关键配置

# 服务器端口
server:
  port: 8080

# 通义千问API配置
qianwen:
  api-key: ${QIANWEN_API_KEY:你的sk}  # ⭐必须配置
  chat-api-url: https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation
  embedding-api-url: https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
  model: qwen-turbo
  embedding-model: text-embedding-v3

# 应用配置
app:
  upload-dir: ./uploads              # 上传文件目录
  chunk-size: 600                    # 文本分块大小
  chunk-overlap: 50                  # 分块重叠
  top-k: 5                           # 向量检索返回数量
  similarity-threshold: 0.05         # 相似度阈值 ⭐重要

九、技术架构

用户浏览器 (http://localhost:8080)
         ↓
    Spring Boot 后端 (端口8080)
         ↓
    ┌────────┬─────────┐
    ↓        ↓         ↓
  H2数据库  Qdrant   通义千问API
  (聊天记录) (向量库)  (向量化+LLM)

核心技术栈：

• Spring Boot 3.2.0
• Qdrant 1.17.1（向量数据库）
• 通义千问 qwen-turbo（大模型）
• H2 Database 2.2.224（嵌入式数据库）
• Apache POI 5.2.5（文档解析）
• ECharts（知识图谱可视化）

十、性能优化建议

10.1 降低CPU占用

文档同步时会自动添加延迟（500ms/chunk），避免CPU满载。如需调整，修改 DocumentService.java 中的 Thread.sleep(500)。

10.2 提高检索速度

• 减少 top-k 值（默认5，可调整为3）
• 增加 similarity-threshold（过滤更多低相关结果）
• 使用SSD硬盘存储Qdrant数据

10.3 内存优化

大文档处理时，建议在启动脚本中增加JVM内存：

set JAVA_OPTS=-Xms512m -Xmx2048m
java %JAVA_OPTS% -jar knowledge-base.jar

十一、联系方式

项目仓库：https://gitee.com/mobuhan/knowledge-base

问题反馈：请在Gitee提交Issue

作者：mobuhan

附录：快速参考

常用命令

# 环境检查
verify-env.bat

# 启动Qdrant
start-qdrant.bat

# 启动后端
run.bat

# 智能启动（自动检查）
smart-start.bat

# 查看端口占用
netstat -ano | findstr :8080
netstat -ano | findstr :6333

# 结束Java进程
Get-Process java | Stop-Process -Force

常用URL

• 前端页面：http://localhost:8080
• H2控制台：http://localhost:8080/h2-console
• Qdrant Web UI：http://localhost:6333/dashboard

默认配置

• 后端端口：8080
• Qdrant HTTP端口：6333
• Qdrant gRPC端口：6334
• H2数据库路径：./data/knowledge_db
• 上传文件路径：./uploads