Microsoft Qlib 详细部署教程

项目概述

Qlib 是微软开源的、面向 AI 的量化投资平台，旨在利用 AI 技术赋能量化研究，从探索想法到实施生产。它支持多种机器学习建模范式，包括监督学习、市场动态建模和强化学习。

核心特性：

功能模块 说明
完整 ML 流水线 数据处理、模型训练、回测
量化投资全链条 因子挖掘、风险建模、组合优化、订单执行
模型库 包含 LightGBM、LSTM、Transformer、TFT 等 20+ 模型
数据框架 高性能数据服务器，比通用数据库快 10-100 倍
RL 框架 支持订单执行等连续决策建模
自动化工作流 qrun 工具支持端到端流程
RD-Agent 集成 支持自动因子挖掘和模型优化

技术栈：Python 3.8-3.12，支持 Windows 和 Linux（推荐 Linux）

部署前准备

系统要求

项目 要求
Python 3.8 - 3.12
操作系统 Windows / Linux（推荐 Linux）
内存 最低 8GB，推荐 16GB+
磁盘空间 最低 10GB（数据文件约 5GB）
Conda 推荐使用（避免头文件缺失问题）

环境检查

1
2
3
python --version
pip --version
conda --version  # 推荐

注意：官方文档建议使用 Conda 管理 Python 环境，在某些情况下，在 Conda 环境外使用 Python 可能导致头文件缺失，引起某些包安装失败 。

方案一：pip 安装（推荐）

这是最简单的部署方式，适合大多数用户。

步骤 1：创建 Conda 环境（推荐）

1
2
3
4
5
# 创建环境
conda create -n qlib python=3.10 -y

# 激活环境
conda activate qlib

步骤 2：安装 Qlib

1
pip install pyqlib

说明：pip 会安装最新的稳定版 Qlib 。

步骤 3：验证安装

1
2
import qlib
print(qlib.__version__)

方案二：从源码安装（开发/最新版本）

如果你需要最新开发版本或进行二次开发，可以从源码构建。

步骤 1：安装依赖

1
2
pip install numpy
pip install --upgrade cython

步骤 2：克隆并安装

1
2
git clone https://github.com/microsoft/qlib.git && cd qlib
pip install .

开发模式安装（推荐用于开发）：

1
pip install -e .[dev]

步骤 3：Mac M1 用户特别说明

如果你使用 Mac M1，可能会遇到构建 LightGBM wheel 的问题，这是由于缺少 OpenMP 依赖。解决方法：

1
2
brew install libomp
pip install .

方案三：Docker 部署

Docker 方式适合需要隔离环境或快速部署的场景。

步骤 1：拉取镜像

1
docker pull pyqlib/qlib_image_stable:stable

步骤 2：启动容器

1
docker run -it --name qlib -v /your/local/directory:/app pyqlib/qlib_image_stable:stable

参数说明：

  • -it：交互式终端
  • --name qlib：容器名称
  • -v /your/local/directory:/app：挂载本地目录

步骤 3：在容器内运行

1
2
3
4
5
# 下载数据
python scripts/get_data.py qlib_data --name qlib_data_simple --target_dir ~/.qlib/qlib_data/cn_data --interval 1d --region cn

# 运行示例工作流
python qlib/cli/run.py examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

容器管理命令

命令 说明
exit 退出容器
docker start -i -a qlib 重启容器
docker stop qlib 停止容器
docker rm qlib 删除容器

数据准备

方式 1：下载社区维护的数据集（推荐）

由于官方数据集的限制，可以使用社区维护的数据源：

1
2
3
4
5
6
7
8
9
10
11
# 下载最新数据
wget https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz

# 创建数据目录
mkdir -p ~/.qlib/qlib_data/cn_data

# 解压
tar -zxvf qlib_bin.tar.gz -C ~/.qlib/qlib_data/cn_data --strip-components=1

# 清理
rm -f qlib_bin.tar.gz

方式 2：使用官方数据获取模块

1
2
3
4
5
# 获取日线数据
python -m qlib.cli.data qlib_data --target_dir ~/.qlib/qlib_data/cn_data --region cn

# 获取分钟数据
python -m qlib.cli.data qlib_data --target_dir ~/.qlib/qlib_data/cn_data_1min --region cn --interval 1min

方式 3：使用脚本获取

1
2
3
4
5
# 日线数据
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/cn_data_1min --region cn --interval 1min

注意：数据集来自 Yahoo Finance，数据可能不完美。如果你有高质量数据集，建议自行准备 。

数据健康检查

1
python scripts/check_data_health.py check_data --qlib_dir ~/.qlib/qlib_data/cn_data

可调整参数：

  • freq：数据频率
  • large_step_threshold_price：允许的最大价格变化
  • large_step_threshold_volume：允许的最大成交量变化
  • missing_data_num：允许数据为空的最大值

