企业官网建设流程全解析

简介：这份PDF文档是华泰证券金工研究团队出品的深度研究报告《微软AI量化投资平台Qlib体验》，面向量化投资研究者、金融工程从业者及希望入门AI选股的学生群体。报告系统梳理了Qlib的基础与进阶功能，对比传统量化策略开发流程，提炼其数据存储方案、表达式引擎与缓存系统等工程创新，并探讨实际使用体会。资源包内仅含1个PDF文件，大小约4.71MB，内容涵盖Qlib安装、数据准备、港股日频量价因子生成、LightGBM选股策略构建与结果展示，以及自定义因子、标签、预处理方式和AI模型的进阶方法。目前已有1172人学习下载。读者可借此快速理解Qlib覆盖量化投资全过程的架构优势，掌握从环境搭建到策略回测的完整操作路径，并获取官方文档之外更具代入感的实战参考与风险提示。

1. Qlib 安装踩坑记：为什么我放弃了 pip 改用 setup.py

2020 年底 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 python=3.8 conda activate qlib_env

Windows 用户需要特别注意：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 和 cython：

pip install numpy pip install --upgrade cython

然后分两种情况。如果你装了 git：

git 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 install

setup.py 方式会自动安装包含开发版在内的最新版本。我在 2020 年 12 月 14 日装出来的版本是 0.6.1.dev0。安装过程会编译 Cython 扩展，耗时大概几分钟，命令行最后出现Finished processing dependencies for pyqlib==0.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 文件内部需要包含以下字段：

这里有两个官方文档没明说但实际会踩的坑。第一，价格数据建议用复权价格。因为后续数据标注环节会用 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_path：CSV 数据所在目录，我的是~/.qlib/csv_data/hk_data
• --qlib_dir：转换后 bin 数据的输出目录
• --symbol_field_name：CSV 中股票代码列的名称，这里是 stock_code
• --date_field_name：CSV 中日期列的名称，这里是 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', region=REG_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 的 T+1 到 T+2 的收益率。你可以通过handler.fetch()获取特征和标签：

# 获取全部数据和标签 data = handler.fetch(col_set="feature") label = handler.fetch(col_set="label")

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, }, }

topk=50表示每天持仓 50 只股票，n_drop=5表示每天最多换出 5 只。limit_threshold是涨跌停限制，港股没有涨跌停，这里设 0.095 只是防止极端价格成交。open_cost和close_cost是买卖手续费，港股实际费率根据券商不同有差异，我按万五买入、千一点五卖出（含印花税）来设。

执行回测：

report, positions = backtest_daily( strategy_config=strategy_config, backtest_config=backtest_config, )

report是每日的收益、净值、换手率等指标，positions是每日持仓明细。

5.2 回测结果解读与绩效指标

回测完成后，用report可以画出净值曲线、超额收益曲线、最大回撤和换手率。我一般会关注几个核心指标：

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 和 instruments，features 目录是空的，或者部分字段没有转换成功。

原因：最常见的是--include_fields参数里逗号后面带了空格，比如写成了open, high, low，Qlib 会把带空格的字段名当成无效字段跳过。另一个原因是 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', region=REG_HK) from qlib.data import D calendar = D.calendar(start_time='2020-01-01', end_time='2020-01-10') print(calendar)

如果能看到 2020 年 1 月上旬的交易日列表，说明数据路径和初始化都没问题。第三步，拉一只股票的数据看看：

from qlib.data import D df = D.features(['0700'], ['$close', '$volume'], start_time='2020-01-01', end_time='2020-01-10') print(df)

正常的话会输出腾讯控股这段时间的收盘价和成交量。如果报错说找不到股票代码，检查 instruments 文件里有没有包含这只股票。第四步，跑一个最小的模型训练和预测，不用完整回测，就确认 Alpha158 因子能生成、LightGBM 能训练：

from qlib.contrib.data.handler import Alpha158 handler = Alpha158(instruments='all', start_time='2019-01-01', end_time='2020-11-30', fit_start_time='2019-01-01', fit_end_time='2019-12-31') data = handler.fetch(col_set='feature') print(data.shape)

能打印出特征矩阵的形状（行数 × 158 列左右），就说明因子生成环节通了。这四步走完，基本可以确认 Qlib 环境、数据、因子、模型四个环节都是通的，再去跑完整回测就不会遇到环境层面的问题了。

从那以后我每次装 Qlib 或者换数据源，都会强制走一遍这个四步验证流程，确认每一步的输出符合预期再往下走。很多看起来复杂的报错，其实都是环境或数据格式的小问题累积出来的，提前验证能省下大量排查时间。希望帮到你。

本文还有配套的精品资源，点击获取