2.4.2 交易所配置

backtest:
    start_time: 2017-01-01
    end_time: 2020-08-01
    account: 100000000      # 初始资金 1 亿
    benchmark: SH000300     # 沪深300 作为基准
    exchange_kwargs:
        limit_threshold: 0.095    # 涨跌停阈值 9.5%
        deal_price: close         # 收盘价成交
        open_cost: 0.0005         # 买入佣金 0.05%
        close_cost: 0.0015        # 卖出佣金 0.15%
        min_cost: 5               # 最低佣金 5 元

2.4.3 完整回测示例

from qlib.contrib.evaluate import backtest_daily, risk_analysis
from qlib.contrib.strategy import TopkDropoutStrategy

# 假设 pred_score 是模型预测分数
strategy_config = {
    "topk": 50,
    "n_drop": 5,
    "signal": pred_score,
}

strategy = TopkDropoutStrategy(**strategy_config)

# 执行回测
report_normal, positions_normal = backtest_daily(
    start_time="2017-01-01",
    end_time="2020-08-01",
    strategy=strategy,
)

# 风险分析
analysis = {}
analysis["excess_return_without_cost"] = risk_analysis(
    report_normal["return"] - report_normal["bench"]
)
analysis["excess_return_with_cost"] = risk_analysis(
    report_normal["return"] - report_normal["bench"] - report_normal["cost"]
)

# 输出结果
import pandas as pd
print(pd.concat(analysis))

输出示例：

                              risk
mean                      0.000708
std                       0.005626
annualized_return         0.178316
information_ratio         1.996555
max_drawdown             -0.081806

2.5 一键运行：qrun

Qlib 提供命令行工具 qrun，一键执行完整工作流：

# 使用 YAML 配置文件运行
cd examples
qrun benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

完整配置文件示例：

# workflow_config.yaml
qlib_init:
    provider_uri: "~/.qlib/qlib_data/cn_data"
    region: cn

market: &market csi300
benchmark: &benchmark SH000300

data_handler_config: &data_handler_config
    start_time: 2008-01-01
    end_time: 2020-08-01
    fit_start_time: 2008-01-01
    fit_end_time: 2014-12-31
    instruments: *market

port_analysis_config: &port_analysis_config
    strategy:
        class: TopkDropoutStrategy
        module_path: qlib.contrib.strategy.strategy
        kwargs:
            topk: 50
            n_drop: 5
            signal: <PRED>
    backtest:
        start_time: 2017-01-01
        end_time: 2020-08-01
        account: 100000000
        benchmark: *benchmark
        exchange_kwargs:
            limit_threshold: 0.095
            deal_price: close
            open_cost: 0.0005
            close_cost: 0.0015
            min_cost: 5

task:
    model:
        class: LGBModel
        module_path: qlib.contrib.model.gbdt
        kwargs:
            loss: mse
            colsample_bytree: 0.8879
            learning_rate: 0.0421
            subsample: 0.8789
            lambda_l1: 205.6999
            lambda_l2: 580.9768
            max_depth: 8
            num_leaves: 210
            num_threads: 20
    dataset:
        class: DatasetH
        module_path: qlib.data.dataset
        kwargs:
            handler:
                class: Alpha158
                module_path: qlib.contrib.data.handler
                kwargs: *data_handler_config
            segments:
                train: [2008-01-01, 2014-12-31]
                valid: [2015-01-01, 2016-12-31]
                test: [2017-01-01, 2020-08-01]
    record:
        - class: SignalRecord
          module_path: qlib.workflow.record_temp
        - class: PortAnaRecord
          module_path: qlib.workflow.record_temp
          kwargs:
              config: *port_analysis_config

第三章：RD-Agent 深度解析

3.1 核心理念：R&D 循环

RD-Agent 将机器学习工程 (MLE) 过程形式化为 研究 (Research) - 开发 (Development) 双循环：

┌─────────────────────────────────────────────────────────────────┐
│                      R&D 循环                                    │
│                                                                  │
│   ┌─────────────────┐              ┌─────────────────┐          │
│   │    RESEARCH     │              │  DEVELOPMENT    │          │
│   │    (研究阶段)    │──────────────▶│   (开发阶段)   │          │
│   │                 │              │                 │          │
│   │ • 假设生成      │              │ • 代码实现      │          │
│   │ • 想法提案      │              │ • 实验执行      │          │
│   │ • 知识提取      │              │ • 反馈分析      │          │
│   └─────────────────┘              └─────────────────┘          │
│           ▲                                │                    │
│           │                                │                    │
│           └────────────────────────────────┘                    │
│                       迭代优化                                   │
└─────────────────────────────────────────────────────────────────┘

