Docker 入门实操：30 分钟打包你的第一个 PyTorch 模型镜像

一、实操前置准备

1. 必备工具与环境

  • 操作系统：Windows（需开启 WSL2）、MacOS（Intel/Apple Silicon 均可）、Linux（Ubuntu 18.04+ 推荐）

  • 核心软件：Docker Desktop（Windows/Mac）/ Docker Engine（Linux），需提前安装并启动（验证：终端输入 docker --version 显示版本即正常）

  • 辅助工具：文本编辑器（VS Code/记事本）、终端（CMD/PowerShell/终端）

  • Python 基础：无需提前配置 PyTorch 环境（Docker 会隔离环境，本地仅需确认能编写 Python 脚本）

2. 任务规划

操作内容

核心目标

准备项目文件（模型脚本+依赖清单）

搭建极简可运行的 PyTorch 项目

编写 Dockerfile（核心步骤）

定义镜像构建规则，理解每一行指令含义

构建 Docker 镜像 + 验证镜像

生成可复用的 PyTorch 模型镜像

运行容器 + 测试模型功能

验证镜像可用性，完成实操闭环

3. 项目前置说明

本次实操采用 极简 PyTorch 预训练模型（ResNet18，无需手动训练，直接调用 torchvision 预训练权重），实现简单的图像推理演示，避免复杂模型训练耗时，确保 30 分钟内完成全部操作。

二、步骤 1：准备项目文件

1. 创建项目目录

首先在本地任意位置创建一个项目文件夹（命名为 pytorch-docker-demo），目录结构如下（手动创建对应文件，无需嵌套子目录）：

pytorch-docker-demo/
├── test_pytorch.py  # PyTorch 模型推理脚本
└── requirements.txt # 项目依赖清单

2. 编写 PyTorch 模型脚本（[test_pytorch.py](test_pytorch.py)）

复制以下极简推理代码到 test_pytorch.py，实现「加载 ResNet18 预训练模型 + 随机生成测试张量 + 完成推理预测」：

# test_pytorch.py
import torch
import torchvision.models as models
import torchvision.transforms as transforms

def main():
    # 1. 确认 CUDA 可用性（无需实际 GPU，Docker 镜像内可识别）
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    print(f"使用设备：{device}")

    # 2. 加载 PyTorch 预训练 ResNet18 模型
    model = models.resnet18(pretrained=True).to(device)
    model.eval()  # 切换为推理模式
    print("ResNet18 预训练模型加载成功！")

    # 3. 生成随机测试图像张量（模拟 3通道、224x224 输入图像）
    test_tensor = torch.randn(1, 3, 224, 224).to(device)  # batch_size=1, channels=3, H=224, W=224

    # 4. 模型推理
    with torch.no_grad():  # 关闭梯度计算，提升推理效率
        output = model(test_tensor)
        pred_class = torch.argmax(output, dim=1).item()  # 获取预测类别索引

    print(f"测试张量推理完成，预测类别索引：{pred_class}")
    print("PyTorch 模型容器运行正常！")

if __name__ == "__main__":
    main()

3. 编写依赖清单（requirements.txt）

列出项目所需 Python 包及指定版本（避免兼容性问题，适配 Docker 环境）：

# requirements.txt
torch==2.0.1
torchvision==0.15.2
pillow==9.5.0

三、步骤 2：编写 Dockerfile（核心步骤）

在 pytorch-docker-demo 目录下，新建文件 Dockerfile（无后缀名，首字母大写），逐行编写如下内容，并理解每一行的核心含义（入门关键，不盲目复制）。

1. 完整 Dockerfile 内容

# 1. 选择基础镜像：轻量 Python 3.9 环境（slim 版本体积小，适合部署）
FROM python:3.9-slim

# 2. 设置工作目录：容器内的项目根目录（后续操作均在此目录下执行）
WORKDIR /app

# 3. 复制依赖清单文件到容器工作目录
COPY requirements.txt .

# 4. 安装项目依赖：使用 pip 安装，换国内清华源加速（解决国外源下载缓慢问题）
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 5. 复制本地所有项目文件（test_pytorch.py 等）到容器工作目录
COPY . .

# 6. 指定容器启动时默认执行的命令：运行 PyTorch 模型脚本
CMD ["python", "test_pytorch.py"]

2. 关键指令详解（入门必懂）

指令

作用说明

新手避坑

FROM

指定基础镜像（所有镜像都必须基于基础镜像构建）

避免选择过大的基础镜像（如 python:3.9 比 python:3.9-slim 大很多）

WORKDIR

创建并进入容器内工作目录

后续 COPY、RUN 指令均基于此目录，无需写绝对路径

COPY

从本地复制文件到容器内

先复制 requirements.txt 再安装依赖（利用 Docker 缓存，后续仅修改模型脚本时，无需重新安装依赖）

RUN

在容器内执行命令（此处为安装依赖）

添加 --no-cache-dir 减少镜像体积，换国内源避免安装超时

CMD

容器启动时默认执行的命令

仅能有一个 CMD 指令，若手动指定容器启动命令，会覆盖此配置

四、步骤 3：构建 Docker 镜像

1. 进入项目目录

