Cresset：一个模板，搞定所有训练

---

简要说明

一种基于 Docker Compose 的新型 MLOps 系统，用于深度学习开发，旨在为深度学习从业者提供可复现且易于使用的交互式开发环境。 希望此处介绍的方法能够成为学术界和工业界的最佳实践。

入门视频（英文）

在新主机上安装

如果您是首次使用该项目，请按照以下步骤操作：

1. 安装适用于目标主机和 NVIDIA GPU 的 NVIDIA CUDA 驱动程序。 如果已安装驱动程序，请确认其版本与目标 CUDA 版本兼容。 CUDA 驱动版本不匹配是新用户最常见的问题。 请参阅 兼容性矩阵 以获取兼容的 CUDA 驱动和 CUDA 工具包版本。

2. 安装 Docker（建议使用 v23.0 及以上版本） 或更新至与 Docker Compose V2 兼容的最新版本。 Docker 与 Docker Compose V2 不兼容也是新用户的常见问题。 注意，Windows 用户可以使用 WSL（Windows Subsystem for Linux）。 Cresset 已在 Windows 11 WSL2 上使用 Windows CUDA 驱动程序和 Docker Desktop for Windows 进行测试。 无需在 WSL 内单独安装 WSL CUDA 驱动程序或 Linux 版 Docker。 请注意，只有 Docker Desktop 受商业 EULA 约束，而 Docker Engine（Linux）和 Lima Docker（Mac）仍然是开源的。 注意：Windows 安全实时防护功能启用时会导致性能显著下降。 为获得最佳性能，请在 Windows 上禁用任何正在运行的杀毒软件。 注意：Linux 主机也可以通过此 仓库 进行安装。

3. 按照此 链接 安装 NVIDIA Container Toolkit。

4. 在 Linux 主机上运行 make install-compose 以安装 Docker Compose V2。 安装过程 不需要 root 权限。请访问 文档 获取最新的安装信息。请注意，对于使用 Docker Desktop 的 WSL 用户，Docker Compose V2 默认可用。

5. 在项目根目录的终端中运行 make env SERVICE=(train|devel|ngc|simple)， 以创建一个基本的 .env 文件。 .env 文件为 docker-compose.yaml 提供环境变量， 允许不同用户和机器根据需要设置各自的变量。 Makefile 也已配置为读取 .env 文件中的值（如果存在）， 从而只需指定一次非默认值。 每台主机都应拥有独立的 .env 文件，用于特定于该主机的配置。

6. 运行 make over 以创建 docker-compose.override.yaml 文件。 将不应通过源代码管理共享的配置添加到该文件中。 例如，特定于每台主机的卷挂载对。

7. 如果 Cresset 被放置在现有项目的子目录中， 请将 volume 对从 .:${PROJECT_ROOT} 更改为 ..:${PROJECT_ROOT}。 Cresset 中的所有命令都假定是在项目根目录下执行的， 但这一设置可以轻松更改。

服务说明

不同的 Docker Compose 服务被组织起来以满足不同的需求。

• train 是默认服务，应在需要编译依赖项时使用， 或当由于计算能力等问题需要从源代码编译 PyTorch 时使用。
• devel 专为需要频繁重新编译且具有复杂依赖关系的 PyTorch CUDA/C++ 开发人员设计。
• ngc 源自官方 NVIDIA PyTorch NGC 镜像，并可选择安装额外的软件包。 建议希望基于 NVIDIA 提供的 NGC 镜像开展工作的用户使用。 请注意，NGC 镜像会随不同版本变化，某个版本的配置可能无法在另一个版本中正常工作。
• simple 默认基于官方 Ubuntu Linux 镜像，因为某些公司限制使用未经 Docker 官方验证的镜像。 它默认通过 conda 安装所有软件包，并可选择通过 conda-lock 安装高度可重复的环境。 请注意，也可以通过 conda 安装 pip 包。 此外，可以通过直接在 .env 文件中指定 BASE_IMAGE 参数来配置基础镜像， 使用除官方 Linux Docker 镜像之外的其他镜像。 在某些情况下，官方 NVIDIA CUDA 镜像中的 PyTorch 运行时性能可能会更优。 请使用测试来基准测试运行速度。 建议没有编译依赖项的用户使用 simple 服务。