3.2 五大功能单元

RD-Agent(Q) 将量化研究分解为五个协同工作的功能单元：

┌─────────────────────────────────────────────────────────────────┐
│                    RD-Agent(Q) 系统架构                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────────┐                                              │
│  │ 规格单元 (S)   │  S = (B, D, F, M)                           │
│  │ Specification │  • B: 背景假设与先验知识                      │
│  └───────┬───────┘  • D: 市场数据接口                           │
│          │           • F: 期望输出格式                           │
│          │           • M: 外部执行环境 (Qlib)                    │
│          ▼                                                       │
│  ┌───────────────┐                                              │
│  │ 综合单元      │  • 知识森林构建                              │
│  │ Synthesis     │  • 假设生成 h^(t+1) = G(H_t^a, F_t^a)       │
│  └───────┬───────┘  • 维护 SOTA 集合                            │
│          │                                                       │
│          ▼                                                       │
│  ┌───────────────┐                                              │
│  │ 实现单元      │  Co-STEER (协同调度与任务执行引擎)            │
│  │ Implementation│  • 思维链推理                                │
│  └───────┬───────┘  • DAG 任务调度                              │
│          │           • 知识库 K 记录 (任务, 代码, 反馈)          │
│          ▼                                                       │
│  ┌───────────────┐                                              │
│  │ 验证单元      │  • Qlib 回测集成                             │
│  │ Validation    │  • 去重 (IC_max 阈值 0.99)                   │
│  └───────┬───────┘  • 性能评估                                  │
│          │                                                       │
│          ▼                                                       │
│  ┌───────────────┐                                              │
│  │ 分析单元      │  • 8 维性能向量评估                          │
│  │ Analysis      │  • 上下文汤普森采样                          │
│  └───────────────┘  • 因子/模型方向选择                         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

3.3 Co-STEER：代码生成引擎

Co-STEER (Collaborative Scheduling and Task Execution Engine) 是 RD-Agent 的核心代码生成引擎：

┌─────────────────────────────────────────────────────────────────┐
│                    Co-STEER 工作流程                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  输入: 假设 H                                                    │
│      │                                                           │
│      ▼                                                           │
│  ┌──────────────────────────────────────────┐                   │
│  │ 1. 任务分解 (DAG 构建)                    │                   │
│  │    输入 → 复杂度评估 → 拓扑排序 π_s       │                   │
│  └──────────────────────────────────────────┘                   │
│      │                                                           │
│      ▼                                                           │
│  ┌──────────────────────────────────────────┐                   │
│  │ 2. 代码生成 (思维链推理)                  │                   │
│  │    任务 → 检索相似实现 → 生成代码         │                   │
│  └──────────────────────────────────────────┘                   │
│      │                                                           │
│      ▼                                                           │
│  ┌──────────────────────────────────────────┐                   │
│  │ 3. 执行与验证                             │                   │
│  │    Docker/Conda 环境 → 运行 → 获取结果    │                   │
│  └──────────────────────────────────────────┘                   │
│      │                                                           │
│      ▼                                                           │
│  ┌──────────────────────────────────────────┐                   │
│  │ 4. 反馈与知识积累                         │                   │
│  │    成功: 存入知识库 K                     │                   │
│  │    失败: 调整复杂度 α_j → 重试            │                   │
│  └──────────────────────────────────────────┘                   │
│                                                                  │
│  输出: 可运行代码 + 性能指标                                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

关键特性：

• 88.9% 执行成功率 (vs 73.3% few-shot baseline)
• 自适应复杂度评分：优先执行简单任务
• 终身知识积累：成功经验持续存入知识库

3.4 因子-模型联合优化

RD-Agent(Q) 的核心创新是 因子-模型联合优化，通过上下文 Bandit 调度器在因子优化和模型优化之间动态切换：

3.4.1 优化策略

