企业官网建设流程全解析

Qlib 快速上手：一条命令跑通 LightGBM 量化研究全流程

【免费下载链接】qlibQlib is an AI-oriented Quant investment platform that aims to use AI tech to empower Quant Research, from exploring ideas to implementing productions. Qlib supports diverse ML modeling paradigms, including supervised learning, market dynamics modeling, and RL, and is now equipped with https://github.com/microsoft/RD-Agent to automate R&D process.项目地址: https://gitcode.com/GitHub_Trending/qli/qlib

本文基于 Qlib 官方 Quick Start 文档，讲解如何从零安装 Qlib、准备 A 股日频数据，并用qrun一条命令自动完成「构建数据集 → 训练 LightGBM 模型 → 回测 → 结果评估」的完整量化研究闭环。读完后，你可以独立复刻该流程，理解每个配置参数的含义，并学会把自定义模型接入同样的工作流。

1. 快速上手的两个核心目标

Qlib 的 Quick Start 文档（docs/introduction/quick.rst）开篇明确了它要验证的两件事：

• 基于 Qlib，搭建一条完整的量化研究工作流非常容易，用户的想法可以快速被验证；
• 即使用公开数据加简单模型（如 LightGBM），机器学习技术在实盘量化投资中依然表现良好。

因此本文不做平台泛览，只聚焦四个环节：安装 → 准备数据 → 自动研究流程（qrun）→ 自定义模型扩展。

2. 安装 Qlib

2.1 从源码安装（官方快速上手推荐路径）

按照 docs/start/installation.rst 与 Quick Start 的说明，源码安装需要先装两个依赖再编译安装：

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

为什么要先装 numpy 和 cython？这一点可以从 setup.py 得到源码级印证：Qlib 在安装时会用 Cython 编译两个 C++ 扩展模块qlib.data._libs.rolling与qlib.data._libs.expanding（对应源文件 qlib/data/_libs/rolling.pyx 和 qlib/data/_libs/expanding.pyx），编译时include_dirs=[NUMPY_INCLUDE]直接引用了 numpy 的头文件路径。如果 numpy/cython 版本不对或缺失，python setup.py install会在扩展模块编译阶段直接失败。这两个 Cython 模块服务于滚动/扩展窗口等数据算子的底层计算，是 Qlib 数据处理层的性能基础。

安装完成后，用以下代码验证：

>>> import qlib >>> qlib.__version__

2.2 环境前提与其他方式

• 官方安装文档说明：Qlib 支持 Windows 和 Linux，推荐在 Linux 上使用，支持 Python 3；
• 除了源码安装，也可以直接pip install pyqlib获取发布版（见 docs/start/installation.rst）；
• 官方建议使用 anaconda/miniconda 管理环境，lightgbm、pytorch 等依赖用 pip 安装。

3. 准备数据：一条命令拉取 A 股日频数据集

安装完成后，运行以下命令加载并准备数据：

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

这个命令会在~/.qlib/qlib_data/cn_data下生成 Qlib 的本地数据目录（含features、calendars、instruments等子目录），后续所有配置里的provider_uri都指向它。

3.1 命令背后的实现

scripts/get_data.py 本体只有几行，它用fire把GetData类暴露为命令行接口：

import fire from qlib.tests.data import GetData if __name__ == "__main__": fire.Fire(GetData)

真正的下载逻辑在 qlib/tests/data.py 的GetData类中。qlib_data方法（qlib/tests/data.py#L153-L211）支持比 Quick Start 示例更完整的参数：

例如拉取 1 分钟频率数据可以写：python get_data.py qlib_data --target_dir ~/.qlib/qlib_data/cn_data_1min --interval 1min --region cn（同样来自qlib_data方法的 docstring 示例）。

两个实操注意点，均可在源码中确认：

1. 会清理旧数据：_unzip在delete_old=True（默认）时会先调用_delete_qlib_data（qlib/tests/data.py#L119-L151），删除目标目录下已有的features、calendars、instruments、features_cache、dataset_cache，并在命令行交互确认后才真正删除——因此不要把--target_dir指向重要目录；
2. 数据质量声明：下载过程中日志会提示该示例数据由 Yahoo Finance 采集，质量不完美；Quick Start 文档也说明该数据集由仓库内 scripts/data_collector/ 中的爬虫脚本收集公开数据生成，用户可以用同一批脚本自行重建。

4. 一条命令的量化研究流程：qrun

Qlib 提供名为qrun的命令行工具，自动执行包含构建数据集、训练模型、回测、评估在内的完整工作流。Quick Start 给出的标准操作是运行 LightGBM 示例：

