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

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

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

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

工作流管理

一、核心概念

1.1 工作流组成

Qlib 框架通过 qrun 工具实现完整的量化研究流程，主要包含三大阶段：

• 数据处理：加载 -> 预处理 -> 切片
• 模型管理：训练推理 -> 持久化
• 策略评估：信号分析 -> 回测验证

1.2 实验追踪

内置 Recorder 系统完整记录：

• 训练阶段：模型参数、训练指标
• 推理阶段：预测结果
• 回测阶段：策略表现指标（详见 Recorder 文档）

二、配置文件详解

2.1 初始化配置

qlib_init:provider_uri: "~/.qlib/qlib_data/cn_data"  # 数据存储路径region: cn  # 市场区域（cn-中国，us-美国）

2.2 任务配置

模型配置

model:class: LGBModel                  # 模型类名module_path: qlib.contrib.model.gbdt  # 模块路径kwargs:                          # 模型超参数loss: msecolsample_bytree: 0.8879learning_rate: 0.0421# ...其他GBDT参数

数据集配置

dataset:class: DatasetHmodule_path: qlib.data.datasetkwargs:handler:                     # 数据处理器配置class: Alpha158module_path: qlib.contrib.data.handlerkwargs: &data_handler_config  # 数据参数锚点start_time: 2008-01-01end_time: 2020-08-01instruments: *market # 引用市场配置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_tempkwargs:config: &port_analysis_config  # 回测策略配置strategy:class: TopkDropoutStrategykwargs:topk: 50        # 选股数量n_drop: 5       # 淘汰数量backtest:account: 100000000  # 初始资金benchmark: SH000300 # 基准指数transaction_cost: 0.002 # 总交易成本

2.3 YAML 锚点机制

• & 创建锚点：market: &market csi300
• * 引用锚点：instruments: *market
• 优势：实现参数集中管理，避免多处重复配置

三、执行与调试

3.1 常规执行

qrun configuration.yaml  # 执行完整工作流

3.2 调试模式

python -m pdb qlib/workflow/cli.py config.yaml  # 使用pdb调试

3.3 等效Python代码

YAML配置对应的Python初始化逻辑：

# 模型初始化示例
from qlib.contrib.model.gbdt import LGBModel
model = LGBModel(loss="mse",colsample_bytree=0.8879,learning_rate=0.0421,# ...其他参数
)# 数据集初始化示例
from qlib.data.dataset import DatasetH
from qlib.contrib.data.handler import Alpha158
dataset = DatasetH(handler=Alpha158(start_time="2008-01-01",end_time="2020-08-01",instruments="csi300"),segments={"train": ("2008-01-01", "2014-12-31"),"valid": ("2015-01-01", "2016-12-31"),"test": ("2017-01-01", "2020-08-01")}
)

四、关键设计原理

4.1 组件化架构

• 基于 init_instance_by_config 实现动态初始化
• 通过配置实现模块的即插即用
• 松耦合设计支持灵活组合

4.2 工作流模板

• 预定义标准工作流模板
• 通过配置覆盖实现定制化
• 支持扩展自定义组件

文档参考：
Qlib 框架设计
策略回测文档
模型开发指南

数据层框架

一、框架概述

1.1 核心功能

• 提供高性能量化投资数据基础设施

• 支持公式化alpha因子构建（参考Building Formulaic Alphas）

• 包含完整数据处理流程：

1.2 核心组件

组件	功能描述	关键类/接口
Data Loader	原始数据加载	QlibDataLoader, StaticDataLoader
Data Handler	数据预处理与特征工程	DataHandlerLP, Processor系列
Dataset	模型专用数据准备	DatasetH
Cache	数据缓存加速	MemCache, DiskExpressionCache

二、数据准备

2.1 数据格式规范

• .bin格式：专为金融数据设计的二进制格式（论文File storage design）

• 数据字段要求：

  # 必须包含的字段（示例）
  required_fields = ['open', 'close', 'high', 'low', 'volume', 'factor']
  

2.2 数据获取与转换

