← 返回工具目录 · 全部教程

Qlib 上手教程:安装、A 股数据、跑通第一个 Alpha158 + LightGBM 模型

实操篇 — 装好 Qlib、拿到 A 股数据、跑通第一个机器学习选股模型

怎么选: 第一次跑通用四步:单独装一个 Python 3.12 环境,pip install pyqlib,下载社区维护的 A 股数据,再运行一条 qrun。官方数据集已经暂停,老教程里的 get_data 现在拿不到数据。策略是每天给一篮子股票打分、买排名靠前的,用 Qlib;盯一两只股票、按均线或指标决定买卖,用 backtrader。Qlib 不负责连券商下单,要实盘先跑模拟盘,再接 QMT 或 PTrade。要在九个回测框架里挑,看回测框架对比;这篇只带你装好并跑通 Alpha158 + LightGBM。

适合谁: 会一点 Python,想在自己电脑上用机器学习给一篮子 A 股打分、再买排名靠前的人。你要的是一条能跑通的路:Python 3.12、社区 A 股数据、一条 qrun,以及 IC、年化超额和最大回撤怎么读。我们 2026-10-21 在 Windows 11 上用 Python 3.12 和 pyqlib 0.9.7 实际跑通过。

不适合谁: 想问一只股票什么时候买、什么时候卖的人,用 backtrader 更直接。想让 Qlib 直接连券商账户下单的人,它不负责这件事。这篇不排先数据再回测的工具顺序,也不是本站的常见问题页,也不是九个回测框架放在一起比的那篇。官方数据已经暂停,照着老教程下载会拿不到数据。

英文版是同一篇: Qlib: install, China A-share data, and a first Alpha158 + LightGBM run。九个回测框架放在一起比,见 量化回测框架怎么选,那不是这篇。

本站与微软、Qlib 项目和社区数据的作者都没有合作关系。下文命令和结果来自我们 2026-10-21 的实际运行(Windows 11、16 核 CPU、Python 3.12、pyqlib 0.9.7),换一台机器、换一版数据,用时和结果都会不同。站内另有 Qlib 工具页。

01 · Qlib 是什么、适合谁

Qlib 是微软开源的 AI 量化投资平台,许可是 MIT。它的重点不在“回测”本身,而在前面:准备数据、算因子、训练模型,再用模型给股票打分、挑分数高的买,回测是这条流水线的最后一步。

所以它适合这样的问题:每天在一篮子股票里,挑出接下来最可能跑赢的那几只。如果你想的是“一只股票什么时候买、什么时候卖”,用 backtrader 更直接。九个回测框架放在一起比,见 量化回测框架怎么选。

02 · 安装:先装一个 Python 3.12

官方 README 写的支持范围是 Python 3.8 到 3.12,Linux、Windows、macOS 都可以。更新的 3.13、3.14 不在列表里。我们的电脑上只有 3.14,所以用 uv 单独建了一个 3.12 的虚拟环境,不碰系统里原来的 Python:

uv venv --python 3.12 qlib-env
qlib-env\Scripts\activate          # macOS / Linux:source qlib-env/bin/activate
uv pip install pyqlib

不用 uv 也行:从 python.org 装一个 3.12,再用 py -3.12 -m venv qlib-env 建环境、pip install pyqlib 安装,道理一样。

• 版本:pip 装到的是 0.9.7(2025-08 发布)。GitHub 上已经有 v0.9.8(2026-10-08),但按它的发布说明只提供源码包,内容是安全加固;新手用 pip 装的 0.9.7 就能跑通下面的流程。
• Mac M1 的坑:README 提醒,M1 上编译 LightGBM 可能失败,要先 brew install libomp。
• 示例配置不在 pip 包里:后面要用的配置文件得从 GitHub 下载,第 04 节给了地址。

03 · 准备 A 股数据:官方数据暂停,用社区数据

