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:
- Hypothesis generator - Generates modeling hypotheses based on data characteristics and problem type
- Experiment manager - Systematically manages the experiment workflow and resources
- Feature engineer - Automatically generates and selects effective features
- Model developer - Automatically selects and tunes models
- Evaluation system - Evaluates model performance across multiple dimensions
- 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:
- Data download and exploration
- Automatically download competition data
- Generate a data exploration report
-
Identify data types and distributions
-
Hypothesis generation
- Generate modeling hypotheses based on data characteristics
- Analyze target variable properties
-
Identify potential feature engineering opportunities
-
Feature engineering
- Automatically generate numerical feature transformations
- Categorical feature encoding
- Interaction feature creation
-
Time feature extraction (if applicable)
-
Model development
- Try multiple algorithms (Random Forest, XGBoost, neural networks, etc.)
- Automatic hyperparameter tuning
-
Cross-validation and model selection
-
Model ensembling
- Stacking/Blending strategies
- Multi-model fusion
-
Weight optimization
-
Submission preparation
- Generate prediction files
- Format validation
- 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:
- Privacy protection
- Data de-identification and anonymization
- HIPAA compliance considerations
-
Local processing, no raw data uploaded
-
Imbalanced data handling
- SMOTE oversampling
- Cost-sensitive learning
-
Threshold tuning
-
Temporal medical data
- Disease course time modeling
- Multi-timepoint features
-
Survival analysis methods
-
Multimodal data fusion
- Structured data (lab test metrics)
- Unstructured data (medical record text)
- 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:
- Command line interface basics - Unified CLI design and monitoring capabilities
- Data science agent in depth - The complete automated machine learning pipeline
- 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