学习笔记：Qlib 量化投资平台框架 — MAIN COMPONENTS Part Ⅲ

学习笔记：Qlib 量化投资平台框架 — MAIN COMPONENTS Part Ⅲ

Qlib 是微软亚洲研究院开源的一个面向人工智能的量化投资平台，旨在实现人工智能技术在量化投资中的潜力，赋能研究，并创造价值，从探索想法到实施生产。Qlib 支持多种机器学习建模范式，包括监督学习、市场动态建模和强化学习。借助 Qlib，用户可以轻松尝试他们的想法，以创建更优秀的量化投资策略。

文中内容仅限技术学习与代码实践参考，市场存在不确定性，技术分析需谨慎验证，不构成任何投资建议。

实验管理

一、系统架构概览

Qlib 提供了一套实验管理系统，名为 QlibRecorder。它包含三个核心组件：

• 实验管理器（Experiment Manager）：管理多个实验的类。
• 实验（Experiment）：代表单个实验的类，每个实例负责一个实验。
• 记录器（Recorder）：负责单次运行记录的类。

系统结构如下：

ExperimentManager  # 实验管理器（Experiment Manager）
    - Experiment 1  # 实验（Experiment）
        - Recorder 1  # 记录器（Recorder）
        - Recorder 2
    - Experiment 2
        - Recorder 1
        - Recorder 2

Qlib 定义了一组接口，并提供了基于 MLFlow 平台的实现 MLflowExpManager。若用户将 ExpManager 的实现设置为 MLflowExpManager，可通过 mlflow ui 命令可视化和查看实验结果。官方文档链接

二、Qlib记录器（QlibRecorder）API

QlibRecorder 提供了高层次的 API，用户可通过 R 与系统交互。以下是部分关键接口：

• start ：在 Python 的 with 语句中启动实验。示例代码：

# start new experiment and recorder
with R.start(experiment_name='test', recorder_name='recorder_1'):
    model.fit(dataset)
    R.log...
    ... # further operations

# resume previous experiment and recorder
with R.start(experiment_name='test', recorder_name='recorder_1', resume=True): # if users want to resume recorder, they have to specify the exact same name for experiment and recorder.
    ... # further operations

可设置参数如实验 ID、名称，记录器 ID、名称，跟踪 URI 及是否恢复等。

• start_exp ：低层次启动实验的方法，需手动结束实验，示例：

R.start_exp(experiment_name='test', recorder_name='recorder_1')
... # further operations
R.end_exp('FINISHED') or R.end_exp(Recorder.STATUS_S)

• end_exp ：手动结束实验，结束当前活动实验及其记录器。
• search_records ：根据实验 ID 等条件搜索记录，返回包含匹配记录的 pandas DataFrame。
• list_experiments ：列出所有现有实验（除删除状态的）。
• list_recorders ：列出指定实验的所有记录器，若未提供实验 ID 或名称，则尝试获取默认实验的记录器。
• get_exp ：根据 ID 或名称获取实验，可设置是否创建新实验。
• delete_exp ：删除指定实验。
• get_uri ：获取当前实验管理器的 URI。
• set_uri ：重置当前实验管理器的默认 URI。
• uri_context ：临时设置 exp_manager 的默认 URI。
• get_recorder ：获取记录器，若存在活动记录器则返回，否则需指定 ID 或名称及对应的实验名称。
• delete_recorder ：删除指定记录器。
• save_objects ：保存对象作为实验工件到 URI，支持从本地文件 / 目录保存或直接保存对象。
• load_object ：从实验的 URI 中加载对象。
• log_params ：记录实验参数。
• log_metrics ：记录实验指标。
• log_artifact ：将本地文件或目录记录为当前活动运行的工件。
• download_artifact ：从运行中下载工件文件或目录到本地目录。
• set_tags ：为记录器设置标签。

三、实验管理器（Experiment Manager）

ExpManager 负责管理不同实验，其 API 与 QlibRecorder 类似。关键方法包括：

• start_exp ：启动实验，包括获取或创建实验并将其设为活动状态。
• end_exp ：结束活动实验。
• create_exp ：创建实验。
• search_records ：获取符合搜索条件的记录 DataFrame。
• get_exp ：获取实验，可获取活动实验或根据 ID、名称获取指定实验，且可设置是否创建新实验。
• delete_exp ：删除实验。
• default_uri ：获取默认跟踪 URI。
• uri ：获取默认跟踪 URI 或当前 URI。
• list_experiments ：列出所有现有实验。

