QQbot/docs/CONFIG_GUIDE.md

# AI模型接入系统 - 配置说明

## 📋 配置文件说明

所有配置都在 `.env` 文件中统一管理。

### 1. 基础配置

```env
# QQ机器人配置
BOT_APPID=你的机器人APPID
BOT_SECRET=你的机器人SECRET

# 日志配置
LOG_LEVEL=INFO

# 沙箱模式
SANDBOX_MODE=False
```

### 2. AI主模型配置

```env
# AI主模型配置
AI_PROVIDER=openai  # 可选: openai, anthropic, deepseek, qwen
AI_MODEL=gpt-4
AI_API_KEY=你的API密钥
AI_API_BASE=https://api.openai.com/v1  # 可选
```

**支持的模型提供商**：
- `openai` - OpenAI (GPT-4, GPT-3.5-turbo等)
- `anthropic` - Anthropic Claude
- `deepseek` - DeepSeek
- `qwen` - 通义千问

### 3. AI嵌入模型配置（用于RAG）

```env
# AI嵌入模型配置（用于RAG记忆检索）
AI_EMBED_PROVIDER=openai  # 可选: openai, deepseek, qwen
AI_EMBED_MODEL=text-embedding-3-small
AI_EMBED_API_KEY=  # 留空则使用 AI_API_KEY
AI_EMBED_API_BASE=  # 留空则使用 AI_API_BASE

# 向量数据库配置
AI_USE_VECTOR_DB=true  # 是否使用Chroma向量数据库（推荐），false则使用JSON存储
```

**为什么需要嵌入模型？**

嵌入模型用于将文本转换为向量，实现RAG（检索增强生成）功能：
- 长期记忆的向量检索
- 相似对话的智能查找
- 上下文相关性匹配


**向量数据库配置**：

系统支持两种存储方式：
1. **Chroma向量数据库**（推荐）：专业的向量存储，支持高效检索和持久化
2. **JSON文件存储**：简单的文件存储，适合测试和小规模使用

```env
AI_USE_VECTOR_DB=true  # 使用Chroma（推荐）
# AI_USE_VECTOR_DB=false  # 使用JSON存储
```

**数据迁移**：

如果你之前使用JSON存储，现在想切换到Chroma，可以使用迁移工具：

```bash
# 预览迁移（不实际执行）
python -m src.ai.migrate_data --dry-run

# 执行迁移
python -m src.ai.migrate_data
```

**嵌入模型配置说明**：


1. **使用OpenAI嵌入模型**（推荐）：
```env
AI_EMBED_PROVIDER=openai
AI_EMBED_MODEL=text-embedding-3-small  # 或 text-embedding-3-large
AI_EMBED_API_KEY=  # 留空使用主模型的key
```

2. **使用DeepSeek嵌入模型**：
```env
AI_EMBED_PROVIDER=deepseek
AI_EMBED_MODEL=deepseek-chat  # DeepSeek使用同一个模型
AI_EMBED_API_KEY=  # 留空使用主模型的key
```

3. **不配置嵌入模型**：
- 如果不配置，系统会尝试使用主模型的嵌入功能
- 如果主模型不支持（如Claude），RAG功能将降级为基于重要性的检索

## 🔧 配置示例

### 示例1: 使用OpenAI（推荐）

```env
# 主模型
AI_PROVIDER=openai
AI_MODEL=gpt-4
AI_API_KEY=sk-xxx

# 嵌入模型（使用OpenAI的嵌入模型）
AI_EMBED_PROVIDER=openai
AI_EMBED_MODEL=text-embedding-3-small
AI_EMBED_API_KEY=  # 留空，使用主模型的key
```

### 示例2: 使用Claude + OpenAI嵌入

```env
# 主模型（Claude）
AI_PROVIDER=anthropic
AI_MODEL=claude-3-5-sonnet-20241022
AI_API_KEY=sk-ant-xxx

# 嵌入模型（OpenAI，因为Claude不提供嵌入）
AI_EMBED_PROVIDER=openai
AI_EMBED_MODEL=text-embedding-3-small
AI_EMBED_API_KEY=sk-xxx  # 需要单独的OpenAI key
```

### 示例3: 使用DeepSeek

```env
# 主模型
AI_PROVIDER=deepseek
AI_MODEL=deepseek-chat
AI_API_KEY=sk-xxx
AI_API_BASE=https://api.deepseek.com/v1

# 嵌入模型（使用同一个DeepSeek模型）
AI_EMBED_PROVIDER=deepseek
AI_EMBED_MODEL=deepseek-chat
AI_EMBED_API_KEY=  # 留空，使用主模型的key
AI_EMBED_API_BASE=  # 留空，使用主模型的base
```

### 示例4: 不使用RAG（最简配置）

```env
# 只配置主模型，不配置嵌入模型
AI_PROVIDER=openai
AI_MODEL=gpt-4
AI_API_KEY=sk-xxx

# 不配置嵌入模型
# AI_EMBED_PROVIDER=
# AI_EMBED_MODEL=
```

这种情况下，记忆系统会降级为基于重要性的检索，不使用向量相似度。

## 📊 嵌入模型对比

| 模型 | 提供商 | 维度 | 性能 | 成本 |
|------|--------|------|------|------|
| text-embedding-3-small | OpenAI | 1536 | 快 | 低 |
| text-embedding-3-large | OpenAI | 3072 | 慢 | 高 |
| deepseek-chat | DeepSeek | - | 中 | 低 |

**推荐**：
- 一般使用：`text-embedding-3-small`
- 高精度需求：`text-embedding-3-large`
- 成本敏感：使用主模型的嵌入功能或不使用RAG

## ⚙️ 高级配置

### 自定义API地址

```env
# 使用代理或自建服务
AI_API_BASE=https://your-proxy.com/v1
AI_EMBED_API_BASE=https://your-proxy.com/v1
```

### 使用不同的API密钥

```env
# 主模型使用一个key
AI_API_KEY=sk-main-xxx

# 嵌入模型使用另一个key
AI_EMBED_API_KEY=sk-embed-xxx
```

## 🔍 验证配置

启动机器人后，查看日志：

```
✅ AI配置: openai/gpt-4
✅ 嵌入模型初始化: openai/text-embedding-3-small
✅ AI客户端初始化完成: openai/gpt-4
```

如果看到这些日志，说明配置成功！

## ❓ 常见问题

**Q: 必须配置嵌入模型吗？**
A: 不是必须的。如果不配置，RAG功能会降级，但基本功能仍可用。

**Q: Claude不支持嵌入怎么办？**
A: 配置OpenAI的嵌入模型作为补充，或者不使用RAG功能。

**Q: 嵌入模型可以和主模型不同吗？**
A: 可以！推荐使用OpenAI的嵌入模型，即使主模型是其他提供商。

**Q: 如何降低成本？**
A: 使用 `text-embedding-3-small` 或不配置嵌入模型。

## 📚 相关文档

- [快速开始](AI_QUICKSTART.md)
- [完整文档](../src/ai/docs/README.md)
- [实现总结](AI_IMPLEMENTATION.md)