Makefile 已被配置为在 .env 文件存在时读取其中指定的值。 因此，在创建 .env 文件后，所有 make 命令将自动使用由 make env SERVICE=${SERVICE} 指定的 ${SERVICE}。

无 root 权限用户注意事项

许多机构禁止使用 Docker，因为它需要 root 权限，从而影响安全性。 对于没有 Docker root 访问权限的用户，建议使用无 root 模式的 Docker 链接。

虽然安装无 root 模式的 Docker 需要主机上的 root 权限， 但在首次安装完成后，后续操作并不需要 root 权限。

在使用无 root 模式的 Docker 时，最方便的做法是在 .env 文件中设置 ADD_USER=exclude， 因为在这种模式下，容器内的 root 用户将映射为宿主机的当前用户。

项目配置

1. 若要从源码构建 PyTorch，请在 .env 文件中设置 BUILD_MODE=include，并指定目标 NVIDIA GPU 的 CUDA 计算能力（CCC）。 可访问 NVIDIA 官网 查找 NVIDIA GPU 的计算能力。有关计算能力及其重要性的详细说明，请参阅 文档。 请注意，如果给定的配置相同，Docker 缓存会保存之前构建的二进制文件。

2. 阅读 docker-compose.yaml 文件，以补充 .env 文件中的额外变量。 此外，您也可以根据需要编辑 docker-compose.yaml 文件，例如更改会话名称、主机名等， 以适应不同的项目和配置。docker-compose.yaml 文件提供了合理的默认值， 但这些默认值可以被 .env 文件中指定的值覆盖。 其中一个重要配置是 ipc: host，它允许容器访问宿主机的共享内存。 这对于多进程操作至关重要，例如在 PyTorch 的 DataLoader 类中使用 num_workers。 在 WSL 上请禁用此配置，并改用 shm_size:，因为在撰写本文时 WSL 尚不支持宿主机 IPC。

3. 编辑 reqs/apt-train.requirements.txt 和 reqs/train-environment.yaml 中的依赖项。 这些文件包含了项目的软件包依赖关系。 apt 依赖项的设计类似于普通的 Python requirements.txt 文件。

4. 编辑服务的 volumes 部分，以将外部目录挂载到容器环境中。 运行 make over 命令生成 docker-compose.override.yaml 文件， 以便添加自定义卷和配置。docker-compose.override.yaml 文件不会被纳入版本控制， 以允许用户和服务器级别的个性化设置。

5. （高级）如果必须在 Docker 镜像构建过程中包含外部文件， 请编辑 .dockerignore 文件，以允许 Docker 构建上下文找到该外部文件。 默认情况下，除依赖文件外，所有其他文件都会被排除在 Docker 构建上下文之外。

以下是一个适用于用户名为 USERNAME、组名为 GROUPNAME、用户 ID 为 1000、组 ID 为 1000 且服务为 train 的用户的 .env 文件示例。 如果无需编译任何依赖项，且所需的软件包可以通过 apt、conda 或 pip 直接下载或安装， 则可使用 simple 服务。

# 由 `make env` 自动生成。
# 当使用 `UID=0`/`USR=root` 的 `root` 用户时，请设置 `ADD_USER=exclude`。
GID=1000
UID=1000
GRP=GROUPNAME
USR=USERNAME
HOST_ROOT=.
SERVICE=train
# 不要在同一台主机上为不同项目使用相同的 `PROJECT` 名称！
PROJECT=train-username             # `PROJECT` 必须为小写。
PROJECT_ROOT=/opt/project
IMAGE_NAME=cresset:train-username  # `IMAGE_NAME` 也会转换为小写。
COMMAND=/usr/bin/zsh --login       # 容器启动时执行的命令。
TZ=Asia/Seoul                      # 设置容器的时区。

# [[可选]]：如果默认配置不满足需求，可手动填写以下配置。