四、实验（Experiment）操作

Experiment 类负责单个实验，包含启动、结束实验及与记录器相关的操作：

• start ：启动实验并设为活动状态，同时启动新记录器。
• end ：结束实验。
• create_recorder ：为实验创建记录器。
• search_records ：获取符合搜索条件的记录 DataFrame。
• delete_recorder ：删除记录器。
• get_recorder ：获取记录器，可获取活动记录器或根据 ID、名称获取指定记录器，且可设置是否创建新记录器。
• list_recorders ：列出实验的所有记录器。

五、记录器（Recorder）操作

Recorder 类负责单次运行记录，处理如记录指标、参数等详细操作：

• save_objects ：保存对象到工件 URI。
• load_object ：加载对象。
• start_run ：启动或恢复记录器运行，返回值可用作上下文管理器。
• end_run ：结束活动记录器。
• log_params ：记录参数。
• log_metrics ：记录指标。
• log_artifact ：记录本地文件或目录为活动运行的工件。
• set_tags ：记录标签。
• delete_tags ：删除标签。
• list_artifacts ：列出记录器的所有工件。
• download_artifact ：下载工件。
• list_metrics ：列出记录器的所有指标。
• list_params ：列出记录器的所有参数。
• list_tags ：列出记录器的所有标签。

六、记录模板（Record Template）

Qlib 提供了 RecordTemp 类，用于生成特定格式的实验结果，包含以下三类：

• SignalRecord ：生成模型预测结果。
• SigAnaRecord ：生成模型的 IC、ICIR、Rank IC 和 Rank ICIR 等指标。例如：

from qlib.contrib.eva.alpha import calc_ic, calc_long_short_return

ic, ric = calc_ic(pred.iloc[:, 0], label.iloc[:, 0])  # 计算预测值与真实值之间的信息系数（IC）和秩信息系数（Rank IC）
long_short_r, long_avg_r = calc_long_short_return(pred.iloc[:, 0], label.iloc[:, 0])  # 计算长短期收益和长期平均收益

• PortAnaRecord ：生成回测结果。示例代码如下：

from qlib.contrib.strategy.strategy import TopkDropoutStrategy  
from qlib.contrib.evaluate import (
    backtest as normal_backtest, 
    risk_analysis, 
)

# backtest  # 回测部分
STRATEGY_CONFIG = {  # 定义策略配置字典
    "topk": 50,  # 选择前 50 个股票
    "n_drop": 5,  # 每次随机丢弃 5 个股票
}  # 策略配置参数
BACKTEST_CONFIG = {  # 定义回测配置字典
    "limit_threshold": 0.095,  # 设置涨跌停阈值为 9.5%
    "account": 100000000,  # 设置初始账户资金为 1 亿元
    "benchmark": BENCHMARK,  # 设置基准指数（需预先定义）
    "deal_price": "close",  # 以收盘价进行交易
    "open_cost": 0.0005,  # 开仓成本为 0.05%
    "close_cost": 0.0015,  # 平仓成本为 0.15%
    "min_cost": 5,  # 最低交易成本为 5 元
}  # 回测配置参数

strategy = TopkDropoutStrategy(**STRATEGY_CONFIG)  # 根据策略配置创建 TopkDropoutStrategy 策略对象
report_normal, positions_normal = normal_backtest(pred_score, strategy=strategy, **BACKTEST_CONFIG)  # 使用 normal_backtest 函数进行回测，传入预测分数、策略对象和回测配置，返回回测报告和持仓数据

# analysis  # 分析部分
analysis = dict()  # 初始化分析结果字典
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"])  # 计算含成本的超额收益风险指标
analysis_df = pd.concat(analysis)  # 将分析结果字典转换为 DataFrame，方便查看和分析  # type: pd.DataFrame
print(analysis_df)  # 打印分析结果 DataFrame

七、已知限制

1. 对象序列化：使用 pickle 保存 Python 对象时，要求保存/加载环境完全一致
2. URI 路径规范：文件路径必须使用绝对路径，不支持 ~/mlruns/ 类简写格式
3. 实验恢复限制：恢复记录器时必须严格匹配原始实验名称和记录器名称

