Qlib上手指南 - 技术栈

Qlib 新手上手指南（Windows，Python 3.8）

面向第一次接触 Qlib 的同学。本文从 0 到 1 带你完成：环境搭建、数据准备、首次运行、结果理解与后续学习路径。

1. 这份文档适合谁

第一次接触 Qlib
想在本机先跑通一个可复现实验
使用 Windows + Conda

2. 你将学到什么

完成本文后，你可以独立完成：

创建并固定一个可复用环境（qlib_env）
下载并管理本地 Qlib 数据（data/cn_data）
跑通第一个 LightGBM 基线实验
看懂核心评估指标（IC、年化收益、回撤等）

3. Qlib 是什么（1 分钟认识）

Qlib 是一个量化研究框架，核心流程是：

准备数据
生成特征/标签
训练模型
回测策略
输出分析报告

你可以把它理解成一个把"数据、模型、回测、评估"串起来的标准化工具链。

在真正的量化实操中，上述的每个部分都可以单个拿出来优化。Qlib的核心优势是把这个流程穿起来了，然后我们可以着重优化其中的一个，并且整体跑通并不影响。

4. 本项目目录说明

requirements.txt：本项目依赖
qlib/：Qlib 源码与官方示例
data/cn_data：本地数据目录（本文指定，如果不指定下载目录，会下载到默认的C盘）
qlib/examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158_local.yaml：本地可运行配置

5. 环境搭建（可复制命令）

在项目根目录执行：

powershell 复制代码

cd "C:\Users\Administrator\Desktop\AlphaForge\qlib example"
conda create -n qlib_env python=3.8 -y
conda activate qlib_env
python -m pip install -U pip setuptools wheel
python -m pip install -r requirements.txt

安装后做一次一致性检查：

powershell 复制代码

where python
where qrun

两者都应指向 C:\ProgramData\Anaconda3\envs\qlib_env\...。

6. 数据下载到指定目录

将数据下载到项目内 data/cn_data：

powershell 复制代码

python -m qlib.cli.data qlib_data --target_dir .\data\cn_data --region cn

检查目录：

powershell 复制代码

Get-ChildItem .\data\cn_data

应至少包含：calendars、features、instruments。

7. 第一次运行（已验证可跑通）

运行命令：

powershell 复制代码

qrun qlib/examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158_local.yaml

这是当前项目里已经验证可跑通的一条基线命令。

qlib中使用的都是yaml命令。yaml命令的讲解如下：

这条命令本质上是：

用一个 YAML 配置文件，自动完成 Qlib 的"初始化 -> 训练 -> 预测分析 -> 回测分析"。

powershell 复制代码

qrun qlib/examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158_local.yaml

命令拆解

qrun：Qlib 的命令行入口。
.../workflow_config_lightgbm_Alpha158_local.yaml：实验配置文件，定义数据路径、模型、训练区间、回测参数等。

qrun 对应实现入口在 $run.py$ (C:/Users/Administrator/Desktop/AlphaForge/qlib example/qlib/qlib/cli/run.py)。

它实际执行了什么（顺序）
1. 读取 YAML（支持 Jinja 模板变量）。
2. 解析配置并初始化 qlib.init(...)（这里会读取 qlib_init.provider_uri）。
3. 构建模型对象（LGBModel）。
4. 构建数据集对象（DatasetH + Alpha158 handler）。
5. 训练模型（fit）。
6. 执行 record 列表中的分析记录器（预测分析、回测分析）。
7. 把结果写入 mlruns/（实验记录）。

训练主流程在 $trainer.py$ (C:/Users/Administrator/Desktop/AlphaForge/qlib example/qlib/qlib/model/trainer.py)。

这份 YAML 里你最需要懂的字段
配置文件：
$workflow_config_lightgbm_Alpha158_local.yaml$ (C:/Users/Administrator/Desktop/AlphaForge/qlib example/qlib/examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158_local.yaml)

qlib_init.provider_uri：数据目录（你现在是 .../data/cn_data）。
market / benchmark：股票池和基准指数。
data_handler_config：数据时间区间、训练拟合区间。
task.model：模型类型与超参数（这里是 LightGBM）。
task.dataset：数据集构造方式（训练/验证/测试切分）。
task.record：要生成哪些报告与回测结果。

