Whisper Docker 配置：在 Docker 中运行 OpenAI Whisper 的完整指南

简介

在 Docker 容器中运行 OpenAI Whisper 可以获得一致、隔离的环境，简化部署并减少「在我机器上能跑」的问题。借助 Docker，你可以：

随处部署 – 在任何支持 Docker 的平台上运行同一镜像
隔离依赖 – 避免与系统包冲突
轻松扩展 – 启动多个容器并行处理
版本可控 – 固定 Whisper 版本与配置
简化上线 – 一条命令拉起整套环境

本指南涵盖在 Docker 中搭建 Whisper 所需的全部内容：从基础容器到支持 GPU、可上生产的配置。

为什么用 Docker 运行 Whisper？

容器化的优势

1. 一致性

开发、预发布与生产环境一致
减少依赖冲突
构建可复现

2. 可移植性

凡有 Docker 即可运行
服务器间迁移更简单
不绑定特定云厂商

3. 隔离性

不污染宿主机
卸载干净（删除容器即可）
通过隔离提升安全性

4. 可扩展性

水平扩展方便
可在多容器间做负载均衡
可为每个容器设置资源上限

5. 与 DevOps 契合

易于接入 CI/CD
便于对接 Kubernetes
适合云上容器服务

前置条件

开始前请确认已具备：

已安装 Docker（20.10 及以上）
Docker Compose（可选，多容器场景）
NVIDIA Docker（可选，GPU 场景）
基本的 Docker 命令知识

安装 Docker

macOS：

# Install Docker Desktop from docker.com
# Or using Homebrew
brew install --cask docker

Ubuntu/Debian：

sudo apt update
sudo apt install docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker

Windows： 从 docker.com 下载 Docker Desktop。

验证安装

docker --version
docker-compose --version

Whisper 基础 Dockerfile

先从一个简单的 Whisper Dockerfile 开始：

FROM python:3.10-slim

# Set working directory
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
RUN pip install --no-cache-dir \
    openai-whisper \
    torch \
    torchaudio

# Copy application code (if you have custom scripts)
# COPY . .

# Set default command
CMD ["whisper", "--help"]

构建镜像

docker build -t whisper:latest .

运行基础容器

docker run --rm whisper:latest whisper --version

带 API 服务的 Dockerfile

生产环境通常需要 API 服务。下面是一个更完整的 Dockerfile：

FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
RUN pip install --no-cache-dir \
    openai-whisper \
    torch \
    torchaudio \
    fastapi \
    uvicorn \
    python-multipart

# Create directories for audio and output
RUN mkdir -p /app/audio /app/output

# Copy application code
COPY app.py .
COPY requirements.txt .

# Expose API port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# Run API server
CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

API 服务示例（app.py）

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import JSONResponse
import whisper
import os

app = FastAPI()

# Load Whisper model (can be configured via env)
model_name = os.getenv("WHISPER_MODEL", "base")
model = whisper.load_model(model_name)

@app.get("/health")
def health():
    return {"status": "healthy"}

@app.post("/transcribe")
async def transcribe(file: UploadFile = File(...)):
    # Save uploaded file
    file_path = f"/app/audio/{file.filename}"
    with open(file_path, "wb") as f:
        content = await file.read()
        f.write(content)
    
    # Transcribe
    result = model.transcribe(file_path)
    
    # Clean up
    os.remove(file_path)
    
    return JSONResponse(content={
        "text": result["text"],
        "language": result["language"]
    })

requirements.txt

fastapi==0.104.1
uvicorn[standard]==0.24.0
python-multipart==0.0.6
openai-whisper
torch
torchaudio

Docker Compose 配置

若需多服务完整栈，请使用 Docker Compose：

docker-compose.yml

version: '3.8'

