Docker 安装

环境要求

使用 Linux NVIDIA GPU 主机，安装 Docker、兼容的显卡驱动和 NVIDIA Container Toolkit (opens in a new tab)。 本镜像不要求主机另外安装 CUDA Toolkit，驱动需支持所选镜像运行库和显卡本身。

构建当前代码

在填写 config.yaml 凭据之前，从干净的公开代码目录构建。 Dockerfile 复制当前目录及配置，不会另行从 GitHub 克隆不同版本。 .dockerignore 排除本地缓存、输出和私人笔记，但不会清除已修改配置里的凭据。

docker build -t videolingo .

默认使用 nvidia/cuda:12.8.1-cudnn-runtime-ubuntu24.04、Python 3.12 和 PyTorch cu128。匹配的 CUDA 12.6 方案：

docker build --build-arg CUDA_VERSION=12.6.3 -t videolingo:cu126 .

这会同时选择 12.6.3-cudnn-runtime-ubuntu24.04 和 cu126。构建时不需要 GPU： setup_env.py 把明确的构建选择传给与主机共用的 installer.py。 其他 CUDA_VERSION 值会被拒绝。

两个方案均采用 Torch/torchaudio 2.8.0、torchvision 0.23.0 和相同的 requirements.txt 约束。镜像是 Linux，本地识别默认使用 Qwen3-ASR + ForcedAligner， 通过官方 qwen-asr 包（Transformers 4.57、Hub <1）在 CUDA 上运行。镜像内不安装 WhisperX，它也不是安装器选项。若要自己追加（例如在派生镜像中），见 WhisperX（手动安装）。Demucs 4.1 使用正常依赖解析。 安装器在镜像构建时自动下载 FFmpeg 和 ffprobe。Ubuntu 提供 Noto CJK 字体和图像运行库。 只有自行追加 WhisperX 时才需要额外安装 FFmpeg 共享库。

启动并保留数据

docker run -d --name videolingo --gpus all -p 127.0.0.1:8501:8501 -v videolingo-output:/app/output -v videolingo-history:/app/history -v videolingo-models:/app/_model_cache -v videolingo-cache:/app/.cache -v videolingo-hf:/root/.cache/huggingface videolingo

打开 http://localhost:8501。命名卷让输出、历史和模型/识别缓存在替换容器后保留。 如需保留配置和术语表，另行挂载本地 config.yaml 和 custom_terms.xlsx。 挂载前文件必须存在，侧栏修改配置需要写权限。使用 cu126 时，将镜像名替换为 videolingo:cu126。

模型（Qwen3-ASR 1.7B/0.6B 与 ForcedAligner，共数 GB）在首次识别时下载到 Hugging Face 缓存卷，不包含在构建镜像内。执行 docker stop videolingo 停止。 上述端口仅监听本机，远程访问需要明确配置监听地址及访问控制。

验证范围

Dockerfile 在构建时执行共用安装检查和 pip check。源码检查不等于已经成功构建 镜像或完成 GPU 处理。第三方预构建镜像不保证与当前代码的依赖一致。