4. YAML 里两个你会经常见到的语法

&name 和 *name：锚点/引用，避免重复写配置。
例如 market: &market csi300，后面 instruments: *market。
<MODEL>、<DATASET>：占位符，训练后会被真实对象替换再传给记录器。

5. 结果会保存到哪里

默认在项目根目录的 mlruns/。

每次运行会创建一个新的 run，里面有参数、指标、预测与回测产物。

6. 你现在可以这样继续用

powershell 复制代码

conda activate qlib_env
qrun qlib/examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158_local.yaml

8. 运行结果怎么看

你首先要找到每次运行的输出在哪。应该在根目录的mlruns下，其中一个长数字文件夹中，这个长数字代表着模型代号，下面的每个文件夹代表着每次的运行。

总览

在同一个 experiment 下共有 5 次 run（目录：mlruns/918039572779910683）：

8b9337b5a2974b1f8ef0f0afae3e84e6
a4f6bb393e36466eb627a755fb5280c4
e9ee6ac36de041e7906c8e87ce6980f4
f649264b25e147a3b7cc63a126b4488f
e44ad02a76e747f7bf78e93ab490389e

第 5 次（成功 run）

run id：e44ad02a76e747f7bf78e93ab490389e

路径：

$成功 run 目录$ (C:/Users/Administrator/Desktop/AlphaForge/qlib example/mlruns/918039572779910683/e44ad02a76e747f7bf78e93ab490389e)

状态：status=3（成功）

它包含完整结果：

artifacts/config：本次运行配置快照
artifacts/task：任务配置
artifacts/dataset：数据集对象
artifacts/params.pkl：训练好的模型参数对象
artifacts/pred.pkl：预测结果
artifacts/label.pkl：标签数据
artifacts/sig_analysis/：信号分析（含 ic.pkl, ric.pkl）
artifacts/portfolio_analysis/：回测分析（收益、仓位、指标等 pkl）

关键指标（来自 metrics/）：

IC = 0.04680587323833807
ICIR = 0.3815683918932705
Rank IC = 0.049049290457489736
Rank ICIR = 0.406748756941287
1day.excess_return_without_cost.annualized_return = 0.1260289794931573
1day.excess_return_without_cost.information_ratio = 1.4285742844475509
1day.excess_return_without_cost.max_drawdown = -0.07230960299230482
1day.excess_return_with_cost.annualized_return = 0.08065424981584728
1day.excess_return_with_cost.information_ratio = 0.9144858856010761
1day.excess_return_with_cost.max_drawdown = -0.08608280684938441

重点看这些输出：

IC / Rank IC：信号与未来收益的相关性，越高通常越好
annualized_return：年化收益
information_ratio：风险调整后收益，越高越稳
max_drawdown：最大回撤，绝对值越小越稳

你会看到三类结果：

benchmark return（基准）
excess return without cost（不含交易成本）
excess return with cost（含交易成本）

通常以"含成本"结果更接近真实交易表现。

如何对每个环节进行优化

推荐路线

你现在最适合按"由浅到深"做个性化：

先做配置级个性化（不改源码）
在这个文件基础上复制一份并改参数：
$workflow_config_lightgbm_Alpha158_local.yaml$ (C:/Users/Administrator/Desktop/AlphaForge/qlib example/qlib/examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158_local.yaml)
优先改这几块：

market / benchmark（如 csi300 改 csi500）
data_handler_config（训练/验证/测试时间）
model.kwargs（学习率、树深、叶子数）
port_analysis_config.strategy.kwargs（topk、n_drop）
交易成本（open_cost、close_cost、min_cost）

再做特征级个性化

先用官方示例理解特征构造，再替换成你的版本：

$features_sample.py$ (C:/Users/Administrator/Desktop/AlphaForge/qlib example/qlib/examples/benchmarks/LightGBM/features_sample.py)
再做模型级个性化

先在 YAML 里切换模型类（不写代码），再考虑自己写模型类并通过 module_path 挂载。
最后做策略级个性化

从"预测分数 -> 下单规则"这层优化，比如：

调整持仓数量和换手频率
加入更严格的成本/滑点假设
改再平衡周期