Voicebox Docker 部署实战从源码构建到 GPU 直通、持久化卷与云环境上线的完整指南【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox本文基于 Voicebox 仓库中的 Docker 部署规划文档 docs/plans/DOCKER_DEPLOYMENT.md 展开系统讲解如何在无头 Linux 服务器、GPU 主机与云平台上以容器方式部署 Voicebox涵盖快速启动、源码构建、NVIDIA/AMD GPU 直通、数据卷规划、环境变量、Compose 编排、故障排查与安全加固。读完本文你将掌握一套可复制的 Voicebox 容器化部署方案并能理解仓库中 Dockerfile、docker-compose.yml 与 docker-compose.rocm.yml 的实际实现细节。需要说明的适用前提该规划文档标注为Status: In Development for v0.2.0其中部分细节如ghcr.io/jamiepine/voicebox预构建镜像、8000端口、/root/.cache/huggingface缓存路径是当时的设计草案当前仓库已落地为“从源码构建”的三段式构建方案容器内端口为17493非 root 用户缓存路径为/home/voicebox/.cache/huggingface。本文会先完整保留文档中的方案内容再结合仓库现状逐项对照说明帮助你区分“规划中的方案”与“当前可直接执行的命令”。一、为什么用 Docker 部署 Voicebox文档给出的核心动机是Docker 支持让 Voicebox 更容易部署典型受益场景包括一致的环境Consistent Environments开发/预发/生产使用同一套镜像GPU 直通GPU Passthrough便捷接入 NVIDIA/AMD GPU服务器部署Server Deployments在无头 Linux 服务器上运行多用户场景Multi-User Setups为每个用户/团队隔离实例云平台部署Cloud Platforms部署到 AWS、GCP、Azure、DigitalOcean 等平台。这个定位在仓库中得到印证后端是 FastAPI 服务入口为backend.main:app前端是 React SPA二者可打进同一镜像由后端直接托管静态页面。backend/routes/health.py 中的根路由实现了这一点当构建产物frontend/index.html存在时返回 SPA 页面否则返回 JSON{message: voicebox API, ...}——这意味着 Docker 镜像天然具备“API Web UI 一体”的服务能力。二、快速启动2.1 使用预构建镜像文档方案文档推荐的三种镜像拉取方式# CPU-only version docker run -p 8000:8000 -v voicebox-data:/app/data \ ghcr.io/jamiepine/voicebox:latest # NVIDIA GPU version docker run --gpus all -p 8000:8000 -v voicebox-data:/app/data \ ghcr.io/jamiepine/voicebox:latest-cuda # AMD GPU version (experimental) docker run --device/dev/kfd --device/dev/dri -p 8000:8000 \ -v voicebox-data:/app/data \ ghcr.io/jamiepine/voicebox:latest-rocm启动后访问http://localhost:8000。当前仓库对照官方用户文档 docs/content/docs/overview/docker.mdx 将预构建镜像标记为 “Prebuilt Images (Coming Soon)”即ghcr.io/jamiepine/voicebox尚未正式发布。当前可行的快速启动方式是源码构建git clone https://gitcode.com/GitHub_Trending/voicebox1/voicebox.git cd voicebox docker compose up随后打开http://localhost:17600默认 compose 将容器内17493映射到宿主127.0.0.1:17600原因见下文第 5 节。首次构建需要几分钟编译前端 安装 Python 依赖之后依赖 Docker 层缓存可以快速启动。2.2 使用 Docker Compose文档方案文档给出了一份带 GPU 预留、模型缓存卷与完整环境变量的 Compose 示例version: 3.8 services: voicebox: image: ghcr.io/jamiepine/voicebox:latest-cuda ports: - 8000:8000 volumes: - voicebox-data:/app/data - huggingface-cache:/root/.cache/huggingface environment: - GPU_MEMORY_FRACTION0.8 # Use 80% of GPU memory - TTS_MODElocal - WHISPER_MODElocal deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] volumes: voicebox-data: huggingface-cache:执行docker compose up -d即可。2.3 当前仓库的默认 Compose可直接复制运行仓库根目录的 docker-compose.yml 是 CPU 默认配置其结构与文档方案一脉相承但做了更精细的工程化设计services: voicebox: build: . container_name: voicebox restart: unless-stopped ports: # Host-side moved to 17600 so the dev/installed Voicebox can keep 17493. # Container still listens on its native port internally. - 127.0.0.1:17600:17493 volumes: # Bind-mount for generated audio (customize the host path as needed) # Host side: ./output/ # Container side: /app/data/generations/ - ./output:/app/data/generations # Named volume for profiles, DB, cache (persists across container restarts) - voicebox-data:/app/data # HuggingFace model cache (so models arent re-downloaded on rebuild) - huggingface-cache:/home/voicebox/.cache/huggingface environment: - LOG_LEVELinfo - NUMBA_CACHE_DIR/tmp/numba_cache networks: - voicebox-net deploy: resources: limits: cpus: 4 memory: 8G networks: voicebox-net: driver: bridge volumes: voicebox-data: huggingface-cache:几个值得注意的设计决策均来自文件内注释宿主机端口选择17600容器内部仍然监听原生端口17493与桌面应用、开发模式保持一致宿主侧偏移是为了避免与本机已安装/开发中的 Voicebox 抢端口./output绑定挂载生成的音频直接落在宿主目录方便外部工具剪辑、发布访问huggingface-cache命名卷保证容器重建时模型不重复下载——这是 ML 容器部署中最容易被忽略、代价又很高的一点。三、从源码构建镜像3.1 基础 Dockerfile文档方案文档给出的最小可用 Dockerfile展示了 Voicebox 容器化部署的核心要素ffmpeg系统依赖、backend/requirements.txt、额外的 Qwen3-TTS 依赖、数据目录创建、端口暴露与 uvicorn 启动命令# Dockerfile FROM python:3.11-slim WORKDIR /app # Install system dependencies RUN apt-get update apt-get install -y \ git \ build-essential \ ffmpeg \ rm -rf /var/lib/apt/lists/* # Copy application COPY backend/ /app/backend/ COPY requirements.txt /app/ # Install Python dependencies RUN pip install --no-cache-dir -r requirements.txt RUN pip install --no-cache-dir githttps://github.com/QwenLM/Qwen3-TTS.git # Create data directory RUN mkdir -p /app/data # Expose port EXPOSE 8000 # Run server CMD [uvicorn, backend.main:app, --host, 0.0.0.0, --port, 8000]构建与运行docker build -t voicebox . docker run -p 8000:8000 -v $(pwd)/data:/app/data voicebox3.2 多阶段构建文档方案文档进一步给出“构建阶段/运行阶段分离”的优化版本用--target安装依赖后整目录拷入运行时缩小镜像体积# Dockerfile.optimized # Stage 1: Build dependencies FROM python:3.11-slim AS builder WORKDIR /build RUN apt-get update apt-get install -y \ git build-essential \ rm -rf /var/lib/apt/lists/* COPY backend/requirements.txt . RUN pip install --no-cache-dir --target/build/packages \ -r requirements.txt RUN pip install --no-cache-dir --target/build/packages \ githttps://github.com/QwenLM/Qwen3-TTS.git # Stage 2: Runtime FROM python:3.11-slim WORKDIR /app # Install only runtime dependencies RUN apt-get update apt-get install -y \ ffmpeg \ rm -rf /var/lib/apt/lists/* # Copy installed packages from builder COPY --frombuilder /build/packages /usr/local/lib/python3.11/site-packages/ # Copy application code COPY backend/ /app/backend/ # Create data directory RUN mkdir -p /app/data EXPOSE 8000 CMD [uvicorn, backend.main:app, --host, 0.0.0.0, --port, 8000]构建docker build -f Dockerfile.optimized -t voicebox:slim .3.3 当前仓库的三段式 Dockerfile实现现状仓库实际落地的 Dockerfile 把文档中“分离构建与运行时”的思想扩展为三段式构建并且用构建参数build ARG统一了 CPU 与 ROCm 两种变体阶段基础镜像职责Stage 1frontendoven/bun:1用 Bun Vite 编译 Web 前端web/工作区并处理 Windows CRLF 检出导致的 package.json 匹配问题Stage 2backend-builderpython:3.11-slim按PYTORCH_VARIANT参数安装 PyTorchcpu 或 rocm 全部 Python 依赖产物装入/install前缀Stage 3 运行时python:3.11-slim只装ffmpeg/curl/gosu拷入 Python 包、后端代码与前端产物关键实现细节构建参数化 GPU 变体顶层ARG PYTORCH_VARIANTcpuROCm 变体时通过pip install --index-url https://download.pytorch.org/whl/rocm${ROCM_VERSION} torch torchaudio并把 pip 全局索引改为 ROCm 源默认ROCM_VERSION6.3RDNA4 需设为7.2。这样同一个 Dockerfile 就能产出 CPU 与 AMD GPU 两种镜像无需像文档方案那样维护两份独立 Dockerfile非 root 运行镜像创建voicebox系统用户数据目录/app/data/generations、/app/data/profiles、/app/data/cache预建并归其所有落实了文档安全章节 “Dont Run as Root” 的建议健康检查内置HEALTHCHECK --interval30s --timeout10s --retries3 --start-period60s CMD curl -f http://localhost:17493/health || exit 1与文档监控章节的 healthcheck 设计一致且start-period给到了 60 秒以容纳模型加载自定义入口点ENTRYPOINT [/usr/local/bin/entrypoint.sh]指向 scripts/rocm-entrypoint.sh——该脚本在启动时自动探测挂载的 GPU 设备节点/dev/kfd、/dev/dri/render*把voicebox用户加入对应设备组找不到组时自动创建gpu$gid最后用gosu降权运行 uvicorn。这意味着 ROCm 部署不再需要手工配置RENDER_GID/VIDEO_GID入口命令CMD [uvicorn, backend.main:app, --host, 0.0.0.0, --port, 17493]。对应地docker-compose.yml 头部注释也给出了两种构建/启动方式# CPU (default) docker compose up --build # ROCm (AMD GPU) docker compose -f docker-compose.yml -f docker-compose.rocm.yml up --build四、GPU 支持4.1 NVIDIA GPUCUDA文档方案文档给出的 CUDA 基础镜像 DockerfileFROM nvidia/cuda:12.1.0-runtime-ubuntu22.04 # Install Python RUN apt-get update apt-get install -y \ python3.11 python3-pip git ffmpeg \ rm -rf /var/lib/apt/lists/* WORKDIR /app # Install PyTorch with CUDA support COPY backend/requirements.txt . RUN pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # Install other dependencies RUN pip3 install -r requirements.txt RUN pip3 install githttps://github.com/QwenLM/Qwen3-TTS.git COPY backend/ /app/backend/ EXPOSE 8000 CMD [uvicorn, backend.main:app, --host, 0.0.0.0, --port, 8000]运行与 Compose 声明docker run --gpus all -p 8000:8000 \ -v voicebox-data:/app/data \ voicebox:cudaservices: voicebox: image: voicebox:cuda deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu]官方用户文档 docs/content/docs/overview/docker.mdx 对当前仓库的说明与之一致先安装 NVIDIA Container Toolkit再在 compose 中加入相同的deploy.resources.reservations.devices声明即可。4.2 AMD GPUROCm文档方案 仓库现状文档中的 ROCm Dockerfile 核心是基于rocm/dev-ubuntu-22.04:6.0安装 ROCm 版 PyTorch并设置HSA_OVERRIDE_GFX_VERSION10.3.0、ROCM_PATH/opt/rocm。运行需要透传 GPU 设备docker run --device/dev/kfd --device/dev/dri \ --group-add video --ipchost --cap-addSYS_PTRACE \ --security-opt seccompunconfined \ -p 8000:8000 -v voicebox-data:/app/data \ voicebox:rocm当前仓库把 ROCm 支持做成了一个 Compose overlay——docker-compose.rocm.yml 与基础 compose 叠加使用-f docker-compose.yml -f docker-compose.rocm.yml它只声明增量构建参数PYTORCH_VARIANT: rocm与ROCM_VERSION: ${ROCM_VERSION:-6.3}、设备/dev/kfd与/dev/dri以及一组针对 AMD 运行时的环境变量services: voicebox: build: context: . args: PYTORCH_VARIANT: rocm ROCM_VERSION: ${ROCM_VERSION:-6.3} devices: - /dev/kfd - /dev/dri environment: # HSA_OVERRIDE_GFX_VERSION forces the ROCm runtime to treat the GPU as a # specific GFX version when auto-detection fails or the GPU is newer than # the ROCm release: # RDNA4 / RX 9000 series: 12.0.0 (requires ROCM_VERSION7.2) # RDNA3 / RX 7000 series / Strix Halo: 11.0.0 # RDNA2 / RX 6000 series: 10.3.0 # RDNA1 / RX 5000 series: 10.1.0 # Vega / GCN5: 9.0.0 - HSA_OVERRIDE_GFX_VERSION${HSA_OVERRIDE_GFX_VERSION:-} # Tune the ROCm memory allocator - PYTORCH_HIP_ALLOC_CONFgarbage_collection_threshold:0.8,max_split_size_mb:512 # Redirect MIOpen kernel cache to a writable, persistent directory. - MIOPEN_USER_DB_PATH/app/data/cache/miopen_db - MIOPEN_CUSTOM_CACHE_DIR/app/data/cache/miopen_cache # Use fast heuristics for kernel selection instead of exhaustive benchmarking. - MIOPEN_FIND_MODEFAST这些环境变量背后的问题都可在后端源码中找到对应HSA_OVERRIDE_GFX_VERSION的自动处理backend/app.py 启动时会先“消毒”一个空的HSA_OVERRIDE_GFX_VERSION空值会污染 ROCm HSA 运行时若未显式设置则通过rocminfo探测 AMD GPU对老卡自动回退为10.3.0RDNA2 兼容对已有原生支持的新卡则跳过设置。也就是说 overlay 中留空${HSA_OVERRIDE_GFX_VERSION:-}是刻意为之——把自动探测权交给应用层MIOpen 缓存重定向文件注释解释了不重定向的后果——新容器中 MIOpen 可能写不了内核缓存而抛出miopenStatusUnknownError将其落到/app/data/cache/下可随voicebox-data卷持久化MIOPEN_FIND_MODEFAST注释指出在 RDNA4 上穷举模式会尝试分配失败的内核导致每次生成时系统卡顿FAST 启发式可规避。配合 scripts/rocm-entrypoint.sh 的设备组自动加入逻辑ROCm 容器无需宿主侧手动--group-add细节这是相比文档原始方案的一次明显简化。4.3 GPU 状态在 API 中如何体现/health端点backend/routes/health.py会汇报gpu_available、gpu_type含CUDA (...)或ROCm (...)的设备名、vram_used_mb、backend_variantcpu/cuda/rocm/xpu、model_loaded、model_downloaded与gpu_compatibility_warning等字段。部署后你可以通过它确认 GPU 是否被容器正确识别而不必依赖nvidia-smi等宿主工具。五、数据卷规划文档将数据卷分为三类用途5.1 必需卷docker run -v voicebox-data:/app/data \ # Profiles, generations, history -v huggingface-cache:/root/.cache/huggingface \ # Downloaded models -p 8000:8000 voicebox注意文档中的/root/.cache/huggingface对应“容器以 root 运行”的假设当前镜像改为非 root 用户后docker-compose.yml 中挂载的是/home/voicebox/.cache/huggingface。5.2 开发态挂载热重载docker run -v $(pwd)/backend:/app/backend \ # Live code changes -v voicebox-data:/app/data \ -e RELOADtrue \ -p 8000:8000 voicebox5.3 自定义模型存储docker run -v /path/to/models:/models \ -e MODELS_DIR/models \ -v voicebox-data:/app/data \ -p 8000:8000 voicebox源码层面的印证backend/config.py 在模块导入时读取VOICEBOX_MODELS_DIR环境变量并直接映射到HF_HUB_CACHE使所有 HuggingFace 下载落到指定目录数据目录内则固定划分为profiles、generations、captures、cache、models等子目录SQLite 数据库voicebox.db位于数据目录根部。这与 Dockerfile 中预创建的/app/data/generations、/app/data/profiles、/app/data/cache目录一一对应。官方文档 docs/content/docs/overview/docker.mdx 给出的卷对照表Volume容器内路径用途./output/app/data/generations生成的音频绑定挂载宿主侧易访问voicebox-data/app/data语音档案、数据库、缓存huggingface-cache/home/voicebox/.cache/huggingface已下载模型跨重建保留六、环境变量6.1 文档规划的变量表docs/plans/DOCKER_DEPLOYMENT.md 中的完整变量清单变量默认值说明TTS_MODElocalTTS 提供方local、remoteTTS_REMOTE_URL-远程 TTS 服务地址WHISPER_MODElocalWhisper 提供方local、openai-api、remoteWHISPER_REMOTE_URL-远程 Whisper 服务地址OPENAI_API_KEY-OpenAI API Key使用 OpenAI Whisper 时GPU_MEMORY_FRACTION0.9GPU 显存使用比例0.0–1.0DATA_DIR/app/data档案/生成物目录MODELS_DIR/app/models本地模型目录LOG_LEVELinfo日志级别debug、info、warning、errorRELOADfalse开发热重载开关用法示例docker run -e TTS_MODElocal \ -e WHISPER_MODEopenai-api \ -e OPENAI_API_KEYsk-... \ -e GPU_MEMORY_FRACTION0.8 \ -e LOG_LEVELinfo \ -p 8000:8000 voicebox由于文档整体处于 In Development 状态上表应视为规划中的接口约定实际生效情况以当前代码为准。6.2 当前仓库已确认的变量结合 docker-compose.yml、backend/config.py 与 backend/app.py以下变量在当前实现中可以确认变量出处作用LOG_LEVELcompose 文件日志级别默认infoVOICEBOX_MODELS_DIRbackend/config.py重写HF_HUB_CACHE自定义模型下载目录VOICEBOX_CORS_ORIGINSbackend/app.py追加 CORS 允许源逗号分隔NUMBA_CACHE_DIRcompose 文件Numba 编译缓存目录容器内指向/tmpHSA_OVERRIDE_GFX_VERSIONROCm overlay强制 ROCm 运行时按指定 GFX 版本处理 GPUPYTORCH_HIP_ALLOC_CONFROCm overlay调优 PyTorch ROCm 显存分配器MIOPEN_USER_DB_PATH/MIOPEN_CUSTOM_CACHE_DIRROCm overlayMIOpen 内核缓存持久化路径MIOPEN_FIND_MODEROCm overlayFAST模式避免穷举内核选择VOICEBOX_BACKEND_VARIANTbackend/routes/health.py覆盖/health汇报的 backend variantVOICEBOX_CLOUD_URL/VOICEBOX_CLOUD_API_URLbackend/config.py本地开发时覆盖 Cloud 端点七、Docker Compose 完整示例7.1 生产部署文档方案带健康检查与自动重启的单机生产配置# docker-compose.prod.yml version: 3.8 services: voicebox: image: ghcr.io/jamiepine/voicebox:latest-cuda container_name: voicebox restart: unless-stopped ports: - 8000:8000 volumes: - voicebox-data:/app/data - huggingface-cache:/root/.cache/huggingface environment: - TTS_MODElocal - WHISPER_MODElocal - GPU_MEMORY_FRACTION0.8 - LOG_LEVELinfo deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] healthcheck: test: [CMD, curl, -f, http://localhost:8000/health] interval: 30s timeout: 10s retries: 3 start_period: 40s volumes: voicebox-data: driver: local huggingface-cache: driver: local运行docker compose -f docker-compose.prod.yml up -d。其健康检查语义已由 Dockerfile 内置的HEALTHCHECK与 backend/routes/health.py 的GET /health实现支撑——镜像自带 curl 依赖专门用于该探测。7.2 开发部署文档方案# docker-compose.dev.yml version: 3.8 services: voicebox: build: context: . dockerfile: Dockerfile ports: - 8000:8000 volumes: - ./backend:/app/backend:ro - voicebox-data:/app/data - huggingface-cache:/root/.cache/huggingface environment: - RELOADtrue - LOG_LEVELdebug - TTS_MODElocal command: uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload volumes: voicebox-data: huggingface-cache:7.3 多服务栈文档方案Voicebox Nginx 反代 Prometheus 监控的组合# docker-compose.stack.yml version: 3.8 services: # Main Voicebox app voicebox: image: ghcr.io/jamiepine/voicebox:latest-cuda restart: unless-stopped volumes: - voicebox-data:/app/data - huggingface-cache:/root/.cache/huggingface environment: - TTS_MODElocal - WHISPER_MODElocal deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] # Nginx reverse proxy nginx: image: nginx:alpine ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro - ./ssl:/etc/nginx/ssl:ro depends_on: - voicebox # Prometheus monitoring (optional) prometheus: image: prom/prometheus ports: - 9090:9090 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml - prometheus-data:/prometheus volumes: voicebox-data: huggingface-cache: prometheus-data:官方文档 docs/content/docs/overview/docker.mdx 对反代给出了带 TLS 与基础认证的 nginx 参考配置proxy_pass http://127.0.0.1:17493并强调Voicebox API 没有内置认证只应暴露给可信网络或置于带认证的反代之后。八、云平台部署8.1 AWS EC2文档方案启动 GPU 实例g4dn.xlarge或p3.2xlarge安装 Docker nvidia-dockerAmazon Linux 2 示例sudo yum install -y docker sudo systemctl start docker distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \ sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update sudo apt-get install -y nvidia-docker2 sudo systemctl restart docker部署docker run --gpus all -d -p 80:8000 \ -v voicebox-data:/app/data \ --restart unless-stopped \ ghcr.io/jamiepine/voicebox:latest-cuda8.2 DigitalOcean文档方案GPU Droplet Docker# Create droplet via CLI doctl compute droplet create voicebox \ --size gpu-h100x1-80gb \ --image ubuntu-22-04-x64 \ --region nyc3 # SSH and deploy ssh rootdroplet-ip curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.sh docker run --gpus all -d -p 80:8000 voicebox:cuda8.3 Google Cloud Run仅 CPU文档方案# Build and push docker build -t gcr.io/your-project/voicebox . docker push gcr.io/your-project/voicebox # Deploy to Cloud Run gcloud run deploy voicebox \ --image gcr.io/your-project/voicebox \ --platform managed \ --region us-central1 \ --memory 4Gi \ --cpu 2 \ --port 80008.4 Fly.io文档方案fly.toml配置app voicebox [build] image ghcr.io/jamiepine/voicebox:latest [[services]] http_checks [] internal_port 8000 protocol tcp [[services.ports]] port 80 handlers [http] [[services.ports]] port 443 handlers [tls, http] [mounts] source voicebox_data destination /app/data部署fly launch fly deploy。使用上述平台配置时请同步将internal_port与端口映射更新为当前镜像的17493并保证模型缓存卷持久化否则实例重建后需重新下载模型。九、故障排查文档列出的五类典型问题及处理方式9.1 GPU 未识别NVIDIAdocker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi失败则重装 nvidia-docker2。AMDdocker run --rm --device/dev/kfd --device/dev/dri rocm/dev-ubuntu-22.04:6.0 rocminfo部署后可辅以GET /health的gpu_type字段二次确认见 4.3 节。9.2 权限错误容器无法写入卷时用宿主用户身份运行docker run --user $(id -u):$(id -g) -v $(pwd)/data:/app/data voicebox当前镜像的默认缓解措施是数据目录在构建期即chown给voicebox用户Dockerfile 第 95–97 行且voicebox-data卷由非 root 进程读写可显著减少此类问题。9.3 内存不足降低 GPU 显存占用docker run -e GPU_MEMORY_FRACTION0.5 voicebox或回退 CPUdocker run -e DEVICEcpu voicebox。另外若容器被宿主 OOM killer 杀死应调高 compose 中的deploy.resources.limits.memory默认 8G官方文档建议同时加载多个引擎时给到 16G 以上。9.4 模型下载失败确保 HuggingFace 缓存卷可写文档写法docker run -v huggingface-cache:/root/.cache/huggingface voicebox或直接复用宿主缓存docker run -v ~/.cache/huggingface:/root/.cache/huggingface voicebox若容器重建后每次都重新下载模型根因通常就是缺少huggingface-cache卷官方文档 Troubleshooting 一节同样强调此点。9.5 端口占用docker run -p 8080:8000 voicebox # Use port 8080 instead当前仓库的对应做法是改 compose 的宿主侧端口如127.0.0.1:8080:17493容器内端口保持不变。9.6 UI 显示为 JSON仓库补充如果打开页面看到的是{message: voicebox API, ...}而不是 Web UI说明前端构建阶段失败、镜像中缺少frontend/index.html——backend/routes/health.py 的根路由会在这种情况下降级返回 JSON。用docker compose build --no-cache重建并检查 “Build frontend” 阶段的输出即可定位。十、安全最佳实践文档提出的四项措施其中前两项已在当前镜像中落地不要以 root 运行——文档建议的 Dockerfile 片段RUN useradd -m -u 1000 voicebox USER voicebox当前 Dockerfile 的实际实现groupadd -r voicebox useradd -r -g voicebox -m -s /bin/bash voicebox运行时通过 gosu 从 root 降权见 scripts/rocm-entrypoint.sh用 Secrets 管理 API Key——不要把密钥写进 composeecho sk-your-key | docker secret create openai_key - docker service create \ --secret openai_key \ -e OPENAI_API_KEY_FILE/run/secrets/openai_key \ voicebox网络隔离——多容器场景使用 internal 网络services: voicebox: networks: - internal nginx: networks: - internal - external ports: - 80:80 networks: internal: internal: true external:资源限制——防止资源耗尽services: voicebox: deploy: resources: limits: cpus: 4 memory: 8G reservations: cpus: 2 memory: 4G默认 docker-compose.yml 已内置cpus: 4/memory: 8G的 limits。此外当前仓库还实现了两条文档未展开的安全边界默认只绑定127.0.0.1compose 端口为127.0.0.1:17600:17493以及默认只允许本地来源的 CORS可用VOICEBOX_CORS_ORIGINS扩展见 backend/app.py。十一、性能调优文档给出的三个方向11.1 GPU 显存管理# Use 80% of GPU (default 90%) docker run -e GPU_MEMORY_FRACTION0.8 voicebox # Allow GPU memory growth (prevents OOM) docker run -e TF_FORCE_GPU_ALLOW_GROWTHtrue voiceboxAMD 场景下当前仓库对应的手段是 ROCm overlay 中的PYTORCH_HIP_ALLOC_CONFgarbage_collection_threshold:0.8,max_split_size_mb:512调优 PyTorch HIP 分配器。11.2 模型预下载缓存预热在正式启动前把模型拉进命名卷# Download models first docker run --rm -v huggingface-cache:/root/.cache/huggingface \ voicebox python -c from transformers import WhisperProcessor, WhisperForConditionalGeneration WhisperProcessor.from_pretrained(openai/whisper-base) WhisperForConditionalGeneration.from_pretrained(openai/whisper-base) # Then run normally docker run -v huggingface-cache:/root/.cache/huggingface voicebox11.3 多 WorkerCMD [uvicorn, backend.main:app, --host, 0.0.0.0, --port, 8000, --workers, 4]从源码结构看Voicebox 后端在进程内管理模型加载与任务队列见 backend/services/generation.py、backend/services/task_queue.py多 worker 会复制进程内的状态与显存占用是否适合生产环境建议在测试环境验证吞吐与显存占用后再定。十二、监控与日志12.1 健康检查内置端点curl http://localhost:8000/healthDocker 健康检查healthcheck: test: [CMD, curl, -f, http://localhost:8000/health] interval: 30s timeout: 10s retries: 3/health的返回结构由 backend/models.py 的HealthResponse定义包含status、model_loaded、model_downloaded、model_size、gpu_available、gpu_type、vram_used_mb、backend_type、backend_variant、gpu_compatibility_warning另有/health/filesystem见 backend/routes/health.py可检查数据目录存在性、可写性与磁盘剩余空间低于 500MB 会报不健康适合纳入外部监控。12.2 Prometheus 指标文档建议在backend/main.py中接入from prometheus_fastapi_instrumentator import Instrumentator Instrumentator().instrument(app).expose(app)之后由 Prometheus 抓取/metrics。这属于规划建议当前后端代码中尚未内置 instrumentator 依赖落地前需自行安装该库。12.3 日志docker logs -f voicebox # Or with compose docker compose logs -f voicebox配合LOG_LEVELdebug可在开发态获取更详细的输出。十三、后续路线与深入入口文档 “Next Steps” 列出的未完成项可视为该能力的边界说明发布官方镜像到 GitHub Container Registry提供 Kubernetes Helm chart创建 Docker Desktop 扩展增加自动化漏洞扫描支持 ARM64 构建树莓派 / Apple Silicon。如果你想继续深入当前仓库的 Docker 实现建议按以下顺序阅读文件关注点Dockerfile三段式构建、PYTORCH_VARIANT/ROCM_VERSION构建参数、非 root 用户、HEALTHCHECKdocker-compose.ymlCPU 默认配置、端口策略、卷与资源限制docker-compose.rocm.ymlROCm overlay设备透传、GFX 覆盖、MIOpen 调优scripts/rocm-entrypoint.sh设备组自动加入与 gosu 降权backend/config.py数据目录、模型目录VOICEBOX_MODELS_DIR→HF_HUB_CACHEbackend/routes/health.py/health、/health/filesystem、SPA 托管逻辑docs/content/docs/overview/docker.mdx面向用户的官方部署文档端口、安全、排错【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考