# NVIDIA GPU 计算能力（CCC）可在 https://developer.nvidia.com/cuda-gpus 查看
CCC=8.6              # 计算能力。RTX3090 的 CCC 为 8.6。
# CCC='8.6+PTX'      # '+PTX' 可实现向前兼容性。也可指定多个 CCC。
# CCC='7.5 8.6+PTX'  # 更多详情请参阅 https://pytorch.org/docs/stable/cpp_extension.html。

# 仅在从源码构建 PyTorch 时使用（`BUILD_MODE=include`）。
# `*_TAG` 变量仅在 `BUILD_MODE=include` 时生效，否则无效。
BUILD_MODE=exclude               # 是否从源码构建 PyTorch。
PYTORCH_VERSION_TAG=v2.0.0       # 可使用任意 `git` 标签（但不能仅使用提交哈希）。
TORCHVISION_VERSION_TAG=v0.15.1

# 通用环境配置。
LINUX_DISTRO=ubuntu   # 可访问 NVIDIA Docker Hub 仓库获取可用的基础镜像。
DISTRO_VERSION=22.04  # https://hub.docker.com/r/nvidia/cuda/tags
CUDA_VERSION=11.8.0   # 必须与硬件及 CUDA 驱动程序兼容。
CUDNN_VERSION=8       # 仅提供主要版本信息。
PYTHON_VERSION=3.10   # 指定 Python 版本。
MKL_MODE=include      # 为 Intel CPU 启用 MKL。

# 高级用法。
TARGET_STAGE=train    # 目标 Dockerfile 阶段。`*.whl` 文件可在 `train-builds` 中找到。
ADD_USER=include      # 是否创建新用户（include）或使用 `root` 用户（exclude）。

初次安装与配置后的常规使用

1. 运行 make build 命令以从 Dockerfile 构建镜像并启动服务。 make 命令在 Makefile 中定义，默认针对 train 服务。 如果镜像已构建完毕，且无需重新构建，则可运行 make up。
2. 运行 make exec 命令进入交互式容器环境。 建议在容器内使用 tmux。
3. 没有第 3 步。直接开始编码即可。 如有任何问题，请查阅文档或提交问题。

Makefile 使用说明

Makefile 包含常用 Docker Compose 命令的快捷方式。请阅读 Makefile 以了解具体命令。

1. make build 会从 Dockerfile 构建 Docker 镜像，无论该镜像是否已存在。此操作会重新安装依赖包到更新后的 requirements 文件中，然后重新创建容器。
2. make up 会基于镜像创建一个新的容器，撤销用户对容器所做的任何更改。允许修改容器设置，如网络端口、挂载卷、共享内存配置等。这是推荐的使用本项目的方式。
3. make exec 会进入由 make build 或 make up 创建的容器的交互式终端。
4. make down 会停止 Compose 容器并删除网络。这是服务拆解所必需的操作。
5. make start 会在不重新创建容器的情况下重启已停止的容器。与 make up 类似，但不会删除当前容器。除非容器中保存的数据绝对必要，否则不建议使用此命令。
6. make ls 会显示所有 Docker Compose 服务，包括正在运行和未运行的服务。
7. make run 用于调试。容器在退出时会被移除。如果某个服务无法启动，请使用此命令查找错误。
8. make build-only 会仅从 Dockerfile 构建 Docker 镜像，而不启动服务。此命令用于帮助将镜像发布到容器注册表。

小贴士