cd examples # 避免在包含 qlib 源码包的目录下运行 qrun benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

注意 Quick Start 特意提醒要cd examples再运行，这是为了避免 Python 把当前目录下的qlib源码包与已安装的包混淆。Quick Start 原文写的是workflow_config_lightgbm.yaml，当前仓库中对应的实际文件是 examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml。

4.1 qrun 的调用链

qrun是安装时注册的入口脚本，在 pyproject.toml 中定义为qrun = "qlib.cli.run:run"，最终进入 qlib/cli/run.py 的workflow()函数（qlib/cli/run.py#L86-L148）。从源码看，它依次做了这几件事：

1. 模板渲染：用 Jinja2 解析 YAML，把配置中引用到的环境变量（os.environ）渲染进内容；
2. 配置合并：若配置里有BASE_CONFIG_PATH，先加载基础配置再用当前配置覆盖（update_config），方便做「基线 + 小改动」的实验配置；
3. 初始化：调用qlib.init，把实验记录器 URI 设为当前目录下的mlruns（MLflow 风格实验目录），即 qlib/cli/run.py#L138-L143；
4. 训练主流程：把task段交给task_train执行训练、生成预测并依次跑record列表中定义的分析记录器。

4.2 读懂 LightGBM 示例配置（Alpha158）

该 YAML 是理解 Qlib「声明式工作流」的最佳样本，逐段拆解如下：

数据与市场设置

qlib_init: provider_uri: "~/.qlib/qlib_data/cn_data" # 第 3 节准备的数据 region: cn market: &market csi300 # 股票池：沪深300 benchmark: &benchmark SH000300 # 基准：沪深300指数 data_handler_config: &data_handler_config start_time: 2008-01-01 end_time: 2020-08-01 fit_start_time: 2008-01-01 fit_end_time: 2014-12-31 # 数据处理器 fit 的窗口 instruments: *market

回测与策略（port_analysis_config）

port_analysis_config: &port_analysis_config strategy: class: TopkDropoutStrategy # 每日持有 score 前 topk 只，随机换掉 n_drop 只 module_path: qlib.contrib.strategy kwargs: signal: <PRED> # 用模型预测值作为交易信号 topk: 50 n_drop: 5 backtest: start_time: 2017-01-01 end_time: 2020-08-01 account: 100000000 # 初始资金 1 亿 benchmark: *benchmark exchange_kwargs: limit_threshold: 0.095 # 涨跌停判断阈值 deal_price: close # 按收盘价成交 open_cost: 0.0005 # 买入费率 0.05% close_cost: 0.0015 # 卖出费率 0.15% min_cost: 5 # 最低手续费

任务定义（task）

task: model: class: LGBModel module_path: qlib.contrib.model.gbdt kwargs: loss: mse colsample_bytree: 0.8879 learning_rate: 0.2 subsample: 0.8789 lambda_l1: 205.6999 lambda_l2: 580.9768 max_depth: 8 num_leaves: 210 num_threads: 20 dataset: class: DatasetH module_path: qlib.data.dataset kwargs: handler: class: Alpha158 # 内置 Alpha158 因子集 module_path: qlib.contrib.data.handler kwargs: *data_handler_config segments: train: [2008-01-01, 2014-12-31] valid: [2015-01-01, 2016-12-31] test: [2017-01-01, 2020-08-01] record: - class: SignalRecord # 生成预测信号 module_path: qlib.workflow.record_temp kwargs: {model: <MODEL>, dataset: <DATASET>} - class: SigAnaRecord # 预测信号分析（IC 等） module_path: qlib.workflow.record_temp kwargs: {ana_long_short: False, ann_scaler: 252} - class: PortAnaRecord # 组合回测分析 module_path: qlib.workflow.record_temp kwargs: {config: *port_analysis_config}

几个值得注意的设计点：

• class+module_path的写法让模型、数据集、记录器都是可插拔的——换成别的模型只需改这几行，这也是后面「自定义模型集成」的基础；
• <PRED>、<MODEL>、<DATASET>是 Qlib 在运行时注入的占位符，表示「前面训练产物会在这里被引用」；
• 数据段（train/valid/test）与回测窗口（2017-01-01 起）严格对齐，训练期不穿越测试期。

4.3 运行结果

qrun结束后会输出形如以下的评估结果（摘自 Quick Start 文档，为典型Forecast model(alpha)的日内交易回测结果）：

risk excess_return_without_cost mean 0.000605 std 0.005481 annualized_return 0.152373 information_ratio 1.751319 max_drawdown -0.059055 excess_return_with_cost mean 0.000410 std 0.005478 annualized_return 0.103265 information_ratio 1.187411 max_drawdown -0.075024

