# RAG知识库系统 - 免费服务使用指南

## 🎉 无需本地部署！使用免费云服务

本指南将帮助你使用免费的云服务替代本地Ollama和ChromaDB，让你无需安装任何AI模型即可使用RAG知识库功能。

## 📋 推荐的免费服务

### 1. 硅基流动 (SiliconFlow) ⭐ 推荐

**优势**:
- ✅ 完全免费（有免费额度）
- ✅ 支持中文嵌入模型
- ✅ 支持DeepSeek-V3等先进模型
- ✅ API兼容OpenAI格式
- ✅ 无需信用卡

**注册地址**: https://cloud.siliconflow.cn

**免费额度**:
- 每月免费Token额度
- 嵌入模型: BAAI/bge-large-zh-v1.5 (免费)
- 生成模型: DeepSeek-V3 (免费)

**获取API Key步骤**:
1. 访问 https://cloud.siliconflow.cn
2. 注册账号（支持微信/手机号）
3. 进入控制台
4. 点击"API密钥"
5. 创建新的API密钥
6. 复制密钥（格式: `sk-xxxxxx`）

### 2. DeepSeek官方API

**优势**:
- ✅ 官方服务，稳定可靠
- ✅ 价格便宜（充值后使用）
- ✅ DeepSeek-V3模型

**注册地址**: https://platform.deepseek.com

**价格**: 
- 输入: ¥1/百万tokens
- 输出: ¥2/百万tokens

### 3. 通义千问 (Qwen)

**优势**:
- ✅ 阿里云服务
- ✅ 有免费试用额度
- ✅ 国内访问速度快

**注册地址**: https://dashscope.aliyun.com

## 🚀 快速配置步骤

### 步骤1: 获取API Key

以硅基流动为例：

1. 访问 https://cloud.siliconflow.cn
2. 注册并登录
3. 进入"API密钥"页面
4. 点击"创建新密钥"
5. 复制生成的密钥（类似: `sk-abcdefghijklmnopqrstuvwxyz123456`）

### 步骤2: 配置application.yml

打开 `ry-xinli-admin/src/main/resources/application.yml`，找到RAG配置部分：

```yaml
# RAG知识库配置
rag:
  # 使用模式: openai(外部API) 或 ollama(本地)
  mode: openai
  
  # OpenAI兼容API配置（免费服务）
  openai:
    # 硅基流动API
    base-url: https://api.siliconflow.cn/v1
    # 替换为你的API Key
    api-key: sk-your-api-key-here  # ⚠️ 修改这里！
    # 嵌入模型 (免费)
    embed-model: BAAI/bge-large-zh-v1.5
    # 生成模型 (免费)
    generate-model: deepseek-ai/DeepSeek-V3
```

**重要**: 将 `sk-your-api-key-here` 替换为你的实际API Key！

### 步骤3: 启动应用

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

### 步骤4: 测试连接

访问健康检查接口：
```bash
curl http://localhost:8080/psychology/rag-test/health
```

应该看到：
```json
{
  "code": 200,
  "data": {
    "ollama": "OK",  // 实际使用的是OpenAI API
    "chromadb": "OK",  // 使用内存存储
    "overall_status": "HEALTHY"
  }
}
```

## 🎯 不同服务的配置示例

### 配置1: 硅基流动 (推荐)

```yaml
rag:
  mode: openai
  openai:
    base-url: https://api.siliconflow.cn/v1
    api-key: sk-your-siliconflow-key
    embed-model: BAAI/bge-large-zh-v1.5
    generate-model: deepseek-ai/DeepSeek-V3
```

**可用模型**:
- 嵌入: `BAAI/bge-large-zh-v1.5`, `BAAI/bge-m3`
- 生成: `deepseek-ai/DeepSeek-V3`, `Qwen/Qwen2.5-72B-Instruct`

### 配置2: DeepSeek官方

```yaml
rag:
  mode: openai
  openai:
    base-url: https://api.deepseek.com/v1
    api-key: sk-your-deepseek-key
    embed-model: deepseek-chat  # DeepSeek不提供专门的嵌入模型
    generate-model: deepseek-chat
```

**注意**: DeepSeek官方API需要充值使用，但价格很便宜。

### 配置3: 通义千问

```yaml
rag:
  mode: openai
  openai:
    base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
    api-key: sk-your-dashscope-key
    embed-model: text-embedding-v2
    generate-model: qwen-plus
```

### 配置4: 混合模式（嵌入用免费，生成用本地）

如果你有本地Ollama，可以混合使用：

```yaml
rag:
  mode: openai  # 主要使用OpenAI
  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:
    url: http://localhost:11434
    generate-model: qwen2.5:7b  # 本地生成（可选）
```

## 💡 使用建议

### 1. 选择合适的模型

