# 知识库问答

**Repository Path**: zhao-qiuling/master

## Basic Information

- **Project Name**: 知识库问答
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-22
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Enterprise RAG Platform v3

一个面向企业内部知识问答场景的 RAG 平台，支持文档上传、异步索引、混合检索、规则重排、Guard 拒答控制、结构化问答以及前后端联调调试。

当前版本状态：

- `v3`
- 本地联调通过
- 重建 `100` 个测试样本后全量联调 `100/100`

## 1. 项目目标

这个项目解决的是“企业知识库可控问答”问题，不只是把大模型接进来，而是把下面几件事串成一条可调试、可观测、可迭代的工程链路：

- 文档上传与索引
- 文本 / Markdown / CSV / 混合文档解析
- 向量召回 + 关键词召回
- Fusion + Rule Rerank + LLM Rerank
- Retrieval Guard + Answer Guard
- 结构化字段直答与比较问答
- QA 日志与 Retrieval 日志追踪
- 前端调试面板与后端 API 联调

## 2. 当前能力

当前版本已经覆盖这些核心能力：

- 支持 `TXT / Markdown / CSV / Excel` 等文档接入
- 支持 MinIO 存储原始文件
- 支持 RabbitMQ 异步索引任务
- 支持 MySQL 持久化文档、索引任务、QA 日志、检索日志
- 支持 Elasticsearch 存储 chunk 并执行向量 / 关键词检索
- 支持 Redis 缓存问答结果与会话记忆
- 支持 Markdown 标题结构增强、后续结构块补带
- 支持结构化 CSV 单文档定向联调
- 支持 `documentId` 级别的单文档检索 / 问答调试
- 支持本地前后端跨域联调

## 3. 技术栈

后端：

- Java 17
- Spring Boot 3.3.5
- Spring AI Alibaba DashScope
- MyBatis-Plus
- MySQL
- Redis
- RabbitMQ
- Elasticsearch
- MinIO
- HanLP

前端：

- Vue 3
- Vite
- TypeScript
- Element Plus
- Axios

## 4. 项目结构

后端核心模块：

- `src/main/java/com/example/rag/web`
  HTTP 接口层，包含文档接口、问答接口、日志接口、异常处理、CORS 配置。
- `src/main/java/com/example/rag/document`
  文档上传、解析、切块、索引任务管理、文件删除与重建索引。
- `src/main/java/com/example/rag/retrieval`
  Query Rewrite、Query Planning、Recall、Fusion、Rerank、Context Build、Retrieval Guard、结构化检索。
- `src/main/java/com/example/rag/ai`
  Prompt 构造、Embedding、Answer Guard、LLM 调用、会话记忆、QA 应用编排。
- `src/main/java/com/example/rag/qa`
  QA 日志查询。
- `src/main/java/com/example/rag/infra`
  Elasticsearch、Redis、RabbitMQ、MinIO、常量与基础设施封装。

前端核心目录：

- `frontend/src/views`
  文档管理、QA 调试、日志中心。
- `frontend/src/api`
  Axios 封装与 API 调用层。

## 5. 核心链路

### 5.1 文档上传与索引链路

1. 前端或接口上传文档。
2. 后端保存文档元数据到 MySQL。
3. 原始文件写入 MinIO。
4. 发送索引任务到 RabbitMQ。
5. 消费端解析文档、切块、抽取 metadata。
6. 生成 embedding 并写入 Elasticsearch。
7. chunk 元数据和索引状态回写 MySQL。

### 5.2 问答链路

1. 用户发起 `/api/qa/ask`。
2. 执行 Query Rewrite 与 Query Planning。
3. 尝试结构化检索直答。
4. 若未命中，执行向量召回和关键词召回。
5. 进行 Score Fusion、Rule Rerank、可选 LLM Rerank。
6. 执行 Retrieval Guard。
7. 构建上下文。
8. 执行 Answer Guard。
9. 通过则构造 Prompt 调用 LLM，拒答则返回受控答案。
10. 写入 QA 日志与 Retrieval 日志，并缓存结果。

## 6. v3 关键优化

这版最重要的不是“多接了几个接口”，而是把复杂文档场景真正打通了。

### 6.1 Markdown 检索链路增强

- 补齐 Markdown 相关 metadata 在 fusion 阶段的透传
- 修复 guard 错用候选列表顺序导致的 `top1/top2` 失真
- 放宽 Markdown 问答放行条件
- 标题块命中后补带后续结构块，避免只拿到标题拿不到正文要求

### 6.2 单文档定向联调能力

- `/api/qa/retrieve` 与 `/api/qa/ask` 新增 `documentId`
- `documentId` 限定真正下推到：
  - 结构化检索
  - 向量召回
  - 关键词召回
