# rag-app

**Repository Path**: barbosa/rag-app

## Basic Information

- **Project Name**: rag-app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-26
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java 知识库 RAG 应用

> 基于 Spring AI + Milvus 的智能问答系统

## 📋 快速开始

### 1. 环境准备

#### 前置条件
- Docker & Docker Compose
- Java 17+
- Maven 3.8+

#### Windows 环境特殊说明

**如果 Docker 命令不可用**：
1. 确保已安装 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)
2. 启动 Docker Desktop 应用程序
3. 等待 Docker 服务完全启动（系统托盘图标显示 "Docker Desktop is running"）
4. 如果使用 WSL2，可以在 WSL 终端中执行 Docker 命令

#### 配置环境变量

**Windows PowerShell**:
```powershell
# 复制配置模板
Copy-Item config\.env.template .env

# 编辑 .env 文件，填写你的 API Key
notepad .env
# 或使用 VS Code
code .env
```

**Linux/Mac**:
```bash
# 复制模板文件
cp config/.env.template .env

# 编辑 .env 文件，填写你的 API Key
vim .env
```

**API 配置选项**：

**选项 1: OpenAI（推荐用于生产环境）**
- `OPENAI_API_KEY`: 你的 OpenAI API Key（获取地址：https://platform.openai.com/api-keys）
- `LLM_PROVIDER=openai`

**选项 2: 硅基流动（推荐用于国内用户）**
- `SILICONFLOW_API_KEY`: 已配置 ✅
- `LLM_PROVIDER=siliconflow`
- `LLM_MODEL=Qwen/Qwen3-VL-32B-Thinking` 或 `Pro/deepseek-ai/DeepSeek-R1`
- 详细说明：查看 [硅基流动配置说明.md](./硅基流动配置说明.md)

#### 启动 Milvus

**Windows PowerShell**:
```powershell
cd milvus
docker-compose up -d

# 查看服务状态
docker-compose ps
```

**Linux/Mac**:
```bash
cd milvus
docker-compose up -d

# 查看服务状态
docker-compose ps
```

#### 验证环境

```bash
cd scripts
./verify-environment.sh
```

### 2. 项目结构

```
rag-app/
├── rag-api/                   # API 层模块
│   └── src/main/java/com/javainterview/rag/
│       ├── controller/        # REST 控制器
│       │   ├── ChatController.java
│       │   └── DocumentController.java
│       └── dto/               # 数据传输对象
│           ├── ChatRequest.java
│           └── ChatResponse.java
│
├── rag-service/               # 业务服务层模块
│   └── src/main/java/com/javainterview/rag/service/
│       ├── ChatService.java              # 聊天服务
│       ├── DocumentService.java         # 文档加载服务
│       ├── ChunkingService.java          # 文档切分服务
│       ├── VectorizationService.java     # 向量化服务
│       └── DocumentProcessingService.java # 文档处理编排服务
│
├── rag-infrastructure/       # 基础设施层模块
│   └── src/main/java/com/javainterview/rag/config/
│       ├── MilvusConfig.java         # Milvus 配置
│       ├── EmbeddingConfig.java      # Embedding 模型配置
│       └── SiliconFlowConfig.java    # 硅基流动 API 配置
│
├── rag-starter/               # 启动模块
│   └── src/main/
│       ├── java/com/javainterview/rag/
│       │   └── RagApplication.java   # 主应用类
│       └── resources/
│           └── application.yml        # 应用配置
│
├── docs/                      # 文档目录
│   ├── README.md              # 文档索引
│   ├── 项目架构图.md          # 项目架构和流程图
│   ├── Docker启动说明.md
│   ├── Docker安装指南.md
│   ├── Milvus启动问题排查.md
│   ├── Milvus启动网络问题解决方案.md
│   ├── 硅基流动配置说明.md
│   ├── 文档处理与向量化使用说明.md
│   ├── 测试应用使用说明.md
│   └── ...                    # 其他文档
│
├── scripts/                   # 脚本工具目录
│   ├── setup-environment.sh   # 环境设置脚本
│   ├── verify-environment.sh  # 环境验证脚本
│   ├── test-api.ps1           # API 测试脚本（简单）
│   ├── test-api-full.ps1      # API 测试脚本（完整）
│   ├── 快速测试.ps1
│   └── 直接测试API.ps1
│
├── tests/                     # 测试文件目录
│   └── test.html              # 浏览器测试页面
│
├── config/                    # 配置文件目录
│   └── .env.template          # 环境配置模板
│
├── milvus/                    # Milvus 配置
│   └── docker-compose.yml
│
├── .env                       # 实际配置（需创建，不提交到 Git）
├── pom.xml                    # 父 POM（多模块管理）
└── README.md                  # 项目主文档
```

