学习笔记：Qlib 量化投资平台框架 — FIRST STEPS

学习笔记：Qlib 量化投资平台框架 — FIRST STEPS

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

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

安装指南

一、环境要求

1. 操作系统
   • 支持 Windows、MacOS 和 Linux，推荐使用 Linux。
2. Python 版本
   • 支持 Python3， Python >=3.8。

二、安装方法

1. 通过 pip 安装

pip install pyqlib

2. 通过源码安装

步骤说明：

1. 进入 Qlib 根目录（包含 setup.py 文件）。

2. 依次执行以下命令：

   # 安装环境依赖
   pip install numpy
   pip install --upgrade cython# 克隆仓库并安装
   git clone https://github.com/microsoft/qlib.git && cd qlib
   python setup.py install
   

三、注意事项

1. 环境管理
   • 推荐使用 anaconda 或 miniconda 创建独立环境。
2. 依赖包安装

   • 需额外通过 pip 安装 lightgbm 和 pytorch：

     pip install lightgbm torch torchaudio torchvision
     

四、验证安装

执行以下 Python 代码确认安装成功：

import qlib
print(qlib.__version__)  # 输出应为当前安装版本（如 0.9.6）

关键总结

• 优先选择 Linux 环境，Python 版本需 >=3.8。
• 源码安装需按顺序处理依赖（numpy → cython → 克隆仓库）。
• 通过 conda 管理环境可减少依赖冲突风险。
• 必须单独安装 lightgbm 和 pytorch 以支持完整功能。

初始化

一、初始化流程

1. 数据准备

   • 执行以下命令下载默认数据集（中国股市数据）：

     python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/cn_data --region cn
     

   • 数据来源：Yahoo Finance（可能存在缺陷，建议用户使用高质量自定义数据）。

   • 自定义数据格式要求：详见 Data Preparation 部分。

2. 初始化 Qlib

   • 在调用其他 API 前，需运行以下 Python 代码初始化：

     import qlib
     from qlib.constant import REG_CNprovider_uri = "~/.qlib/qlib_data/cn_data"  # 数据存储路径
     qlib.init(provider_uri=provider_uri, region=REG_CN)
     

   • 注意：禁止在 Qlib 代码仓库目录内导入 qlib 包，否则可能报错。

二、关键参数解析

qlib.init() 支持以下核心参数配置：

• provider_uri
  类型：str，必填，数据存储路径（如 ~/.qlib/qlib_data/cn_data）。

• region
  类型：str，默认值为REG_CN，市场模式：

  • REG_CN（中国股市）
  • REG_US（美国股市）
    不同模式对应交易规则（如最小交易单位、交易限制）。

• redis_host
  类型：str，默认值为"127.0.0.1"，Redis 主机地址（用于缓存与锁机制）。

• redis_port
  类型：int，默认值为6379，Redis 端口。

• exp_manager
  类型：dict，默认值无，实验管理器配置（如使用 MLflow）：

  exp_manager={"class": "MLflowExpManager","module_path": "qlib.workflow.expm","kwargs": {"uri": "path/mlruns", "default_exp_name": "Experiment"}
  }
  

• mongo
  类型：dict，默认值无，MongoDB 配置（用于任务管理）：

  mongo={"task_url": "mongodb://localhost:27017/","task_db_name": "rolling_db"
  }
  

• logging_level
  默认值无，系统日志级别（如 DEBUG, INFO）。

• kernels
  类型：int，默认值无，表达式引擎进程数（调试时可设为 1）。

三、注意事项

1. 数据与 region 一致性

   • region 必须与 provider_uri 中数据对应。当前 get_data.py 仅支持中国数据，使用美国数据需用户自行准备。

2. Redis 依赖

   • 若 Redis 连接失败（错误配置或未启动），缓存机制将失效。

3. 实验管理器配置

   • exp_manager 需严格按字典格式定义类、模块路径及参数（如 MLflowExpManager）。

4. MongoDB 前置条件

   • 使用 mongo 参数前需安装并启动 MongoDB，通过 URI 访问（支持带认证的 URL）。

5. 调试建议

   • 调试表达式计算时，设置 kernels=1 以简化问题定位。

四、补充说明

• 区域模式扩展性：region 是预定义配置的快捷方式，用户可通过手动设置交易单位（trade_unit）、限制阈值（limit_threshold）等覆盖默认行为。
• 缓存机制文档：详见 Cache 部分。

数据检索功能

一、环境初始化

import qlib
qlib.init(provider_uri='~/.qlib/qlib_data/cn_data')  # 必须初始化后才能获取数据

• 需预先完成数据下载并设置正确的provider_uri路径

二、交易日历操作