• Makefile 中的 PROJECT、SERVICE 和 COMMAND 变量会优先使用 .env 文件中指定的变量（如果存在）。
• 如果遇到问题，首先尝试运行 make down 删除当前容器，然后运行 make up 从镜像创建新容器。当宿主机出现问题时，显式地销毁容器通常是必要的。
• 如果在执行 make up 时服务启动卡住，请检查 docker system df 以确认宿主机是否有足够的磁盘空间。
• make up 类似于重启计算机：当前容器会被移除，并基于当前镜像创建一个新容器。
• make build 类似于重置或格式化计算机：如果当前镜像存在，则会被移除；然后根据 Dockerfile 重新构建镜像，并基于新镜像创建容器。相比之下，make up 只有在指定的镜像不存在时才会从源代码构建镜像。
• make exec 类似于登录到计算机：它是最重要的命令，允许用户以交互方式访问容器的终端。
• 已挂载的卷和网络端口等配置无法在运行中的容器中更改，必须创建新的容器才能生效。
• Docker 默认会缓存所有构建内容，直到达到 defaultKeepStorage 的限制。默认情况下，构建会复用之前构建的缓存层，从而仅构建修改过的层，大大加快后续构建速度。
• 如果在 git clone 时构建失败，请在网络连接稳定的情况下再次尝试 make build。
• 如果在 pip install 时构建失败，请检查 PyPI 镜像地址和包的依赖要求。
• 如果出现网络问题，请运行 docker network ls 检查是否存在冲突。大多数网络和 SSH 问题可以通过运行 docker network prune 来解决。

项目概述

项目的主要组成部分如下，其他文件均为辅助工具：

1. Dockerfile
2. docker-compose.yaml
3. docker-compose.override.yaml
4. reqs/(*requirements.txt|*environment.yaml)
5. .env

当用户输入 make up 或其他 make 命令时，Makefile 中指定的命令会被执行。Makefile 用于定义快捷命令和变量。

当执行与 Docker Compose 相关的命令（例如 make build）时，Docker Compose 会读取 docker-compose.yaml 和 .env 文件。docker-compose.yaml 文件指定了合理的默认值，但用户可以根据需要进行修改。.env 文件中指定的值会优先于 docker-compose.yaml 文件中的默认值。而 Shell 中设置的环境变量又会优先于 .env 文件中的设置。为了使不同用户和不同机器能够使用不同的配置，.env 文件被特意排除在版本控制之外。

docker-compose.yaml 文件负责管理配置、构建、运行等操作，这些操作都基于 Dockerfile 进行。有关详细信息，请参阅 Docker Compose 规范 和 参考文档。

docker-compose.override.yaml 文件会在设置阶段被 docker-compose.yaml 文件读取。它可以添加特定于每个宿主机的配置，这些配置不应通过版本控制共享，例如针对宿主机特定路径的卷挂载。

Dockerfile 被配置为仅读取 reqs 目录下的依赖文件。编辑 reqs/pip-train.requirements.txt 可以指定 Python 包的依赖要求；编辑 reqs/apt-train.requirements.txt 则可以指定 Ubuntu 包的依赖要求。如果需要在构建过程中从私有代码构建镜像，用户必须编辑 .dockerignore 文件，以便将其他文件复制到构建环境中。

Dockerfile 使用 Docker BuildKit 和多阶段构建，通过阶段名称以及通过 docker-compose.yaml 传递的构建时环境变量来控制构建流程。有关 Docker BuildKit 的更多信息，请参阅其 语法文档。docker-compose.yaml 文件中指定的 train 服务使用了 Dockerfile 中定义的 train 阶段，该阶段假定使用 Ubuntu 镜像。

存在的理由

本节旨在介绍一种深度学习开发的新范式。 我们希望 Cresset，或者至少其背后的理念，最终能成为中小型深度学习研究与开发的最佳实践。

在深度学习社区中，使用 conda 或 pip 在本地环境中进行开发非常普遍。 然而，这种方式容易导致开发环境及其运行代码无法复现。 这种状况严重阻碍了科学进步，许多读者对此都深有体会。

Docker 容器是跨不同计算环境提供可复现程序的标准方法。 它们创建隔离的运行环境，使程序能够在不受宿主机或其他容器干扰的情况下运行。 有关详细信息，请参阅 官方文档。

但在实际应用中，Docker 容器常常被误用。 容器的设计初衷是短暂存在的，最佳实践建议每次运行时都创建一个新的容器。 然而，这给开发带来了极大的不便，尤其是对于深度学习应用而言——需要不断安装新库，且许多 bug 只有在运行时才会显现。 因此，许多研究人员选择在交互式容器中进行开发。 Docker 用户通常会编写类似如下的 run.sh 脚本： docker run -v my_data:/mnt/data -p 8080:22 -t my_container my_image:latest /bin/bash （是不是很熟悉？）然后通过 SSH 连接到正在运行的容器。 甚至 VSCode 还提供了远程开发模式，可以直接在容器内编写代码。

