企业官网建设流程全解析

• 人工智能
• 大模型
• 模型优化
• 模型量化
• 模型压缩

本文以 Model-Optimizer 仓库中的部署环境配置文档为核心，系统梳理将 ModelOpt 量化后的统一 HuggingFace（unified HF）checkpoint 部署为 OpenAI 兼容推理服务所需的全部前置工作：三大推理框架（vLLM、SGLang、TRT-LLM）的安装与最低版本要求、SLURM 集群容器化部署的规范写法、以及官方/自定义 Docker 镜像的两种部署路径。读完本文，你可以独立完成从环境检查、框架安装到 SLURM / Docker 启动 vLLM 服务的完整部署闭环，并能利用仓库提供的部署脚本deploy.sh快速上线 ModelOpt FP8 / NVFP4 量化模型。

一、部署环境准备概览

Model-Optimizer 的量化产物是"统一 HuggingFace checkpoint"：一组safetensors权重文件、一个记录量化配置的hf_quant_config.json，以及模型结构、分词器与元数据相关的 JSON 文件（详见 统一 HF Checkpoint 文档）。这类 checkpoint 可以被 vLLM、SGLang、TensorRT-LLM 三大推理框架直接加载，因此部署环境的核心工作就是安装并校准这三套框架的版本。

部署技能的整体决策流程（见 SKILL.md）依次为：识别 checkpoint（本地量化目录 / HF Hub ID / 未量化模型）→ 选择推理框架 → 检查运行环境（GPU 数量、框架是否已安装）→ 启动服务 → 验证健康状态。而环境检查的第一步就是确认框架版本是否满足要求。

二、推理框架安装与最低版本要求

官方文档 setup.md 给出了三个框架的安装方式与最低版本：

vLLM

pip install vllm

最低版本为0.10.1。该版本是识别quantization="modelopt"量化标记的门槛——如果启动时提示quantization="modelopt" not recognized，通常意味着 vLLM 版本过旧（详见后文"常见错误处理"）。

SGLang

pip install "sglang[all]"

最低版本为0.4.10。[all]extra 会带入 SGLang 服务端运行所需的完整依赖集（包括 FlashInfer 等后端组件）。仓库部署技能中强调，对于大型 MoE 模型、多节点部署或 Blackwell FP4 场景，启动命令应以 SGLang cookbook（按hw/quant/strategy/nodes元组生成经过验证的命令）为准，手工拼参数容易出错，详见 sglang.md。

TRT-LLM

TRT-LLM 推荐通过 NVIDIA 官方容器安装：

docker pull nvcr.io/nvidia/tensorrt-llm/release:<version>

也可以使用 pip 安装（需要本机具备 CUDA toolkit）：

pip install tensorrt-llm

最低版本为0.17.0。值得注意的是，部署参考文档 trtllm.md 中针对统一 HF checkpoint 的直接 LLM API路径给出的最低版本是1.2.0，并注明该版本面向统一 HF 加载路径（部署套件实际验证的是 1.3.x 容器线）。0.17.0 是传统部署路径的最低门槛，两个数字口径不同，落地时请按所选部署路径对应检查。

安装后版本自检

部署技能 SKILL.md 提供了标准的版本探测命令，启动服务前建议先跑一遍：

python -c "import vllm; print(f'vLLM {vllm.__version__}')" 2>/dev/null || echo "vLLM not installed" python -c "import sglang; print(f'SGLang {sglang.__version__}')" 2>/dev/null || echo "SGLang not installed" python -c "import tensorrt_llm; print(f'TRT-LLM {tensorrt_llm.__version__}')" 2>/dev/null || echo "TRT-LLM not installed"

未安装或版本不足时，按本节的安装命令补齐即可。

框架选型建议

部署技能给出的推荐优先级（未指定框架时）如下：

三、SLURM 集群部署：容器参数必须放在srun行

对于 SLURM 集群，部署技能明确要求在容器内执行推理服务。一个非常容易踩坑的规范是：容器的相关 flags（镜像、挂载、工作目录等）必须写在srun命令行上，而不是SBATCH指令或脚本的其他位置，否则容器环境不会正确传递到计算节点。

官方文档 setup.md 给出的完整作业脚本模板如下（请按实际集群替换<account>、<partition>、<num_gpus>等占位符）：

