使用 Docker 构建与运行 Recommenders 多环境镜像:CPU / PySpark / GPU 实战指南
使用 Docker 构建与运行 Recommenders 多环境镜像:CPU / PySpark / GPU 实战指南
本指南以 tools/docker/README.md 为骨架,系统讲解如何利用仓库根目录下的 Dockerfile 构建集成了全部依赖与代码的 Recommenders 容器镜像,并覆盖 CPU、PySpark、GPU、GPU+PySpark 四种运行环境的构建与启动命令、全部构建参数的含义与取值、容器内运行单元测试的方法,以及与 VS Code Dev Container 和 CI 测试工作流的联动。读完本文,你将能够独立搭建可运行示例 Notebook 或执行仓库单元测试的 Docker 环境,并根据硬件条件灵活切换计算后端。
镜像的用途:一份 Dockerfile,服务三类场景
该 Dockerfile 构建出的镜像内置了运行本仓库示例 Notebook(examples)与单元测试(tests)所需的全部依赖和代码,在仓库中被用于三个场景:
- VS Code Dev Container:.devcontainer/devcontainer.json 以
deps阶段为目标构建开发容器,帮助开发者快速获得可编码、可调试、可测试的隔离环境(参见 SETUP.md 的 "Setup for Developers" 一节); - CI 测试工作流:.github/workflows 下的测试流程借助该镜像创建 CPU / GPU / Spark 测试环境(参见 tests/README.md);
- 本地运行示例:按本文命令构建镜像后,容器内默认启动 Jupyter Notebook,可直接体验 examples 中的推荐算法 Notebook。
镜像采用 Docker 官方推荐的 多阶段构建(multistage builds),使同一份构建脚本可以产出面向不同计算后端的镜像。容器启动后,可通过 http://localhost:8888 访问 Jupyter Notebook。
多阶段构建架构:Compute → Dependencies → Final
从 Dockerfile 的源码结构可以看出,镜像由三个连续阶段组成:
| 阶段 | Dockerfile 位置 | 作用 |
|---|---|---|
| Compute 阶段 | L20 CPU 基础镜像、L30 GPU 基础镜像 | 通过 ARG COMPUTE 选择 CPU(buildpack-deps:24.04)或 GPU(nvidia/cuda:13.2.1-devel-ubuntu24.04)基础镜像,两者均固定了镜像摘要(sha256)以保证可复现性 |
| Dependencies 阶段 | L38-L103 | 安装 curl/git/unzip/zip、通过 SDKMAN! 安装 OpenJDK(Spark 场景)、安装 uv,并用 uv 创建 Python 虚拟环境(默认 /root/.venvs/Recommenders);Dev Container 因需要可编辑安装而基于此阶段构建 |
| Final 阶段 | L110-L149 | 复制 Recommenders 源码、安装包与 extras 依赖、配置 Jupyter 内核,并声明默认启动命令 |
几个值得注意的底层细节(均可从 Dockerfile 源码验证):
- SDKMAN! 管理 JDK:当
EXTRAS中包含spark时,Dockerfile 通过 SDKMAN! 安装并切换至 OpenJDK 21.0.2-open(L83-L87),并在容器启动命令中重新sourceSDKMAN 初始化脚本以保证JAVA_HOME等环境就绪; - uv 管理 Python 依赖:虚拟环境由
uv venv --python ${PYTHON_VERSION}创建(L102-L103),并设置了UV_LINK_MODE=copy、UV_HTTP_TIMEOUT=300等环境变量,pip 安装通过uv pip install完成; - 安装重试机制:Final 阶段对
uv pip install做了最多 5 次、每次间隔 5 秒的重试循环(L128-L140),提升网络不稳定时的构建成功率; - 默认启动 Jupyter:容器
CMD激活虚拟环境后以--ip=0.0.0.0 --port=8888 --no-browser --allow-root启动 Jupyter Notebook,并允许任意来源访问、不要求 token(L149),同时将Recommenders注册为默认 Jupyter 内核(L142-L146)。
构建参数(Build Arguments)详解
与 Docker 内置的 ENV 构建参数类似,以下参数均通过 docker build 命令的 --build-arg 指定。其中前五个是 tools/docker/README.md 明确列出的核心参数:
| 构建参数 | 说明 | 默认值 |
|---|---|---|
COMPUTE |
计算后端,可选 cpu、gpu |
cpu |
EXTRAS |
附加依赖,可选 dev、gpu、spark,可组合,如 [gpu,spark] |
空(无 extras) |
GIT_REF |
要安装的 Recommenders 的 Git 引用,如 main、staging;空值表示以可编辑方式安装当前本地克隆 |
main |
JDK_VERSION |
使用的 OpenJDK 版本 | >=21 |
PYTHON_VERSION |
使用的 Python 版本 | 3.11 |
RECO_DIR |
当 GIT_REF 为空时,容器中 Recommenders 副本的存放路径 |
/root/Recommenders |
此外,Dockerfile 中还有若干内部构建参数值得了解:RECO_VENV_DIR(虚拟环境路径,默认 /root/.venvs/Recommenders)、VM_PROXY_CERTIFICATE(HTTPS 代理 CA 证书内容,非空时会写入系统证书库并执行 update-ca-certificates)、VM_PIP_INDEX_URL(自定义 PyPI 镜像源,默认使用官方 PyPI)、UV_INSECURE_HOST(uv 下载时信任的非安全主机)。
关于 EXTRAS 的具体依赖内容,可在 setup.py 的 extras_require 中核实:dev 包含 black、pytest、pytest-cov、pytest-mock;gpu 包含 tensorflow、torch、nvidia-ml-py、tf-slim 等;spark 包含 pyspark 与 pyarrow。需要注意的是,README 文档化的 JDK_VERSION 参数在当前版本 Dockerfile 中并未直接引用,实际镜像构建时安装的是固定版本 OpenJDK 21.0.2-open,若你依赖该参数做版本定制,需以 Dockerfile 实际实现为准。
四种环境的构建与运行命令
以下命令均应在仓库根目录下执行(构建上下文为仓库根目录)。四种环境共用相同的 docker run 形态:将本仓库 examples 目录挂载到容器 /root/examples,映射 8888 端口,并以 -d 后台运行。
CPU 环境
docker build -t recommenders:cpu .
docker run -v ../../examples:/root/examples -p 8888:8888 -d recommenders:cpu
默认 COMPUTE=cpu、无 extras,适合运行纯 CPU 的模型与 Notebook(如 SAR、surprise 等)。
PySpark 环境
docker build -t recommenders:pyspark --build-arg EXTRAS=[spark] .
docker run -v ../../examples:/root/examples -p 8888:8888 -d recommenders:pyspark
通过 EXTRAS=[spark] 安装 PySpark 依赖,同时 Dockerfile 会自动通过 SDKMAN! 安装 OpenJDK,满足 Spark 运行前提,可运行如 als_movielens.ipynb 等 Spark 模型 Notebook。
GPU 环境
docker build -t recommenders:gpu --build-arg COMPUTE=gpu .
docker run --runtime=nvidia -v ../../examples:/root/examples -p 8888:8888 -d recommenders:gpu
GPU 镜像基于 nvidia/cuda 官方镜像构建,运行依赖宿主机的 NVIDIA 容器运行时(--runtime=nvidia)。在采用新版 NVIDIA Container Toolkit 的宿主机上,也可等价使用 --gpus all 参数。
GPU + PySpark 环境
docker build -t recommenders:gpu-pyspark --build-arg COMPUTE=gpu --build-arg EXTRAS=[gpu,spark] .
docker run --runtime=nvidia -v ../../examples:/root/examples -p 8888:8888 -d recommenders:gpu-pyspark
同时启用 GPU 计算与 Spark 依赖,适合需要 GPU 训练同时又要读写 Spark 数据源的场景。
挂载说明:命令中的
../../examples是相对于tools/docker目录的路径,等价于仓库根目录下的 examples。若容器内挂载了/root/examples,则直接运行其中 Notebook 即可。
进阶构建:指定 Git 引用与 Python 版本
除默认的 main 分支安装外,还可灵活组合构建参数:
- 安装 Python 3.10 + staging 分支的 Recommenders:
docker build -t recommenders:staging --build-arg GIT_REF=staging --build-arg PYTHON_VERSION=3.10 .
GIT_REF=staging 时,Final 阶段会执行 uv pip install recommenders${EXTRAS} @ git+https://github.com/recommenders-team/recommenders@staging,即直接从 GitHub 拉取指定引用安装。
- 以可编辑方式安装当前本地克隆,并附带 dev 依赖:
# 先进入 Recommenders 仓库根目录,将本地克隆拷贝进镜像
cd ../../
docker build -t recommenders:dev --build-arg GIT_REF= --build-arg EXTRAS=[dev] -f tools/docker/Dockerfile .
当 GIT_REF 为空时,镜像会直接 COPY ./ 当前目录并执行 uv pip install "recommenders[dev] @ ." 的可编辑安装,容器内的代码与本地保持同步,便于开发迭代。
- 查看构建详细进度:在
docker build命令中附加--progress=plain即可输出完整的构建日志。
在容器内运行单元测试
构建好镜像后,可以直接在容器中执行仓库的单元测试。测试命令中的 marker 过滤表达式 -m "not spark and not gpu and not notebooks and not experimental" 用于排除需要 Spark、GPU、Notebook 执行环境及实验性功能的用例,仅运行纯 CPU 的单元测试。
- 使用
recommenders:cpu镜像:该镜像仅安装了 recommenders 包本身(不含测试依赖与仓库全量代码),因此需先临时补装 pytest 相关工具并克隆测试代码:
docker run -it recommenders:cpu bash -c 'uv pip install pytest pytest-cov pytest-mock; \
apt-get install -y git; \
git clone https://github.com/recommenders-team/recommenders.git; \
cd Recommenders; \
pytest tests/unit -m "not spark and not gpu and not notebooks and not experimental"'
- 使用
recommenders:dev镜像:该镜像内含本地仓库完整副本(含 tests 目录)与dev依赖,可直接运行:
docker run -it recommenders:dev bash -c 'cd Recommenders; \
pytest tests/unit -m "not spark and not gpu and not notebooks and not experimental"'
关于测试的分类与标记体系(spark、gpu、notebooks、experimental 等),可进一步阅读 tests/README.md;测试分组定义见 tests/test_groups.yml。
与 Dev Container 及 CI 工作流的联动
这份 Dockerfile 的价值不止于本地手动构建,它同时是开发环境与自动化测试环境的"单一事实来源":
- VS Code Dev Container:.devcontainer/devcontainer.json 以
deps阶段为目标("target": "deps"),传入COMPUTE=cpu、PYTHON_VERSION=3.11,并在容器创建后通过postCreateCommand执行uv pip install -e .[dev,spark],配合 VS Code 的 Python 插件、black/isort/pylint 等扩展,即可获得开箱即用的开发环境;开发流程详见 SETUP.md; - CI 测试工作流:self-hosted-runner.yml 中可以看到
docker build --build-arg COMPUTE='${compute}' --build-arg EXTRAS='${extras}'的调用,随后docker run --rm --gpus all或docker run --rm在容器内执行对应测试组(L122-L149);compshare-vm.yml 则按需分配 VM 后复用同一套 Docker 构建逻辑。
因此,无论你是在本地开发、在 CI 中回归测试,还是只想快速跑通示例 Notebook,都可以从这一份 Dockerfile 出发,获得行为一致的运行环境。
常见问题与使用建议
- 镜像体积与构建速度:Dockerfile 大量使用了 BuildKit 的缓存挂载(
--mount=type=cache,分别作用于 apt 缓存与 uv 缓存目录),重复构建时可显著提速;如需观察进度可使用--progress=plain; - GPU 不可用:请确认宿主机已安装 NVIDIA 驱动与 NVIDIA Container Toolkit,且运行时参数与驱动版本匹配;
- 网络受限环境:可通过
VM_PIP_INDEX_URL指定内网 PyPI 镜像源,通过VM_PROXY_CERTIFICATE注入代理 CA 证书,这两个参数在 Dockerfile 中均有原生支持; - 端口占用:若
8888被占用,可将-p映射改为其他宿主机端口,例如-p 8889:8888; - 开发调试:优先使用 Dev Container 方案(见 SETUP.md),容器内代码与本地克隆保持同步,可避免每次改动都重新构建镜像。