services:
  whisper-api:
    build: .
    container_name: whisper-api
    ports:
      - "8000:8000"
    volumes:
      - ./audio:/app/audio
      - ./output:/app/output
    environment:
      - WHISPER_MODEL=base
      - CUDA_VISIBLE_DEVICES=0
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  # Optional: Redis for queue management
  redis:
    image: redis:7-alpine
    container_name: whisper-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  redis-data:

使用 Docker Compose 启动

# Start services
docker-compose up -d

# View logs
docker-compose logs -f whisper-api

# Stop services
docker-compose down

Docker 中的 GPU 支持

使用 GPU 加速需要 NVIDIA 容器工具包（原 NVIDIA Docker）运行时：

安装 NVIDIA Docker

Ubuntu/Debian：

# Add NVIDIA Docker repository
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

# Install
sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

支持 GPU 的 Dockerfile

FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04

WORKDIR /app

# Install Python
RUN apt-get update && apt-get install -y \
    python3.10 \
    python3-pip \
    ffmpeg \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies with CUDA support
RUN pip3 install --no-cache-dir \
    openai-whisper \
    torch \
    torchaudio \
    --index-url https://download.pytorch.org/whl/cu118

# Install API dependencies
RUN pip3 install --no-cache-dir \
    fastapi \
    uvicorn \
    python-multipart

COPY app.py .
EXPOSE 8000

CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

使用 GPU 运行

# Using docker run
docker run --gpus all -p 8000:8000 whisper-gpu:latest

# Using docker-compose

带 GPU 的 docker-compose.yml

version: '3.8'

services:
  whisper-api:
    build: .
    container_name: whisper-api-gpu
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    ports:
      - "8000:8000"
    volumes:
      - ./audio:/app/audio
      - ./output:/app/output
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

面向生产的优化 Dockerfile

下面是带优化、可上生产的 Dockerfile（多阶段构建）：

# Multi-stage build for smaller image
FROM python:3.10-slim as builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

# Final stage
FROM python:3.10-slim

WORKDIR /app

