跳转至

RD-Agent 教程 - 第二章:核心功能详解

2.1 命令行界面基础

CLI 结构和设计原理

RD-Agent 采用统一的命令行界面(CLI)设计,所有功能都通过 rdagent 命令访问。CLI 的核心实现位于 rdagent/app/cli.py,使用 Typer 框架构建,提供了直观和强大的命令行体验。

架构分析

# rdagent/app/cli.py 核心结构
import typer
from rdagent.app.data_science.loop import main as data_science
from rdagent.app.qlib_rd_loop.factor import main as fin_factor
from rdagent.app.qlib_rd_loop.model import main as fin_model
from rdagent.app.qlib_rd_loop.quant import main as fin_quant

app = typer.Typer()

# 注册命令
app.command(name="fin_factor")(fin_factor)
app.command(name="fin_model")(fin_model)
app.command(name="data_science")(data_science)

命令分类和组织方式

RD-Agent 的命令按功能领域组织:

命令类别 命令 功能描述 主要用途
金融量化 fin_factor 因子自动挖掘 发现有效的量化因子
fin_model 模型自动演进 优化预测模型
fin_quant 因子模型联合优化 端到端策略开发
fin_factor_report 报告因子提取 从金融报告提取信号
数据科学 data_science 通用数据科学任务 ML 竞赛、建模项目
通用模型 general_model 论文模型实现 研究论文复现
工具功能 ui Web 界面 可视化监控
health_check 健康检查 系统状态验证
collect_info 信息收集 诊断和调试

自动环境加载机制

RD-Agent CLI 的一个重要特性是自动加载环境变量:

from dotenv import load_dotenv
load_dotenv(".env")  # 自动加载当前目录的 .env 文件

优势: - 🔄 自动配置加载,无需手动设置环境变量 - 📁 支持项目级配置,不同项目可有不同配置 - 🔒 配置文件本地存储,提高安全性

基础命令使用

帮助系统使用

# 查看所有可用命令
rdagent --help

# 查看特定命令的详细帮助
rdagent fin_factor --help
rdagent data_science --help

# 查看子命令参数
rdagent ui --help

示例输出:

