简介这份PDF文档是华泰证券金工研究团队出品的深度研究报告《微软AI量化投资平台Qlib体验》面向量化投资研究者、金融工程从业者及希望入门AI选股的学生群体。报告系统梳理了Qlib的基础与进阶功能对比传统量化策略开发流程提炼其数据存储方案、表达式引擎与缓存系统等工程创新并探讨实际使用体会。资源包内仅含1个PDF文件大小约4.71MB内容涵盖Qlib安装、数据准备、港股日频量价因子生成、LightGBM选股策略构建与结果展示以及自定义因子、标签、预处理方式和AI模型的进阶方法。目前已有1172人学习下载。读者可借此快速理解Qlib覆盖量化投资全过程的架构优势掌握从环境搭建到策略回测的完整操作路径并获取官方文档之外更具代入感的实战参考与风险提示。1. Qlib 安装踩坑记为什么我放弃了 pip 改用 setup.py2020 年底 Qlib 刚开源那阵子我正好在折腾港股量价因子选股的一套流程看到微软亚洲研究院放出了这个 AI 量化投资平台第一反应是赶紧装一个试试。结果从 pip install pyqlib 开始就翻车了——命令行跑完看似成功一执行策略脚本就报各种依赖缺失折腾了大半天才搞明白Windows 下 Qlib 对编译环境有硬性要求pip 装的是稳定版但很多示例代码依赖的是开发版才有的模块。后来换成 setup.py 方式从源码编译安装才把环境跑通。这篇文章就是把我从零装 Qlib、配数据、跑通港股日频 LightGBM 选股策略的完整过程记录下来包括中间踩过的坑和绕过去的办法。如果你也在 Windows 或 Mac 上装 Qlib 卡住了或者想用港股数据而不是官方默认的 A 股数据跑一遍完整流程这篇笔记应该能帮你省下不少时间。2. 安装 Qlib 之前环境依赖与版本选择2.1 Python 版本和 C 编译工具的前置检查Qlib 官方推荐 Python 3.7 及更新版本。我实测下来Python 3.7 和 3.8 最稳3.9 在部分依赖包上会有兼容性报错。如果你用的是 Anaconda建议单独建一个虚拟环境避免和已有包冲突conda create -n qlib_env python3.8 conda activate qlib_envWindows 用户需要特别注意Qlib 运行依赖 Microsoft Visual C 14.0。如果你直接 pip install pyqlib大概率会遇到这个报错error: Microsoft Visual C 14.0 is required. Get it with Build Tools for Visual Studio这里有个很容易搞混的点——只装 Microsoft Visual C Redistributable 运行组件是不够的必须装完整的 Microsoft Visual Studio 或者 Microsoft C 生成工具。我一开始就是只装了 Redistributable结果报错依旧。后来去微软官网下载了 C 生成工具安装时勾选“使用 C 的桌面开发”工作负载装完重启命令行问题才解决。Mac 用户相对省心一些Xcode Command Line Tools 通常已经覆盖了编译需求跑xcode-select --install确认一下即可。2.2 pip 安装与 setup.py 安装的取舍Qlib 官方给了两种安装方式。pip 安装最简单pip install pyqlib这条命令会自动拉取最新的稳定版。但我实际用下来pip 方式有两个问题一是 Windows 下如果 C 编译环境没配好安装过程会直接失败二是 pip 装的是 release 版本而官方文档和示例代码有时引用的是开发版才有的模块跑示例脚本容易报 ModuleNotFoundError。所以我更推荐 setup.py 方式从源码编译安装。先更新 numpy 和 cythonpip install numpy pip install --upgrade cython然后分两种情况。如果你装了 gitgit clone https://github.com/microsoft/qlib.git cd qlib python setup.py install如果没装 git就去 GitHub 下载 zip 源码包解压到任意路径比如我放在C:/Users/username/anaconda3/Lib/site-packages/qlib确保 setup.py 在这个路径下然后在该路径打开命令行python setup.py installsetup.py 方式会自动安装包含开发版在内的最新版本。我在 2020 年 12 月 14 日装出来的版本是 0.6.1.dev0。安装过程会编译 Cython 扩展耗时大概几分钟命令行最后出现Finished processing dependencies for pyqlib0.6.1.dev0就说明成功了。提示如果你所在网络环境不支持 git clone直接用 zip 源码包方式即可效果完全一样。3. 数据准备从官方数据下载到港股 CSV 格式转换3.1 get_data 下载官方数据及常见报错处理Qlib 自带 A 股和美股数据供学习测试。下载 A 股数据的命令是在 Qlib 安装路径下运行python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/cn_data --region cn这里有个坑如果你是用 pip 方式安装的 Qlib运行上面这条命令大概率会报ModuleNotFoundError: No module named qlib.tests。原因是 pip 安装包没有包含 tests 目录而 get_data 脚本依赖它。解决办法是从 GitHub 下载 Qlib 的 zip 源码包把里面的 tests 文件夹拷贝到你的 Qlib 安装路径下。下载成功后数据会保存在C:/Users/username/.qlib/qlib_data/cn_data。这个目录结构后面会反复用到建议先记下来。3.2 dump_all 转换用户自有数据港股 CSV 的字段要求官方数据只能用来跑通流程真正做研究还是得用自己的数据。Qlib 支持用户提供 CSV 格式数据通过 dump_all 指令转换成 bin 和 txt 格式。我以港股行情数据为例把每只股票存成一个 CSV 文件文件名就是股票代码整个文件夹命名为 hk_data。数据覆盖 2008 年初到 2020 年 11 月末一共 3739 只股票含权证和已退市股票。每个 CSV 文件内部需要包含以下字段字段名称字段说明stock_code股票代码和文件名一致date日频日期volume成交量money成交额vwap复权均价open复权开盘价high复权最高价low复权最低价close复权收盘价factor复权因子change相对前一个交易日涨跌幅这里有两个官方文档没明说但实际会踩的坑。第一价格数据建议用复权价格。因为后续数据标注环节会用 close 或 vwap 计算未来收益率回测环节也会用 close、open 或 vwap 进行交易不复权的话收益率计算会出问题。第二数据里必须包含 factor 或 change 字段否则跑官方示例代码examples/workflow_by_code.py时策略收益和净值会出现异常。除了个股数据还需要准备指数数据作为基准。我把恒生指数行情数据以相同形式保存在同一路径下命名为 hkhsi.csv。3.3 dump_all 命令参数详解与执行数据准备好之后回到 Qlib 安装路径运行python scripts/dump_bin.py dump_all --csv_path ~/.qlib/csv_data/hk_data --qlib_dir ~/.qlib/qlib_data/hk_data --symbol_field_name stock_code --date_field_name date --include_fields open,high,low,close,volume,money,factor,vwap,change参数逐个说明--csv_pathCSV 数据所在目录我的是~/.qlib/csv_data/hk_data--qlib_dir转换后 bin 数据的输出目录--symbol_field_nameCSV 中股票代码列的名称这里是 stock_code--date_field_nameCSV 中日期列的名称这里是 date--include_fields需要转换的字段列表注意逗号后面不能有空格否则转换会报错转换完成后新数据保存在C:/Users/username/.qlib/qlib_data/hk_data目录下包含 calendar、features 和 instruments 三个子目录。calendar 存交易日历features 存各股票的各字段 bin 文件instruments 存股票池信息。4. 因子生成与 LightGBM 选股策略构建4.1 初始化运行环境与自定义股票池数据转换好之后就可以在 Python 里初始化 Qlib 运行环境了。核心代码就几行import qlib from qlib.constant import REG_HK # 初始化 Qlib指定数据路径和地区 qlib.init(provider_uri~/.qlib/qlib_data/hk_data, regionREG_HK)provider_uri指向你转换后的 bin 数据目录region指定市场区域港股用 REG_HK。初始化完成后可以用qlib.data.D.calendar()获取交易日历用qlib.data.D.instruments()获取全部股票代码。自定义股票池是实际研究中的常见需求。比如我只想选恒生指数成分股或者剔除低价股和低流动性股票可以通过 instruments 文件来控制。Qlib 的股票池定义在instruments/all.txt文件里每行格式是股票代码 起始日期 结束日期。我一般会先写一个筛选脚本把符合条件比如日均成交额大于某个阈值、价格大于 1 港元的股票筛出来生成自定义的股票池文件。4.2 Alpha158 因子库的调用与标签生成Qlib 内置了 Alpha158 和 Alpha360 两个因子库。Alpha158 包含 158 个量价因子涵盖 K 线形态、均线、波动率、成交量等维度。调用方式from qlib.contrib.data.handler import Alpha158 # 定义数据处理器指定股票池和日期范围 data_handler_config { start_time: 2008-01-01, end_time: 2020-11-30, fit_start_time: 2008-01-01, fit_end_time: 2017-12-31, instruments: all, } handler Alpha158(**data_handler_config)fit_start_time和fit_end_time用于数据预处理阶段的拟合通常设置为训练集的时间范围避免用到未来数据。标签方面Alpha158 默认用下期收益率作为标签具体是 close 的 T1 到 T2 的收益率。你可以通过handler.fetch()获取特征和标签# 获取全部数据和标签 data handler.fetch(col_setfeature) label handler.fetch(col_setlabel)4.3 LightGBM 模型训练参数配置Qlib 把模型训练、因子生成、回测等环节通过 workflow 串联起来。最直接的方式是定义一个 task 字典把模型参数和数据集参数都写进去from qlib.contrib.model.gbdt import LGBModel from qlib.contrib.data.handler import Alpha158 from qlib.workflow import R # 模型参数 model_config { loss: mse, learning_rate: 0.05, num_leaves: 64, num_threads: 8, } # 数据集参数 dataset_config { class: DatasetH, module_path: qlib.data.dataset, kwargs: { handler: { class: Alpha158, module_path: qlib.contrib.data.handler, kwargs: { start_time: 2008-01-01, end_time: 2020-11-30, fit_start_time: 2008-01-01, fit_end_time: 2017-12-31, instruments: all, }, }, segments: { train: (2008-01-01, 2017-12-31), valid: (2018-01-01, 2018-12-31), test: (2019-01-01, 2020-11-30), }, }, }learning_rate控制每棵树的学习率0.05 是比较保守的设置配合num_leaves64 可以防止过拟合。num_threads根据你机器的 CPU 核心数来设。训练集、验证集、测试集的划分通过 segments 控制注意验证集和测试集不能和训练集有时间重叠。训练代码model LGBModel(**model_config) dataset DatasetH(**dataset_config) model.fit(dataset) pred model.predict(dataset)model.fit()内部会自动完成因子生成、预处理、训练全过程。pred是模型对测试集的预测值也就是每只股票每天的预期收益打分。5. 策略回测与绩效分析从信号到净值曲线5.1 回测参数配置与执行拿到模型预测值之后下一步是构建选股策略并回测。Qlib 的回测配置通过port_analysis_config控制from qlib.contrib.evaluate import backtest_daily from qlib.contrib.strategy import TopkDropoutStrategy # 策略参数每天选预测得分最高的 50 只持有 50 只 strategy_config { class: TopkDropoutStrategy, module_path: qlib.contrib.strategy, kwargs: { signal: pred, topk: 50, n_drop: 5, }, } # 回测参数 backtest_config { start_time: 2019-01-01, end_time: 2020-11-30, account: 100000000, benchmark: hkhsi, exchange_kwargs: { freq: day, limit_threshold: 0.095, deal_price: close, open_cost: 0.0005, close_cost: 0.0015, min_cost: 5, }, }topk50表示每天持仓 50 只股票n_drop5表示每天最多换出 5 只。limit_threshold是涨跌停限制港股没有涨跌停这里设 0.095 只是防止极端价格成交。open_cost和close_cost是买卖手续费港股实际费率根据券商不同有差异我按万五买入、千一点五卖出含印花税来设。执行回测report, positions backtest_daily( strategy_configstrategy_config, backtest_configbacktest_config, )report是每日的收益、净值、换手率等指标positions是每日持仓明细。5.2 回测结果解读与绩效指标回测完成后用report可以画出净值曲线、超额收益曲线、最大回撤和换手率。我一般会关注几个核心指标指标含义观察要点IC / Rank IC预测值与实际收益的相关性大于 0.03 算可用大于 0.05 算不错年化收益策略每年的平均收益对比基准指数看超额最大回撤净值从高点到低点的最大跌幅超过 20% 要警惕换手率每日持仓变动比例过高会侵蚀收益夏普比率单位风险的超额收益大于 1 算合格IC 和 Rank IC 是判断模型预测能力最直接的指标。如果 IC 很低甚至为负说明模型没有学到有效信号需要检查因子质量、标签定义或者训练集划分。净值曲线要结合市场环境看2019 年到 2020 年港股整体波动较大如果策略在下跌月份也能跑赢基准说明有一定的选股能力。6. 避坑与排查Qlib 安装配置中最容易翻车的五个点6.1 报错 Microsoft Visual C 14.0 is required现象pip install pyqlib 或 python setup.py install 过程中直接报错提示缺少 Microsoft Visual C 14.0。原因Qlib 的部分 Cython 扩展需要 C 编译环境Windows 上默认没有安装。解决去微软官网下载 Microsoft C 生成工具安装时勾选“使用 C 的桌面开发”工作负载。注意只装 Redistributable 运行组件没用必须装生成工具或完整版 Visual Studio。装完重启命令行再试。6.2 get_data 报 ModuleNotFoundError: No module named qlib.tests现象运行python scripts/get_data.py qlib_data ...时报找不到 qlib.tests 模块。原因pip 安装的 Qlib 包不包含 tests 目录而 get_data 脚本依赖它。解决从 GitHub 下载 Qlib 的 zip 源码包把里面的 tests 文件夹拷贝到 Qlib 安装路径下。或者直接用 setup.py 方式从源码安装源码包里自带 tests。6.3 dump_all 转换后数据为空或字段缺失现象dump_all 执行完qlib_dir 下只有 calendar 和 instrumentsfeatures 目录是空的或者部分字段没有转换成功。原因最常见的是--include_fields参数里逗号后面带了空格比如写成了open, high, lowQlib 会把带空格的字段名当成无效字段跳过。另一个原因是 CSV 文件名字和 stock_code 字段不一致。解决检查 include_fields 参数确保逗号后没有空格。检查每个 CSV 文件名是否和文件内 stock_code 列的值完全一致。转换前可以先拿一两个股票的小样本测试。6.4 回测净值曲线异常收益离谱现象回测跑出来的净值曲线要么是一条直线要么波动巨大和预期完全不符。原因大概率是数据里缺少 factor 或 change 字段。Qlib 的回测和标签计算依赖复权因子或涨跌幅字段缺失的话收益率计算会出错。解决确保 CSV 数据包含 factor 或 change 字段。如果只有不复权价格至少要有 change 字段记录每日涨跌幅。另外检查价格是否用了复权价不复权价格在除权除息日会产生跳空导致收益率计算错误。6.5 训练集和测试集时间重叠导致过拟合现象模型在测试集上 IC 很高但实盘或样本外表现很差。原因数据预处理阶段的 fit_start_time 和 fit_end_time 设置不当用到了测试集的数据做拟合造成数据泄露。解决fit_end_time 必须早于或等于训练集结束时间绝对不能覆盖验证集和测试集。我一般把 fit_end_time 设为训练集最后一天确保预处理参数只从训练数据中学到。7. 装完之后怎么验证 Qlib 真的跑通了装完 Qlib 最怕的就是“看起来装好了一跑就报错”。我一般会用一个最小验证流程来确认环境没问题。第一步打开 Python 命令行执行import qlib和qlib.__version__确认能正常导入并打印出版本号。第二步初始化 Qlib 并读取交易日历import qlib from qlib.constant import REG_HK qlib.init(provider_uri~/.qlib/qlib_data/hk_data, regionREG_HK) from qlib.data import D calendar D.calendar(start_time2020-01-01, end_time2020-01-10) print(calendar)如果能看到 2020 年 1 月上旬的交易日列表说明数据路径和初始化都没问题。第三步拉一只股票的数据看看from qlib.data import D df D.features([0700], [$close, $volume], start_time2020-01-01, end_time2020-01-10) print(df)正常的话会输出腾讯控股这段时间的收盘价和成交量。如果报错说找不到股票代码检查 instruments 文件里有没有包含这只股票。第四步跑一个最小的模型训练和预测不用完整回测就确认 Alpha158 因子能生成、LightGBM 能训练from qlib.contrib.data.handler import Alpha158 handler Alpha158(instrumentsall, start_time2019-01-01, end_time2020-11-30, fit_start_time2019-01-01, fit_end_time2019-12-31) data handler.fetch(col_setfeature) print(data.shape)能打印出特征矩阵的形状行数 × 158 列左右就说明因子生成环节通了。这四步走完基本可以确认 Qlib 环境、数据、因子、模型四个环节都是通的再去跑完整回测就不会遇到环境层面的问题了。从那以后我每次装 Qlib 或者换数据源都会强制走一遍这个四步验证流程确认每一步的输出符合预期再往下走。很多看起来复杂的报错其实都是环境或数据格式的小问题累积出来的提前验证能省下大量排查时间。希望帮到你。本文还有配套的精品资源点击获取