评估与结果分析

一、核心功能模块

1.1 分析系统设计原则

• 所有累积收益指标（如回报率、最大回撤）采用累加计算方式
• 避免指标随时间呈指数级失真
• 支持可视化投资组合评估分析

1.2 图形报告体系

# 获取全部支持的图形报告列表
import qlib.contrib.report as qcr  # 导入QLib分析报告模块
print(qcr.GRAPH_NAME_LIST)  # 输出所有支持的图形报告名称
# 输出结果：
['analysis_position.report_graph',
 'analysis_position.score_ic_graph',
 'analysis_position.cumulative_return_graph',
 'analysis_position.risk_analysis_graph',
 'analysis_position.rank_label_graph',
 'analysis_model.model_performance_graph']

二、持仓分析（Analysis Position）

2.1 核心报告参数配置

# 查看详细功能文档
help(qcr.analysis_position.report_graph)  # 获取持仓分析报告文档说明

2.2 图形坐标系统

图形元素	X轴	Y轴指标
主报告	交易日	cum_bench（基准累积收益）
		cum_return_wo_cost（无成本组合累积收益）
		cum_return_w_cost（含成本组合累积收益）

2.3 关键指标解析

• 阴影区域：

  • 上方阴影：无成本组合累积收益的最大回撤（Max Drawdown）
  • 下方阴影：无成本累积异常收益（CAR）的最大回撤

• 衍生指标：

  1. cum_ex_return_wo_cost: 无成本CAR序列
  2. turnover: 换手率序列
  3. return_wo_mdd: 无成本组合最大回撤序列
  

三、预测评分分析（Score IC）

3.1 统计指标

• 信息系数（Information Coefficient）：
  • ic：标签与预测评分间的皮尔逊相关系数（Pearson）
  • rank_ic：标签与预测评分间的斯皮尔曼秩相关系数（Spearman’s rank）

3.2 标签定义

$$label=\frac{Ref(close,-2)}{Ref(close,-1)}-1$$

四、风险分析（Risk Analysis）

4.1 基础风险指标

指标名称	计算维度
标准差（Standard Deviation）	CAR无成本/含成本的波动率
年化收益率（Annualized Return）	CAR无成本/含成本的年化率
信息比率（Information Ratio）	CAR无成本/含成本的风险调整收益比
最大回撤（Max Drawdown）	CAR无成本/含成本的最大损失

4.2 月度分析维度

X轴配置：按月分组的交易日
Y轴指标：
- annualized_return_graphics：月度CAR年化率
- max_drawdown_graphics：月度CAR最大回撤
- information_ratio_graphics：月度信息比率
- std_graphics：月度CAR标准差

五、模型性能分析（Model Performance）

5.1 分组策略

组别	标签排名比例（Ranking Ratio）
Group1	≤20%
Group2	20% < x ≤40%
Group3	40% < x ≤60%
Group4	60% < x ≤80%
Group5	>80%

5.2 对比策略

$$rankingratio=\frac{AscendingRankingoflabel}{PortfolioStockCount}$$

5.3 核心指标对比

对比策略	计算方法
long-short	Group1与Group5累积收益差值
long-average	Group1与全股票平均收益差值

5.4 统计诊断工具

• 信息系数分布：

  • 日度IC分布直方图
  • 月度IC均值序列
  • IC正态分布Q-Q图

• 自相关分析：

  • 预测评分与滞后评分的皮尔逊相关系数序列
  • 用于估算换手率参数

六、引用规范

1. 信息比率定义参考：Information Ratio – IR
2. 特征工程文档参考：Data Feature

在线服务

一、核心概念

1.1 在线服务（Online Serving）

用于实时市场条件下的模型预测与交易，包含四大核心模块：

• 在线管理器（Online Manager）
• 在线策略（Online Strategy）
• 在线工具（Online Tool）
• 更新器（Updater）

1.2 已知限制

• 当前仅支持更新下一交易日预测
• 不支持生成下一交易日订单（公共数据限制）https://github.com/microsoft/qlib/issues/215#issuecomment-766293563

二、核心模块详解

2.1 Online Manager