from qlib.data import D
calendar = D.calendar(start_time='2010-01-01', end_time='2017-12-31', freq='day')
print(calendar[:2])  # 输出前两个交易日

• 支持时间范围过滤
• 可指定频率参数(freq)

三、股票池管理

1. 基础配置

D.instruments(market='all')  # 全市场配置
D.instruments(market='csi300')  # 沪深300成分股

2. 动态筛选器

(1) 正则筛选器

from qlib.data.filter import NameDFilter
name_filter = NameDFilter(name_rule_re='SH[0-9]{4}55')  # 匹配SHxxxx55格式

(2) 表达式筛选器

from qlib.data.filter import ExpressionDFilter
expr_filter = ExpressionDFilter(rule_expression='$close>2000')  # 收盘价大于2000

(3) 组合使用

instruments = D.instruments(market='csi300', filter_pipe=[name_filter, expr_filter])

四、特征数据加载

1. 基础特征获取

fields = ['$close', '$volume', 'Ref($close, 1)', 'Mean($close, 3)', '$high-$low']
data = D.features(['SH600000'], fields, start_time='2010-01-01', freq='day')

完整Features参考详见官方文档：Feature API Reference

2. 带缓存的加载

D.features(..., disk_cache=1)  # 启用缓存
D.features(..., disk_cache=0)  # 禁用缓存（客户端默认）
D.features(..., disk_cache=2)  # 服务端更新缓存

3. 高级表达式构建

方法一：字符串表达式

"(($high / $close) + ($open / $close)) * ..."

方法二：代码对象构建

from qlib.data.ops import *
f1 = Feature("high") / Feature("close")
f2 = Feature("open") / Feature("close")
f3 = (f1 + f2) * (f1 + f2) / (f1 + f2)

五、注意事项

1. 首次请求数据时因缓存初始化可能较慢
2. 相同股票池和字段的后续请求会利用缓存加速
3. 复杂表达式建议分步构建以提高可读性
4. 时间范围参数需遵循格式规范

完整API参考详见官方文档：Data API Reference

自定义模型集成

一、核心流程

1. 定义模型类：继承 qlib.model.base.Model
2. 编写配置文件：描述模型路径和参数
3. 模型测试：通过命令行或代码验证

二、自定义模型类实现规范

2.1 必须重写方法

(1) __init__ 方法

• 接收来自配置文件的初始化参数
• 必须与配置文件参数命名严格一致
• 示例逻辑：

def __init__(self, loss='mse', **kwargs):# 参数校验if loss not in {'mse', 'binary'}:raise NotImplementedError# 参数存储self._params.update(objective=loss, **kwargs)

(2) fit 方法

• 输入必须包含 dataset: DatasetH
• 支持可选参数默认值（如 num_boost_round=1000）
• 典型处理流程：

def fit(self, dataset, num_boost_round=1000):# 数据准备df_train, df_valid = dataset.prepare(...)# 特征/标签分离x_train, y_train = df_train["feature"], df_train["label"]# 模型训练self.model = lgb.train(...)

(3) predict 方法

• 必须返回 pd.Series 格式预测结果
• 示例实现：

def predict(self, dataset):x_test = dataset.prepare(...)return pd.Series(self.model.predict(x_test.values), index=x_test.index)

2.2 可选方法

finetune 方法

• 需继承 ModelFT 基类
• 实现微调逻辑：

def finetune(self, dataset, num_boost_round=10):dtrain = self._prepare_data(dataset)self.model = lgb.train(..., init_model=self.model)

三、配置文件规范

model:class: LGBModel                  # 类名module_path: qlib.contrib.model  # 模块路径args:loss: mse                    # __init__参数learning_rate: 0.0421        # 模型超参数max_depth: 8# ...其他参数

注意要点：

1. args 内参数通过 **kwargs 传递给 __init__
2. 基准配置参考路径：examples/benchmarks/<MODEL_NAME>/

四、模型测试方法

4.1 命令行测试

cd examples
qrun benchmarks/LightGBM/workflow_config_lightgbm.yaml

4.2 代码测试

参考示例：examples/workflow_by_code.ipynb

五、关键注意事项

1. 参数一致性：配置参数必须与__init__定义完全匹配
2. 数据维度：
   • LightGBM 要求标签为 1D 数组
   • 需处理 y_train.values.ndim == 2 的情况
3. 错误处理：
   • 必须校验 self.model is not None 后才执行预测
4. 微调要求：
   • 需显式继承 ModelFT 基类

六、扩展参考

1. 预测模型文档：Forecast Model: Model Training & Prediction
2. API 文档：Model API
3. 基准模型实现：examples/benchmarks/ 目录下的各模型实现

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