┌─────────────────────────────────────────────────────────────────┐
│              因子-模型联合优化 (交替优化)                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   时间步 t                                                       │
│      │                                                           │
│      ▼                                                           │
│  ┌─────────────────────────────────────────┐                    │
│  │ 状态向量 x_t ∈ R^8                      │                    │
│  │ [IC, ICIR, RankIC, RankICIR,           │                    │
│  │  ARR, IR, -MDD, SR]                    │                    │
│  └─────────────────────────────────────────┘                    │
│      │                                                           │
│      ▼                                                           │
│  ┌─────────────────────────────────────────┐                    │
│  │ 上下文 Thompson 采样                    │                    │
│  │                                         │                    │
│  │ For each action a ∈ {factor, model}:   │                    │
│  │   θ̃^(a) ~ N(μ^(a), (P^(a))^(-1))       │                    │
│  │   r̂^(a) = θ̃^(a)^T x_t                 │                    │
│  │                                         │                    │
│  │ a_t = argmax_a r̂^(a)                  │                    │
│  └─────────────────────────────────────────┘                    │
│      │                                                           │
│      ├─── a_t = factor ───▶ 执行因子演化                        │
│      │                                                           │
│      └─── a_t = model ────▶ 执行模型演化                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

3.4.2 三种演化模式

3.4.3 实验性能对比

CSI 300 数据集 (2008-2020)：

与传统因子库对比：

关键发现：

• 2x 年化收益 提升对比传统因子库
• 70% 更少因子 (仅用 Alpha 158/360 的 ~22%)
• 成本低于 $10 (12 小时完整实验)

3.5 Bandit 调度器消融实验

第四章：环境搭建与快速入门

4.1 Qlib 安装

# 方式 1: pip 安装
pip install pyqlib

# 方式 2: 源码安装
pip install numpy cython
git clone https://github.com/microsoft/qlib.git
cd qlib
pip install -e .

# 方式 3: Docker
docker pull pyqlib/qlib_image_stable:stable

4.2 RD-Agent 安装

# 创建环境
conda create -n rdagent python=3.10
conda activate rdagent

# 安装 RD-Agent
pip install rdagent

# 开发者安装 (最新版)
git clone https://github.com/microsoft/RD-Agent.git
cd RD-Agent
make dev

4.3 LLM 后端配置

创建 .env 文件：

# OpenAI 配置
CHAT_MODEL=gpt-4o
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_API_KEY=sk-your-key

# 或 DeepSeek 配置 (更经济)
CHAT_MODEL=deepseek/deepseek-chat
DEEPSEEK_API_KEY=sk-your-key
EMBEDDING_MODEL=litellm_proxy/BAAI/bge-m3
LITELLM_PROXY_API_BASE=https://api.siliconflow.cn/v1

LLM 要求：

• ChatCompletion 能力
• JSON mode 支持
• Embedding query 支持

4.4 Docker 配置 (RD-Agent 执行环境)

# 确保 Docker 可用 (无需 sudo)
docker run hello-world

# 如果需要非 root 访问
sudo usermod -aG docker $USER
# 重新登录生效

4.5 数据准备

# 下载 Qlib 数据
python scripts/get_data.py qlib_data \
    --target_dir ~/.qlib/qlib_data/cn_data \
    --region cn

# 验证数据
python -c "import qlib; qlib.init(provider_uri='~/.qlib/qlib_data/cn_data'); print('OK')"

第五章：实战案例

5.1 案例 1：Qlib 基础工作流

目标：使用 LightGBM + Alpha158 在 CSI 300 上训练模型并回测

# 01_qlib_basic_workflow.py
import qlib
from qlib.utils import init_instance_by_config
from qlib.workflow import R
from qlib.workflow.record_temp import SignalRecord, PortAnaRecord

# 1. 初始化 Qlib
qlib.init(provider_uri="~/.qlib/qlib_data/cn_data", region="cn")

# 2. 配置
market = "csi300"
benchmark = "SH000300"

