使用 NVIDIA CUDA Docker 部署 Transformer Lab API从镜像构建到 Compose 一键起服务的完整指南【免费下载链接】transformerlab-appThe open source research environment for AI researchers to seamlessly train, evaluate, and scale models from local hardware to GPU clusters.项目地址: https://gitcode.com/GitHub_Trending/tr/transformerlab-app本篇技术指南围绕 Transformer Lab 仓库中 api/docker/gpu/nvidia 目录下的 CUDA 部署方案展开系统讲解如何利用Dockerfile.cuda、docker-compose.yml.tpl、deploy.sh与deploy.ps1在 Linux/macOS 与 Windows 上以 GPU 加速方式拉起 Transformer Lab API 服务。读完本文你将掌握 NVIDIA GPU 环境下 Docker 部署的完整前置条件、双平台脚本化部署流程、Compose 模板中 GPU 预留与卷挂载的底层含义以及常见故障的定位与处理方法。一、部署方案概览与文件职责Transformer Lab 是一个面向 AI 研究者的开源研究环境用于在从本地硬件到 GPU 集群的范围内训练、评估和扩展模型。api/docker/gpu/nvidia目录提供了完整的 NVIDIA GPU 容器化部署素材共包含四个文件文件职责Dockerfile.cuda构建 CUDA 版镜像的 Dockerfile。官方发布版本一般直接拉取预构建镜像仅在需要自定义时才自行构建docker-compose.yml.tplDocker Compose 配置模板由部署脚本注入版本号与 HOME 路径后生成最终docker-compose.ymldeploy.shLinux/macOS 一键部署脚本deploy.ps1Windows PowerShell 一键部署脚本两个部署脚本的核心逻辑一致自动获取 Transformer Lab API 的最新发布版本号将其注入模板生成 Compose 文件随后执行docker compose up -d拉起容器。镜像命名规范为transformerlab/api:版本号-cuda例如transformerlab/api:v0.30.3-cuda。从源码结构看同一套部署体系在仓库中还有 CPU 与 AMD 两个变体api/docker/cpu 与 api/docker/gpu/amd后者的 Dockerfile 基于rocm/dev-ubuntu-22.04构建并通过独立的entrypoint.sh启动服务。二、前置条件环境准备清单部署前需要确保系统满足以下条件Docker从 Docker 官方网站安装适用于当前操作系统的 Docker 引擎或 Docker Desktop。Docker Compose通常随 Docker Desktop 一起提供也可作为独立软件包安装。NVIDIA GPU 驱动与 NVIDIA Container ToolkitGPU 支持所必需安装合适的 NVIDIA 驱动并按照 NVIDIA Container Toolkit 的官方安装指南完成配置使容器能够访问宿主机 GPU。curl用于从发布仓库获取最新版本号。Linux/Mac通过包管理器安装例如sudo apt-get install curlDebian/Ubuntu或brew install curlmacOS。Windows若系统中不存在 curlPowerShell 部署脚本会通过winget自动安装。envsubst仅 Linux/Mac 需要属于 GNU gettext 软件包安装方式为sudo apt-get install gettextmacOS 上为brew install gettext brew link --force gettext。deploy.sh使用它完成模板变量替换。PowerShellWindows 需要Windows 10 及以上版本默认自带。三、Linux/macOS 一键部署3.1 获取仓库代码将仓库克隆到本地并进入 CUDA 部署目录git clone https://gitcode.com/GitHub_Trending/tr/transformerlab-app cd api/docker/gpu/nvidia该目录位于仓库根路径下因此先克隆整个仓库再进入部署子目录即可。3.2 赋予脚本执行权限并运行chmod x deploy.sh ./deploy.sh3.3 deploy.sh 的自动化流程拆解对照 deploy.sh 源码脚本依次执行以下动作检查 curl若系统缺少 curl脚本自动调用sudo apt-get update sudo apt-get install -y curl进行安装第 4-7 行。获取最新版本号脚本查询 GitHub Releases APItransformerlab/transformerlab-api仓库并解析出tag_name第 10-13 行若解析失败则输出 Failed to fetch the latest version. 并以非零状态退出第 15-18 行。剥离版本号前缀通过${RAW_VERSION#v}去除 tag 开头的v字符例如v0.30.3变成0.30.3第 21 行。导出 VERSION 环境变量将版本号export VERSION供envsubst替换模板占位符使用第 26 行。生成 Compose 文件执行envsubst docker-compose.yml.tpl docker-compose.yml将模板中的${VERSION}占位符替换为实际版本号生成最终的docker-compose.yml第 29 行。拉起容器docker compose up -d以守护模式部署服务第 34 行。3.4 访问 API部署完成后API 服务监听于http://localhost:8338。该端口号与 Dockerfile.cuda 中的EXPOSE 8338及 run.sh 中默认的PORT8338保持一致从镜像层到服务层全链路统一。四、WindowsPowerShell部署4.1 克隆仓库并进入目录在 PowerShell 中执行git clone https://gitcode.com/GitHub_Trending/tr/transformerlab-app cd api\docker\gpu\nvidia4.2 运行部署脚本必要时以管理员身份打开 PowerShell然后执行.\deploy.ps14.3 deploy.ps1 的自动化流程拆解对照 deploy.ps1 源码检查 curl若Get-Command curl失败则通过winget install --id curl.curl -e --source winget自动安装第 2-5 行。获取最新版本使用Invoke-RestMethod调用 GitHub Releases API读取tag_name第 8-16 行。剥离前缀$response.tag_name.TrimStart(v)去除版本号开头的v第 19 行。路径转换将$env:USERPROFILE中的反斜杠替换为正斜杠得到$homeDir用于后续卷挂载路径第 24 行。模板替换读取docker-compose.yml.tpl全文通过正则-replace同时完成${VERSION}与${HOME}两处占位符替换输出为 UTF-8 编码的docker-compose.yml第 27-33 行。拉起容器docker compose up -d第 38 行。与 Linux 版本的关键差异在于Windows 脚本额外注入了HOME目录并将宿主机的用户缓存与工作区目录挂载进容器详见下文卷挂载说明。4.4 访问 API部署完成后在浏览器中访问http://localhost:8338即可进入 Transformer Lab 的 Web 界面。五、docker-compose.yml 模板逐项解析api/docker/gpu/nvidia/docker-compose.yml.tpl 是理解整个 GPU 部署行为的核心文件全文如下services: transformerlab-api: image: transformerlab/api:${VERSION}-cuda container_name: transformerlab-api ports: - 8338:8338 ipc: host volumes: - transformerlab_data:/root/.transformerlab/ - ${HOME}/.cache:/root/.cache - ${HOME}/.transformerlab/workspace:/root/.transformerlab/workspace deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped tty: true stdin_open: true volumes: transformerlab_data:各配置项的技术含义如下配置项含义image: transformerlab/api:${VERSION}-cuda镜像版本占位符由部署脚本替换。-cuda后缀标识 CUDA 构建变体与 CPU 版本transformerlab/api:${VERSION}相区分对比 api/docker/cpu/docker-compose.yml.tplports: 8338:8338将容器 8338 端口映射到宿主机 8338与EXPOSE 8338及 run.sh 默认端口一致ipc: host使用宿主机 IPC 命名空间对依赖共享内存的深度学习推理/训练场景如 PyTorch DataLoader 的多进程通信尤为重要transformerlab_data:/root/.transformerlab/命名卷挂载持久化 Transformer Lab 的全部数据模型、任务、配置等到名为transformerlab_data的 Docker 卷容器重建后数据不丢失${HOME}/.cache:/root/.cache将宿主机 Hugging Face 等工具的缓存目录挂载进容器复用已下载的模型缓存避免重复下载${HOME}/.transformerlab/workspace:/root/.transformerlab/workspace将宿主机工作区目录与容器内工作区打通方便直接在宿主机管理任务脚本与产出deploy.resources.reservations.devicesDocker Compose 的 GPU 资源预留语法driver: nvidia指定 NVIDIA 容器运行时count: all表示把宿主机全部 GPU 暴露给容器capabilities: [gpu]声明所需能力。该段依赖 NVIDIA Container Toolkit 正常工作restart: unless-stopped容器异常退出或宿主机重启后自动拉起手动 stop 除外tty/stdin_open为容器分配 TTY 并保持标准输入打开便于交互式调试与日志输出对比说明CPU 变体模板api/docker/cpu/docker-compose.yml.tpl没有ipc: host与 GPU 预留段卷名也不同transformerlab_data_cpu体现了两套部署在资源需求上的差异。六、Dockerfile.cuda 镜像构建原理若需自定义镜像可基于 Dockerfile.cuda 自行构建。其构建逻辑分为四层6.1 基础镜像与构建工具FROM nvidia/cuda:12.8.1-devel-ubuntu22.04 SHELL [/bin/bash, --login, -c] ENV DEBIAN_FRONTENDnoninteractive RUN apt-get update apt-get install -y \ curl \ git \ python3.11 \ python3-pip \ python-is-python3 \ g \ ninja-build基础镜像选用nvidia/cuda:12.8.1-devel-ubuntu22.04即 CUDA 12.8.1 开发版 Ubuntu 22.04-devel变体包含编译工具链为后续构建 PyTorch 等 CUDA 扩展提供完整环境。SHELL [/bin/bash, --login, -c]确保 RUN 指令以登录 shell 执行使 conda 等初始化脚本的路径生效。DEBIAN_FRONTENDnoninteractive关闭 apt 交互提示保证构建过程可无人值守。安装的最小依赖集curl、git、Python 3.11、pip、g、ninja-build是 api/install.sh 运行所必需的编译与下载工具。6.2 调用 install.sh 完成三段式安装RUN curl -fsSL https://raw.githubusercontent.com/transformerlab/transformerlab-app/refs/heads/main/api/install.sh | bash -s download_transformer_lab install_conda create_conda_environment构建阶段直接以管道方式执行install.sh的三个子命令对应 api/install.sh 第 668-710 行的参数分派逻辑download_transformer_lab下载指定版本的发布压缩包解压到~/.transformerlab/src并同时下载静态 Web 前端transformerlab_web.tar.gz还会自动生成TRANSFORMERLAB_JWT_SECRET与TRANSFORMERLAB_REFRESH_SECRET写入~/.transformerlab/.env。install_conda在~/.transformerlab/miniforge3安装 Miniforgeconda 发行版。create_conda_environment创建 Python 3.11 的 conda 环境~/.transformerlab/envs/transformerlab。注意镜像构建阶段刻意不执行install_dependencies即不安装全部 Python 依赖这是分层缓存优化的体现——将耗时最长的依赖安装延迟到容器首次启动时进行以加速镜像构建与推送。6.3 运行期声明与环境准备EXPOSE 8338 VOLUME [/root/.transformerlab/] WORKDIR /root/.transformerlab/src/ RUN chmod x ./run.sh ENTRYPOINT [/bin/bash, -c, /root/.transformerlab/src/install.sh install_dependencies exec /root/.transformerlab/src/run.sh]EXPOSE 8338声明容器监听端口VOLUME声明数据持久化挂载点与 Compose 中的命名卷对应。WORKDIR指向源码目录run.sh即服务启动脚本。ENTRYPOINT是运行期的核心容器每次启动时先执行install.sh install_dependencies检测 GPU 类型并安装带 CUDA/ROCm/CPU 后缀的 Python 依赖见 api/install.sh 第 398-524 行随后通过exec转交控制权给run.sh启动服务。6.4 install_dependencies 的 GPU 检测逻辑值得深入说明的是依赖安装阶段的 GPU 自适应逻辑api/install.sh 第 414-511 行检测到nvidia-smi且存在 NVIDIA GPU 时通过 conda 安装 CUDA 12.8.1 运行时并使用uv pip install .[nvidia]安装带 NVIDIA 扩展的依赖PyTorch 索引默认使用cu128若检测到 DGX Spark/etc/dgx-release含 DGX Spark或显式设置TLAB_FORCE_CUDA131则切换为cu130。检测到rocminfo时走 ROCm 分支.[rocm]。两者都未检测到则退化为 CPU 安装.[cpu]并提示安装 NVIDIA 驱动。这解释了为什么同一个 CUDA 镜像在无 GPU 的机器上也能启动——运行时会根据实际硬件自动降级。七、故障排查指南以下排查思路均可在部署脚本与模板源码中找到对应依据Docker 未运行确认 Docker 守护进程已启动Linux 上可执行sudo systemctl start docker。curl 缺失Linux/macOS 用包管理器安装sudo apt-get install curl或brew install curlWindows 下deploy.ps1会自动调用winget install --id curl.curl安装。envsubst 命令未找到Linux/macOS安装 GNU gettextsudo apt-get install gettext或 macOS 上brew install gettext brew link --force gettext。GPU 未被检测到确认宿主机存在受支持的 NVIDIA GPU、NVIDIA 驱动与 NVIDIA Container Toolkit 均已正确安装Compose 中deploy.resources.reservations段只有在 Toolkit 正常工作时才生效。无法获取最新版本号检查网络连通性及 GitHub API 是否可达临时规避方案是手动设置版本号——在执行脚本前export VERSION你的版本号脚本会直接使用该值继续deploy.sh 中的VERSION在生成模板前会被强制替换。Docker Compose 报错确认 Compose 版本兼容性并及时升级。Windows 上若docker compose up -d在镜像下载后长时间卡住很可能是 Docker 无法访问HOME目录打开生成的docker-compose.yml注释掉卷挂载段最后两行后重试volumes: - transformerlab_data:/root/.transformerlab/ # - C:/Users/username/.cache:/root/.cache # - C:/Users/username/.transformerlab/workspace:/root/.transformerlab/workspace若容器随即成功启动即可确认是宿主机目录权限问题。权限问题使用提升权限运行脚本——Linux/macOS 加sudoWindows 以管理员身份打开 PowerShell。八、日常运维日志、停止与数据清理查看日志docker compose logs transformerlab-api停止并移除容器docker compose down连同数据卷一起删除慎用会清空全部数据docker compose down -vdown -v会删除transformerlab_data命名卷即清除~/.transformerlab/下的模型、任务与配置数据操作前请务必确认数据已备份。九、自定义部署与进阶建议自定义镜像修改 Dockerfile.cuda 加入自定义实现后自行构建同时更新 docker-compose.yml.tpl 中的镜像引用或构建上下文build:指令使 Compose 使用你构建的镜像。调整运行参数可修改模板中的端口映射如9338:8338、卷挂载路径或 GPU 资源预留如将count: all改为具体数量count: 2以适应不同的硬件资源与多租户场景。多 GPU 与集群扩展Transformer Lab 本身支持通过计算提供商compute provider将任务分发到远程 GPU 集群容器化部署作为单机 GPU 入口可与 docs/task-execution 描述的 Job 分发体系配合使用。十、相关资源索引部署文档api/docker/gpu/nvidia/README.md镜像定义api/docker/gpu/nvidia/Dockerfile.cudaCompose 模板api/docker/gpu/nvidia/docker-compose.yml.tplLinux 部署脚本api/docker/gpu/nvidia/deploy.shWindows 部署脚本api/docker/gpu/nvidia/deploy.ps1服务安装器含 GPU 检测与依赖安装逻辑api/install.sh服务启动脚本端口、uvicorn 与 CUDA 路径处理api/run.shAMD ROCm 变体api/docker/gpu/amd/DockerfileCPU 变体api/docker/cpu/docker-compose.yml.tpl后端架构文档docs/backend.md、docs/task-execution/README.md至此你已具备从零开始在 NVIDIA GPU 环境下一键部署 Transformer Lab API 的完整能力理解四个部署文件的分工、掌握双平台脚本流程、读懂 Compose 模板与镜像构建的每一处细节并能独立定位部署过程中最常见的故障。【免费下载链接】transformerlab-appThe open source research environment for AI researchers to seamlessly train, evaluate, and scale models from local hardware to GPU clusters.项目地址: https://gitcode.com/GitHub_Trending/tr/transformerlab-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考