# TCM-RAG

**Repository Path**: LCC_Z/tcm-rag

## Basic Information

- **Project Name**: TCM-RAG
- **Description**: 基于 **RAG（检索增强生成）** 的中医肠胃健康问答系统。用户可通过自然语言描述症状，系统从中医文档知识库中检索相关内容，并结合本地大模型生成辨证分析与调理建议。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 中医肠胃智能问答平台

基于 **RAG（检索增强生成）** 的中医肠胃健康问答系统，面向软件工程课程大作业场景。用户可通过自然语言描述症状，系统从中医文档知识库中检索相关内容，并结合本地大模型生成辨证分析与调理建议。

## 功能概览

| 模块 | 说明 |
|------|------|
| 智能问答 | 基于 `tcm_document` 文档库的 RAG 检索 + Ollama 生成回答 |
| 用户系统 | 注册、登录、个人资料；支持普通用户与管理员角色 |
| 问诊历史 | 保存并查看历史问诊记录（后端持久化，离线时前端本地兜底） |
| 管理后台 | 用户管理、问诊记录查看、系统配置维护（仅 `ADMIN`） |
| RAG 对比 | 对比「RAG 增强回答」与「纯大模型回答」，支持批量测试与可视化报告 |
| 数据初始化 | 提供接口导入默认用户、胃痛证治文档及系统配置 |

## 技术栈

**后端** `tcm-qa-platform`

- Java 17、Spring Boot 3.5.6
- Spring Data JPA、MySQL 8
- Redis（问答缓存）
- Ollama（默认模型 `qwen2:1.5b`）
- SpringDoc OpenAPI（接口文档）

**前端** `tcm-frontend`

- Vue 3、Vite 5、Vue Router、Pinia
- Element Plus、ApexCharts

## 项目结构

```
代码/
├── README.md                 # 本文件
├── tcm-qa-platform/          # Spring Boot 后端
│   ├── src/main/java/        # 业务代码（RAG、用户、问诊等）
│   ├── src/main/resources/
│   │   ├── application.properties
│   │   └── db/               # 数据库建表脚本
│   ├── 对比报告生成器.html    # RAG 对比报告可视化（独立 HTML）
│   └── comparison_report_data.json
└── tcm-frontend/             # Vue 3 前端
    ├── src/pages/            # 登录、对话、历史、管理、对比等页面
    └── src/api/              # 后端 API 封装
```

## 环境要求

| 依赖 | 版本建议 |
|------|----------|
| JDK | 17+ |
| Maven | 3.8+ |
| Node.js | 18+ |
| MySQL | 8.0+ |
| Redis | 6+ |
| Ollama | 最新版，并已拉取 `qwen2:1.5b` 模型 |

## 快速开始

### 1. 准备数据库

方式一：执行 SQL 脚本（推荐首次部署）

```bash
# 脚本路径
tcm-qa-platform/src/main/resources/db/migration/create_database.sql
# 或使用简化版
tcm-qa-platform/src/main/resources/db/数据库创建脚本_简化版.sql
```

方式二：依赖 JPA 自动建表（`spring.jpa.hibernate.ddl-auto=update`，首次启动会自动创建表结构）。

> **注意**：`application.properties` 中默认数据库名为 `tcm_1`，而 SQL 脚本创建的是 `tcm`。请统一数据库名称，或修改配置中的 `spring.datasource.url`。

### 2. 配置后端

编辑 `tcm-qa-platform/src/main/resources/application.properties`：

```properties
# MySQL
spring.datasource.url=jdbc:mysql://localhost:3306/tcm_1?useSSL=false&serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=UTF-8
spring.datasource.username=你的用户名
spring.datasource.password=你的密码

# Redis
spring.data.redis.host=localhost
spring.data.redis.port=6379

# Ollama
ollama.api.url=http://localhost:11434
ollama.api.model=qwen2:1.5b
ollama.api.enabled=true
```

拉取 Ollama 模型：

```bash
ollama pull qwen2:1.5b
```

### 3. 启动后端

```bash
cd tcm-qa-platform
mvn spring-boot:run
```

默认地址：`http://localhost:8080`

接口文档（Swagger UI）：`http://localhost:8080/swagger-ui.html`

