用 Docker 部署并扩展本地模型服务

说明如何用 vLLM 官方 Docker 镜像在 NVIDIA GPU 主机上启动模型 API，并按 GPU 调度、共享内存与健康检查要求规划多实例扩展和排错。

用 Docker 部署并扩展本地模型服务，可以把模型服务封装成容器，先验证单个实例，再按 GPU 资源安排多个独立实例。做本地部署大模型时，宿主机运行时、共享内存、缓存和健康检查要一起处理。先确认容器拿到 GPU、服务接口可响应，再扩大实例数量；启动日志本身不是接口可用证明。

本地部署大模型前先准备什么

按 Docker 的 GPU 接入文档，宿主机应先安装 NVIDIA 驱动并重启，再安装 NVIDIA Container Toolkit；容器通过 --gpus 使用 GPU。先用下面的命令确认容器能看到全部 GPU：

docker run -it --rm --gpus all ubuntu nvidia-smi

多 GPU 主机也可以按索引选择设备。由于 device 值包含逗号，必须保留引号：

--gpus '"device=0,2"'

如果按 UUID 配置，可先列出 UUID：

nvidia-smi -L

安装 NVIDIA Container Toolkit 后，按 NVIDIA Container Toolkit 安装指南配置 Docker runtime，并重启 Docker daemon：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

运行器配置命令会更新 /etc/docker/daemon.json。如果容器仍看不到 GPU，应先复查驱动、Toolkit、Docker daemon 和 --gpus，不要先改模型。部署前还要确定模型名称、缓存目录和访问凭证要求。

用 Docker 启动 vLLM 模型服务

vLLM 的 Docker 部署文档使用 vllm/vllm-openai 运行 OpenAI 兼容服务，并给出了以下启动方式：

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/Qwen3-0.6B

镜像标签是容器参数与 vLLM engine arguments 的分界，因此 --model 放在镜像标签之后。-v 把宿主机 Hugging Face 缓存挂载到容器路径，-p 8000:8000 映射服务端口，--env 则在运行时传入访问凭证，避免把凭证写入镜像。

共享内存配置错误先检查这里

vLLM 使用 PyTorch，进程间会使用共享内存，tensor parallel inference 尤其如此。官方文档允许使用 --ipc=host 或 --shm-size 提供共享内存；如果启动错误指向 shared memory 或 IPC，应先检查这一配置。

验证模型服务是否真的可用

vLLM 快速入门说明，服务默认监听 http://localhost:8000，地址可通过 --host 和 --port 设置。容器启动后执行：

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

/v1/models 用于列出模型。当前一个 server process 一次承载一个模型，因此需要多个模型时，应使用独立进程和容器，而不是假设同一进程可以同时切换模型。

容器正常但接口不通

先检查端口映射和 vLLM 进程状态，再检查 /v1/models。该请求成功只能说明模型列表接口可以响应，不代表已经完成性能验证。

扩展服务时配置 GPU 调度

需要增加容量时，可在前述单进程边界上增加独立服务实例。使用 Kubernetes 时，按 Kubernetes GPU 调度文档，安装厂商设备插件后，集群会暴露 nvidia.com/gpu 这类可调度资源。GPU 应设置在 limits 中：

resources:
  limits:
    nvidia.com/gpu: YOUR_VALUE

把 YOUR_VALUE 换成实际申请的 GPU 数量。Kubernetes 默认使用 limit 作为 request；如果同时设置 requests 和 limits，两者必须相同，只设置 GPU request 而不设置 limit 则不允许。Node Feature Discovery 可以自动发现并标记 GPU 节点。

GPU 资源声明不等于自动扩缩容。实例数量、流量入口和扩缩策略取决于当前 Kubernetes 组件及 vLLM 的部署配置，应在对应文档中确认，不要套用未经核对的字段或命令。

用 HEALTHCHECK 识别失效服务

Dockerfile 参考说明，HEALTHCHECK 用来判断进程仍在运行但已经无法提供服务的容器。文档列出的默认参数是：

--interval=30s --timeout=30s --start-period=0s --start-interval=5s --retries=3

在实际 HEALTHCHECK 命令中，可以把 /v1/models 作为探测目标之一，但要先确认镜像中存在可用的 HTTP 客户端，不要直接假定镜像带有 curl。检查命令应返回 0 表示健康、1 表示不健康；退出码 2 为保留值，不应使用。

容器连续达到 retries 次失败后才会标记为 unhealthy。单次检查超过 timeout 会被视为失败并以 SIGKILL 终止；同一 Dockerfile 中只有最后一条 HEALTHCHECK 生效。

排查时按 GPU 可见、共享内存、服务接口、健康状态和调度资源的顺序逐项检查，并记录镜像标签、模型名称、挂载路径、端口、GPU 选择和健康检查命令，避免同时修改多个变量。

这些步骤依据正文所链接的官方文档整理，未做任何运行或测量；使用前应按当前版本复核。