QMLDocker：把整个量子机器学习实验室装进一个容器

一、痛点场景：一个 Mac M1 用户的心路历程

如果你是一位对量子机器学习（QML）感兴趣的研究者或学生，你一定遇到过这样的困境：想要同时运行 Qiskit 做电路模拟、PennyLane 做量子微分编程、PaddlePaddle 做参数化量子电路训练，但每装一个库都要和 CUDA 版本、Python 版本、M1 芯片兼容性问题搏斗一番。

BoltzmannEntropy 就是这样一个"受够了"的开发者。他试图在搭载 M1 Max 芯片的 MacBook Pro 上同时安装 Qiskit 和 Paddle-Quantum，折腾了数周未果。最终他决定换一个思路：与其让环境去迁就硬件，不如把整个开发环境打包成一个 Docker 镜像，随时随地开箱即用。 QMLDocker 就这样诞生了。

二、项目背景：量子计算民主化的轻量化尝试

QMLDocker 由 GitHub 用户 BoltzmannEntropy 于 2023 年 1 月创建，最后更新于 2026 年 2 月，是一个以 GPL-3.0 开源协议发布的 Docker 容器项目。虽然目前仅有 46 颗星、18 个 Fork，但它在量子计算爱好者和 QML 初学者群体中具有相当的实用价值——无需在本地逐个安装十几个依赖库，一个镜像搞定所有。

项目的核心定位是：为量子计算初学者提供一个开箱即用的统一实验环境。作者在 README 中明确指出，目标用户是"刚接触量子计算的学生和研究人员"。

三、技术解析：Docker 构建的工程细节

3.1 基础镜像选型

项目基于 NVIDIA 官方 TensorRT 镜像 nvcr.io/nvidia/tensorrt:21.07-py3 构建，这意味着：

• 预装了 CUDA 11.1 和 cuDNN，无需额外配置 GPU 环境
• 包含 TensorRT 推理优化工具，适合部署量子-经典混合推理任务
• 系统层为 Ubuntu 18.04，稳定性优先

3.2 完整的量子计算生态

容器内预装了几乎所有主流量子计算框架：

框架	用途
Qiskit	IBM 开源的量子电路编程框架
Cirq	Google 开发的量子算法研究框架
PennyLane	量子机器学习专用框架，支持自动微分
QuTiP	量子光学和开放量子系统模拟
PaddlePaddle / Paddle-Quantum	百度开源的量子机器学习框架
TorchQuantum	基于 PyTorch 的量子神经网络库
Tequila	通用量子变分算法框架

3.3 不仅仅是 Python

除了量子计算库，镜像还包含：

• CMake 3.20.1：用于编译 C++ 量子模拟器
• Eigen3 + Quantum++ (Q++)：C++ 量子计算库生态
• 完整 LaTeX 发行版：方便撰写 QML 论文
• ONNX Runtime：模型互操作性支持
• SSH 服务器：支持远程连接开发

3.4 Jupyter Notebook 作为 Web UI

容器通过 Jupyter Notebook 提供交互式 Web 界面，端口映射为 8077:7842，默认密码为 mk2==2km。随镜像提供了一个 25KB 的 quantum-libs.ipynb 示例 notebook，演示主流 QML 库的导入和基本用法。

四、快速上手：从零构建到运行

准备工作

# 1. 安装 Docker Desktop（macOS/Windows）或 Docker Engine（Linux）
docker --version

# 2. 克隆仓库
git clone https://github.com/BoltzmannEntropy/QMLDocker.git
cd QMLDocker

构建镜像（约需 15-30 分钟，首次构建）

# 标准构建
docker build -t quantdoc-no-avx .

# 或直接使用提供的脚本
chmod +x build.sh
./build.sh

⚠️ M1/M2 Mac 用户注意：必须显式指定 --platform linux/amd64，因为部分量子库尚未提供 ARM64 原生支持。

运行容器

# 标准运行
docker run --platform linux/amd64 -it \
  --memory="10g" \
  -p 8077:7842 \
  quantdoc-no-avx:latest bash

# 或使用 run.sh（需先编辑共享目录路径）
./run.sh

容器启动后，通过浏览器访问 http://localhost:8077，输入密码 mk2==2km 即可进入 Jupyter Notebook 环境。

预置的 QML 示例仓库

镜像 /home/qmuser 目录下预克隆了 12 个 QML 相关仓库：

• PaddlePaddle/Quantum — 百度量子计算教程
• mit-han-lab/torchquantum — 清华唐虎杰团队
• PennyLaneAI/qml — PennyLane 官方教程集
• Hands-On-Quantum-Machine-Learning-With-Python-Vol-1 等

五、争议与局限

5.1 安全性隐患

项目最大的争议点在于默认凭证公开化：Jupyter 密码 mk2==2km 和 SSH 私钥直接嵌入 Docker 镜像的构建产物中，任何能访问该镜像的人都可以提取这些凭证。生产环境使用前必须：

• 重新生成 SSH 密钥对
• 修改 Jupyter 密码或删除 jupyter_notebook_config.py 中的预设密码

5.2 镜像体积与更新滞后

由于集成了大量库，镜像体积较大（预计 15-20GB），在国内网络环境下构建和拉取都面临挑战。基础镜像 tensorrt:21.07 发布于 2021 年 7 月，其中 CUDA 11.1 版本已不是最新，长期未更新的基础镜像可能导致安全漏洞。

5.3 非真正的"零配置"

虽然 Docker 屏蔽了安装过程，但对于没有 Docker 基础的初学者而言，构建过程中如果遇到网络超时、磁盘空间不足、M1 芯片兼容性等问题，依然需要一定的排查能力。"一键启动"的体验并不完美。

六、行业意义：QML 工具链碎片化的缩影

QMLDocker 折射出当前量子机器学习领域的一个核心矛盾：工具链的高度碎片化。从 2019 年 Qiskit、Tequila 分别独立发展，到 2020 年 PennyLane 异军突起，再到 2021 年后百度 Paddle-Quantum、亚马逊 Braket 相继入局，QML 研究者往往需要在 5-10 个框架之间来回切换，每个框架的安装方式、API 风格、硬件要求各不相同。

QMLDocker 的思路代表了一种务实的解决方案：不追求统一框架，而是提供"工具超市"式的共存环境。研究者可以根据具体任务自由选择 Qiskit 模拟器、PennyLane 自动微分、或 Paddle-Quantum 的参数化电路模块，而无需反复重装环境。

这种"容器优先"的理念也呼应了量子云计算平台（IBM Quantum Platform、AWS Braket、Azure Quantum）的趋势——未来 QML 研究者将越来越多地在云端容器环境中工作，而非本地机器。

七、总结

QMLDocker 是一个务实、有针对性的 Docker 工具盘，适合以下场景：

场景	推荐度
QML 初学者搭建实验环境	⭐⭐⭐⭐⭐
研究者快速对比不同量子框架	⭐⭐⭐⭐
M1/M2 Mac 用户运行 Qiskit/Paddle-Quantum	⭐⭐⭐⭐
生产环境部署 QML 应用	⭐⭐（需修复安全配置）
企业级 QML 研发平台	⭐⭐（建议基于此镜像二次定制）

如果你厌倦了在量子库的安装泥潭中挣扎，QMLDocker 值得一试——毕竟，把时间花在量子算法研究上，比折腾环境配置要有价值得多。

---

本报告基于 GitHub 公开信息生成，分析时间：2026-08-13
项目地址：https://github.com/BoltzmannEntropy/QMLDocker