### 4. 初始化数据（首次运行）

后端启动后，使用 Postman 或 curl 调用以下接口：

```bash
# 创建默认用户（表为空时生效）
curl -X POST http://localhost:8080/api/data-init/users

# 导入胃痛证治分类文档（RAG 知识库）
curl -X POST http://localhost:8080/api/data-init/stomach-pain-documents
```

### 5. 启动前端

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

浏览器访问：`http://localhost:5173`

在登录页可将后端地址设置为 `http://localhost:8080`。若后端未启动，前端对话会使用本地 Mock 数据演示。

## 默认测试账号

通过 `/api/data-init/users` 初始化后可使用：

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | admin123 | 管理员 |
| user1 | user123 | 普通用户 |
| user2 | user123 | 普通用户 |
| user3 | user123 | 普通用户 |

管理员注册码（自行注册管理员时）：`ADMIN2024`

## 主要 API

### 认证

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 登录，返回 `token` 与用户信息 |
| POST | `/api/auth/register` | 注册 |

### RAG 问答

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/rag/chat` | 发送对话消息，获取 RAG 回答 |
| GET | `/api/rag/health` | 健康检查 |
| GET | `/api/rag/cache/stats` | 缓存统计 |
| POST | `/api/rag/refresh` | 刷新知识库缓存 |

### 问诊记录

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/consult-records` | 创建问诊记录 |
| GET | `/api/consult-records/user/{userId}` | 查询用户历史 |
| GET | `/api/consult-records/all` | 查询全部（管理端） |

### RAG 对比测试

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/rag/comparison/batch` | 批量对比测试 |
| POST | `/api/rag/comparison/single` | 单题对比 |
| GET | `/api/rag/comparison/status` | 对比服务状态 |

### 数据管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/data-init/users` | 初始化默认用户 |
| POST | `/api/data-init/stomach-pain-documents` | 导入胃痛文档 |
| POST | `/api/data-import/document` | 导入自定义文档 |

请求头（需登录的接口）：

```
Authorization: Bearer <token>
```

## RAG 工作原理（简述）

```
用户提问
   ↓
症状标准化 / 口语映射
   ↓
从 tcm_document 检索相关文档片段（关键词 + 权重）
   ↓
拼装 Prompt，调用 Ollama 生成回答
   ↓
返回答案及检索来源（sources）
```

知识库以 **文档表** `tcm_document` 为唯一 RAG 数据源；结构化表（证候、症状等）保留在库中，供扩展或历史数据兼容。

## RAG 对比报告

1. 在前端访问 **对比测试** 页面（`/comparison`），或调用 `/api/rag/comparison/batch` 获取对比数据。
2. 将结果保存为 `tcm-qa-platform/comparison_report_data.json`。
3. 用浏览器打开 `tcm-qa-platform/对比报告生成器.html`，加载 JSON 即可生成图表报告。

## 前端页面

| 路由 | 页面 | 权限 |
|------|------|------|
| `/login` | 登录 / 注册 | 公开 |
| `/chat` | 智能问答 | 已登录 |
| `/history` | 问诊历史 | 已登录 |
| `/profile` | 个人资料 | 已登录 |
| `/admin` | 管理后台 | 管理员 |
| `/comparison` | RAG 对比测试 | 已登录 |

## 运行测试

```bash
cd tcm-qa-platform
mvn test
```

包含文档导入、RAG 问答、数据初始化等相关测试类。

## 注意事项

1. **配置安全**：请勿将真实数据库密码提交到版本库；本地修改 `application.properties` 后建议加入 `.gitignore` 或使用环境变量。
2. **Ollama 依赖**：`ollama.api.enabled=false` 时部分生成功能不可用，问答质量会下降。
3. **Redis 可选**：Redis 未启动时缓存相关功能可能报错，请确保 Redis 服务已启动，或按需调整配置。
4. **免责声明**：本系统输出仅供参考，不能替代专业医师诊断与治疗。

## 子项目说明

- 前端单独说明见 [`tcm-frontend/README.md`](tcm-frontend/README.md)
- 后端为 Maven 标准 Spring Boot 工程，入口类：`com.example.tcmqaplatform.TcmApplication`

## 许可证

课程作业项目，仅供学习交流使用。