教程目标与适用范围
面向Linux GPU服务器，用官方vLLM镜像建立可持久化、可重启的推理服务。
本文依据对应项目的官方文档和官方仓库整理。命令用于建立可重复的基线环境，不承诺未经目标硬件实测的速度、显存或并发数字。
部署前检查
- 宿主机nvidia-smi正常
- NVIDIA Container Toolkit已经安装
- 模型缓存目录权限正确
执行前请记录操作系统、驱动、容器、Python、框架和模型版本。生产机器不要直接使用无法追溯的第三方镜像或模型文件。
安装与启动
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
docker run -d --name vllm --restart unless-stopped --gpus all --ipc=host -p 127.0.0.1:8000:8000 -v /data/huggingface:/root/.cache/huggingface vllm/vllm-openai:latest --model Qwen/Qwen3-8B --served-model-name qwen3-8b关键参数说明
- --ipc=host用于避免共享内存过小
- 缓存挂载避免容器重建后重新下载
- 本地端口绑定可防止未经授权访问
第一次启动应使用较短上下文、单并发和保守资源参数。基础请求稳定后，每次只改变一个变量，并保存修改前后的日志和指标。
验证步骤
1. 检查容器日志和模型加载 2. 访问/v1/models 3. 用curl发送聊天请求 4. 重建容器验证缓存复用
验收不能只看“是否返回文本”。至少记录首个响应时间、完整耗时、输入输出规模、CPU/GPU利用率、显存峰值和失败原因，并验证服务重启后仍能恢复。
常见问题与处理
- 容器看不到GPU：先修复Toolkit
- 共享内存报错：核对ipc或shm设置
- 重复下载：检查挂载路径和权限
生产环境补充
服务对外开放前应增加认证、TLS、限流、超时、请求大小限制、日志脱敏、健康检查和监控告警。模型缓存与配置必须持久化，并保留能够回退的镜像和启动参数。
性能基线怎么记录
不要用一次手工对话判断部署质量。准备固定请求集，分别覆盖短输入短输出、长输入短输出和短输入长输出。先预热模型，再以1、2、4、8并发逐级测试；每一级记录首Token延迟、端到端耗时、输入输出Token、GPU显存峰值、GPU利用率、CPU和内存占用以及失败请求。测试客户端必须有足够性能，否则测到的可能是客户端瓶颈。
不同模型、精度、上下文和输出长度的吞吐数字不能直接横向比较。发布测试结果时必须同时附带GPU型号与数量、驱动、框架版本、模型提交或文件哈希、启动命令和请求分布。出现性能提升时还应复查输出质量，避免量化、截断或错误模板造成“速度更快但结果不可用”。
日志、监控和故障恢复
至少保留服务启动日志、请求状态码、请求耗时、模型加载事件和GPU错误。提示词和输出可能包含敏感信息，默认不应全文写入日志；确需留样时要脱敏并设置保存期限。GPU监控不能只看利用率，还要关注显存、温度、功耗、降频、Xid错误和进程退出。
主动执行一次恢复演练：停止进程或容器，确认服务能够按配置重新启动；模拟模型目录不可访问，确认健康检查不会误报正常；恢复上一份配置，确认客户端无需修改即可继续请求。只有完成恢复验证，重启策略才算真正有效。
升级与回退
升级驱动、镜像、推理框架或模型时不要覆盖唯一运行版本。新旧版本应使用不同目录或镜像标签，先在独立端口完成接口、质量和性能回归，再切换流量。保存上一版模型哈希、镜像摘要、依赖锁定文件、完整启动参数和环境变量；发生输出异常、性能回退或显存增长时，可以在同一硬件上恢复旧版本复核。
升级完成后检查客户端依赖的模型名、返回字段、流式结束方式、工具调用和错误码。所谓“兼容接口”并不保证所有可选参数在不同框架之间完全一致。
适用边界
latest标签便于测试但不适合长期生产，验收后应固定镜像版本或摘要。官方文档可能随版本更新，实际执行前应打开原文核对当前命令和支持范围。
