QQbot/docs/CONFIG_GUIDE.md

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

📋 配置文件说明

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

1. 基础配置

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

# 日志配置
LOG_LEVEL=INFO

# 沙箱模式
SANDBOX_MODE=False

2. AI主模型配置

# 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）

# 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文件存储：简单的文件存储，适合测试和小规模使用

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

数据迁移：

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

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

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

嵌入模型配置说明：

1. 使用OpenAI嵌入模型（推荐）：

AI_EMBED_PROVIDER=openai
AI_EMBED_MODEL=text-embedding-3-small  # 或 text-embedding-3-large
AI_EMBED_API_KEY=  # 留空使用主模型的key

2. 使用DeepSeek嵌入模型：

AI_EMBED_PROVIDER=deepseek
AI_EMBED_MODEL=deepseek-chat  # DeepSeek使用同一个模型
AI_EMBED_API_KEY=  # 留空使用主模型的key

3. 不配置嵌入模型：

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

🔧 配置示例

示例1: 使用OpenAI（推荐）

# 主模型
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嵌入

# 主模型（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

# 主模型
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（最简配置）

# 只配置主模型，不配置嵌入模型
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地址

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

使用不同的API密钥

# 主模型使用一个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 或不配置嵌入模型。

📚 相关文档

• 快速开始
• 完整文档
• 实现总结