**嵌入模型**（用于向量化）:
- `BAAI/bge-large-zh-v1.5`: 中文效果好，1024维 ⭐推荐
- `BAAI/bge-m3`: 多语言支持，1024维
- `text-embedding-v2`: 通义千问的嵌入模型

**生成模型**（用于生成报告）:
- `deepseek-ai/DeepSeek-V3`: 最新最强，推理能力强 ⭐推荐
- `Qwen/Qwen2.5-72B-Instruct`: 阿里千问，中文好
- `Qwen/Qwen2.5-7B-Instruct`: 更快，适合简单任务

### 2. 控制成本

虽然有免费额度，但还是要注意：

1. **减少Top-K数量**:
```yaml
rag:
  retrieval:
    top-k: 3  # 从5减少到3，减少检索量
```

2. **提高相似度阈值**:
```yaml
rag:
  retrieval:
    similarity-threshold: 0.75  # 从0.7提高到0.75，过滤更多结果
```

3. **减小文本块大小**:
```yaml
rag:
  text-splitter:
    chunk-size: 500  # 从800减少到500
    chunk-overlap: 100  # 从200减少到100
```

### 3. 监控使用量

大多数服务都提供使用量监控：

- **硅基流动**: 控制台 → 用量统计
- **DeepSeek**: 控制台 → 账单
- **通义千问**: 控制台 → 资源包

## 🧪 测试功能

### 测试1: 向量化

```bash
curl -X POST "http://localhost:8080/psychology/rag-test/test-embedding" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "text=这是一个测试"
```

预期输出：
```json
{
  "code": 200,
  "data": {
    "embedding_dimension": 1024,
    "first_5_values": [0.123, -0.456, ...]
  }
}
```

### 测试2: 文本生成

```bash
curl -X POST "http://localhost:8080/psychology/rag-test/test-generation" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "prompt=什么是心理学？"
```

### 测试3: 完整流程

```bash
# 1. 上传文档
curl -X POST "http://localhost:8080/psychology/knowledge/upload" \
  -F "file=@test.txt" \
  -F "category=心理学"

# 2. 智能问答
curl -X POST "http://localhost:8080/psychology/ai/chat" \
  -H "Content-Type: application/json" \
  -d '{"question":"什么是人格心理学？","context":""}'
```

## ❌ 常见问题

### 问题1: API Key无效

**错误**: `401 Unauthorized` 或 `Invalid API Key`

**解决**:
1. 检查API Key是否正确复制（包括`sk-`前缀）
2. 确认API Key没有过期
3. 检查是否有免费额度剩余

### 问题2: 模型不存在

**错误**: `Model not found`

**解决**:
1. 检查模型名称是否正确
2. 访问服务商文档查看可用模型列表
3. 尝试使用推荐的模型名称

### 问题3: 请求超时

**错误**: `Read timed out`

**解决**:
1. 检查网络连接
2. 增加超时时间（在代码中已设置120秒）
3. 尝试使用更小的模型

### 问题4: 免费额度用完

**解决**:
1. 等待下月额度刷新
2. 充值少量金额（通常很便宜）
3. 切换到其他免费服务

## 📊 性能对比

| 服务 | 嵌入速度 | 生成速度 | 成本 | 稳定性 |
|------|---------|---------|------|--------|
| 硅基流动 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 免费 | ⭐⭐⭐⭐ |
| DeepSeek | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 极低 | ⭐⭐⭐⭐⭐ |
| 通义千问 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 免费试用 | ⭐⭐⭐⭐⭐ |
| 本地Ollama | ⭐⭐⭐ | ⭐⭐ | 免费 | ⭐⭐⭐ |

## 🎯 推荐配置

### 开发测试环境

```yaml
rag:
  mode: openai
  openai:
    base-url: https://api.siliconflow.cn/v1
    api-key: sk-your-key
    embed-model: BAAI/bge-large-zh-v1.5
    generate-model: Qwen/Qwen2.5-7B-Instruct  # 更快
  retrieval:
    top-k: 3
    similarity-threshold: 0.75
```

### 生产环境

```yaml
rag:
  mode: openai
  openai:
    base-url: https://api.deepseek.com/v1
    api-key: sk-your-key
    embed-model: deepseek-chat
    generate-model: deepseek-chat
  retrieval:
    top-k: 5
    similarity-threshold: 0.7
```

## 📞 获取帮助

- **硅基流动文档**: https://docs.siliconflow.cn
- **DeepSeek文档**: https://platform.deepseek.com/docs
- **通义千问文档**: https://help.aliyun.com/zh/dashscope

---

**提示**: 使用免费服务时，建议先小规模测试，确认效果后再大规模使用。大多数服务都提供充值选项，价格通常很便宜（几元到几十元即可使用很久）。