#!/bin/bash #SBATCH --job-name=deploy #SBATCH --account=<account> #SBATCH --partition=<partition> #SBATCH --nodes=1 #SBATCH --ntasks-per-node=1 #SBATCH --gpus-per-node=<num_gpus> #SBATCH --time=04:00:00 #SBATCH --output=deploy_%j.log srun \ --container-image="<path/to/container.sqsh>" \ --container-mounts="<data_root>:<data_root>" \ --container-workdir="<workdir>" \ --no-container-mount-home \ bash -c "python -m vllm.entrypoints.openai.api_server \ --model <checkpoint_path> \ --quantization modelopt \ --tensor-parallel-size <num_gpus> \ --host 0.0.0.0 --port 8000"

要点解读：

• --container-image指向.sqsh容器镜像文件，--container-mounts将数据盘映射进容器，--container-workdir设置容器内工作目录，--no-container-mount-home避免挂载 HOME 目录引发权限问题；
• 服务命令在bash -c "..."中执行，与裸机（bare metal）部署的命令完全一致，即python -m vllm.entrypoints.openai.api_server；
• 这里展示的是 vLLM 的 OpenAI 兼容入口；SGLang 对应为python -m sglang.launch_server --model-path <path> --quantization modelopt --tp <num_gpus>，TRT-LLM 则通过tensorrt_llm.LLMPython API 或 AutoDeploy 运行（见 vllm.md、sglang.md、trtllm.md）。

从集群外部访问服务

SLURM 节点通常不直接暴露给外部网络，需要通过 SSH 隧道或节点主机名访问。先用squeue查询任务分配的节点名：

squeue -u $USER -o "%j %N %S" # Get the node name # Then SSH tunnel or use the node's hostname directly

拿到节点名后，可做 SSH 端口转发（如ssh -L 8000:localhost:8000 <node_hostname>）或直接在集群内网使用http://<node_hostname>:8000访问。注意：该端口只在集群网络内可达。

另外，部署技能在远程部署前有一个硬性前置：提交任何携带容器镜像的 SLURM 作业前，必须先在集群上确认容器注册表的登录凭证有效（见 SKILL.md 的远程部署章节），凭证缺失时不要提交作业，避免作业在节点上拉取镜像失败。

四、Docker 部署

4.1 官方镜像（推荐）

三个框架都有官方发布镜像，直接拉取即可：

以官方 vLLM 镜像为例启动 OpenAI 兼容服务：

docker run --gpus all -p 8000:8000 \ -v /path/to/checkpoint:/model \ vllm/vllm-openai:latest \ --model /model \ --quantization modelopt \ --host 0.0.0.0 --port 8000

说明：

• --gpus all透传全部 GPU；-p 8000:8000映射服务端口；-v /path/to/checkpoint:/model将本地量化 checkpoint 挂载进容器，--model /model指向挂载点；
• FP8 checkpoint 使用--quantization modelopt，NVFP4 checkpoint 使用--quantization modelopt_fp4，这一对应关系同样适用于 vLLM 与 SGLang（见 support-matrix.md 的量化标记表）；TRT-LLM 则从hf_quant_config.json自动识别，无需显式传参。

4.2 Blackwell（sm_103）NVFP4 的镜像版本陷阱

仓库部署资料中特别警告了一个容易忽略的版本陷阱：NVFP4 在 Blackwell B300 / GB300（sm_103）上推理必须使用 CUDA-13 构建的镜像。从 vLLM v0.20.0 起，release tag 不带后缀即为 CUDA-13（-cu129才是 CUDA-12 的退出版本）；而 v0.19.x 及更早版本规则相反（-cu130代表 CUDA 13）。不要只看 tag 名字——应通过平台子清单（arm64 Grace/GB300、amd64 x86）的 config blob 中报告的CUDA_VERSION >= 13来选择镜像。CUDA-12 构建没有sm_103的 FP4 kernel，vLLM 会在加载 checkpoint 后于引擎初始化时报CUDA error: no kernel image is available for execution on the device。部署前建议用nvidia-smi实际核对 GPU 型号，因为集群的 GPU 标签可能过期。

4.3 自定义镜像（可选）

仓库提供了定制 Dockerfile：examples/vllm_serve/Dockerfile。它以vllm/vllm-openai:v${VLLM_VERSION}（默认 0.28.0，可用构建参数覆盖）为基础，额外完成四件事：安装 git 与 build-essential、以可编辑模式安装 Model-Optimizer 本体（含all,dev-test,mlflow依赖）、安装 Llama4 所需的flash-attn==2.7.4.post1、以及预编译 CUDA 扩展到/workspace/torch_extensions。这意味着该镜像可以让 vLLM 直接运行 ModelOpt 量化模型，而不必依赖发行版镜像中内置的 modelopt 版本。