2.2.1 官方数据集下载

# 下载中国A股日频数据
python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/cn_data --region cn# 下载美股分钟级数据
python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/us_1min --region us --interval 1min

2.2.2 CSV转QLib格式

# 转换自定义CSV数据
python scripts/dump_bin.py dump_all \--csv_path ~/.qlib/csv_data/my_data \--qlib_dir ~/.qlib/qlib_data/my_data \--include_fields open,close,high,low,volume,factor \--date_field_name date \--symbol_field_name stock_code

2.3 数据自动更新

# 手动更新指定日期数据
python scripts/data_collector/yahoo/collector.py update_data_to_bin \--qlib_data_1d_dir ~/.qlib/qlib_data/cn_data \--trading_date 2023-01-01 \--end_date 2023-01-31# 配置Linux定时任务（每周一至五执行）
* * * * 1-5 python /path/to/collector.py update_data_to_bin --qlib_data_1d_dir <data_dir>

三、数据处理核心模块

3.1 数据API体系

3.1.1 特征工程

from qlib.data import Feature# 基础特征获取
high = Feature('high')  # 获取最高价
close = Feature('close')  # 获取收盘价# 表达式运算
from qlib.data.ops import Ref, Mean
feature_expr = Ref(close, 5) / Mean(high, 20)  # 5日收盘价/20日均线

3.1.2 数据过滤

# 配置示例（YAML格式）
filter:filter_type: ExpressionDFilterrule_expression: "$close > Mean($close, 20) AND $volume > 1e6"filter_start_time: 2020-01-01keep: True  # 保留符合条件标的

3.2 数据处理器（Data Handler）

3.2.1 处理器配置

from qlib.contrib.data.handler import Alpha158handler_config = {"start_time": "2010-01-01","end_time": "2023-12-31","fit_start_time": "2010-01-01","fit_end_time": "2020-12-31","instruments": "csi300","processors": [{"class": "DropnaLabel"},{"class": "CSZScoreNorm", "kwargs": {"fields_group": "feature"}}]
}
handler = Alpha158(**handler_config)

3.2.2 常用处理器类型

处理器	功能	适用场景
ZscoreNorm	Z-Score标准化	特征归一化
CSRankNorm	横截面排名归一化	因子排序
Fillna	缺失值填充	数据清洗
TanhProcess	双曲正切处理	噪声抑制

3.3 数据集管理

from qlib.data.dataset import DatasetH# 创建数据集实例
dataset = DatasetH(handler=handler,segments={'train': ('2010-01-01', '2018-12-31'),'valid': ('2019-01-01', '2020-12-31'),'test': ('2021-01-01', '2023-12-31')}
)# 获取训练数据
train_df = dataset.prepare('train')

四、缓存机制

4.1 内存缓存架构

from qlib.data.cache import H# 访问缓存单元
calendar_cache = H['c']  # 交易日历缓存
instrument_cache = H['i']  # 标的池缓存
feature_cache = H['f']  # 特征数据缓存# 自定义缓存策略
class CustomCache(ExpressionCache):def _uri(self, instrument, field, freq):return f"custom/{instrument}/{field}_{freq}.bin"

4.2 磁盘缓存配置

# 表达式缓存示例
from qlib.data.cache import DiskExpressionCacheexpr_cache = DiskExpressionCache(expression="Mean($close, 20)", freq="day",disk_dir="~/.qlib/cache/expressions"
)# 数据集缓存示例
from qlib.data.cache import DiskDatasetCachedataset_cache = DiskDatasetCache(instruments="csi300",fields=["$close", "$volume"],start_time="2020-01-01",end_time="2023-12-31",freq="day"
)

五、文件结构规范

5.1 标准目录结构

~/.qlib/
├── qlib_data/
│   ├── calendars/
│   │   └── day.txt
│   ├── instruments/
│   │   ├── all.txt
│   │   └── csi300.txt
│   └── features/
│       ├── SH600000/
│       │   ├── open.day.bin
│       │   └── close.day.bin
├── calculated/
│   └── SH600000/
│       └── 8a3d7f.../
│           ├── data.bin
│           └── .meta
└── cache/└── a1b2c3.../├── data.bin├── .meta└── .index