这是现在最容易卡住的一步。Qlib 的 README 写明:因为数据安全政策更严格,官方数据集暂停提供,推荐改用社区维护的 investment_data。网上很多老教程里的 get_data 下载命令,现在拿不到官方数据。

investment_data 每天在 GitHub 发布一个压缩包,许可是 Apache-2.0。按它的说明,数据由 Wind、财汇(这两个只到 2019 年)、Tushare、AKShare 等多个来源合并而成,价格做了复权。我们下载的 2026-10-21 版解压后是这样:

• 日期从 2000-01-04 到 2026-10-21,共 6170 只股票,包含已经退市的股票和北交所;
• 每只股票有开盘、最高、最低、收盘、均价、成交量、成交额、涨跌幅和复权因子;
• 带沪深 300、中证 500、中证 800、中证 1000 和全市场的成分股名单。

Windows 用 PowerShell,依次运行(用的是系统自带的 curl.exe 和 tar,我们的 Windows 11 上都有):

curl.exe -L -o qlib_bin.tar.gz https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz
mkdir $HOME\.qlib\qlib_data\cn_data
tar -zxf qlib_bin.tar.gz -C $HOME\.qlib\qlib_data\cn_data --strip-components=1

macOS / Linux 用 README 给的命令:

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

压缩包 500 多 MB,解压后约 700 MB。社区数据的说明建议下载后先校验:同一个发布页里有个 qlib_bin.manifest.json,里面写着压缩包的 SHA256。Windows 上用 Get-FileHash qlib_bin.tar.gz -Algorithm SHA256 算一遍,两边一致再解压。我们下载的那一版,大小和 SHA256 都和清单一致。

04 · 第一次跑通:一条 qrun

从 GitHub 下载官方示例配置 workflow_config_lightgbm_Alpha158.yaml(我们用的是 0.9.7 标签下的版本,和 pip 装的版本对应)。配置第 2 行 provider_uri 是数据目录,默认写的是 ~/.qlib/qlib_data/cn_data,也就是上一步解压的位置;数据放在别处,或者运行时提示找不到数据,就改成你数据目录的完整路径(我们测试时就是改成了完整路径)。然后运行:

$env:MLFLOW_ALLOW_FILE_STORE="true"      # macOS / Linux:export MLFLOW_ALLOW_FILE_STORE=true
qrun workflow_config_lightgbm_Alpha158.yaml

第一行是我们实际踩到的坑:不加它,新装环境里的 mlflow(Qlib 用来保存实验记录的组件,我们装到的是 3.17.2)会直接报错退出,提示 “filesystem tracking backend is in maintenance mode”,报错信息里自己给的绕过办法就是设置这个环境变量。加上以后,我们这次从读数据、训练到回测一共用了约 4 分钟(16 核 CPU)。实验记录存在你运行命令时所在目录的 mlruns 文件夹里。

这份示例配置做的事,翻译成大白话:

• 选股范围:沪深 300 成分股,对比基准是沪深 300 指数。
• 时间切三段:2008 到 2014 年训练模型,2015 到 2016 年用来调参,2017-01 到 2020-08 是真正的考试(回测)。考试期的数据模型训练时没见过。
• 模型:LightGBM,一种常用的树模型,输入是下一节讲的 158 个因子,输出是每只股票的打分。
• 怎么买卖:每天持有打分最高的 50 只,每天最多把手里排名掉下去的 5 只换掉。按官方文档,这样换手率大约是每天 20%。
• 成本假设:买入 0.05%、卖出 0.15%、每笔最低 5 元,涨跌超过 9.5% 视为涨跌停买卖不了,按收盘价成交。

最后一条只是 Qlib 示例的假设,不是现在的真实费率。证券交易印花税已经自 2023 年 8 月 28 日起减半征收(财政部公告),佣金和过户费各家券商不一样,以开户券商的说明为准。想让回测更接近你自己的情况,把配置里的 open_cost、close_cost、min_cost 改成你的实际费率。