打开终端，通过 cd 命令进入 pytorch-docker-demo 目录（示例为 Mac/Linux 命令，Windows 类似）：

# 示例：替换为你的项目实际路径
cd /home/ubuntu/pytorch-docker-demo

2. 执行镜像构建命令

使用 docker build 命令构建镜像，核心参数 -t 用于指定镜像名称和标签（格式：镜像名:标签，标签通常为版本号）：

# 构建镜像，命名为 pytorch-first，标签为 v1.0，当前目录（.）为构建上下文
sudo docker build -t pytorch-first:v1.0 .

3. 构建过程说明

  • 终端会逐行执行 Dockerfile 中的指令，每一步会生成一个「中间镜像」，最后生成最终镜像

  • 若出现 Successfully built xxx + Successfully tagged pytorch-first:v1.0，说明构建成功

补充说明：为什么没有看到旧版成功提示？

这是 Docker 版本迭代导致的输出格式差异，并非构建失败：

  1. 旧版 Docker（20.x 及更早版本）构建成功后，会明确输出 Successfully built xxx（镜像 ID）和 Successfully tagged xxx:xxx（镜像标签）；

  2. 新版 Docker（23.x 及以上版本）采用了更简洁的「进度条式输出」，将「镜像构建」「标签命名」「镜像解压」整合为 exporting to image 步骤，不再单独输出那两行提示，但功能完全一致；

  3. 构建日志中 naming to 就是标签命名成功，unpacking to 就是镜像构建完成，和旧版提示的含义完全相同。

  • 常见问题排查：

  1. 报错 Docker daemon is not running：启动 Docker Desktop/Docker Engine

  2. 依赖安装超时：检查网络，或确认 requirements.txt 中包版本是否合法

  3. 命令报错 no such file or directory：确认终端在项目目录下，文件名称（大小写）无误

4. 验证镜像是否创建成功

执行 docker images 命令查看本地镜像列表，若能找到 pytorch-first 镜像，说明构建成功：

# 查看本地镜像
sudo docker images

# 预期输出（示例）
REPOSITORY       TAG       IMAGE ID       CREATED         SIZE
pytorch-first    v1.0      abc123456789   2 minutes ago   1.2GB

五、步骤 4：运行容器 + 测试模型

1. 执行容器运行命令

使用 docker run 命令启动容器，基于我们构建的 pytorch-first:v1.0 镜像：

# 运行容器，--rm 表示容器停止后自动删除（测试环境推荐，避免残留无用容器）
docker run --rm pytorch-first:v1.0

2. 验证运行结果

若终端输出如下信息，说明容器正常运行，PyTorch 模型加载和推理均成功：

使用设备：cpu  # 若本地有 GPU 并配置 Docker GPU 支持，会显示 cuda
ResNet18 预训练模型加载成功！
测试张量推理完成，预测类别索引：xxx  # 索引值不固定，正常即可
PyTorch 模型容器运行正常！

3. 额外操作：进入容器内部（可选）

若想查看容器内的文件结构，可使用交互式运行命令进入容器：

# -it 开启交互式终端，/bin/bash 指定终端类型
docker run -it --rm pytorch-first:v1.0 /bin/bash

# 进入容器后，可执行以下命令查看文件
ls  # 查看工作目录下的文件（应显示 test_pytorch.py、requirements.txt）
pwd # 查看当前工作目录（应显示 /app）

# 退出容器：输入 exit 即可
exit

六、常见问题排查（新手必看）

  • Docker 命令无权限（Linux）

解决方案：将当前用户添加到 docker 组，执行 sudo usermod -aG docker $USER，重启终端后生效。

  • Windows 下构建镜像报错「文件格式错误」

解决方案：VS Code 中设置文件换行格式为 LF（Docker 容器基于 Linux 环境，不支持 CRLF 换行）。

  • 镜像体积过大

解决方案：使用 slim 基础镜像、--no-cache-dir 参数、清理冗余文件（如 RUN rm -rf /root/.cache/pip）。

  • GPU 无法识别（需 GPU 支持）

解决方案：安装 NVIDIA Container Toolkit，运行命令添加 --gpus all，如 docker run --rm --gpus all pytorch-first:v1.0。

七、实操总结与拓展

1. 核心成果

  • 完成了「项目文件准备 → Dockerfile 编写 → 镜像构建 → 容器运行」的完整闭环

  • 得到了第一个可复用的 PyTorch 模型镜像 pytorch-first:v1.0

  • 理解了 Docker 核心指令的作用，掌握了 AI 模型容器化的入门方法

2. 后续拓展方向

  • 镜像推送：将镜像推送到 Docker Hub/阿里云镜像仓库，实现跨环境共享

  • 镜像优化：使用多阶段构建减小镜像体积，或基于 nvidia/cuda 基础镜像支持 GPU 加速

  • 服务化部署：将 PyTorch 模型封装为 API（FastAPI），通过 Docker 部署为可访问的推理服务

  • 容器编排：使用 Docker Compose 管理多容器应用（如模型服务 + 监控工具）

posted @ 2025-12-27 18:06  szjmc  阅读(4)  评论(0)    收藏  举报  来源