自动化工作流（qrun）

Qlib 提供 qrun 工具，可自动运行整个工作流（包括构建数据集、训练模型、回测和评估）。

运行 LightGBM 示例

1
2
cd examples
qrun benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

调试模式运行

1
python -m pdb qlib/cli/run.py examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

预期输出示例

text

1
2
3
4
5
6
7
'The following are analysis results of the excess return without cost.'
                   risk
mean               0.000708
std                0.005626
annualized_return  0.178316
information_ratio  1.996555
max_drawdown      -0.081806

图形化报告分析

步骤 1：安装分析依赖

1
python -m pip install .[analysis]

步骤 2：运行 Jupyter Notebook

1
jupyter notebook examples/workflow_by_code.ipynb

分析内容

  • 预测信号分析：分组累积收益、收益分布、信息系数（IC）、自相关性
  • 组合分析：回测收益

项目结构说明

text

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
qlib/
├── qlib/                    # 核心包
│   ├── data/               # 数据模块
│   ├── model/              # 模型库
│   ├── workflow/           # 工作流
│   ├── contrib/            # 贡献模块
│   └── rl/                 # 强化学习
├── scripts/                # 数据采集脚本
│   ├── data_collector/     # 数据收集器
│   │   ├── yahoo/          # Yahoo Finance
│   │   ├── pit/            # Point-in-Time 数据
│   │   └── baostock_5min/  # Baostock 5分钟数据
│   └── get_data.py         # 数据获取
├── examples/               # 示例和基准
│   └── benchmarks/         # 模型基准
├── docs/                   # 文档
└── tests/                  # 测试

支持的模型

Qlib 内置 20+ 模型，包括：

类别 模型
GBDT XGBoost、LightGBM、CatBoost
神经网络 MLP、LSTM、GRU、ALSTM、GATs、SFM
时序模型 TFT、TabNet、TCN、ADARNN、ADD
Transformer Transformer、Localformer、TRA
集成 DoubleEnsemble、TCTS
其他 IGMTF、HIST、KRNN、Sandwich

运行单个模型

1
2
# 使用 run_all_model.py 运行特定模型
python run_all_model.py run --models=lightgbm

运行多个模型

1
2
# 运行所有模型 10 次迭代
python run_all_model.py run 10

注意：多模型运行脚本目前仅支持 Linux 。

常见问题排查

问题 解决方案
安装失败，提示缺少头文件 使用 Conda 环境，或安装 build-essential 等开发工具
Python 版本不兼容 确认使用 Python 3.8-3.12
Cython 安装错误 升级 Python 到 3.8+，或使用 Conda 的 Python
Mac M1 LightGBM 构建失败 先运行 brew install libomp
数据下载失败 检查网络连接，使用社区数据源替代
pandas group_key 错误 这是 pandas 1.5-2.0 的破坏性变更，需设置 group_key=False
数据健康检查警告 检查缺失数据量、价格跳变等是否在可接受范围

数据健康检查参数说明

1
2
3
4
python scripts/check_data_health.py check_data --qlib_dir ~/.qlib/qlib_data/cn_data \
  --missing_data_num 30055 \
  --large_step_threshold_volume 94485 \
  --large_step_threshold_price 20

数据更新

自动更新（Linux）

1
2
3
4
5
# 编辑 crontab
crontab -e

# 添加定时任务（每个交易日执行）
* * * * 1-5 python <script_path> update_data_to_bin --qlib_data_1d_dir <user_data_dir>

手动更新

1
2
3
4
python scripts/data_collector/yahoo/collector.py update_data_to_bin \
  --qlib_data_1d_dir <user_data_dir> \
  --trading_date <start_date> \
  --end_date <end_date>

离线模式与在线模式

Qlib 数据服务器支持两种部署模式：

模式 说明
离线模式（默认） 数据部署在本地
在线模式 数据作为共享服务部署，所有客户端共享数据和缓存

在线模式文档参见 Qlib-Server 仓库。

总结

部署方式 适用场景 难度 推荐度
pip 安装 大多数用户 ⭐ ⭐⭐⭐⭐⭐
源码安装 开发/最新功能 ⭐⭐⭐ ⭐⭐⭐
Docker 部署 隔离环境/快速部署 ⭐⭐ ⭐⭐⭐⭐

对于大多数用户，pip 安装是最简单直接的选择：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 创建 Conda 环境（推荐）
conda create -n qlib python=3.10 -y
conda activate qlib

# 安装 Qlib
pip install pyqlib

# 验证
python -c "import qlib; print(qlib.__version__)"

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

# 运行示例工作流
cd examples
qrun benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

安装完成后，你可以参考官方文档和示例 notebooks 开始量化研究。Qlib 提供了丰富的模型库和完整的工作流支持，适合从因子挖掘到组合优化的全链条研究。