NVFP4 量化

将模型量化为 NVFP4，以使用 TensorRT Model Optimizer 在 Spark 上运行。

概述

操作指令

故障排除

基本思路

NVFP4 是 NVIDIA Blackwell GPU 引入的一种 4 位浮点格式，旨在保持模型精度的同时，降低推理工作负载的内存带宽和存储需求。与统一的 INT4 量化不同，NVFP4 保留了浮点语义，采用共享指数和紧凑尾数，从而实现更高的动态范围和更稳定的收敛性。NVIDIA Blackwell Tensor Core 原生支持 FP16、FP8 和 FP4 之间的混合精度执行，使模型能够使用 FP4 计算权重和激活值，同时以更高的精度（通常为 FP16）进行累加。这种设计最大限度地减少了矩阵乘法期间的量化误差，并支持 TensorRT-LLM 中的高效转换流水线，从而实现精细的逐层量化。

直接益处包括：

内存使用量比 FP16 降低约 3.5 倍，比 FP8 降低约 1.8 倍。
保持接近 FP8 的准确度（通常损失小于1%）
提高推理速度和能源效率

您将完成

您将使用 NVIDIA 的 TensorRT 模型优化器在 TensorRT-LLM 容器内量化 DeepSeek-R1-Distill-Qwen-7B 模型，生成 NVFP4 量化模型，以便在 NVIDIA DGX Spark 上部署。

这些示例使用了 NVIDIA FP4 量化模型，通过降低模型层的精度，可以将模型大小减少约一半。这种量化方法旨在保持精度的同时，显著提升吞吐量。但是，需要注意的是，量化可能会影响模型精度——我们建议您运行评估，以验证量化模型是否能满足您的应用场景要求。

前置知识

使用 Docker 容器和 GPU 加速工作负载
理解模型量化概念及其对推理性能的影响
具备 NVIDIA TensorRT 和 CUDA 工具包环境的使用经验
熟悉 Hugging Face 模型库和身份验证

先决条件

采用 Blackwell 架构 GPU 的 NVIDIA Spark 设备
已安装支持 GPU 的 Docker
已配置 NVIDIA Container Toolkit
足够的模型文件和输出存储空间
Hugging Face 账户可以访问目标模型

请检查您的设置：

# Check Docker GPU access
docker run --rm --gpus all nvcr.io/nvidia/tensorrt-llm/release:spark-single-gpu-dev nvidia-smi

# Verify sufficient disk space
df -h .

时间和风险

预计时间：45-90 分钟，具体取决于网络速度和模型尺寸大小
风险等级：
- 模型下载可能因网络问题或 Hugging Face 认证问题而失败。
- 量化过程会占用大量内存，在 GPU 内存不足的系统上可能会失败。
- 输出文件较大（数 GB），需要足够的存储空间
回滚：删除输出目录和所有拉取的 Docker 镜像以恢复原始状态。
最后更新时间：2025 年 12 月 15 日
- 在步骤 8 中修复无法访问的客户端 CURL 请求。
- 更新 ModelOptimizer 项目名称

第 1 步 – 配置 Docker 权限

要轻松管理容器而无需使用 sudo，您必须处于 Docker 组中。如果您选择跳过此步骤，则需要使用 sudo 运行 Docker 命令。
打开一个新的终端并测试 Docker 访问权限。在终端中运行：

docker ps

如果您看到权限被拒绝错误（例如 permission denied while trying to connect to the Docker daemon socket），请将您的用户添加到 docker 组，这样就不再需要使用 sudo 命令。

sudo usermod -aG docker $USER
newgrp docker

第 2 步 – 准备环境

创建一个本地输出目录，用于存储量化后的模型文件。该目录将被挂载到容器中，以便在容器退出后保留结果。

mkdir -p ./output_models
chmod 755 ./output_models

第 3 步 - 使用 Hugging Face 验证

通过设置 Hugging Face 身份验证令牌来确保可以访问 DeepSeek 模型。

# Export your Hugging Face token as an environment variable
# Get your token from: https://huggingface.co/settings/tokens
export HF_TOKEN="your_token_here"

容器将自动使用该令牌进行模型下载。

第 4 步 - 运行 TensorRT 模型优化器容器

启动 TensorRT-LLM 容器，启用 GPU 访问权限，针对多 GPU 工作负载优化 IPC 设置，并挂载卷以进行模型缓存和输出持久化。

docker run --rm -it --gpus all --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 \
-v "./output_models:/workspace/output_models" \
-v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
-e HF_TOKEN=$HF_TOKEN \
nvcr.io/nvidia/tensorrt-llm/release:spark-single-gpu-dev \
bash -c "
git clone -b 0.35.0 --single-branch https://github.com/NVIDIA/Model-Optimizer.git /app/TensorRT-Model-Optimizer && \
cd /app/TensorRT-Model-Optimizer && pip install -e '.[dev]' && \
export ROOT_SAVE_PATH='/workspace/output_models' && \
/app/TensorRT-Model-Optimizer/examples/llm_ptq/scripts/huggingface_example.sh \
--model 'deepseek-ai/DeepSeek-R1-Distill-Qwen-7B' \
--quant nvfp4 \
--tp 1 \
--export_fmt hf
"

