Skip to content

RD-Agent Tutorial - Chapter 2: Core Functions In Depth

2.1 Command Line Interface Basics

CLI Structure and Design Principles

RD-Agent adopts a unified command line interface (CLI) design; all features are accessed through the rdagent command. The core implementation of the CLI is located in rdagent/app/cli.py, built with the Typer framework, providing an intuitive and powerful command line experience.

Architecture Analysis

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

Command Categories and Organization

RD-Agent's commands are organized by functional domain:

Command Category Command Description Primary Use Case
Financial Quant fin_factor Automatic factor mining Discovering effective quantitative factors
fin_model Automatic model evolution Optimizing prediction models
fin_quant Joint factor-model optimization End-to-end strategy development
fin_factor_report Report factor extraction Extracting signals from financial reports
Data Science data_science General data science tasks ML competitions, modeling projects
General Models general_model Paper model implementation Research paper reproduction
Utility Functions ui Web interface Visual monitoring
health_check Health check System status verification
collect_info Information collection Diagnostics and debugging

Automatic Environment Loading Mechanism

An important feature of the RD-Agent CLI is automatic loading of environment variables:

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

Advantages: - 🔄 Automatic configuration loading, no need to set environment variables manually - 📁 Project-level configuration support, different projects can have different configurations - 🔒 Configuration files stored locally, improving security

Basic Command Usage

Using the Help System

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

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

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

Example output:

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

Global Parameters and Options

Although most of RD-Agent's configuration is managed through the .env file, some commands support runtime parameters:

# 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

Log and Output Management

RD-Agent provides rich logging capabilities:

# 默认日志级别运行
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

Log structure:

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

Using the Monitoring Interface

Web UI Startup and Configuration

RD-Agent provides a powerful web interface for real-time monitoring and result viewing:

# 基本启动
rdagent ui --port 19899

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

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

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

Real-Time Monitoring Features

The Web UI provides the following monitoring capabilities:

1. Experiment progress tracking - 📊 Real-time display of experiment status - 📈 Performance metric charts - ⏱️ Timeline view - 🔄 Automatic refresh

2. Log viewer - 📝 Structured log display - 🔍 Log search and filtering - 📋 Multiple log levels (INFO, DEBUG, ERROR) - 💾 Log export functionality

3. Result visualization - 📊 Factor performance comparison - 📈 Model training curves - 🎯 Backtest result charts - 📋 Detailed performance reports

Interface Feature Details

Main dashboard:

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

Experiment list:

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

2.2 Data Science Agent In Depth

Data Science Scenario Overview

RD-Agent's data science agent is a fully automated machine learning engineering system capable of autonomously completing the entire pipeline from data exploration to model deployment. The agent won first place in the MLE-bench benchmark, demonstrating powerful automation capabilities.

Supported Task Types

Task Type Description Application Scenarios Technical Characteristics
Tabular data modeling Prediction tasks on structured data Financial forecasting, user behavior analysis Feature engineering, model ensembling
Time series forecasting Predictive modeling of time series data Stock price prediction, demand forecasting Time series features, sequence models
Image classification Computer vision tasks Medical imaging, product recognition CNN, transfer learning
Natural language processing Text data processing Sentiment analysis, document classification Pretrained models, embeddings
Regression analysis Continuous value prediction Price prediction, rating estimation Linear/nonlinear models

Workflow and Architecture

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

Core components:

  1. Hypothesis generator - Generates modeling hypotheses based on data characteristics and problem type
  2. Experiment manager - Systematically manages the experiment workflow and resources
  3. Feature engineer - Automatically generates and selects effective features
  4. Model developer - Automatically selects and tunes models
  5. Evaluation system - Evaluates model performance across multiple dimensions
  6. Knowledge management - Accumulates and reuses experiment experience

Integration with Other Tools

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

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

Kaggle Competition Automation

Kaggle API Configuration

First you need to configure the Kaggle API to access competition data:

# 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

Environment Variable Configuration

Add data science related configuration to the .env file:

# 数据科学代理配置
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

Automatic Competition Data Download

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

Complete Competition Workflow Demonstration

Using "Tabular Playground Series - Dec 2021" as an example:

Step 1: Environment preparation

# 创建项目目录
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: Start the automated workflow

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

Step 3: Real-time monitoring

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

Automated workflow:

  1. Data download and exploration
  2. Automatically download competition data
  3. Generate a data exploration report
  4. Identify data types and distributions

  5. Hypothesis generation

  6. Generate modeling hypotheses based on data characteristics
  7. Analyze target variable properties
  8. Identify potential feature engineering opportunities

  9. Feature engineering

  10. Automatically generate numerical feature transformations
  11. Categorical feature encoding
  12. Interaction feature creation
  13. Time feature extraction (if applicable)

  14. Model development

  15. Try multiple algorithms (Random Forest, XGBoost, neural networks, etc.)
  16. Automatic hyperparameter tuning
  17. Cross-validation and model selection

  18. Model ensembling

  19. Stacking/Blending strategies
  20. Multi-model fusion
  21. Weight optimization

  22. Submission preparation

  23. Generate prediction files
  24. Format validation
  25. Automatic submission (optional)

Medical Prediction Model Scenario

Medical Data Processing

Medical data often has special characteristics, and RD-Agent provides dedicated processing capabilities:

# 运行医疗预测任务
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/

Handling medical data characteristics:

  1. Privacy protection
  2. Data de-identification and anonymization
  3. HIPAA compliance considerations
  4. Local processing, no raw data uploaded

  5. Imbalanced data handling

  6. SMOTE oversampling
  7. Cost-sensitive learning
  8. Threshold tuning

  9. Temporal medical data

  10. Disease course time modeling
  11. Multi-timepoint features
  12. Survival analysis methods

  13. Multimodal data fusion

  14. Structured data (lab test metrics)
  15. Unstructured data (medical record text)
  16. Medical image data

Prediction Model Development

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

Model Evaluation and Optimization

Medical model evaluation places greater emphasis on:

  • 🎯 Clinical metrics: Sensitivity, Specificity, PPV, NPV
  • 📊 ROC/PR curves: Performance across different thresholds
  • ⚖️ Cost-benefit analysis: The cost of misdiagnosis and missed diagnosis
  • 🔍 Interpretability: SHAP values and feature importance

General Data Science Tasks

Custom Dataset Processing

For non-competition data, RD-Agent supports flexible data ingestion:

# 创建数据目录结构
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 Format Requirements

Standard tabular data:

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

Multimodal data:

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

Model Selection and Tuning

RD-Agent intelligently selects the most suitable algorithms:

Algorithm selection for classification tasks:

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"],
}

Hyperparameter tuning strategies:

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

Feature Engineering Automation

Numerical feature processing:

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

Categorical feature processing:

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

Automatic feature generation:

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

Summary

This chapter introduced RD-Agent's core functions in detail, including:

  1. Command line interface basics - Unified CLI design and monitoring capabilities
  2. Data science agent in depth - The complete automated machine learning pipeline
  3. Practical application scenarios - Kaggle competitions, medical prediction, general modeling

In the next chapter, we will explore the advanced features of the quantitative finance agent and the general model agent.


Quick reference commands:

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

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

# 健康检查
rdagent health_check

# 查看帮助
rdagent data_science --help