Usage: rdagent [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  data_science        Run data science automation
  fin_factor         Run factor mining
  fin_model          Run model evolution
  fin_quant          Run factor-model joint optimization
  general_model      Extract and implement models from papers
  health_check       Check system health
  ui                 Start web interface

全局参数和选项

虽然 RD-Agent 的大部分配置通过 .env 文件管理,但某些命令支持运行时参数:

# UI 命令的常用参数
rdagent ui --port 19899 --log-dir ./log --debug

# 健康检查的选择性检查
rdagent health_check --no-check-env --no-check-docker

# 数据科学命令的竞赛指定
rdagent data_science --competition tabular-playground-series-dec-2021

日志和输出管理

RD-Agent 提供丰富的日志记录功能:

# 默认日志级别运行
rdagent fin_factor

# 启用详细日志(通过环境变量)
export RDAGENT_LOG_LEVEL=DEBUG
rdagent fin_factor

# 指定日志输出目录
export RDAGENT_LOG_DIR=./custom_logs
rdagent fin_quant

# 快速测试,只验证一次
rdagent data_science --competition titanic --loop-n 1

日志结构:

logs/
├── rdagent.log                 # 主日志文件
├── experiments/                # 实验日志
│   ├── factor_exp_001/
│   └── model_exp_001/
└── ui/                        # Web UI 日志
    └── access.log

监控界面使用

Web UI 启动和配置

RD-Agent 提供了强大的 Web 界面用于实时监控和结果查看:

# 基本启动
rdagent ui --port 19899

# 指定日志目录
rdagent ui --port 19899 --log-dir ./logs

# 启用调试模式
rdagent ui --port 19899 --debug

# 数据科学专用界面
rdagent ui --port 19899 --data_science True

实时监控功能

Web UI 提供以下监控能力:

1. 实验进度追踪 - 📊 实时显示实验状态 - 📈 性能指标图表 - ⏱️ 时间线视图 - 🔄 自动刷新

2. 日志查看器 - 📝 结构化日志显示 - 🔍 日志搜索和过滤 - 📋 多级别日志(INFO、DEBUG、ERROR) - 💾 日志导出功能

3. 结果可视化 - 📊 因子性能对比 - 📈 模型训练曲线 - 🎯 回测结果图表 - 📋 详细性能报告

界面功能详解

主仪表板:

┌─────────────────────────────────────────┐
│ RD-Agent 监控面板                        │
├─────────────────────────────────────────┤
│ 🔄 实验状态: 运行中 (2/5)                │
│ ⏱️ 运行时间: 1小时23分钟                  │
│ 📊 当前任务: 因子验证                     │
│ 🎯 最佳得分: 0.234 (IC)                  │
└─────────────────────────────────────────┘

实验列表:

实验ID    | 类型    | 状态    | 开始时间    | 得分
---------|---------|---------|-------------|-------
EXP_001  | 因子    | 完成    | 14:23:01   | 0.198
EXP_002  | 因子    | 运行中  | 14:45:12   | -
EXP_003  | 模型    | 等待    | -          | -

2.2 数据科学代理详解

数据科学场景概述

RD-Agent 的数据科学代理是一个全自动的机器学习工程系统,能够自主完成从数据探索到模型部署的完整流程。该代理在 MLE-bench 基准测试中获得第一名,展现了强大的自动化能力。

支持的任务类型

任务类型 描述 应用场景 技术特点
表格数据建模 结构化数据的预测任务 金融预测、用户行为分析 特征工程、模型集成
时间序列预测 时序数据的预测建模 股价预测、需求预测 时序特征、序列模型
图像分类 计算机视觉任务 医疗影像、产品识别 CNN、迁移学习
自然语言处理 文本数据处理 情感分析、文档分类 预训练模型、嵌入
回归分析 连续值预测 价格预测、评分预估 线性/非线性模型

工作流程和架构

graph TD
    A[数据输入] --> B[假设生成]
    B --> C[实验设计]
    C --> D[特征工程]
    D --> E[模型开发]
    E --> F[验证测试]
    F --> G[结果分析]
    G --> H{性能满足要求?}
    H -->|否| I[反馈学习]
    I --> B
    H -->|是| J[模型输出]

    style B fill:#e1f5fe
    style D fill:#f3e5f5
    style E fill:#e8f5e8
    style G fill:#fff3e0

核心组件:

  1. 假设生成器 - 基于数据特征和问题类型生成建模假设
  2. 实验管理器 - 系统化管理实验流程和资源
  3. 特征工程器 - 自动生成和选择有效特征
  4. 模型开发器 - 自动选择和调优模型
  5. 评估系统 - 多维度评估模型性能
  6. 知识管理 - 积累和复用实验经验

与其他工具的集成

# 支持的数据格式和来源
Data Sources:
├── CSV/Excel 文件
├── Kaggle 竞赛数据
├── 数据库连接 (SQL)
├── API 数据源
├── 图像文件夹
└── 文本文档集合

Model Frameworks:
├── Scikit-learn
├── XGBoost/LightGBM
├── PyTorch
├── TensorFlow/Keras
├── Transformers (Hugging Face)
└── 自定义模型

Kaggle 竞赛自动化

Kaggle API 配置

首先需要配置 Kaggle API 以访问竞赛数据:

# 1. 获取 Kaggle API Token
# 登录 Kaggle -> Account -> Create New Token
# 下载 kaggle.json 文件

# 2. 配置 API 文件
mkdir -p ~/.kaggle
mv ~/Downloads/kaggle.json ~/.kaggle/
chmod 600 ~/.kaggle/kaggle.json

# 3. 验证配置
kaggle competitions list

环境变量配置

在 .env 文件中添加数据科学相关配置:

# 数据科学代理配置
DS_LOCAL_DATA_PATH="./data/competitions"
DS_CODER_ON_WHOLE_PIPELINE=True
DS_IF_USING_MLE_DATA=True
DS_SAMPLE_DATA_BY_LLM=True
DS_SCEN=rdagent.scenarios.data_science.scen.KaggleScen

# LLM 配置(如前所述)
CHAT_MODEL=gpt-4o
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=your-api-key

竞赛数据自动下载

# 自动下载并处理竞赛数据
rdagent data_science --competition tabular-playground-series-dec-2021

# 指定自定义数据路径
export DS_LOCAL_DATA_PATH="./custom_data"
rdagent data_science --competition house-prices-advanced-regression-techniques

完整竞赛流程演示

以 "Tabular Playground Series - Dec 2021" 为例:

Step 1: 环境准备

# 创建项目目录
mkdir kaggle_rdagent_demo && cd kaggle_rdagent_demo

# 配置环境
cat > .env << EOF
CHAT_MODEL=gpt-4o
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=your-openai-api-key

DS_LOCAL_DATA_PATH="$(pwd)/data"
DS_CODER_ON_WHOLE_PIPELINE=True
DS_IF_USING_MLE_DATA=True
DS_SAMPLE_DATA_BY_LLM=True
DS_SCEN=rdagent.scenarios.data_science.scen.KaggleScen
EOF

Step 2: 启动自动化流程

# 启动 RD-Agent 数据科学代理
rdagent data_science --competition tabular-playground-series-dec-2021

Step 3: 实时监控

# 在另一个终端启动监控界面
rdagent ui --port 19899 --data_science True
# 访问 http://localhost:19899

自动执行的流程:

  1. 数据下载和探索
  2. 自动下载竞赛数据
  3. 生成数据探索报告
  4. 识别数据类型和分布

  5. 假设生成

  6. 基于数据特征生成建模假设
  7. 分析目标变量特性
  8. 识别潜在的特征工程机会

  9. 特征工程

  10. 自动生成数值特征变换
  11. 类别特征编码
  12. 交互特征创建
  13. 时间特征提取(如适用)

  14. 模型开发

  15. 尝试多种算法(随机森林、XGBoost、神经网络等)
  16. 自动超参数调优
  17. 交叉验证和模型选择

  18. 模型集成

  19. Stacking/Blending 策略
  20. 多模型融合
  21. 权重优化

  22. 提交准备

  23. 生成预测文件
  24. 格式验证
  25. 自动提交(可选)

医疗预测模型场景

医疗数据处理

医疗数据通常具有特殊性,RD-Agent 提供专门的处理能力:

# 运行医疗预测任务
rdagent data_science --competition medical-prediction-task

# 示例:急性肾衰竭预测
wget https://github.com/SunsetWolf/rdagent_resource/releases/download/ds_data/arf-12-hours-prediction-task.zip
unzip arf-12-hours-prediction-task.zip -d ./data/

医疗数据特点处理:

  1. 隐私保护
  2. 数据脱敏和匿名化
  3. HIPAA 合规性考虑
  4. 本地处理,不上传原始数据

  5. 不平衡数据处理

  6. SMOTE 过采样
  7. 成本敏感学习
  8. 阈值调优

  9. 时序医疗数据

  10. 病程时间建模
  11. 多时间点特征
  12. 生存分析方法

  13. 多模态数据融合

  14. 结构化数据(检验指标)
  15. 非结构化数据(病历文本)
  16. 医学图像数据

预测模型开发

# 医疗预测的特殊配置示例
medical_config = {
    "task_type": "classification",
    "positive_class_weight": 10,  # 处理不平衡
    "cross_validation_folds": 10,  # 更多折数
    "feature_selection": "medical_relevance",
    "interpretability": True,  # 医疗需要可解释性
    "ensemble_methods": ["voting", "stacking"],
    "evaluation_metrics": ["auc", "precision", "recall", "f1"],
}

模型评估和优化

医疗模型的评估更注重:

  • 🎯 临床指标: Sensitivity, Specificity, PPV, NPV
  • 📊 ROC/PR 曲线: 不同阈值下的性能
  • ⚖️ 成本效益分析: 误诊和漏诊的代价
  • 🔍 可解释性: SHAP 值和特征重要性

通用数据科学任务

自定义数据集处理

对于非竞赛数据,RD-Agent 支持灵活的数据接入:

# 创建数据目录结构
mkdir -p custom_project/data
cd custom_project

# 准备数据文件
# train.csv - 训练数据
# test.csv - 测试数据(可选)
# sample_submission.csv - 提交格式(可选)

# 配置环境
cat > .env << EOF
DS_LOCAL_DATA_PATH="$(pwd)/data"
DS_CODER_ON_WHOLE_PIPELINE=True
DS_IF_USING_MLE_DATA=False  # 非 MLE 数据
DS_SAMPLE_DATA_BY_LLM=False
DS_SCEN=rdagent.scenarios.data_science.scen.DataScienceScen
EOF

# 运行分析
rdagent data_science --competition custom_project

数据格式要求

标准表格数据:

data/
├── train.csv          # 必需:训练数据
├── test.csv           # 可选:测试数据
├── sample_submission.csv  # 可选:提交格式
└── description.md     # 可选:问题描述

多模态数据:

data/
├── tabular/
│   ├── train.csv
│   └── test.csv
├── images/
│   ├── train/
│   └── test/
├── text/
│   ├── train_texts.json
│   └── test_texts.json
└── config.yaml       # 数据配置文件

模型选择和调优

RD-Agent 智能选择最适合的算法:

分类任务算法选择:

classification_algorithms = {
    "small_data": ["RandomForest", "SVM", "LogisticRegression"],
    "medium_data": ["XGBoost", "LightGBM", "CatBoost"],
    "large_data": ["NeuralNetwork", "TabNet", "AutoML"],
    "text_data": ["BERT", "RoBERTa", "DistilBERT"],
    "image_data": ["ResNet", "EfficientNet", "ViT"],
}

超参数调优策略:

tuning_strategies = {
    "bayesian_optimization": "高效的参数空间搜索",
    "random_search": "快速初步调优",
    "grid_search": "精确但耗时的搜索",
    "evolutionary": "复杂空间的全局优化",
    "hyperband": "多保真度优化",
}

特征工程自动化

数值特征处理:

numerical_transformations = [
    "StandardScaler",      # 标准化
    "MinMaxScaler",        # 归一化
    "RobustScaler",        # 鲁棒缩放
    "PowerTransformer",    # 幂变换
    "QuantileTransformer", # 分位数变换
    "PCA",                 # 主成分分析
    "PolynomialFeatures",  # 多项式特征
]

类别特征处理:

categorical_transformations = [
    "OneHotEncoder",       # 独热编码
    "LabelEncoder",        # 标签编码
    "TargetEncoder",       # 目标编码
    "BinaryEncoder",       # 二进制编码
    "HashingEncoder",      # 哈希编码
    "FrequencyEncoder",    # 频次编码
]

自动特征生成:

auto_feature_generation = [
    "feature_interactions",  # 特征交互
    "feature_aggregations", # 特征聚合
    "feature_ratios",       # 特征比值
    "feature_differences",  # 特征差值
    "time_based_features",  # 时间特征
    "text_embeddings",      # 文本嵌入
]

总结

本章详细介绍了 RD-Agent 的核心功能,包括:

  1. 命令行界面基础 - 统一的 CLI 设计和监控能力
  2. 数据科学代理详解 - 自动化机器学习的完整流程
  3. 实际应用场景 - Kaggle 竞赛、医疗预测、通用建模

下一章我们将深入探讨量化金融代理和通用模型代理的高级功能。


快速参考命令:

# 启动数据科学项目
rdagent data_science --competition <project_name>

# 启动监控界面
rdagent ui --port 19899 --data_science True

# 健康检查
rdagent health_check

# 查看帮助
rdagent data_science --help