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 是一个量化研究框架，核心流程是：

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

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

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

4. 本项目目录说明

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

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

在项目根目录执行：

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

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

where python
where qrun

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

6. 数据下载到指定目录

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

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

检查目录：

Get-ChildItem .\data\cn_data

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

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

运行命令：

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

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

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

这条命令本质上是：

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

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

1. 命令拆解

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

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

---

2. 它实际执行了什么（顺序）
   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)。

---

3. 这份 YAML 里你最需要懂的字段
   配置文件：

   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：股票池和基准指数。
• 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. 你现在可以这样继续用

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

8. 运行结果怎么看

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

总览

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

1. 8b9337b5a2974b1f8ef0f0afae3e84e6
2. a4f6bb393e36466eb627a755fb5280c4
3. e9ee6ac36de041e7906c8e87ce6980f4
4. f649264b25e147a3b7cc63a126b4488f
5. 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（含交易成本） 通常以"含成本"结果更接近真实交易表现。 ## 如何对每个环节进行优化 **推荐路线** 你现在最适合按"由浅到深"做个性化： 1. 先做配置级个性化（不改源码） 在这个文件基础上复制一份并改参数： \[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`） 2. 再做特征级个性化 先用官方示例理解特征构造，再替换成你的版本： \[features_sample.py\](C:/Users/Administrator/Desktop/AlphaForge/qlib example/qlib/examples/benchmarks/LightGBM/features_sample.py) 3. 再做模型级个性化 先在 YAML 里切换模型类（不写代码），再考虑自己写模型类并通过 `module_path` 挂载。 4. 最后做策略级个性化 从"预测分数 -\> 下单规则"这层优化，比如： * 调整持仓数量和换手频率 * 加入更严格的成本/滑点假设 * 改再平衡周期