Qlib Docker 部署指南：从零构建可运行的量化研究容器

Qlib Docker 部署指南：从零构建可运行的量化研究容器

【免费下载链接】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

给新同事配环境时，我在干净的 Linux 机器上做了一次 Qlib Docker 部署：用仓库根目录的 Dockerfile 构建镜像，容器内下载 A 股日线数据包并完整跑通 LightGBM 基准回测，全程没有手动处理任何依赖冲突。Qlib 是面向 AI 的量化投资平台，覆盖数据加载、因子建模、策略回测的完整研究链路，容器化让这套链路在任何机器上都能复现。

Docker 方案适用的边界

如果你的目标是多人、多机器共享一套可复现的研究环境，镜像方式比手工 pip install 更稳：仓库里的 Dockerfile 把 numpy、pandas、scikit-learn 等依赖都固定了版本，每个人拿到的环境完全一致。两种情况不必上容器：单机只跑一次脚本，直接python -m pip install pyqlib即可；正在开发 qlib 源码、需要频繁重编译的贡献者，则应直接选用下文的 nightly 构建方式。

启动前检查：构建 Qlib Docker 镜像的三项确认

先执行这条命令确认 Docker 守护进程可用：

docker --version && docker run hello-world

跑不通就先修好 Docker 本身，别急着构建镜像。剩下两项做目检：

• 磁盘空间不低于 20GB。镜像本身加上 A 股数据包占用不小，回测报告还要写盘。
• 网络畅通。构建过程有两处大下载：pip 安装 Qlib 及其依赖、容器内拉取行情数据，任一环节断网都会卡住。
• 仓库根目录存在 Dockerfile 和 build_docker_image.sh，后者是下一节构建流程的入口。

全局总览：四步的依赖顺序

镜像构建与数据下载相互独立，但回测必须在数据就位之后执行，下面按这个顺序展开。

拉取 Qlib 源码并构建 qlib_image

用仓库自带脚本一次构建

git clone https://gitcode.com/GitHub_Trending/qli/qlib cd qlib bash build_docker_image.sh

脚本有两个交互问题：是否构建 nightly 版（默认 no，即 stable 稳定版）、是否把镜像推送到 Docker Hub（默认 no）。选择推送前，先把脚本顶部的docker_user变量改成自己的 Docker Hub 用户名，否则登录与打标步骤无法完成。

IS_STABLE 构建参数决定装的是哪种 Qlib

不想走交互脚本时，直接用 docker build 命令：

docker build -t qlib_image -f ./Dockerfile . docker build --build-arg IS_STABLE=no -t qlib_image:nightly -f ./Dockerfile .

两行命令的差别在安装的 Qlib 版本：默认IS_STABLE=yes时执行pip install pyqlib，装的是 PyPI 发布版；IS_STABLE=no则用仓库源码python setup.py install现场编译，适合贡献者验证未发布的改动。Dockerfile 基于 miniconda3 镜像，创建 python 3.8 的 conda 环境，并固定 numpy 1.23.5、pandas 1.5.3 等版本，常见的版本冲突问题由它直接消化。

启动 Qlib 容器并下载 A 股日线数据

镜像构建完成后进入交互式 shell：

docker run -it --name qlib_env -v $(pwd):/qlib -p 8888:8888 qlib_image /bin/bash

-v把本地源码目录挂到容器内/qlib，examples 下的配置在容器里即可直接引用；-p 8888:8888为之后启动 Jupyter 预留端口。

容器内先下载数据：

python scripts/get_data.py qlib_data --name qlib_data_simple --target_dir ~/.qlib/qlib_data/cn_data --interval 1d --region cn

qlib_data_simple是小数据集，几分钟即可下完；要完整数据集就去掉--name参数（默认qlib_data）。--region cn/us切换 A 股与美股市场。注意脚本默认delete_old=True：对已存在的 target_dir 会先删除再重新下载，想保留旧数据就追加--exists_skip True。完整参数说明见 scripts/get_data.py。

结果验收：用一次 LightGBM 基准回测验证

验收标准就一条：完整回测能复现。执行：

python qlib/cli/run.py examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

这条命令基于 Alpha158 特征集，完成 LightGBM 模型训练、预测生成和 TopkDropout 策略回测的全流程。满足以下三条即说明环境就绪：

• ✅ 命令输出 IC、年化收益、最大回撤等评估指标，过程无中断。
• ✅ 实验 recorder 目录中生成对应的回测报告，文件结构完整。
• ✅ 可选：容器内执行jupyter notebook --ip=0.0.0.0能启动 notebook，宿主机 8888 端口可访问，examples/ 下的示例脚本可直接打开。

调优与排障：镜像构建与容器使用的高频问题

构建失败与构建变慢

构建中 pip install 超时，先在宿主机配置国内 pip 镜像源（pip config global index-url指向国内镜像），再重新构建即可，不需要改动 Dockerfile。反复构建时依赖镜像缓存层：只改数据不重装依赖，就不必重跑 docker build。

容器复用、资源限制与数据持久化

容器停止后不必每次重新 docker run，直接恢复原容器：

docker start -i -a qlib_env

宿主机资源紧张时，在 docker run 后追加--cpus 4 --memory 8g限制容器用量。数据包若希望跨容器保留，启动时把数据目录挂到宿主机：

docker run -it --name qlib_env -v $(pwd):/qlib \ -v ~/qlib_data:/root/.qlib/qlib_data -p 8888:8888 qlib_image /bin/bash

容器默认用户是 root，内部数据路径为/root/.qlib/qlib_data，挂出后新数据下载与回测读取都走宿主机目录。以上命令参数组合的出处见 docs/developer/how_to_build_image.rst。

这套方案适合谁与后续动作

需要稳定 Qlib 研究环境、多人协作或多版本并行验证的读者，可直接照此镜像化。 环境就绪后，可换更高频数据包（--interval 1min）扩展到日内场景，或把 examples/benchmarks/ 里的基准配置换成自己的策略配置开始回测。

【免费下载链接】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