构建并启动：

docker build -f examples/vllm_serve/Dockerfile -t vllm-modelopt . docker run --gpus all -p 8000:8000 \ -v /path/to/checkpoint:/model \ vllm-modelopt \ python -m vllm.entrypoints.openai.api_server \ --model /model \ --quantization modelopt \ --host 0.0.0.0 --port 8000

五、用仓库部署脚本快速上线（可选替代路径）

除手工拼命令外，仓库提供了一键部署脚本 deploy.sh，自动处理 GPU 探测、量化格式识别（FP8 vs FP4）、服务生命周期（start/stop/restart/status）、健康检查轮询与 API 测试，适合标准本地部署场景：

# 启动 vLLM 服务（自动识别 checkpoint 量化格式） "$SKILL_DIR/scripts/deploy.sh" start --model ./qwen3-0.6b-fp8 # 以 SGLang + 4 卡张量并行启动 NVFP4 模型 "$SKILL_DIR/scripts/deploy.sh" start --model ./llama-70b-nvfp4 --framework sglang --tp 4 # 从 HuggingFace Hub 启动 "$SKILL_DIR/scripts/deploy.sh" start --model nvidia/Llama-3.1-8B-Instruct-FP8 # 测试 API / 查看状态 / 停止 "$SKILL_DIR/scripts/deploy.sh" test "$SKILL_DIR/scripts/deploy.sh" status "$SKILL_DIR/scripts/deploy.sh" stop

脚本核心参数（--model必填，其余可省略）：

量化格式自动检测的判定顺序为：hf_quant_config.json中的quantization.quant_algo（含fp4/nvfp4判为modelopt_fp4，含fp8判为modelopt）→config.json中的quantization_config.quant_method == "modelopt"→ 均不存在视为未量化；对于 HF Hub ID 则按模型名中的fp8/fp4关键字做启发式推断。注意int4_awq、w4a8_awq等格式仅 TRT-LLM 支持，脚本会直接报错并提示改用--framework trtllm。

六、部署后验证与常见错误

无论走哪条部署路径，服务启动后都必须完成验证（部署技能将其列为成功标准）：

# 健康检查 curl -s http://localhost:8000/health # 列出已加载模型 curl -s http://localhost:8000/v1/models | python -m json.tool # 测试一次文本生成 curl -s http://localhost:8000/v1/completions \ -H "Content-Type: application/json" \ -d '{ "model": "<model_name>", "prompt": "The capital of France is", "max_tokens": 32 }' | python -m json.tool

三项检查全部通过后才能向用户报告部署成功。

部署过程中常见的错误与修复建议（整理自 SKILL.md 的错误处理表）：

若模型不在已验证的支持矩阵内，部署可能因权重键不匹配、量化/未量化层混淆或架构映射缺失而失败，此时可按 unsupported-models.md 中的迭代调试循环（运行 → 读错误 → 诊断 → 打补丁 → 重跑）处理；kernel 级问题应转交框架团队，不要自行修改 CUDA kernel。

七、延伸阅读

• 部署技能总览 SKILL.md：完整的决策流程、量化格式自动检测、GPU 显存估算（BF16 ≈ 2B/参数、FP8 ≈ 1B/参数、FP4 ≈ 0.5B/参数）与成功标准；
• vLLM 部署参考：realquant（默认、专用 kernel）与 fakequant（研究用，慢 2–5 倍）两条路径及基准测试命令；
• SGLang 部署参考：关键启动 flags、Blackwell/Hopper 的 MoE/FP4 后端选择、EAGLE 投机解码配置；
• TRT-LLM 部署参考：统一 HF checkpoint 的直接 LLM API、AutoDeploy 工作流与 NVFP4 的 Blackwell 硬件约束；
• 部署支持矩阵：支持的量化格式（FP8 / FP8_PB / NVFP4 / NVFP4_AWQ / INT4_AWQ / W4A8_AWQ）、各框架最低版本及各框架量化标记对应关系；
• 统一 HF Checkpoint 与模型支持矩阵：checkpoint 导出格式、export_hf_checkpoint()API 与按模型/框架/格式的权威支持矩阵。

• 人工智能
• 大模型
• 模型优化
• 模型量化
• 模型压缩