两行分别是不含成本与含成本的超额收益（相对 benchmark）的均值、标准差、年化收益、信息比率与最大回撤，可以直观看到交易成本（上面配置中的费率与 min_cost）对策略表现的侵蚀。工作流与qrun的更多细节参见 docs/component/workflow.rst。

5. 用代码构建等价工作流

除了「一个 YAML 跑到底」，Qlib 的第二种接口是用代码像搭积木一样构建工作流。Quick Start 建议用 jupyter 运行examples/workflow_by_code.ipynb来做组合分析与预测分数分析；当前仓库中对应的可执行脚本是 examples/workflow_by_code.py，其模块 docstring 明确说明它与qrun XXX.yaml几乎做同样的事。其主流程（examples/workflow_by_code.py#L19-L85）：

import qlib from qlib.constant import REG_CN from qlib.utils import init_instance_by_config, flatten_dict from qlib.workflow import R from qlib.workflow.record_temp import SignalRecord, PortAnaRecord, SigAnaRecord from qlib.tests.data import GetData from qlib.tests.config import CSI300_BENCH, CSI300_GBDT_TASK if __name__ == "__main__": provider_uri = "~/.qlib/qlib_data/cn_data" GetData().qlib_data(target_dir=provider_uri, region=REG_CN, exists_skip=True) qlib.init(provider_uri=provider_uri, region=REG_CN) model = init_instance_by_config(CSI300_GBDT_TASK["model"]) dataset = init_instance_by_config(CSI300_GBDT_TASK["dataset"]) # ... port_analysis_config 中显式配置 SimulatorExecutor + TopkDropoutStrategy with R.start(experiment_name="workflow"): R.log_params(**flatten_dict(CSI300_GBDT_TASK)) model.fit(dataset) R.save_objects(**{"params.pkl": model}) recorder = R.get_recorder() SignalRecord(model, dataset, recorder).generate() # 预测 SigAnaRecord(recorder).generate() # 信号分析 PortAnaRecord(recorder, port_analysis_config, "day").generate() # 回测

对照两种接口的差异，代码版多显式了两件事：一是通过 qlib/tests/config.py 中的CSI300_GBDT_TASK复用与 YAML 同构的任务字典；二是显式写出SimulatorExecutor（time_per_step: "day"）这一执行器配置——在 YAML 里它由qrun内部按 record 需求自动补全，而代码接口需要你自己声明。运行该脚本后，同样可以在mlruns目录下找到记录器产物，并做后续的图形化报告分析（见下一节）。

6. 图形化报告分析

Quick Start 的最后一步是图形化报告：用 jupyter 运行examples/workflow_by_code.ipynb（即上文脚本的 notebook 形态）后，可以得到两类分析：

• 组合分析（portfolio analysis）：累计收益、买卖持仓走势、风险分析（年化收益、最大回撤、信息比率等）；
• 预测分数分析（prediction score analysis）：模型预测信号的 IC、多空收益、自相关性等。

这些报告由 Qlib 的分析模块生成，更多图表细节可参考 docs/component/report.rst。

7. 自定义模型集成

Qlib 内置了一批模型（LightGBM、MLP等）作为Forecast Model的示例实现，例如本快速上手用到的LGBModel就在qlib.contrib.model.gbdt模块中；qlib/contrib/model/下还包含 LSTM、GRU、Transformer、CatBoost、XGBoost 等大量 PyTorch 与 GBDT 模型，examples/benchmarks/ 中每个模型目录都配有对应的workflow_config_*.yaml，可逐个替换第 4 节的task.model段来对比。

如果你有自己的模型，Qlib 提供了标准化的集成路径：只需让模型类实现fit/predict等约定接口，即可通过class+module_path的方式写进 YAML 或init_instance_by_config调用。完整指引见 docs/start/integration.rst。

8. 关键路径速查

适用前提提示：以上快速上手基于 A 股（region=cn）日频公开数据与 CSI300 股票池，属于研究演示配置；数据由公开爬虫采集，质量与覆盖度有限，生产使用应替换为自有数据源并按data_collector脚本或dump_bin流程自建数据。

【免费下载链接】qlibQlib is an AI-oriented Quant investment platform that aims to use AI tech to empower Quant Research, from exploring ideas to implementing productions. Qlib supports diverse ML modeling paradigms, including supervised learning, market dynamics modeling, and RL, and is now equipped with https://github.com/microsoft/RD-Agent to automate R&D process.项目地址: https://gitcode.com/GitHub_Trending/qli/qlib