#Docker 部署

官方提供面向 OpenAI 兼容服务的镜像，Docker Hub 上常用名仍是 vllm/vllm-openai（标签如 :latest 或具体版本）。镜像内已带 CUDA 构建与入口；你只要把 GPU、端口和 Hugging Face 缓存交给容器。命令随发行微调，以 Using Docker 为准。

宿主机需要：NVIDIA Container Toolkit，且 nvidia-smi 在宿主机正常。这不是 CPU 镜像。

#最小运行示例

官方文档近期示例常用很小的 Qwen 仓。本课与之一致地用未门控小模型（可换成文档当前的 Qwen/Qwen3-0.6B 等）：

docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=$HF_TOKEN" \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-0.5B-Instruct

镜像名后面的参数会传给服务入口，等价于 vllm serve 的引擎参数（--tensor-parallel-size、--quantization 等）。

验证：

curl http://localhost:8000/v1/models

#指定 GPU 与张量并行

两块卡做 tp=2：

docker run --runtime nvidia --gpus '"device=0,1"' \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --tensor-parallel-size 2

--gpus 语法因 Docker / NVIDIA 插件版本而异，以你环境的 docker run --help 为准。

#Compose 草稿

services:
  vllm:
    image: vllm/vllm-openai:latest
    ipc: host
    ports:
      - "8000:8000"
    volumes:
      - huggingface:/root/.cache/huggingface
    environment:
      HF_TOKEN: ${HF_TOKEN:-}
    command: ["--model", "Qwen/Qwen2.5-0.5B-Instruct", "--dtype", "auto"]
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Compose 的 GPU 写法有 deploy.resources 与 gpus: 两套，取决于 Compose 文件版本。以当前 Docker 文档为准。 应用服务应使用服务名 http://vllm:8000/v1，不要用 localhost。

#安全与运维

• 生产钉镜像 版本标签（如 v0.x.y），不要长期漂在 latest。
• 不要把 HF_TOKEN 写进 Dockerfile ENV 后推到公共仓库。
• 端口暴露给公网前加反向代理；容器网络 ≠ 鉴权。
• 日志看权重是否下载完、NCCL 是否报错、OOM。
• AMD / Intel 另有 vllm/vllm-openai-rocm、vllm/vllm-openai-xpu 等变体（名称以当前文档为准），本课不展开。

根用户、非 root、OpenShift 的 UID 说明见官方 Docker 页；若挂载卷权限不对，缓存目录会无法写。

#故障排查

本机已用 pip 跑通再容器化，更容易区分「CUDA 问题」和「Docker 问题」。

#下一步

• 生产服务
• 实战案例
• 本站 Docker 教程