DEV Community

Henry Lin
Henry Lin

Posted on

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

#architecture #cli #python #tutorial

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)
Enter fullscreen mode Exit fullscreen mode

命令分类和组织方式

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 文件
Enter fullscreen mode Exit fullscreen mode

优势：

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

基础命令使用

帮助系统使用 

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

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

# 查看子命令参数
rdagent ui --help
Enter fullscreen mode Exit fullscreen mode

示例输出：

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
Enter fullscreen mode Exit fullscreen mode

全局参数和选项

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

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

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

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

日志和输出管理

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

# 默认日志级别运行
rdagent fin_factor

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

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

日志结构：

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

监控界面使用

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
Enter fullscreen mode Exit fullscreen mode

实时监控功能

Web UI 提供以下监控能力：

1. 实验进度追踪

  • 📊 实时显示实验状态
  • 📈 性能指标图表
  • ⏱️ 时间线视图
  • 🔄 自动刷新

2. 日志查看器

  • 📝 结构化日志显示
  • 🔍 日志搜索和过滤
  • 📋 多级别日志（INFO、DEBUG、ERROR）
  • 💾 日志导出功能

3. 结果可视化

  • 📊 因子性能对比
  • 📈 模型训练曲线
  • 🎯 回测结果图表
  • 📋 详细性能报告

界面功能详解

主仪表板：

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

实验列表：

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

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
Enter fullscreen mode Exit fullscreen mode

核心组件：

  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)
└── 自定义模型
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

环境变量配置

在 .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
Enter fullscreen mode Exit fullscreen mode

竞赛数据自动下载 

# 自动下载并处理竞赛数据
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
Enter fullscreen mode Exit fullscreen mode

完整竞赛流程演示

以 "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
Enter fullscreen mode Exit fullscreen mode

Step 2: 启动自动化流程

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

Step 3: 实时监控

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

自动执行的流程：

  1. 数据下载和探索

    • 自动下载竞赛数据
    • 生成数据探索报告
    • 识别数据类型和分布

  2. 假设生成

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

  3. 特征工程

    • 自动生成数值特征变换
    • 类别特征编码
    • 交互特征创建
    • 时间特征提取（如适用）

  4. 模型开发

    • 尝试多种算法（随机森林、XGBoost、神经网络等）
    • 自动超参数调优
    • 交叉验证和模型选择

  5. 模型集成

    • Stacking/Blending 策略
    • 多模型融合
    • 权重优化

  6. 提交准备

    • 生成预测文件
    • 格式验证
    • 自动提交（可选）

医疗预测模型场景

医疗数据处理

医疗数据通常具有特殊性，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/
Enter fullscreen mode Exit fullscreen mode

医疗数据特点处理：

  1. 隐私保护

    • 数据脱敏和匿名化
    • HIPAA 合规性考虑
    • 本地处理，不上传原始数据

  2. 不平衡数据处理

    • SMOTE 过采样
    • 成本敏感学习
    • 阈值调优

  3. 时序医疗数据

    • 病程时间建模
    • 多时间点特征
    • 生存分析方法

  4. 多模态数据融合

    • 结构化数据（检验指标）
    • 非结构化数据（病历文本）
    • 医学图像数据

预测模型开发 

# 医疗预测的特殊配置示例
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"],
}
Enter fullscreen mode Exit fullscreen mode

模型评估和优化

医疗模型的评估更注重：

  • 🎯 临床指标: 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
Enter fullscreen mode Exit fullscreen mode

数据格式要求

标准表格数据：

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

多模态数据：

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

模型选择和调优

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"],
}
Enter fullscreen mode Exit fullscreen mode

超参数调优策略：

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

特征工程自动化

数值特征处理：

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

类别特征处理：

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

自动特征生成：

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

总结

本章详细介绍了 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
Enter fullscreen mode Exit fullscreen mode

Top comments (0)