# springai-react-tcm-qa

**Repository Path**: CodingKeep/springai-react-tcm-qa

## Basic Information

- **Project Name**: springai-react-tcm-qa
- **Description**: SpringAI + React AI TCM Ancient Books QA System
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 岐黄智问 —— 中医古籍智能问答系统

基于 **Spring Boot 3.5 + Spring AI + Agentic RAG + React 18** 的中医古籍智能问答系统。

## 项目介绍

本系统面向中医古籍学习、知识检索、AI 辅助问答和引用溯源，实现：

**用户提问 → Agent 主动检索 → 古籍证据整理 → 大模型回答 → 引用出处展示**

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | Java 21, Spring Boot 3.5, Spring AI, Spring Security |
| 数据库 | PostgreSQL 16 + pgvector, Redis |
| ORM | MyBatis-Plus |
| 大模型 | DeepSeek (OpenAI-compatible API) |
| 前端框架 | React 18, TypeScript, Vite |
| 样式 | Tailwind CSS |
| 状态管理 | Zustand |

## 目录结构

```
root
├── backend/          # Spring Boot 后端
├── frontend/         # React 前端
├── docker-compose.yml
└── README.md
```

## 环境要求

- Java 21+
- Node.js 18+
- Docker & Docker Compose
- Maven 3.9+

## 快速启动

### 1. 启动基础设施

```bash
docker compose up -d
```

启动 PostgreSQL 16 (pgvector) 和 Redis。

### 2. 启动后端

```bash
# 如需真实大模型问答，请先配置 DEEPSEEK_API_KEY（参考下方说明）
mvn -f backend/pom.xml spring-boot:run
```

### 3. 启动前端

```bash
npm --prefix frontend install
npm --prefix frontend run dev
```

访问 http://localhost:5173

## 配置说明

### application-dev.yml 核心配置

后端通过 `application-dev.yml` 或环境变量读取配置：

| 变量 | 说明 | 示例 |
|------|------|------|
| `DEEPSEEK_API_KEY` | DeepSeek API Key，真实问答时必填 | sk-xxx |
| `DEEPSEEK_BASE_URL` | DeepSeek API 地址 | https://api.deepseek.com |
| `DEEPSEEK_MODEL` | 对话模型名称 | deepseek-chat |
| `AI_EMBEDDING_PROVIDER` | Embedding 提供方，默认 mock | mock 或 remote |
| `EMBEDDING_MODEL` | Embedding 模型名称，remote 模式使用 | text-embedding-v3 |
| `EMBEDDING_BASE_URL` | Embedding API 地址，remote 模式使用 | https://api.deepseek.com |
| `EMBEDDING_API_KEY` | Embedding API Key，remote 模式使用 | sk-xxx |

### Embedding 模式

通过 `ai.embedding.provider` 或环境变量 `AI_EMBEDDING_PROVIDER` 配置：
- `mock`：使用随机向量（开发测试）
- `remote`：调用远程 Embedding API

## 知识库导入

系统内置示例古籍数据位于：

```
backend/src/main/resources/data/sample_huangdi_neijing.json
```

知识库导入接口需要登录后携带 JWT Token。可先注册或登录：

```bash
POST /api/auth/register
POST /api/auth/login
```

再通过文件上传接口导入：

```bash
POST /api/knowledge/import
```

请求字段名为 `file`，文件选择 `backend/src/main/resources/data/sample_huangdi_neijing.json`。

## Agentic RAG 流程

```
用户问题
→ 安全边界检查
→ 问题意图识别
→ query rewrite 问题改写
→ multi query 多路检索
→ pgvector 向量检索 + keyword 关键词检索
→ 检索结果融合
→ rerank 排序
→ 证据片段压缩
→ Agent 判断证据是否足够
→ 不足则二次检索
→ 构造带引用的 Prompt
→ 调用大模型
→ SSE 流式输出
→ 保存完整回答和引用关系
```

## 常见问题

**Q: 数据库连接失败？**
A: 确认 `docker compose up -d` 已执行，PostgreSQL 端口 5432 可用。

**Q: 前端 401 错误？**
A: Token 过期，重新登录即可。

**Q: Embedding 报错？**
A: 开发阶段默认使用 `AI_EMBEDDING_PROVIDER=mock`，无需配置 Embedding API Key；如设置为 `remote`，需同时配置 `EMBEDDING_API_KEY`。

**Q: 如何添加真实古籍数据？**
A: 参考 `backend/src/main/resources/data/sample_huangdi_neijing.json` 的 JSON 格式准备数据，然后调用知识库导入接口上传文件。