注意：您可能会遇到这种情况 pynvml.NVMLError_NotSupported：Not Supported. 在某些环境下，出现这种情况属于正常现象，不会影响结果，我们将在即将发布的版本中修复此问题。注意：如果您的模型过大，可能会遇到内存不足的错误。您可以尝试量化一个较小的模型。

这条命令：

以完全 GPU 访问权限和优化的共享内存设置运行容器
将输出目录挂载到持久化量化模型文件的位置
挂载您的 Hugging Face 缓存，以避免重新下载模型。
从源代码克隆并安装 TensorRT 模型优化器
使用 NVFP4 量化参数执行量化脚本

第 5 步 - 监控量化过程

量化过程将显示以下进度信息：

来自 Hugging Face 的模型下载进度
量化校准步骤
模型导出和验证阶段

第 6 步 - 验证量化模型

容器完成后，验证量化模型文件是否已成功创建。

# Check output directory contents
ls -la ./output_models/

# Verify model files are present
find ./output_models/ -name "*.bin" -o -name "*.safetensors" -o -name "config.json"

您应该在输出目录中看到模型权重文件、配置文件和分词器文件。

第 7 步 - 测试模型加载

首先，设置量化模型的路径：

# Set path to quantized model directory
export MODEL_PATH="./output_models/saved_models_DeepSeek-R1-Distill-Qwen-7B_nvfp4_hf/"

现在使用一个简单的测试来验证量化模型是否可以正确加载：

docker run \
  -e HF_TOKEN=$HF_TOKEN \
  -v $HOME/.cache/huggingface/:/root/.cache/huggingface/ \
  -v "$MODEL_PATH:/workspace/model" \
  --rm -it --ulimit memlock=-1 --ulimit stack=67108864 \
  --gpus=all --ipc=host --network host \
  nvcr.io/nvidia/tensorrt-llm/release:spark-single-gpu-dev \
  bash -c '
    python examples/llm-api/quickstart_advanced.py \
      --model_dir /workspace/model/ \
      --prompt "Paris is great because" \
      --max_tokens 64
    '

第 8 步 - 使用 OpenAI 兼容的 API 运行模型

使用量化模型启动 TensorRT-LLM OpenAI 兼容 API 服务器。首先，设置量化模型的路径：

# Set path to quantized model directory
export MODEL_PATH="./output_models/saved_models_DeepSeek-R1-Distill-Qwen-7B_nvfp4_hf/"

docker run \
  -e HF_TOKEN=$HF_TOKEN \
  -v "$MODEL_PATH:/workspace/model" \
  --rm -it --ulimit memlock=-1 --ulimit stack=67108864 \
  --gpus=all --ipc=host --network host \
  nvcr.io/nvidia/tensorrt-llm/release:spark-single-gpu-dev \
  trtllm-serve /workspace/model \
    --backend pytorch \
    --max_batch_size 4 \
    --port 8000

运行以下命令，使用客户端 CURL 请求测试服务器：

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-R1-Distill-Qwen-7B",
    "messages": [{"role": "user", "content": "What is artificial intelligence?"}],
    "max_tokens": 100,
    "temperature": 0.7,
    "stream": false
  }'

第 9 步 - 清理和回滚

清理环境并删除生成的文件：

警告：

这将永久删除所有量化模型文件和缓存数据。

# Remove output directory and all quantized models
rm -rf ./output_models

# Remove Hugging Face cache (optional)
rm -rf ~/.cache/huggingface

# Remove Docker image (optional)
docker rmi nvcr.io/nvidia/tensorrt-llm/release:spark-single-gpu-dev

第 10 步 - 后续步骤

可部署的量化模型现已准备就绪。后续步骤通常包括：

与原始模型相比，对推理性能进行基准测试。
将量化模型集成到推理流程中。
部署到 NVIDIA Triton 推理服务器以用于生产环境。
针对您的具体用例进行额外的验证测试。

在单个 Spark 上运行的常见问题


错误	原因	修复
访问 Hugging Face 时显示“权限被拒绝”	HF令牌缺失或无效	使用有效令牌运行 huggingface-cli login
容器因 CUDA 内存不足而退出	GPU 内存不足	减小批处理大小或使用具有更多 GPU 内存的机器
输出目录中未找到模型文件	卷挂载失败或路径错误	核实 $(pwd)/output_models 解析正确
容器内 Git clone 失败	网络连接问题	请检查网络连接并重试。
量化过程停滞	容器资源限制	增加 Docker 内存限制或使用 --ulimit
无法访问 URL 的受限存储库	部分 HuggingFace 模型的访问权限受限	恢复你的 HuggingFace 令牌并在浏览器上请求访问门控模型

注意：

DGX Spark 使用统一内存架构 (UMA)，支持 GPU 和 CPU 之间的动态内存共享。由于许多应用程序仍在更新以利用 UMA，即使在 DGX Spark 的内存容量范围内，您也可能会遇到内存问题。如果发生这种情况，请手动刷新缓冲区缓存：

sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'