# Install runtime dependencies only
RUN apt-get update && apt-get install -y \
    ffmpeg \
    curl \
    && rm -rf /var/lib/apt/lists/* \
    && apt-get clean

# Copy Python packages from builder
COPY --from=builder /root/.local /root/.local

# Make sure scripts in .local are usable
ENV PATH=/root/.local/bin:$PATH

# Create non-root user for security
RUN useradd -m -u 1000 whisper && \
    mkdir -p /app/audio /app/output && \
    chown -R whisper:whisper /app

USER whisper

# Copy application code
COPY --chown=whisper:whisper app.py .
COPY --chown=whisper:whisper requirements.txt .

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

多阶段构建的好处

镜像更小 – 最终镜像仅含运行时依赖
构建更快 – 编译依赖可单独缓存
更安全 – 非 root 用户、攻击面更小

环境变量配置

通过环境变量让 Docker 配置可切换：

Dockerfile

FROM python:3.10-slim

WORKDIR /app

RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir \
    openai-whisper \
    torch \
    torchaudio \
    fastapi \
    uvicorn \
    python-multipart

COPY app.py .

# Environment variables with defaults
ENV WHISPER_MODEL=base
ENV MAX_FILE_SIZE=100MB
ENV LOG_LEVEL=INFO

EXPOSE 8000

CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

带环境变量的 docker-compose.yml

version: '3.8'

services:
  whisper-api:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./audio:/app/audio
      - ./output:/app/output
    environment:
      - WHISPER_MODEL=small
      - MAX_FILE_SIZE=200MB
      - LOG_LEVEL=DEBUG
      - CUDA_VISIBLE_DEVICES=0
    env_file:
      - .env
    restart: unless-stopped

.env 文件

WHISPER_MODEL=small
MAX_FILE_SIZE=200MB
LOG_LEVEL=INFO
CUDA_VISIBLE_DEVICES=0

卷（Volume）管理

合理的卷配置可保证数据持久化：

带卷的 docker-compose.yml

version: '3.8'

services:
  whisper-api:
    build: .
    ports:
      - "8000:8000"
    volumes:
      # Bind mount for development
      - ./audio:/app/audio
      - ./output:/app/output
      
      # Named volume for model cache (persists across containers)
      - whisper-models:/root/.cache/whisper
      
      # Config volume
      - ./config:/app/config:ro
    environment:
      - WHISPER_MODEL=base

volumes:
  whisper-models:
    driver: local

好处

模型缓存 – 下载一次，多容器复用
数据持久 – 容器重启后输出仍在
配置灵活 – 无需重建镜像即可更新配置

健康检查与监控

带健康检查的 Dockerfile

FROM python:3.10-slim

WORKDIR /app

RUN apt-get update && apt-get install -y \
    ffmpeg \
    curl \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir \
    openai-whisper \
    fastapi \
    uvicorn

COPY app.py .

# Health check endpoint
HEALTHCHECK --interval=30s \
            --timeout=10s \
            --start-period=40s \
            --retries=3 \
            CMD curl -f http://localhost:8000/health || exit 1

EXPOSE 8000
CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

健康检查端点

from fastapi import FastAPI
import whisper

app = FastAPI()
model = whisper.load_model("base")

@app.get("/health")
def health():
    try:
        # Quick test transcription
        return {"status": "healthy", "model": "base"}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}, 503

常见使用场景

场景一：开发环境

version: '3.8'

services:
  whisper-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app
      - /app/__pycache__
    ports:
      - "8000:8000"
    environment:
      - WHISPER_MODEL=tiny
      - DEBUG=true
    command: uvicorn app.py:app --reload --host 0.0.0.0 --port 8000

场景二：带队列的生产环境

version: '3.8'

services:
  whisper-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - REDIS_URL=redis://redis:6379
      - WHISPER_MODEL=small
    depends_on:
      - redis
      - worker

  worker:
    build: .
    command: python worker.py
    environment:
      - REDIS_URL=redis://redis:6379
      - WHISPER_MODEL=small
    volumes:
      - ./audio:/app/audio
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  redis-data:

场景三：多模型部署

version: '3.8'

services:
  whisper-fast:
    build: .
    ports:
      - "8001:8000"
    environment:
      - WHISPER_MODEL=tiny
      - PORT=8000

  whisper-balanced:
    build: .
    ports:
      - "8002:8000"
    environment:
      - WHISPER_MODEL=base
      - PORT=8000

  whisper-accurate:
    build: .
    ports:
      - "8003:8000"
    environment:
      - WHISPER_MODEL=large
      - PORT=8000

最佳实践

1. 使用明确版本的基础镜像

不推荐：

FROM python:latest

推荐：

FROM python:3.10-slim

2. 减少镜像层

不推荐：

RUN apt-get update
RUN apt-get install -y ffmpeg
RUN apt-get install -y git

推荐：

RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    && rm -rf /var/lib/apt/lists/*

3. 使用 .dockerignore

创建 .dockerignore：

__pycache__
*.pyc
*.pyo
*.pyd
.Python
.env
.venv
venv/
.git
.gitignore
README.md
*.md
.DS_Store

4. 设置资源限制

services:
  whisper-api:
    build: .
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

5. 使用健康检查

生产容器应始终配置健康检查：

HEALTHCHECK --interval=30s --timeout=10s CMD curl -f http://localhost:8000/health || exit 1

6. 非 root 用户

RUN useradd -m -u 1000 whisper
USER whisper

7. 缓存模型

用卷缓存已下载模型：

volumes:
  - whisper-models:/root/.cache/whisper

常见问题排查

问题一：容器立刻退出

现象： 启动后马上结束

处理：

# Check logs
docker logs <container-id>

# Run interactively to debug
docker run -it whisper:latest /bin/bash

问题二：GPU 不可用

现象： 容器内检测不到 GPU

处理：

# Verify NVIDIA Docker
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

# Check runtime
docker info | grep -i runtime

问题三：内存不足

现象： 容器 OOM

处理：

# Increase memory limit
deploy:
  resources:
    limits:
      memory: 8G

问题四：模型下载慢或每次重启都下载

现象： 每次启动都重新拉模型

处理：

# Use volume for model cache
volumes:
  - whisper-models:/root/.cache/whisper

问题五：权限拒绝

现象： 无法写入卷

处理：

# Fix permissions in Dockerfile
RUN chown -R whisper:whisper /app

性能优化

1. 预加载模型

在 Dockerfile 构建阶段下载模型：

# Download model during build
RUN python -c "import whisper; whisper.load_model('base')"

2. 使用 faster-whisper

追求更高吞吐可使用 faster-whisper：

RUN pip install --no-cache-dir faster-whisper

3. 多进程

配置 worker 数量：

CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

4. 资源分配

按负载分配 CPU 与内存：

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G

安全考量

1. 使用官方基础镜像

FROM python:3.10-slim  # Official Python image

2. 漏洞扫描

docker scan whisper:latest

3. 保持镜像更新

定期更新基础镜像与依赖：

FROM python:3.10-slim  # Use latest patch version
RUN pip install --upgrade pip

4. 限制网络暴露

services:
  whisper-api:
    build: .
    networks:
      - internal
    # No external ports if accessed via reverse proxy

总结

将 Whisper 容器化可获得稳健、可扩展的语音转文字方案。要点如下：

从简入手 – 先写基础 Dockerfile
善用 Docker Compose – 简化多服务栈
启用 GPU – 生产环境需要性能时
遵循最佳实践 – 安全、优化与可观测性
充分测试 – 再上生产

配置得当的 Docker 方案能让你在本地开发到云上生产之间，一致地部署 Whisper。

后续步骤

构建第一个容器 – 从基础 Dockerfile 开始
加入 GPU 支持 – 若有 NVIDIA GPU
配置 Docker Compose – 搭建完整应用栈
部署到云端 – 使用 ECS、GKE、AKS 等容器服务

更多部署思路请参阅 Whisper Cloud Deployment 与 Whisper API vs Local Deployment。

Whisper Docker 配置：在 Docker 中运行 OpenAI Whisper 的完整指南

简介

为什么用 Docker 运行 Whisper？

容器化的优势

前置条件

安装 Docker

验证安装

Whisper 基础 Dockerfile

构建镜像

运行基础容器

带 API 服务的 Dockerfile

API 服务示例（app.py）

requirements.txt

Docker Compose 配置

docker-compose.yml

使用 Docker Compose 启动

Docker 中的 GPU 支持

安装 NVIDIA Docker

支持 GPU 的 Dockerfile

使用 GPU 运行

带 GPU 的 docker-compose.yml

面向生产的优化 Dockerfile

多阶段构建的好处

环境变量配置

Dockerfile

带环境变量的 docker-compose.yml

.env 文件

卷（Volume）管理

带卷的 docker-compose.yml

好处

健康检查与监控

带健康检查的 Dockerfile

健康检查端点

常见使用场景

场景一：开发环境

场景二：带队列的生产环境

场景三：多模型部署

最佳实践

1. 使用明确版本的基础镜像

2. 减少镜像层

3. 使用 .dockerignore

4. 设置资源限制

5. 使用健康检查

6. 非 root 用户

7. 缓存模型

常见问题排查

问题一：容器立刻退出

问题二：GPU 不可用

问题三：内存不足

问题四：模型下载慢或每次重启都下载

问题五：权限拒绝

性能优化

1. 预加载模型

2. 使用 faster-whisper

3. 多进程

4. 资源分配

安全考量

1. 使用官方基础镜像

2. 漏洞扫描

3. 保持镜像更新

4. 限制网络暴露

总结

后续步骤

相关文章

什么是语音转文字以及如何使用：完整新手指南

如何在线将音频转换为文字：免费且准确的方法（2026 指南）

如何为 STT 去除背景噪声：语音转文字降噪完整指南

立即免費試用