这种方法的问题在于，这些交互式容器同样难以复现，与本地开发环境无异。 运行中的容器无法连接新的端口或挂载新的 卷。 如果容器内的计算环境是在数月的安装和构建过程中逐步搭建起来的，那么唯一保持它的方法就是将容器保存为镜像，并基于该镜像重新创建容器。 经过几次这样的迭代后，生成的镜像会变得臃肿不堪，混乱程度丝毫不亚于原本要取代的本地环境。

当准备部署时，这些问题会更加突出。 MLOps 是一组旨在可靠高效地部署和维护机器学习模型的最佳实践，近年来因其重要性而广受欢迎——许多从业者意识到，在初始开发阶段结束后，持续维护机器学习系统至关重要。

然而，上述不良实践导致大量精力被浪费在将研究代码转化为生产级产品上。 往往连最初的开发者几个月后都无法重现相同的模型。 为此，许多公司不得不组建专门的团队来负责模型转换，这无疑是一笔巨大的开销。

为了解决这些问题，我们提出使用 Docker Compose 作为简单的 MLOps 解决方案。 借助 Docker 和 Docker Compose，整个训练环境都可以被复现。 目前，Docker Compose 在深度学习社区尚未普及， 可能是因为它通常被宣传为多容器解决方案。 但这是一种误解——它同样适用于单容器开发。

我们提供了一个 docker-compose.yaml 文件，用于轻松管理容器。 使用提供的 docker-compose.yaml 文件将创建一个交互式环境， 提供与在远程服务器上使用终端非常相似的编程体验。 同时，还支持与主流 IDE（PyCharm、VSCode）的集成。

此外，它还允许用户分别指定构建和运行时的配置， 从而无需再使用自定义的 Shell 脚本来管理环境。 若需挂载新的卷或映射新的端口，只需删除当前容器， 在 docker-compose.yaml 中添加一行配置，然后运行 make up 即可基于同一镜像创建一个新的容器。

构建缓存功能使得新镜像的构建速度极快， 从而消除了 Docker 普及的另一大障碍——漫长的首次构建时间。 更多关于 Compose 的信息，请访问 官方文档。

Docker Compose 也可以用于部署， 这对于中小型部署场景尤为有用。 一旦需要采用 Kubernetes 等容器编排工具进行大规模部署时， 从一开始就使用可复现的 Docker 环境，将加速开发流程， 并为全面采用 MLOps 打下坚实基础。 通过简化开发流程来缩短上市时间，无论是一家初创公司还是科技巨头， 都是极具竞争力的优势。

希望本文提出的技术能够帮助深度学习社区实现“一次编写，随处训练”。 即便大多数用户并未被这一方法所打动， 至少也能让许多不幸的研究生免于陷入反复搭建 conda 环境的西西弗斯式劳动——好不容易配置好环境，却往往在论文提交前夕彻底崩溃。

Compose 作为最佳实践

与为每个环境编写自定义 Shell 脚本相比，Docker Compose 具有明显优势。 它不仅将构建和运行所需的所有变量和命令集中到一个文件中， 而且与 Docker 原生集成，使得复杂的 Docker 构建和运行配置变得简单易行。

以这种方式使用 Docker Compose 是一种通用技术， 并不依赖于本项目的任何特定内容。 项目中的其他服务也进一步强调了这一点。

在 PyCharm 和 VSCode 中使用 Compose

Docker Compose 容器环境不仅可以在终端中使用，还可以与流行的 Python IDE 配合使用。PyCharm 和 Visual Studio Code 这两款在深度学习社区中非常受欢迎的 IDE，都与 Docker Compose 兼容。

PyCharm（仅限 Professional 版）

Docker 和 Docker Compose 均可作为 Python 解释器原生使用。有关详细信息，请参阅 Docker 和 Compose 的教程。此外，JetBrains 的 Gateway 也可以用于连接到正在运行的容器。