05 · Alpha158 是什么

Alpha158 是 Qlib 自带的一套因子,也就是给模型看的“线索”。我们从安装好的 0.9.7 源码里数过,正好 158 个,全部只用开高低收和成交量算出来,不用财报:

• K 线形态 9 个:比如实体占开盘价的比例 ($close-$open)/$open、上影线、下影线有多长。
• 当天价格 4 个:开盘、最高、最低、均价,都除以收盘价,变成相对值。
• 滚动计算 145 个:29 种算法 × 5 个时间窗口(5、10、20、30、60 天),比如 N 天涨幅、N 天均线、N 天波动、N 天里价格所处位置、价量相关性、上涨天数占比。

它们本身不保证有用,作用是给模型一个现成的起点。想换成自己的因子,可以在配置里换掉 Alpha158 这个 handler,或者在它的基础上加。

06 · 结果怎么读

跑完后屏幕最后会打印几组数字。下表是我们这次的结果,和 Qlib 官方在 benchmarks 页面公布的同一模型结果(20 次随机种子的平均)放在一起:

几点要读懂:

• IC 0.05 左右是什么水平:相关系数最高是 1。0.05 说明打分和实际涨跌只有很弱的同向关系,单看一只股票几乎没用,要靠一次持有很多只、长期重复才可能体现出来。
• 年化是相加,不是复利:按 Qlib 的源码,年化收益等于每天平均收益乘以 238,是简单相加算的,不是复利,和平时说的年化不完全一样。
• 看的是“超额”:收益和回撤都是比沪深 300 指数多出来的部分。同一时期沪深 300 自己的最大回撤是 -37%,也就是说,策略本身亏不亏,还要把指数的涨跌加回去看。
• 和官方不完全一样很正常:数据版本不同、随机种子不同,结果都会变。我们 IC 和官方几乎一样,收益高一些,原因没有逐项拆过,不要当成“社区数据更好”。

07 · 改成你自己的

• 把时间延到最近:示例配置只用到 2020-08,但社区数据已经到 2026-10。把配置里 end_time 和三段 segments 往后挪,就能看最近几年的表现。注意训练段、调参段、考试段不能重叠。
• 换股票池:官方 benchmarks 页面给了换成中证 500 的方法:把配置里的 csi300 换成 csi500,基准 SH000300 换成 SH000905。
• 换模型:examples/benchmarks 下面每个文件夹是一个模型(比如 XGBoost、MLP、LSTM),各有现成配置,换一个配置文件再跑一次 qrun 就能比较。README 提醒,不同模型的环境依赖不一样(比如 TFT 只支持 Python 3.6~3.7),换之前先看该模型文件夹里的说明。

08 · 常见坑

• mlflow 报错 “filesystem tracking backend is in maintenance mode”:运行前设置 MLFLOW_ALLOW_FILE_STORE=true,见第 04 节。
• Python 版本太新:3.13、3.14 不在官方支持范围,装不上或跑出奇怪的错,先换 3.12。
• 老教程的数据命令拿不到数据:官方数据集暂停了,改用第 03 节的社区数据。
• 别加载来路不明的配置和模型:v0.9.8 的发布说明专门加强了这方面的安全限制。用 0.9.7 时,只运行你自己看过的配置文件。
• 回测好看不等于能赚钱:考试期只有 2017 到 2020 年,换一段行情可能完全不同;真实成本、冲击成本、停牌都会让实盘比回测差。先跑一段时间 模拟盘。

09 · 接下来看什么

• 数据想自己掌控、每天更新:Tushare 和 AKShare 怎么选,以及 akshare 数据实操。
• 想看 Qlib 之外的 AI 量化项目:AI 量化开源项目有哪些。
• 想把选股结果接到实盘:QMT 和 PTrade 怎么选。

本文不构成任何投资建议。机器学习模型在历史数据上的表现不代表未来收益;Qlib 和社区数据的功能、版本和许可以其官方说明为准。