4. 环境搭建与快速开始

在正式进入策略开发之前，先把运行环境跑通，是每一位量化工程师必须完成的第一步。Qlib 是微软开源的 AI 量化投资平台，覆盖数据管理、因子计算、模型训练、回测与组合优化等完整链路。本章将带你从零完成 Python 环境配置、Qlib 安装、数据下载、初始化配置，并运行第一个示例策略，确保后续章节的学习有一个稳定、可复现的基础。

一、核心原理：Qlib 的运行结构

理解 Qlib 的目录结构，能帮助你快速定位问题。Qlib 的运行依赖三个关键部分：

• Python 运行环境：建议使用 Python 3.8～3.12，配合 conda 或 venv 隔离依赖，避免与系统包冲突。
• Qlib 核心包：通过 pip 安装，提供 qlib 命令行工具与 Python API。
• 数据目录（provider_uri）：Qlib 不内置行情数据，需要单独下载并指定路径，所有策略都从这里读取特征与标签。

三者关系可以概括为：环境提供解释器，Qlib 提供框架，数据提供燃料。任何一环缺失，示例策略都无法运行。

二、方法流程：五步完成环境搭建

步骤 1：创建并激活 Python 环境

conda create -n qlib python=3.10 -y
conda activate qlib
python -V
# 输出示例：Python 3.10.13

步骤 2：安装 Qlib

pip install pyqlib -i https://pypi.tuna.tsinghua.edu.cn/simple
python -c "import qlib; print(qlib.__version__)"
# 输出示例：0.9.6

如果后续需要运行深度学习模型（如 LSTM、Transformer），可额外安装 pip install torch。基础示例策略仅依赖 numpy、pandas，无需 GPU。

步骤 3：下载示例数据

# 下载中国 A 股日频数据到 ~/.qlib/qlib_data/cn_data
python -m qlib.run.get_data qlib_data \
  --target_dir ~/.qlib/qlib_data/cn_data \
  --region cn \
  --interval 1d \
  --delete_cache

下载完成后，目录中会出现 calendars、instruments、features 三个子目录，分别保存交易日历、股票池和特征数据。

步骤 4：初始化 Qlib

import qlib
from qlib.constant import REG_CN

qlib.init(provider_uri="~/.qlib/qlib_data/cn_data", region=REG_CN)
print("Qlib init success")

qlib.init 会加载日历与股票池，并注册数据提供者。若路径错误，会抛出 ValueError: Please check the provider_uri，此时应检查数据是否下载完整。

步骤 5：运行第一个示例策略

cd examples
qrun benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

该命令会依次执行数据处理、模型训练、预测与回测，最终在 mlruns 目录生成实验记录，并在终端打印 IC、年化收益、最大回撤等指标。

三、关键配置与参数清单

四、案例场景：从零到一次完整回测

假设你是一名刚接触量化的开发者，希望验证 LightGBM + Alpha158 因子在沪深 300 上的表现。完整流程如下：

1. 激活 qlib 环境，确认 import qlib 无报错。
2. 下载 cn_data 数据，确认 features 目录下存在 sh600000 等文件。
3. 执行 qrun 命令，观察日志中 dataset、model、backtest 各阶段是否依次完成。
4. 打开 mlruns 目录，查看生成的指标文件与预测结果。

五、误区与复盘

• 误区一：直接 pip install qlib。正确包名是 pyqlib，安装错误包会导致导入失败。
• 误区二：忽略数据下载。Qlib 不含数据，未下载就初始化会报路径错误。
• 误区三：在系统 Python 中安装。依赖冲突会污染全局环境，务必使用虚拟环境。
• 误区四：路径使用相对路径。建议统一使用 ~/.qlib/qlib_data/cn_data 或绝对路径，避免切换目录后失效。