xinli/README-RAG-SYSTEM.md

# 🎯 RAG知识库系统 - 完整使用指南

## 📖 目录

1. [系统简介](#系统简介)
2. [快速开始](#快速开始)
3. [配置说明](#配置说明)
4. [API文档](#api文档)
5. [常见问题](#常见问题)

---

## 系统简介

基于RAG（检索增强生成）技术的心理评估知识库系统，支持：

- ✅ **文档管理**: 上传、解析、向量化心理学文档
- ✅ **智能问答**: 基于知识库回答专业问题
- ✅ **报告生成**: 生成AI增强的心理评估报告
- ✅ **自动监听**: 自动处理上传目录的新文档

### 🎉 两种部署方式

| 方式 | 优势 | 适用场景 |
|------|------|---------|
| **免费云服务** ⭐ | 无需部署、速度快、成本低 | 开发测试、小规模生产 |
| **本地部署** | 数据私密、无网络依赖 | 大规模生产、高安全要求 |

---

## 快速开始

### 方式1: 使用免费云服务 (推荐) ⭐

**耗时**: 约7分钟

#### 步骤1: 获取API Key (2分钟)

1. 访问 https://cloud.siliconflow.cn
2. 注册账号（微信/手机号）
3. 进入控制台 → API密钥
4. 创建新密钥
5. 复制密钥（格式: `sk-xxxxxx`）

#### 步骤2: 配置 (1分钟)

编辑 `ry-xinli-admin/src/main/resources/application.yml`:

```yaml
rag:
  mode: openai  # 使用云服务
  openai:
    base-url: https://api.siliconflow.cn/v1
    api-key: sk-你的密钥  # ⚠️ 替换这里
    embed-model: BAAI/bge-large-zh-v1.5
    generate-model: deepseek-ai/DeepSeek-V3
```

#### 步骤3: 启动 (2分钟)

```bash
cd ry-xinli-admin
mvn spring-boot:run
```

#### 步骤4: 测试 (1分钟)

访问: http://localhost:8080/psychology/rag-test/health

看到 `"overall_status": "HEALTHY"` 即成功！

**详细指南**: 查看 `QUICK-START-FREE-API.md`

---

### 方式2: 本地部署

**耗时**: 约30分钟（首次需下载模型）

#### 步骤1: 安装Ollama

```bash
# Windows: 下载安装包
https://ollama.ai/download

# 启动Ollama
ollama serve
```

#### 步骤2: 下载模型

```bash
# 嵌入模型 (约1GB)
ollama pull nomic-embed-text

# 生成模型 (约20GB)
ollama pull deepseek-r1:32b
```

#### 步骤3: 安装ChromaDB

```bash
pip install chromadb
chroma run --path D:\wwwroot\RAG\data\chroma_db --port 8000
```

#### 步骤4: 配置

```yaml
rag:
  mode: ollama  # 使用本地服务
  ollama:
    url: http://localhost:11434
    embed-model: nomic-embed-text
    generate-model: deepseek-r1:32b
```

#### 步骤5: 启动

```bash
cd ry-xinli-admin
mvn spring-boot:run
```

**详细指南**: 查看 `RAG-QUICK-START.md`

---

## 配置说明

### 完整配置示例

```yaml
rag:
  # 模式选择: openai(云服务) 或 ollama(本地)
  mode: openai
  
  # OpenAI兼容API配置
  openai:
    base-url: https://api.siliconflow.cn/v1
    api-key: sk-your-key
    embed-model: BAAI/bge-large-zh-v1.5
    generate-model: deepseek-ai/DeepSeek-V3
  
  # Ollama本地配置
  ollama:
    url: http://localhost:11434
    embed-model: nomic-embed-text
    generate-model: deepseek-r1:32b
  
  # ChromaDB配置
  chromadb:
    url: http://localhost:8000
    collection: psychology_knowledge
  
  # 存储配置
  storage:
    upload-path: D:/wwwroot/RAG/uploads
    log-path: D:/wwwroot/RAG/logs
  
  # 文件监听
  file-watcher:
    enabled: false  # 是否自动处理新文件
    watch-path: D:/wwwroot/RAG/uploads
  
  # 检索配置
  retrieval:
    top-k: 5  # 检索数量
    similarity-threshold: 0.7  # 相似度阈值
  
  # 文本分块
  text-splitter:
    chunk-size: 800  # 分块大小
    chunk-overlap: 200  # 重叠大小
```

### 推荐配置

#### 开发环境

```yaml
rag:
  mode: openai
  openai:
    api-key: sk-your-key
    generate-model: Qwen/Qwen2.5-7B-Instruct  # 更快
  retrieval:
    top-k: 3  # 减少检索
```

#### 生产环境

```yaml
rag:
  mode: openai
  openai:
    api-key: sk-your-key
    generate-model: deepseek-ai/DeepSeek-V3  # 更强
  retrieval:
    top-k: 5
    similarity-threshold: 0.7
```

---

## API文档

### 知识库管理

#### 上传文档

```http
POST /psychology/knowledge/upload
Content-Type: multipart/form-data

file: 文件对象
category: 分类（可选）
```

#### 获取文档列表

```http
GET /psychology/knowledge/list?pageNum=1&pageSize=10
```

#### 删除文档

```http
DELETE /psychology/knowledge/{id}
```

### AI分析

#### 生成报告

```http
POST /psychology/ai/generate-report
Content-Type: application/json

{
  "assessmentData": {
    "questionnaire_name": "MMPI",
    "scores": {"抑郁": 65, "焦虑": 70}
  },
  "userProfile": {
    "user_id": "123",
    "name": "张三",
    "age": 30
  }
}
```

#### 智能问答

```http
POST /psychology/ai/chat
Content-Type: application/json

{
  "question": "什么是MMPI量表？",
  "context": ""
}
```

#### 系统状态

```http
GET /psychology/ai/system/status
```

**完整API文档**: 查看 `RAG-API-EXAMPLES.md`

---

## 常见问题

### Q1: 如何选择部署方式？

**推荐使用免费云服务**，除非：
- 需要处理敏感数据（选本地）
- 没有网络连接（选本地）
- 需要大规模并发（选本地）

### Q2: 免费服务够用吗？

对于开发测试和小规模使用完全够用：
- 硅基流动: 每月免费额度
- DeepSeek: 充值10元可用很久
- 成本: 约0.001元/次查询

### Q3: 如何切换服务？

只需修改配置：

```yaml
# 从云服务切换到本地
rag:
  mode: ollama  # 改为ollama

# 从本地切换到云服务
rag:
  mode: openai  # 改为openai
```

### Q4: 支持哪些文档格式？

- ✅ PDF
- ✅ Word (.docx, .doc)
- ✅ TXT

### Q5: 如何提高生成质量？

1. **上传更多相关文档**
2. **使用更强的模型**: DeepSeek-V3
3. **调整检索参数**: 增加top-k
4. **优化提示词**: 修改PromptBuilder

### Q6: 遇到错误怎么办？

1. 查看日志: `D:\wwwroot\RAG\logs\`
2. 检查健康状态: `/psychology/rag-test/health`
3. 查看错误代码对照表（见下方）

### 错误代码对照

| 错误 | 原因 | 解决方案 |
|------|------|---------|
| 401 | API Key无效 | 检查API Key是否正确 |
| 429 | 请求过多 | 等待或充值 |
| 500 | 服务器错误 | 查看日志 |
| 503 | 服务不可用 | 检查服务是否启动 |

---

## 📚 相关文档

- **快速开始**: `QUICK-START-FREE-API.md`
- **免费服务指南**: `RAG-FREE-SERVICES-GUIDE.md`
- **API示例**: `RAG-API-EXAMPLES.md`
- **部署检查清单**: `RAG-DEPLOYMENT-CHECKLIST.md`
- **本地部署指南**: `RAG-QUICK-START.md`

---

## 🎯 下一步

1. ✅ 完成快速开始
2. 📤 上传心理学文档
3. 💬 测试智能问答
4. 📊 生成评估报告
5. 🎨 开发前端页面

---

## 📞 技术支持

遇到问题？

1. 查看文档目录中的相关指南
2. 检查系统日志
3. 访问服务商文档:
   - 硅基流动: https://docs.siliconflow.cn
   - DeepSeek: https://platform.deepseek.com/docs

---

**版本**: 1.0.0  
**更新时间**: 2025-12-19  
**作者**: ddnai