大模型本地部署版本管理规范

大模型本地部署应采用“版本号绑定发布物、流量别名负责切换、验证报告负责验收、回退指向旧版本”的闭环：模型、数据、运行时、镜像、配置与结果应落在同一发布记录中。大模型部署的发布单要能回答运行哪个模型、依赖与数据来自哪里、使用什么命令和配置，以及怎样复现验证与回退。

版本号只标识不可变发布

若部署包采用 SemVer，Semantic Versioning 2.0.0 规定：不兼容 API 变更升级 MAJOR，向后兼容功能升级 MINOR，向后兼容修复升级 PATCH；主版本增加时，后两项归零。版本发布后不得原地修改内容，任何变化都要另发版本；0.y.z 的公开 API 不应视为稳定。你应把这些规则做成发布检查，避免版本号与实际文件脱节。

模型、数据与流量指针分开管理

按 MLflow Model Registry 文档，注册模型具有唯一名称，并包含 versions、aliases、tags 与其他元数据；同一名称下首个注册版本为 version 1，后续注册递增，可通过 models:/<model-name>/<model-version> 引用。alias 是指向具体版本的可变命名引用，重新分配 champion alias 可以切换生产流量，因此 alias 适合作为切换指针，不可变发布证据仍须记录实际目标版本。

DVC 数据版本文档 说明，dvc add 会创建小型 .dvc 元数据文件并提交到 Git，文件哈希决定缓存路径；切换 .dvc 文件修订后运行 dvc checkout 可同步工作区，dvc push 则把本地缓存上传到已配置的远程存储。发布记录应同时保存数据修订、配置快照和对应模型版本，不能只保留可移动的名称。

固定 vLLM 环境与启动入口

vLLM Quickstart 列出的前置条件是 Linux 与 Python 3.10 至 3.13，并推荐用 uv 建立 Python 3.12 的全新环境；--torch-backend=auto 会根据已安装的 CUDA driver 选择 PyTorch index。文档中的 server 命令是 vllm serve Qwen/Qwen2.5-1.5B-Instruct，默认地址为 http://localhost:8000，可用 --host 和 --port 指定地址；当前一个 server 进程承载一个模型，模型列表通过 GET /v1/models 获取。

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

vllm serve Qwen/Qwen2.5-1.5B-Instruct

服务启动后，在另一个终端检查：

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

核对返回的模型标识是否与发布单一致，再运行固定的功能用例。模型列表检查只能确认服务响应，不能代替功能、性能和回归验证。

镜像、缓存与编排一起发布

vLLM Docker 文档 提供 Docker Hub 上的 vllm/vllm-openai 镜像，用于运行 OpenAI compatible server；示例映射 8000 端口、挂载 Hugging Face cache 并启用 --ipc=host，其他 engine args 放在镜像标签之后。该文档还说明，可用 --shm-size 代替 --ipc=host；PyTorch 会在进程间使用共享内存，tensor parallel inference 尤其需要它。

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

这是文档中的运行示例，发布单仍须写入实际镜像标识，不能只保留 latest。容器映射、cache 路径、共享内存选项和 engine args 都应随版本归档；若使用 Kubernetes，Deployment 清单、镜像标识、启动参数、Secret 引用与模型缓存声明也应绑定到同一发布版本。

固定比较口径再验收

若用 MLPerf 统一回归口径，MLPerf Inference Rules 将 system under test 定义为接受性能测量的软硬件资源集合，并要求所有提交使用 LoadGen。Server 场景按 Poisson distribution 发送 query，以相应 latency constraint 下支持的 maximum Poisson throughput 为指标；Offline 场景在开始时以单个 query 发出全部样本，没有 latency constraint，指标为 measured throughput；Single stream 在前一个 query 完成后发送下一个，并报告 p90 latency estimate。

因此，每次比较都应保存模型、依赖、镜像、硬件、启动参数、测试场景与约束文件。改变 system under test 或比较场景后，不应把结果当作同一发布版本的直接回归结论。

大模型部署的发布与回退门禁

• 候选版本：写明模型及数据修订、Python 与运行时依赖、镜像、完整命令、配置、验证报告和回退目标。
• 发布验收：先检查服务与模型标识，再执行固定功能用例和基准流程；任何缺失项都阻止发布。
• 回退操作：按已验证的切换方案恢复旧版本，并让模型、数据、运行时、镜像与配置重新对应同一发布组合。
• 常见出错点：只保存可变 alias 而不保存目标版本、覆盖已发布内容、遗漏容器共享内存设置，以及使用不同软硬件或场景比较结果。

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

资料来源

• Semantic Versioning 2.0.0
• ML Model Registry
• DVC Data Versioning
• vLLM Quickstart
• Using Docker | vLLM
• MLPerf Inference Rules