- 避免“先全库 topK，再文档过滤”导致相似文档漏召回

### 6.3 Guard 稳定性修复

- 支持短但证据充分的条款类、制度类上下文放行
- 去掉问答阶段对 `canAnswer(contextBuildResult)` 的重复拦截
- 修复 `CLAUSE`、`MIXED` 等场景被二次误拒答的问题

### 6.4 前后端联调支持

- 后端新增统一 CORS 配置
- 默认允许：
  - `http://127.0.0.1:5173`
  - `http://localhost:5173`

## 7. 环境准备

本地依赖：

- JDK 17
- Maven 3.9+
- Node.js 18+
- Docker Desktop

建议直接通过 Docker 启动基础依赖：

```bash
docker compose -f docker-compose.local.yml up -d
```

当前 `docker-compose.local.yml` 包含：

- MySQL
- RabbitMQ
- Elasticsearch
- MinIO

Redis 需要你本地单独准备或后续自行补进 compose。

## 8. 关键配置

后端主配置文件：

- [application.yml](C:/Users/33295/OneDrive/Desktop/AI/src/main/resources/application.yml)

重点关注：

- `spring.datasource`
- `spring.rabbitmq`
- `rag.redis`
- `rag.minio`
- `rag.elasticsearch`
- `rag.ai.alibaba`
- `rag.retrieval`
- `rag.web.cors.allowed-origins`

模型相关：

- 当前默认接阿里云百炼 / DashScope
- `api-key` 读取 `rag.ai.alibaba.api-key`

## 9. 启动方式

### 9.1 启动后端

```bash
mvn spring-boot:run
```

后端默认地址：

- `http://127.0.0.1:8080`

健康检查：

- `http://127.0.0.1:8080/actuator/health`

### 9.2 启动前端

```bash
cd frontend
npm install
npm run dev
```

前端默认地址：

- `http://127.0.0.1:5173`
- `http://localhost:5173`

前端当前默认通过 Vite 代理访问后端：

- `/api -> http://127.0.0.1:8080`
- `/actuator -> http://127.0.0.1:8080`

## 10. 常用接口

文档相关：

- `POST /api/documents/upload`
- `GET /api/documents`
- `GET /api/documents/{id}/chunks`
- `DELETE /api/documents/{id}`

问答相关：

- `POST /api/qa/retrieve`
- `POST /api/qa/ask`

日志相关：

- `GET /api/qa/logs`
- `GET /api/qa/retrieval-logs`

### 10.1 检索调试请求示例

```json
{
  "query": "报销流程是什么",
  "documentId": 308
}
```

### 10.2 问答请求示例

```json
{
  "question": "第4.2条是什么",
  "documentId": 348
}
```

## 11. 测试与验证结果

这次版本收口时，重新清理旧样本后，重建了 `100` 个干净测试文件，覆盖：

- `CLEAN_PROCESS`
- `DIRTY_WEAK_TITLE`
- `CLAUSE`
- `STRUCTURED_CSV`
- `MIXED`
- `MARKDOWN`

最终联调结果：

- 总数：`100`
- 通过：`100`
- 通过率：`100.0%`

分类结果：

- `CLEAN_PROCESS 20/20`
- `DIRTY_WEAK_TITLE 20/20`
- `CLAUSE 20/20`
- `STRUCTURED_CSV 20/20`
- `MIXED 10/10`
- `MARKDOWN 10/10`

结果报告：

- [live_eval_results_after_recharge.json](C:/Users/33295/OneDrive/Desktop/AI/tmp/bulk_eval_100_regen/live_eval_results_after_recharge.json)

## 12. 适合展示的亮点

如果你用于答辩、汇报或演示，建议重点讲这几个点：

- 不是“简单接个大模型”，而是构建了完整的企业级 RAG 主链路
- 支持复杂文档类型，不只处理普通文本
- 对 Markdown、CSV、条款类问法做了专项优化
- 有 Guard 机制，能控制拒答与幻觉风险
- 有单文档定向调试能力，便于定位线上问题
- 有日志、缓存、异步索引和前端调试台，工程完整度高

## 13. 相关文档

- [PROJECT_GUIDE.md](C:/Users/33295/OneDrive/Desktop/AI/docs/PROJECT_GUIDE.md)
- [ARCHITECTURE.md](C:/Users/33295/OneDrive/Desktop/AI/docs/ARCHITECTURE.md)
- [PRESENTATION_SCRIPT.md](C:/Users/33295/OneDrive/Desktop/AI/docs/PRESENTATION_SCRIPT.md)