RD-Agent 教程 - 第一章：基础入门
-（本教程未经全部验证，仅供参考）
1.1 项目概述与核心理念
RD-Agent 简介与背景
RD-Agent (Research & Development Agent) 是由微软研究院开发的开源自动化研发框架，专门用于数据驱动的AI解决方案构建。该项目在业界权威的机器学习工程基准测试 MLE-bench 中获得了第一名的优异成绩，成为目前表现最佳的机器学习工程代理。
核心理念：R&D 框架
RD-Agent 的设计哲学基于两个核心组件：
R (Research): 🔬 研究组件
- 自动提出新的假设和想法
- 分析现有方案的局限性
- 基于领域知识生成创新解决方案
D (Development): 🛠️ 开发组件
- 将研究想法转化为可执行代码
- 实现和验证假设
- 持续优化和改进解决方案
MLE-bench 基准测试表现
| Agent | Low (%) | Medium (%) | High (%) | All (%) |
|---|---|---|---|---|
| R&D-Agent o1-preview | 48.18 ± 2.49 | 8.95 ± 2.36 | 18.67 ± 2.98 | 22.4 ± 1.1 |
| R&D-Agent o3(R)+GPT-4.1(D) | 51.52 ± 6.21 | 7.89 ± 3.33 | 16.67 ± 3.65 | 22.45 ± 2.45 |
| AIDE o1-preview | 34.3 ± 2.4 | 8.8 ± 1.1 | 10.0 ± 1.9 | 16.9 ± 1.1 |
核心优势与应用价值
1. 自动化数据驱动研发流程
端到端自动化：从数据分析到模型部署的完整流程
智能决策支持：基于数据洞察自动生成解决方案
持续学习能力：从历史经验中学习并不断改进
2. 多代理协作架构
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 研究代理 │ │ 开发代理 │ │ 评估代理 │
│ Research Agent │◄──►│ Development │◄──►│ Evaluation │
│ │ │ Agent │ │ Agent │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│• 假设生成 │ │• 代码实现 │ │• 性能评估 │
│• 策略规划 │ │• 测试验证 │ │• 反馈生成 │
│• 知识整合 │ │• 优化改进 │ │• 质量控制 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
3. 持续学习和演进能力
CoSTEER 框架：协作演进策略框架
知识积累：自动构建和维护领域知识库
自适应优化：根据反馈动态调整策略
适用场景与目标用户
🏢 量化投资团队
自动因子挖掘：从海量数据中发现有效因子
策略开发：自动生成和优化交易策略
风险管理：智能风险控制和组合优化
成本效益：相比传统方法，以不到10美元成本获得2倍收益
🔬 数据科学家
特征工程自动化：智能特征生成和选择
模型选择优化：自动化模型架构搜索
实验管理：系统化的实验追踪和对比
管道构建：端到端机器学习管道自动构建
🎓 研究人员和学者
论文复现：自动从论文中提取和实现模型
研究助手：智能文献分析和知识提取
实验设计：科学的实验方案生成和执行
成果整理：自动化研究成果文档化
🏆 Kaggle 竞赛参与者
端到端自动化：从数据探索到模型提交
特征工程：智能特征创建和组合
模型集成：多模型融合策略优化
时间管理：高效的竞赛时间分配
1.2 系统要求与环境准备
硬件和软件要求
操作系统支持
Linux: ✅ 完全支持（Ubuntu 18.04+, CentOS 7+）
Windows: ❌ 当前不支持
macOS: ❌ 当前不支持
重要提示: RD-Agent 目前仅支持 Linux 系统。如果您使用 Windows 或 macOS，建议使用 Docker、WSL2 或虚拟机运行 Linux 环境。
Python 版本要求
Python 3.10: ✅ 完全支持（推荐）
Python 3.11: ✅ 完全支持
Python 3.9: ⚠️ 部分功能可能受限
Python 3.12+: ⚠️ 可能存在兼容性问题
内存和计算资源建议
| 使用场景 | 内存要求 | CPU 要求 | 存储空间 |
|---|---|---|---|
| 轻量级使用 | 4GB+ | 2核+ | 10GB+ |
| 中等规模 | 8GB+ | 4核+ | 50GB+ |
| 大规模应用 | 16GB+ | 8核+ | 100GB+ |
| 生产环境 | 32GB+ | 16核+ | 500GB+ |
Docker 环境配置
Docker 安装和配置
RD-Agent 强依赖 Docker 来提供隔离的运行环境，确保实验的可重现性。
Ubuntu/Debian 安装 Docker：
# 更新包索引
sudo apt-get update
# 安装必要的包
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg \
lsb-release
# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# 设置稳定版本仓库
echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装 Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
CentOS/RHEL 安装 Docker：
# 安装必要的包
sudo yum install -y yum-utils
# 添加 Docker 仓库
sudo yum-config-manager \
--add-repo \
https://download.docker.com/linux/centos/docker-ce.repo
# 安装 Docker Engine
sudo yum install docker-ce docker-ce-cli containerd.io
# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker
无 sudo 权限运行配置
这是必需的配置步骤！ RD-Agent 要求当前用户能够在不使用 sudo 的情况下运行 Docker 命令。
# 创建 docker 用户组（如果不存在）
sudo groupadd docker
# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER
# 重新加载用户组权限（或者重新登录）
newgrp docker
# 验证配置是否成功
docker run hello-world
期望输出：
Hello from Docker!
This message shows that your installation appears to be working correctly.
...
LLM API 准备
支持的 LLM 提供商
RD-Agent 通过 LiteLLM 支持多种大语言模型提供商：
| 提供商 | 支持的模型 | 推荐用途 | 成本考虑 |
|---|---|---|---|
| OpenAI | GPT-4, GPT-4-turbo, GPT-3.5-turbo | 通用场景，高质量输出 | $$$ |
| Azure OpenAI | GPT-4, GPT-3.5-turbo | 企业级应用，合规要求 | $$$ |
| DeepSeek | deepseek-chat, deepseek-coder | 代码生成，经济实惠 | $ |
| Anthropic | Claude-3.x | 长文本处理，分析任务 | $$ |
| Gemini Pro | 多模态需求 | $$ |
API 密钥获取指南
OpenAI API 密钥获取：
- 访问 OpenAI API 官网
- 注册/登录账户
- 前往 "API Keys" 页面
- 点击 "Create new secret key"
- 复制并安全保存 API 密钥
Azure OpenAI 配置：
- 登录 Azure Portal
- 创建 Azure OpenAI 资源
- 获取 API 密钥、端点和部署名称
- 记录 API 版本信息
DeepSeek API 密钥获取：
- 访问 DeepSeek API 平台
- 注册账户并完成验证
- 前往 API 密钥管理页面
- 生成新的 API 密钥
成本预算建议
| 使用强度 | 月成本预算 | 适用场景 |
|---|---|---|
| 学习试用 | $10-50 | 教程学习，小规模实验 |
| 中等使用 | $50-200 | 项目开发，中等规模应用 |
| 重度使用 | $200-1000 | 生产环境，大规模应用 |
| 企业级 | $1000+ | 企业级部署，持续运行 |
1.3 安装与基础配置
安装方式选择
用户版本安装（推荐）
对于大多数用户，直接通过 PyPI 安装是最简单的方式：
# 创建 conda 环境（推荐）
conda create -n rdagent python=3.10
conda activate rdagent
# 或使用 venv
python3.10 -m venv rdagent_env
source rdagent_env/bin/activate
# 安装 RD-Agent
pip install rdagent
开发者版本安装
如果您想要体验最新功能或参与开发，可以从源码安装：
# 克隆仓库
git clone https://github.com/microsoft/RD-Agent.git
cd RD-Agent
# 创建开发环境
conda create -n rdagent-dev python=3.10
conda activate rdagent-dev
# 安装开发依赖
make dev
# 或者手动安装
pip install -e .
pip install -r requirements/dev.txt
依赖管理和虚拟环境
为什么需要虚拟环境？
- 避免包版本冲突
- 确保环境一致性
- 便于环境管理和迁移
推荐的环境管理方式：
# 使用 conda（推荐）
conda create -n rdagent python=3.10
conda activate rdagent
# 或使用 pyenv + venv
pyenv install 3.10.12
pyenv local 3.10.12
python -m venv rdagent_env
source rdagent_env/bin/activate
基础环境配置
.env 文件配置详解
RD-Agent 使用 .env 文件来管理环境变量配置。在项目根目录创建 .env 文件：
# 在项目目录下创建 .env 文件
touch .env
LiteLLM 统一后端配置
方式一：统一 API 基础配置（推荐新手）
# OpenAI 配置示例
CHAT_MODEL=gpt-4o
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_API_BASE=https://api.openai.com/v1
方式二：分离式 API 配置（高级用户）
# 聊天模型配置
CHAT_MODEL=gpt-4o
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_API_BASE=https://api.openai.com/v1
# 嵌入模型配置（使用不同提供商）
EMBEDDING_MODEL=litellm_proxy/BAAI/bge-large-en-v1.5
LITELLM_PROXY_API_KEY=your-siliconflow-api-key
LITELLM_PROXY_API_BASE=https://api.siliconflow.cn/v1
多种 LLM 提供商配置示例
OpenAI 标准配置：
# 基础配置
CHAT_MODEL=gpt-4o
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_BASE=https://api.openai.com/v1
# 可选：推理模型特殊配置
# REASONING_THINK_RM=True # 启用思维过程移除
Azure OpenAI 配置：
# Azure OpenAI 配置
CHAT_MODEL=azure/gpt-4o-deployment-name
EMBEDDING_MODEL=azure/embedding-deployment-name
AZURE_API_KEY=your-azure-api-key
AZURE_API_BASE=https://your-resource.openai.azure.com/
AZURE_API_VERSION=2024-02-15-preview
DeepSeek 经济型配置：
# DeepSeek 聊天模型（经济实惠）
CHAT_MODEL=deepseek/deepseek-chat
DEEPSEEK_API_KEY=sk-your-deepseek-api-key
# SiliconFlow 嵌入模型（DeepSeek 无嵌入模型）
EMBEDDING_MODEL=litellm_proxy/BAAI/bge-m3
LITELLM_PROXY_API_KEY=sk-your-siliconflow-api-key
LITELLM_PROXY_API_BASE=https://api.siliconflow.cn/v1
# 推理模型配置
REASONING_THINK_RM=True
混合配置（推荐高级用户）：
# 高性能聊天模型
CHAT_MODEL=gpt-4o
OPENAI_API_KEY=sk-your-openai-api-key
# 经济型嵌入模型
EMBEDDING_MODEL=litellm_proxy/BAAI/bge-large-en-v1.5
LITELLM_PROXY_API_KEY=sk-your-siliconflow-api-key
LITELLM_PROXY_API_BASE=https://api.siliconflow.cn/v1
# 其他配置
REASONING_THINK_RM=False
健康检查与验证
rdagent health_check 使用
安装完成后，首先进行系统健康检查：
# 完整健康检查
rdagent health_check
# 跳过环境变量检查
rdagent health_check --no-check-env
# 跳过 Docker 检查
rdagent health_check --no-check-docker
# 只检查端口占用
rdagent health_check --no-check-env --no-check-docker
期望的成功输出：
✅ Docker is installed and working correctly
✅ Port 19899 is available
✅ Environment variables are configured correctly
✅ LLM API connection successful
✅ All systems check passed!
常见配置问题排查
问题 1：Docker 权限错误
❌ Error: Got permission denied while trying to connect to the Docker daemon socket
解决方案：
# 确保用户在 docker 组中
sudo usermod -aG docker $USER
newgrp docker
# 重新运行健康检查
rdagent health_check
问题 2：API 密钥无效
❌ Error: Invalid API key provided
解决方案：
# 检查 .env 文件中的 API 密钥
cat .env | grep API_KEY
# 确保密钥正确且有效
# 重新配置 API 密钥
问题 3：端口被占用
❌ Error: Port 19899 is already in use
解决方案：
# 查看端口占用情况
netstat -tlnp | grep 19899
# 结束占用进程或更换端口
rdagent ui --port 19900
问题 4：网络连接问题
❌ Error: Failed to connect to API endpoint
解决方案：
# 检查网络连接
curl -I https://api.openai.com/v1/models
# 配置代理（如需要）
export https_proxy=http://proxy.company.com:8080
export http_proxy=http://proxy.company.com:8080
环境验证清单
在开始使用 RD-Agent 之前，请确认以下检查项：
- [ ] 操作系统: Linux 环境
- [ ] Python 版本: 3.10 或 3.11
- [ ] 虚拟环境: 已激活专用环境
- [ ] Docker: 安装并可无 sudo 运行
- [ ] 网络连接: 能访问 LLM API 端点
- [ ] API 密钥: 有效且有足够余额
- [ ] 存储空间: 至少 10GB 可用空间
- [ ] 端口: 19899 端口可用（或指定其他端口）
- [ ] 权限: 当前用户有读写项目目录权限
至此，您已完成 RD-Agent 的基础安装和配置。下一章我们将详细介绍 RD-Agent 的核心功能和使用方法。
快速验证安装
完成所有配置后，让我们进行一个快速的功能验证：
# 激活环境
conda activate rdagent
# 验证安装
python -c "import rdagent; print('RD-Agent installed successfully!')"
# 运行健康检查
rdagent health_check
# 查看可用命令
rdagent --help
如果所有步骤都正常完成，您现在已经准备好开始使用 RD-Agent 的强大功能了！
SOCIAL SHARE CARD GENERATOR