# 3. 任务配置
task = {
    "model": {
        "class": "LGBModel",
        "module_path": "qlib.contrib.model.gbdt",
        "kwargs": {
            "loss": "mse",
            "learning_rate": 0.05,
            "max_depth": 8,
            "num_leaves": 200,
            "num_threads": 10,
        },
    },
    "dataset": {
        "class": "DatasetH",
        "module_path": "qlib.data.dataset",
        "kwargs": {
            "handler": {
                "class": "Alpha158",
                "module_path": "qlib.contrib.data.handler",
                "kwargs": {
                    "start_time": "2008-01-01",
                    "end_time": "2020-08-01",
                    "fit_start_time": "2008-01-01",
                    "fit_end_time": "2014-12-31",
                    "instruments": market,
                },
            },
            "segments": {
                "train": ("2008-01-01", "2014-12-31"),
                "valid": ("2015-01-01", "2016-12-31"),
                "test": ("2017-01-01", "2020-08-01"),
            },
        },
    },
}

# 4. 初始化
model = init_instance_by_config(task["model"])
dataset = init_instance_by_config(task["dataset"])

# 5. 训练与记录
with R.start(experiment_name="qlib_lightgbm_demo"):
    # 训练
    model.fit(dataset)
    
    # 预测
    pred = model.predict(dataset, segment="test")
    
    # 保存模型
    R.save_objects(model=model)
    
    # 记录预测
    sr = SignalRecord(model, dataset, R.get_recorder())
    sr.generate()
    
    print(f"预测完成，共 {len(pred)} 条记录")
    print(pred.head())

运行：

python 01_qlib_basic_workflow.py

5.2 案例 2：完整回测流程

# 02_full_backtest.py
import qlib
from qlib.contrib.evaluate import backtest_daily, risk_analysis
from qlib.contrib.strategy import TopkDropoutStrategy

qlib.init(provider_uri="~/.qlib/qlib_data/cn_data", region="cn")

# 假设已有预测分数 pred_score
# pred_score: pd.DataFrame, index=(datetime, instrument), columns=['score']

# 策略配置
strategy = TopkDropoutStrategy(
    topk=50,
    n_drop=5,
    signal=pred_score,
)

# 回测
report, positions = backtest_daily(
    start_time="2017-01-01",
    end_time="2020-08-01",
    strategy=strategy,
    benchmark="SH000300",
)

# 分析
excess_return = report["return"] - report["bench"]
analysis_result = risk_analysis(excess_return)

print("=" * 50)
print("回测结果分析")
print("=" * 50)
print(f"年化收益率: {analysis_result['annualized_return']:.2%}")
print(f"信息比率:   {analysis_result['information_ratio']:.2f}")
print(f"最大回撤:   {analysis_result['max_drawdown']:.2%}")
print("=" * 50)

5.3 案例 3：RD-Agent 因子演化

# 启动因子演化 (约 6 小时)
rdagent fin_factor

# 查看日志目录
ls -la log/

预期输出：

log/
├── __session__/
│   ├── 0/
│   │   ├── 0_direct_exp_gen    # 假设生成
│   │   ├── 1_coding            # 代码实现
│   │   ├── 2_running           # 回测执行
│   │   └── 3_feedback          # 反馈分析
│   ├── 1/
│   └── ...
└── rdagent.log

5.4 案例 4：RD-Agent 因子-模型联合演化

# 完整因子-模型联合演化 (约 12 小时)
rdagent fin_quant

# 使用 Web UI 监控
rdagent ui --port 19899 --log-dir log/ --data-science

访问 http://localhost:19899 查看实时演化进度。

5.5 案例 5：从研报提取因子

# 准备研报目录
mkdir -p reports
# 将 PDF/Word 研报放入 reports/ 目录

# 提取因子
rdagent fin_factor_report --report-folder=reports/

5.6 案例 6：自定义模型配置

# 03_custom_model.py
import qlib
from qlib.utils import init_instance_by_config

qlib.init(provider_uri="~/.qlib/qlib_data/cn_data", region="cn")

# 自定义 PyTorch 神经网络
custom_model_config = {
    "class": "MLP",
    "module_path": "qlib.contrib.model.pytorch_nn",
    "kwargs": {
        "d_feat": 6,          # 输入特征维度 (6 个价格/量字段)
        "hidden_size": 256,
        "num_layers": 3,
        "dropout": 0.1,
        "n_epochs": 100,
        "lr": 0.001,
        "batch_size": 4096,
        "early_stop": 10,
        "loss": "mse",
        "GPU": 0,
    },
}

model = init_instance_by_config(custom_model_config)
print("模型创建成功:", model)

第六章：高级配置与优化

6.1 RD-Agent 配置参数

