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