当使用 ngc 服务时，可通过 GUI 将 /usr/local/lib/python3/dist-packages 和 /opt/conda/lib/python3/site-packages 添加到解释器搜索路径中，以启用对通过 conda 安装的包的代码补全支持。

注意：拥有有效大学邮箱地址的用户可以免费使用 PyCharm Professional 及其他 JetBrains IDE。

VSCode

安装 Remote Development 扩展包。有关详细信息，请参阅 教程。

VSCode 使用技巧

由于 docker-compose.yaml 文件中挂载了 ${HOME}/.vscode-server 卷，该卷用于在不同容器之间保留 .vscode-server 目录，因此在访问由 Cresset 创建的远程容器时，VSCode 可能无法启动。

VSCode 连接失败的原因是：如果指定为卷的任何主机目录不存在，Docker 会自动创建该目录，并将目录的所有者设置为 root。而已经存在的目录则会保留其原有的所有权。当 .vscode-server 目录被 Docker 以这种方式创建后，VSCode 就无法在该目录中安装任何文件。

这一问题已在 Makefile 中修复，但与 .vscode-server 目录相关的问题仍经常出现。要解决此问题，只需将目录的所有权更改为当前用户，执行命令 sudo chown -R $(id -u):$(id -g) ${HOME}/.vscode-server。该命令既可以在宿主机上执行，也可以在容器内执行，这在宿主机没有 sudo 权限时非常有用。

此外，当一个用户在同一台机器上切换多个基于 Cresset 的容器时，VSCode 可能无法找到容器的工作区。这是因为 docker-compose.yaml 文件会将宿主机的 ~/.vscode-server 目录挂载到所有容器的 /home/${USR}/.vscode-server 目录下，以在容器之间保留 VSCode 扩展。为了解决这个问题，可以在宿主机上创建一个新的目录来挂载各个容器的 .vscode-server 目录。例如，可以为项目1设置卷映射 ${HOME}/.vscode-project1:/home/${USR}/.vscode-server，为项目2设置 ${HOME}/.vscode-project2:/home/${USR}/.vscode-server。请务必先在宿主机上创建 ${HOME}/.vscode-project1 和 ${HOME}/.vscode-project2，否则这些目录的所有者将是 root，从而导致 VSCode 因权限问题而无限期卡住。

对于其他 VSCode 问题，可以尝试删除宿主机上的 ~/.vscode-server。

已知问题

1. 通过 ssh 连接到正在运行的容器会清除所有由 ENV 设置的环境变量。这是因为 sshd 会启动一个新的环境，从而删除所有之前的变量。强烈建议使用 docker 或 docker compose 命令进入容器。

2. 在终端中运行 pip install package[option] 会因 Z shell 的 globbing 功能而失败。诸如 [、]、* 等字符会被 Z shell 解释为特殊命令。为了跨 Shell 的一致性，请使用字符串字面量，例如 pip install 'package[option]'。

3. 如果在 git clone 时构建失败，只需再次尝试运行 make build。大多数构建步骤会被缓存。失败很可能是由于安装过程中出现的网络问题所致。更新 Git 子模块并不是一个完全可靠的操作，具体可参考 此解答。

4. 如果宿主机的 CUDA 驱动程序与 Docker 镜像中的 CUDA 版本不兼容，torch.cuda.is_available() 将返回 ... UserWarning: CUDA initialization:... 错误，或者镜像根本无法启动。此时应升级宿主机的 CUDA 驱动程序，或降低镜像中的 CUDA 版本。请查阅 兼容性矩阵，确认宿主机的 CUDA 驱动程序是否与所需的 CUDA 版本兼容。同时，还需检查宿主机上的 CUDA 驱动程序是否已正确配置。可以通过 nvidia-smi 命令查看 CUDA 驱动程序的版本。

5. 在 Linux 宿主机上，如果已安装的 Docker 引擎版本过低，Docker Compose V2 将静默失败。请将 Docker 更新至最新版本（23.0 及以上），以便使用 Docker Compose V2。