5.2 跨市场模式配置

# 中国市场初始化
from qlib.constant import REG_CN
qlib.init(provider_uri='~/.qlib/qlib_data/cn_data', region=REG_CN)# 美国市场初始化
from qlib.constant import REG_US
qlib.init(provider_uri='~/.qlib/qlib_data/us_data', region=REG_US)

六、最佳实践建议

1. 数据版本控制：每次数据更新后生成新的版本目录
2. 缓存清理策略：设置定期清理过期缓存（建议保留最近30天）
3. 异常处理：对关键数据处理步骤添加try-except块
4. 性能监控：使用内置cache命中率统计（H[‘f’].cache_hit_rate）

注：更多API细节参考Qlib官方文档

预测模型

一、概述

Qlib的Forecast Model模块专注于股票预测评分生成，支持两种使用方式：

1. 通过qrun实现自动化工作流（详见工作流管理）
2. 作为独立模块使用（基于松散耦合设计）

二、核心基类与接口

2.1 基础模型类

qlib.model.base.Model

• 核心方法：
  • fit(): 模型训练接口
  • predict(): 执行预测
  • finetune(): 模型微调（通过ModelFT子类实现）

2.2 扩展功能

• 完整API参考：Model API文档

三、LightGBM模型应用示例

3.1 完整实现代码

# 初始化环境（需提前执行qlib.init）
from qlib.contrib.model.gbdt import LGBModel
from qlib.contrib.data.handler import Alpha158
from qlib.utils import init_instance_by_config, flatten_dict
from qlib.workflow import R
from qlib.workflow.record_temp import SignalRecord, PortAnaRecord# 市场配置参数
market = "csi300"
benchmark = "SH000300"# 数据处理器配置
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,             # 标的范围
}# 任务配置字典
task = {"model": {"class": "LGBModel","module_path": "qlib.contrib.model.gbdt","kwargs": {                    # LightGBM超参数"loss": "mse","colsample_bytree": 0.8879,"learning_rate": 0.0421,"subsample": 0.8789,"lambda_l1": 205.6999,     # L1正则系数"lambda_l2": 580.9768,     # L2正则系数"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"),},},},
}# 模型实例化
model = init_instance_by_config(task["model"])  # 动态加载模型类
dataset = init_instance_by_config(task["dataset"])  # 创建数据集对象# 实验流程
with R.start(experiment_name="workflow"):# 记录超参数R.log_params(**flatten_dict(task))# 模型训练model.fit(dataset)# 生成预测信号recorder = R.get_recorder()sr = SignalRecord(model, dataset, recorder)sr.generate()  # 输出预测结果到记录器

3.2 关键组件说明

1. 数据处理器：

   • 使用内置Alpha158特征集（文档参考）
   • 支持自定义特征工程扩展

2. 实验记录：

   • SignalRecord自动记录预测信号（模板说明）
   • 完整示例见examples/train_backtest_analyze.ipynb

3. 预测评分语义：

   • 默认表示股票评级，数值越高预期收益越高
   • 实际语义取决于用户标签设置

四、自定义模型开发

4.1 集成步骤

1. 继承基类qlib.model.base.Model
2. 实现核心接口：
   • fit(): 训练逻辑
   • predict(): 推理逻辑
3. 参考自定义模型集成指南

4.2 最佳实践

• 保持与现有组件接口兼容
• 通过init_instance_by_config实现动态加载
• 利用R记录器保存实验数据

五、性能调优

1. 特征工程：
   • 修改Alpha158处理器配置
   • 开发自定义特征处理器
2. 超参数优化：
   • 调整LGBM正则化参数（lambda_l1/lambda_l2）
   • 优化树结构参数（max_depth/num_leaves）
3. 数据分段策略：
   • 调整训练/验证/测试集时间窗口
   • 支持滚动窗口训练策略

六、API参考

完整接口定义见：Model API文档

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