#### 模块职责说明

- **rag-starter**: **程序启动入口**（Application Entry Point），包含 `main` 方法，负责启动整个 Spring Boot 应用
- **rag-api**: **业务请求入口**（HTTP Request Entry Point），包含 Controller 和 DTO，负责处理 HTTP 请求
- **rag-service**: 业务服务层，包含所有业务逻辑服务（文档处理、向量化、聊天等）
- **rag-infrastructure**: 基础设施层，包含配置类（Milvus、Embedding、硅基流动等）

> 💡 **两个"入口"的区别**：
> - `rag-starter` = 程序启动入口（类似"餐厅开门营业"），启动应用让服务可用
> - `rag-api` = 业务请求入口（类似"点餐窗口"），处理每个 HTTP 请求
> 
> 详细说明请参考：[模块职责说明.md](docs/模块职责说明.md)

#### 模块依赖关系

```
rag-starter (启动模块)
    ├── rag-api (API 层)
    │   └── rag-service (服务层)
    │       └── rag-infrastructure (基础设施层)
    ├── rag-service (服务层)
    │   └── rag-infrastructure (基础设施层)
    └── rag-infrastructure (基础设施层)
```

## 🚀 下一步

环境准备完成后，将进入：

**阶段二：文档处理与向量化**
- 创建 Spring Boot 项目
- 实现文档加载
- 实现文档切分
- 实现向量化处理

## 🧪 测试工具

### 快速测试 API（无需编译）

**PowerShell 测试脚本**：
```powershell
# 简单测试
.\scripts\test-api.ps1

# 完整测试（多个问题）
.\scripts\test-api-full.ps1

# 快速测试
.\scripts\快速测试.ps1
```

**浏览器测试**：
- 双击打开 `tests/test.html` 文件
- 或运行：`start tests/test.html`

**测试结果**：✅ API 正常工作，所有测试通过

### Spring Boot 应用测试

如果已安装 Maven：
```powershell
# 编译（多模块项目）
mvn clean compile

# 运行（在 rag-starter 模块中）
cd rag-starter
mvn spring-boot:run

# 或者在根目录运行
mvn spring-boot:run -pl rag-starter

# 测试接口
# GET: http://localhost:8080/api/chat/ask?question=你好
# POST: http://localhost:8080/api/chat/ask
```

## 📚 相关文档

### 项目文档
- [文档目录](./docs/README.md) - 所有文档索引
- [硅基流动配置说明](./docs/硅基流动配置说明.md) - 硅基流动 API 配置和使用指南
- [测试应用使用说明](./docs/测试应用使用说明.md) - Spring Boot 应用使用说明
- [文档处理与向量化使用说明](./docs/文档处理与向量化使用说明.md) - 文档处理和向量化功能使用说明

### 外部文档
- [RAG 应用完整方案](../tech-insights/学习规划/知识库RAG应用完整方案.md)
- [环境准备实施指南](../tech-insights/学习规划/RAG应用环境准备实施指南.md)

## 🔧 故障排查

### Milvus 无法启动

```bash
# 查看日志
cd milvus
docker-compose logs -f

# 重启服务
docker-compose restart
```

### API 连接失败

- 检查 `.env` 文件中的 API Key 是否正确
- 检查网络连接
- 检查 OpenAI 账户余额

## 📝 当前状态

### ✅ 已完成

- ✅ 项目结构：多模块架构（rag-api、rag-service、rag-infrastructure、rag-starter）
- ✅ 环境准备：Docker Desktop、Milvus 服务、硅基流动 API
- ✅ 文档处理：文档加载、切分、向量化功能
- ✅ RAG 功能：向量检索、上下文构建、增强生成
- ✅ API 接口：基础问答、RAG 问答、文档处理接口

### ⏳ 待完成

- ⏳ Java/Maven 环境安装（进行中）
- ⏳ 项目编译验证
- ⏳ 应用启动测试
- ⏳ 知识库文档处理
- ⏳ 功能测试和优化

### 📋 环境就绪后验证

参考：[环境就绪后验证指南](./docs/环境就绪后验证指南.md)

**快速验证脚本**:
```powershell
.\scripts\验证环境.ps1
```

**最后更新**: 2025-12-03