6.1.1 基础配置 (QuantBasePropSetting)

6.1.2 因子演化配置 (FactorCoSTEERSettings)

6.1.3 模型演化配置 (ModelCoSTEERSettings)

6.2 环境变量配置

# 导出配置
export QLIB_QUANT_EVOLVING_N=20
export QLIB_QUANT_ACTION_SELECTION="bandit"
export FACTOR_CoSTEER_MAX_LOOP=15
export MODEL_CoSTEER_ENV_TYPE="conda"

# 运行
rdagent fin_quant

6.3 Qlib 性能优化

6.3.1 数据缓存

# 启用数据缓存
qlib.init(
    provider_uri="~/.qlib/qlib_data/cn_data",
    region="cn",
    redis_cache={
        "host": "localhost",
        "port": 6379,
    }
)

6.3.2 并行训练

# 多线程配置
model_config = {
    "class": "LGBModel",
    "kwargs": {
        "num_threads": 20,  # CPU 核心数
    }
}

6.3.3 GPU 加速

# PyTorch 模型 GPU 配置
nn_config = {
    "class": "MLP",
    "kwargs": {
        "GPU": 0,  # GPU ID
        "batch_size": 8192,
    }
}

第七章：性能评估指标

7.1 因子评估指标

7.2 策略评估指标

7.3 回测输出解读

# 典型输出
                              risk
mean                      0.000708    # 日均超额收益
std                       0.005626    # 日超额收益波动
annualized_return         0.178316    # 年化收益率 17.83%
information_ratio         1.996555    # 信息比率 2.0
max_drawdown             -0.081806    # 最大回撤 8.18%

评估标准：

• IR > 1.5：优秀
• IR > 2.0：非常优秀
• MDD < 10%：风险可控
• Calmar > 1.5：风险调整后收益良好

第八章：最佳实践与注意事项

8.1 最佳实践

8.1.1 数据准备

1. 使用 Point-in-Time 数据：避免前视偏差
2. 定期更新数据：设置 crontab 自动更新
3. 验证数据质量：检查缺失值、异常值

# crontab 自动更新 (每日 18:00)
0 18 * * * python /path/to/update_qlib_data.py

8.1.2 模型训练

1. 时间分割严格：训练集 < 验证集 < 测试集
2. 使用早停：避免过拟合
3. 交叉验证：滚动窗口验证

# 滚动验证配置
segments = {
    "train": ("2008-01-01", "2012-12-31"),
    "valid": ("2013-01-01", "2014-12-31"),
    "test": ("2015-01-01", "2016-12-31"),
}

8.1.3 RD-Agent 使用

1. 优先使用 Bandit 调度器：性能最佳
2. 因子优化先行：因子优化迭代更快
3. 监控成本：LLM 调用约 $10/实验
4. 保存 Session：支持断点续传

8.2 常见问题

Q1: 数据下载失败

# 使用社区数据源
# https://github.com/chenditc/investment_data/releases
wget https://github.com/chenditc/investment_data/releases/download/...

Q2: Docker 权限问题

# 添加用户到 docker 组
sudo usermod -aG docker $USER
# 重新登录

Q3: GPU 内存不足

# 减小 batch_size
config = {
    "kwargs": {
        "batch_size": 1024,  # 从 4096 减小
    }
}

Q4: RD-Agent 执行超时

# 增加超时时间
export FACTOR_CoSTEER_FILE_BASED_EXECUTION_TIMEOUT=7200  # 2 小时
export MODEL_CoSTEER_RUNNING_TIMEOUT_PERIOD=1200  # 20 分钟

8.3 风险提示

1. 市场风险：历史表现不代表未来收益
2. 过拟合风险：注意样本外验证
3. 模型风险：黑天鹅事件可能导致模型失效
4. 技术风险：LLM 生成代码需人工审核

第九章：扩展与生态

9.1 Qlib 生态

9.2 相关论文

1. Qlib: Towards an AI-oriented Quantitative Investment Platform (arXiv:2009.11189)
2. R&D-Agent-Quant: Multi-Agent Factor-Model Co-Optimization (NeurIPS 2025, arXiv:2505.15155)
3. DoubleEnsemble: A New Ensemble Method (ICDM 2020)
4. TCTS: Time-Contrastive Pretraining (ICML 2021)

9.3 社区资源