6. 如果 .env 文件中将用户设置为 root，即 UID=0, USR=root，则应将 ADD_USER=exclude 设置为排除新建用户，因为预期的新用户不应为 root 用户。

期望事项

1. 更多星标。没有感谢就没有贡献！

2. 欢迎提交 bug 报告。目前仅对最新版本进行了严格测试。如果您发现有版本无法正常构建，请提出问题。但在提交之前，请确保您的宿主机上的 Docker、Docker Compose，尤其是 NVIDIA 驱动程序，均为最新版本。

3. 欢迎提供其他语言的翻译以及现有翻译的更新。请创建单独的 LANG.README.md 文件并提交拉取请求。

Cresset 快速上手指南

Cresset 是一个基于 Docker Compose 的 MLOps 系统，旨在为深度学习开发者提供可复现、易用的交互式开发环境。它支持从源码编译 PyTorch、管理复杂依赖，并适用于学术与工业界场景。

环境准备

在开始之前，请确保您的主机满足以下要求：

• 操作系统：Linux (推荐 Ubuntu 22.04+)、Windows 11 (需安装 WSL2) 或 macOS。
• GPU 驱动：安装与目标 CUDA 版本兼容的 NVIDIA 显卡驱动。
  • 注意：驱动版本不匹配是新用户最常见的问题，请参考 NVIDIA 兼容性矩阵。
• Docker：安装 Docker Engine (v23.0+) 或 Docker Desktop。
  • Windows 用户请使用 WSL2 后端，无需在 WSL 内单独安装 Linux 版 Docker 或 CUDA 驱动。
  • 性能提示：Windows 用户若遇到显著卡顿，建议暂时禁用实时防病毒保护。
• NVIDIA Container Toolkit：必须安装以支持容器调用 GPU。
  • 安装指南：NVIDIA Container Toolkit Install Guide
• 权限说明：如果您的机构禁止使用 root 权限运行 Docker，建议配置 Rootless Docker。

安装步骤

请在项目根目录下执行以下命令完成初始化：

1. 安装 Docker Compose V2 (Linux 主机需要，WSL/Docker Desktop 通常已内置)：

   make install-compose
   

   注：此步骤不需要 root 权限。

2. 生成环境变量文件： 根据您的需求选择服务类型（train, devel, ngc, 或 simple）。

   • train: 默认选项，适合需要编译依赖或从源码构建 PyTorch 的场景。
   • simple: 适合无编译依赖的用户，通过 conda/pip 安装包，兼容性更好。

   执行以下命令生成 .env 文件（以 train 为例）：

   make env SERVICE=train
   

3. 创建本地覆盖配置： 生成 docker-compose.override.yaml 文件，用于配置本机特有的挂载卷（Volumes）等不被版本控制的设置：

   make over
   

4. 配置 .env 文件 (可选但推荐)： 编辑生成的 .env 文件，修改以下关键参数以适配您的环境：

   • UID / GID: 设置为当前用户的 ID (Linux/Mac 下可通过 id 命令查看)，避免容器内文件权限问题。
   • CCC: 设置 GPU 的 Compute Capability (例如 RTX 3090 为 8.6)。若需从源码编译 PyTorch，此项必填。
   • PROJECT: 设置唯一的项目名称（必须小写）。
   • SERVICE: 确认与您第一步选择的服务一致。

基本使用

完成配置后，即可开始构建环境并进入开发：

1. 构建镜像并启动容器： 默认针对 .env 中指定的 SERVICE 进行构建和启动：

   make build
   

   首次构建可能需要较长时间，特别是当 BUILD_MODE=include 需要从源码编译 PyTorch 时。

2. 进入交互式开发环境： 构建完成后，运行以下命令进入容器终端：

   make run
   

   默认将启动 /usr/bin/zsh (可在 .env 的 COMMAND 字段修改)。

3. 其他常用命令：

   • 停止并移除容器：make down
   • 重新构建（不使用缓存）：make build-no-cache
   • 查看日志：make logs

提示：所有 make 命令会自动读取 .env 文件中的配置。若需切换服务（例如从 train 切换到 simple），请修改 .env 中的 SERVICE 变量后重新执行 make build。