目标架构
本教程将模型文件持久化到宿主机，只在 `127.0.0.1:8000` 提供服务，由Nginx或业务网关负责TLS、认证和限流。示例采用Qwen小型模型跑通流程，确认稳定后再换成32B、72B或量化模型。这样能把“容器问题”和“大模型容量问题”分开排查。
运行前检查与目录规划
nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
sudo mkdir -p /data/ai/huggingface /data/ai/vllm-logs
sudo chown -R $(id -u):$(id -g) /data/ai
df -h /data/ai磁盘空间至少包含权重、下载临时文件和一个可回退版本。Hugging Face缓存必须挂载到宿主机，否则删除容器后会重新下载几十或几百GB权重。
固定镜像并启动服务
先拉取经过测试的明确版本。以下模型与镜像仅作可复现示例，部署当天应核对vLLM官方支持列表：
```bash export VLLM_IMAGE=vllm/vllm-openai:v0.11.0 docker pull "$VLLM_IMAGE" docker image inspect "$VLLM_IMAGE" --format '{{index .RepoDigests 0}}'
docker run -d --name qwen-vllm \ --restart unless-stopped \ --gpus all \ --ipc=host \ -p 127.0.0.1:8000:8000 \ -v /data/ai/huggingface:/root/.cache/huggingface \ -e HUGGING_FACE_HUB_TOKEN \ "$VLLM_IMAGE" \ --model Qwen/Qwen3-8B \ --served-model-name qwen3-8b \ --max-model-len 8192 \ --gpu-memory-utilization 0.85 \ --dtype auto
docker logs -f --tail 100 qwen-vllm ```
`--ipc=host`避免PyTorch多进程共享内存过小；`--served-model-name`决定客户端填写的模型名；`--max-model-len`直接影响KV Cache容量；`--gpu-memory-utilization`不是“GPU利用率目标”，而是vLLM可用于权重、缓存和工作区的显存比例。
三层验收：进程、模型、生成
服务端口打开不等于模型可用。依次执行：
```bash docker inspect -f '{{.State.Health.Status}} {{.State.Status}}' qwen-vllm curl -sS http://127.0.0.1:8000/v1/models | python -m json.tool
curl -sS http://127.0.0.1:8000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"qwen3-8b","messages":[{"role":"user","content":"用三句话解释KV Cache。"}],"temperature":0.2,"max_tokens":256}' \ | python -m json.tool ```
然后验证流式结束标志：
curl -N http://127.0.0.1:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"qwen3-8b","stream":true,"messages":[{"role":"user","content":"列出GPU服务上线前的五项检查。"}],"max_tokens":256}'客户端必须正确处理分块、连接中断和 `[DONE]`。如果只测试非流式接口，上线后常会暴露代理缓存或超时问题。
显存不足应该先改什么
启动OOM时按顺序处理：先确认没有其他进程占卡；降低 `max-model-len`；适当降低显存利用比例；再考虑量化或多卡。不要一上来把利用比例设成0.98，驱动、CUDA Graph和峰值工作区仍需要余量。
nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv
docker logs qwen-vllm 2>&1 | grep -Ei 'oom|memory|cache|error' | tail -n 80单请求能运行但并发OOM，通常是KV Cache容量问题。准备1K、8K和接近上限的输入，分别以1、2、4、8并发逐级压测，记录首Token、逐Token、P95和拒绝数。
双卡部署不是加一个参数就结束
两张同型号GPU可从张量并行开始：
# 在原启动参数后增加
--tensor-parallel-size 2启动前用 `nvidia-smi topo -m` 检查拓扑。PCIe跨NUMA或没有高速互联时，多卡通信可能抵消计算收益。比较单卡量化与双卡高精度时，必须保持模型、请求和输出长度一致。
对外服务必须增加的保护
不要直接把8000端口绑定到 `0.0.0.0` 暴露公网。网关应提供TLS、API密钥、单用户并发、最大请求体、最大Token、连接超时和日志脱敏。提示词可能包含代码与商业资料，默认日志只记录请求ID、Token数量、耗时和错误码。
升级和回退
新版本使用新容器名和端口，例如 `qwen-vllm-next:8001`，复用只读模型缓存但保留独立启动参数。依次回归模型列表、普通对话、流式输出、工具调用、长上下文和压力测试，再切换网关。保存旧镜像摘要和命令，出现输出格式、显存或性能回退时可在数分钟内恢复。
