📚 课程目录第4章 Qlib平台入门

4. Qlib平台入门

在进入强化学习订单执行之前，必须先建立对 Qlib 的整体认知。Qlib 是微软开源的量化投资平台，它并不是一个“策略脚本集合”，而是一套围绕数据、模型、回测与工作流构建的工程化框架。理解它的分层结构，能帮助我们在后续章节中把订单执行环境、状态特征与奖励函数准确地挂接到正确的位置。

一、核心原理：Qlib 的四层架构

Qlib 的设计遵循“数据与计算分离、配置驱动流程”的原则，可以概括为四层：

数据层（Data Layer）：负责原始行情、财务数据、特征表达式的存储与检索，核心是 qlib.data 与二进制 .bin 格式。
模型层（Model Layer）：封装预测模型，如 LightGBM、LSTM、Transformer，统一 fit 与 predict 接口。
策略与回测层（Strategy & Backtest）：将预测信号转换为交易决策，并在模拟撮合下计算收益、回撤等指标。
工作流层（Workflow）：通过 YAML 配置文件与 qrun 命令，把数据、模型、策略、回测串成可复现的流水线。

这四层的关系是：工作流读取配置 → 数据层提供特征 → 模型层输出预测 → 策略层生成订单 → 回测层评估结果。强化学习订单执行本质上是在“策略层”引入一个可学习的执行智能体，因此前三层的稳定运行是前提。

二、数据层：Qlib 的“燃料系统”

Qlib 的数据层有两个关键概念：表达式引擎和数据缓存。用户不需要手动拼接 DataFrame，而是用类似 Ref($close, 1)、Mean($volume, 5) 的表达式描述特征，Qlib 会自动计算并缓存。

# 初始化数据路径
import qlib
from qlib.data import D

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

# 用表达式获取特征
instruments = D.instruments(market="csi300")
fields = ["$close", "Ref($close, 1)", "Mean($volume, 5)"]
df = D.features(instruments, fields, start_time="2020-01-01", end_time="2020-12-31")
print(df.head())

首次使用需要准备数据。常见做法是下载社区提供的 cn_data 包，或使用 scripts/get_data.py 自行转换。数据目录通常包含 calendars、instruments、features 三个子目录，分别记录交易日历、股票池和特征二进制文件。

表达式引擎是 Qlib 数据层的精髓。后续构建订单执行状态时，买卖价差、成交量、波动率等特征都可以用表达式统一描述，避免在训练循环里重复写数据清洗逻辑。

三、工作流与配置文件：用 YAML 驱动一次实验

Qlib 推荐用 YAML 描述实验。一个最小工作流包含 qlib_init、market、benchmark、data_handler、model、strategy、backtest 等字段。下面是一个简化示例：

qlib_init:
    provider_uri: "./qlib_data/cn_data"
    region: cn
market: &market csi300
benchmark: &benchmark SH000300
data_handler_config: &data_handler_config
    start_time: 2018-01-01
    end_time: 2020-08-01
    fit_start_time: 2018-01-01
    fit_end_time: 2019-12-31
    instruments: *market
task:
    model:
        class: LGBModel
        module_path: qlib.contrib.model.gbdt
        kwargs:
            loss: mse
            learning_rate: 0.05
    dataset:
        class: DatasetH
        module_path: qlib.data.dataset
        kwargs:
            handler:
                class: Alpha158
                module_path: qlib.contrib.data.handler
                kwargs: *data_handler_config
            segments:
                train: [2018-01-01, 2019-12-31]
                valid: [2020-01-01, 2020-06-30]
                test:  [2020-07-01, 2020-08-01]
    record:
        - class: SignalRecord
          module_path: qlib.workflow.record_temp

运行命令非常简洁：

qrun workflow_config_lightgbm.yaml

执行后，Qlib 会在 mlruns 目录下生成实验记录，包含模型文件、预测结果和回测指标。这种“配置即实验”的方式，让订单执行策略的对比实验也能被统一管理。

四、安装与快速运行一个简单策略

推荐使用 Python 3.8+ 的虚拟环境安装：

pip install pyqlib
# 或从源码安装最新版
git clone https://github.com/microsoft/qlib.git
cd qlib
pip install -e .

安装完成后，按以下流程跑通第一个策略：

准备数据：下载或转换 cn_data 到本地目录。
编写或复用 YAML 配置，指定模型为 LGBModel，数据集为 Alpha158。
执行 qrun，等待训练与回测完成。
查看 mlruns 中的指标，确认 IC、年化收益、最大回撤等是否合理。

如果只想快速验证环境，可以运行官方示例：

cd examples
qrun benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

看到类似 INFO: backtest finished 与指标输出，说明数据层、模型层、回测层已经打通。

五、常见误区与复盘清单

误区	表现	正确做法
数据路径配置错误	报错找不到 calendars 或 features	确认 `provider_uri` 指向包含三个子目录的根目录
时间区间越界	训练集与测试集重叠或超出数据范围	先查日历范围，再设置 segments
表达式写错	特征全为 NaN	用 `D.features` 单独验证表达式
忽略缓存	重复计算导致速度慢	保留 `.bin` 缓存，避免频繁重建
直接改源码	升级后冲突	优先通过配置和继承扩展

Qlib 的配置文件对缩进和字段名非常敏感。YAML 中一个空格错误就可能导致任务静默失败或使用默认值。建议每次修改后先用小时间区间试跑，确认无误再扩大范围。

掌握以上内容后，你已经具备在 Qlib 中搭建标准量化实验的能力。下一阶段，我们将把订单执行问题抽象为强化学习环境，并复用本章的数据层与工作流机制，让执行智能体在可控、可复现的框架中训练与评估。