1. 功能 ：管理多个 Online Strategy，并动态运行它们。可随时间变化更新在线模型及预测，还支持模拟 Online Strategy 以验证策略或寻找更优策略。
2. 使用场景 ：提供了 4 种不同情况，包括 Online + Trainer、Online + DelayTrainer、Simulation + Trainer、Simulation + DelayTrainer，分别适用于不同的训练和模拟需求。
3. 关键类 ：OnlineManager，其参数包括策略（strategies）、训练器（trainer）、开始时间（begin_time）和数据频率（freq）等。
4. 主要方法 ：
   • first_train()：获取每个策略的初始任务并训练。
   • routine()：执行每个策略的典型更新流程，如更新预测、准备任务、模型和信号等。
   • get_collector()：获取收集结果的 Collector 实例。
   • add_strategy()：添加新的策略。
   • prepare_signals()：准备交易信号。
   • get_signals()：获取已准备的在线信号。
   • simulate()：从当前时间开始模拟直到结束时间。

2.2 Online Strategy

1. 功能 ：与 Online Manager 配合，负责任务生成、模型更新和信号准备。

2. 关键类 ：OnlineStrategy，需指定唯一名称或 ID（name_id），可选参数包括训练器（trainer）。

3. 主要方法 ：

   • prepare_tasks(cur_time, **kwargs)：根据当前时间准备新任务。
   • prepare_online_models(trained_models, cur_time=None)：从已训练模型中选择在线模型。
   • first_tasks()：生成初始任务。
   • get_collector()：获取收集结果的 Collector 实例。

4. 示例类 ：RollingStrategy，使用最新滚动模型作为在线模型，参数包括名称 ID、任务模板和滚动生成器等。

2.3 Online Tool

1. 功能 ：管理和标记在线模型，使用户能根据时间变化高效切换模型。
2. 关键类 ：OnlineTool 和基于 Recorder 的 OnlineToolR。
3. 主要方法 ：
   • set_online_tag(tag, recorder)：为模型设置在线标签。
   • get_online_tag(recorder)：获取模型的在线标签。
   • reset_online_tag(recorder)：将模型重置为在线状态。
   • online_models()：获取当前在线模型列表。
   • update_online_pred(to_date=None)：更新在线模型的预测。

2.4 Updater

1. 功能 ：当股票数据更新时，更新预测等工件。

2. 关键类 ：

   • RMDLoader：用于加载模型和数据集，以进行推理。
   • RecordUpdater：更新特定记录器的信息。
   • DSBasedUpdater：基于 Qlib 数据集更新数据，假设数据为多级索引的 pandas DataFrame。
   • PredUpdater：更新记录器中的预测。
   • LabelUpdater：更新记录器中的标签。

3. 主要方法 ：

   • get_dataset(start_time, end_time, segments=None, unprepared_dataset=None)：加载、配置和设置数据集。
   • update(*args, **kwargs)：更新特定记录器的信息。
   • prepare_data(unprepared_dataset=None)：加载数据集。
   • get_update_data(dataset)：基于给定数据集返回更新的数据

三、使用场景对比

场景组合	训练方式	适用场景
Online + Trainer	顺序训练	实时交易场景
Online + DelayTrainer	延迟训练	批量任务预处理
Simulation + Trainer	顺序训练	历史模拟验证
Simulation + DelayTrainer	并行训练	无时序依赖模型

四、代码工作流示例

4.1 在线模式+普通训练器

# 初始化训练任务
tasks = first_train()
models = trainer.train(tasks)
trainer.end_train(models)

# 每日例行流程
for day in online_trading_days:
    # 准备新任务
    new_tasks = strategy.prepare_tasks()
    # 训练新模型
    new_models = trainer.train(new_tasks)
    # 上线新模型
    strategy.prepare_online_models(new_models)
    # 生成交易信号
    prepare_signals()

五、关键注意事项

1. 数据源需持续更新（QLib提供Yahoo数据更新脚本）
2. 在线模型管理需通过OnlineTool设置状态标签
3. 预测更新使用PredUpdater，标签更新使用LabelUpdater
4. 信号生成支持覆盖（over_write=True）和追加两种模式

风险提示与免责声明
本文内容基于公开信息研究整理，不构成任何形式的投资建议。历史表现不应作为未来收益保证，市场存在不可预见的波动风险。投资者需结合自身财务状况及风险承受能力独立决策，并自行承担交易结果。作者及发布方不对任何依据本文操作导致的损失承担法律责任。市场有风险，投资须谨慎。