DGX Spark 中文社区

基本思路

投机采样通过使用 小而快速的模型 提前起草多个标记，然后让 更大的模型 快速验证或调整它们，从而加速文本生成。
这样，大模型不需要逐步预测每个令牌，从而在保持输出质量的同时减少延迟。

你将完成什么

您将使用两种方法在 NVIDIA Spark 上使用 TensorRT-LLM 探索投机采样：EAGLE-3 和 Draft-Target。
这些示例演示了如何在保持输出质量的同时加速大型语言模型推理。

为什么是两台 Spark？

单个 DGX Spark 具有在 CPU 和 GPU 之间共享的 128 GB 统一内存。这足以运行带有 EAGLE-3 的 GPT-OSS-120B 或带有 Draft-Target 的 Llama-3.3-70B 等模型，如 操作步骤 选项卡中所示。

Qwen3-235B-A22B 等较大的模型超出了单个 Spark 在内存中的容量 - 即使使用 FP4 量化，模型权重、KV 缓存和 Eagle3 草稿头总共也需要超过 128 GB。通过连接两个 Spark，您可以将可用内存增加一倍，达到 256 GB，从而可以为这些更大的模型提供服务。

在两台 Spark 上运行选项卡将逐步完成此设置。两台 Spark 通过 QSFP 电缆连接，并使用 张量并行性 (TP=2) 来分割模型 - 每台 Spark 保存每层权重矩阵的一半，并计算每个前向传递的对应部分。节点使用 NCCL 和 OpenMPI 通过高带宽链路传送中间结果，因此该模型作为跨两台设备的单个逻辑实例运行。

简而言之：两台 Spark 可以让您运行单台设备放不下的模型，而 Eagle3 投机采样会通过并行起草和验证多个 token 进一步加速推理。

开始之前需要了解什么

Docker 和容器化应用程序的经验
了解投机采样概念
熟悉 TensorRT-LLM 服务和 API 端点
了解大型语言模型的 GPU 内存管理

先决条件

具有足够可用 GPU 内存的 NVIDIA Spark 设备

启用 GPU 支持的 Docker

docker run --gpus all nvcr.io/nvidia/tensorrt-llm/release:1.3.0rc12 nvidia-smi

用于模型访问的主动 Hugging Face 令牌
用于模型下载的网络连接

时间与风险

持续时间： 10-20 分钟用于设置，额外时间用于模型下载（因网络速度而异）
风险： 大型模型的 GPU 内存耗尽、容器注册表访问问题、下载期间网络超时
回滚： 停止 Docker 容器并可选择清理下载的模型缓存。
最后更新： 2026 年 4 月 20 日
- 升级到最新容器1.3.0rc12
- 添加在两个 Spark 上使用 Qwen3-235B-A22B 进行投机采样的示例

步骤1.配置Docker权限

要在不使用 sudo 的情况下轻松管理容器，您必须位于 docker 组中。如果您选择跳过此步骤，则需要使用 sudo 运行 Docker 命令。

打开新终端并测试 Docker 访问。在终端中，运行：

docker ps

如果您看到权限被拒绝错误（例如尝试连接到 Docker 守护进程套接字时权限被拒绝），请将您的用户添加到 docker 组，这样您就不需要使用 sudo 运行命令。

sudo usermod -aG docker $USER
newgrp docker

步骤2.设置环境变量

设置下游服务的环境变量：

export HF_TOKEN=<your_huggingface_token>

步骤 3. 运行投机采样方法

选项 1：EAGLE-3

通过执行以下命令来运行 EAGLE-3 投机采样：

docker run \
  -e HF_TOKEN=$HF_TOKEN \
  -v $HOME/.cache/huggingface/:/root/.cache/huggingface/ \
  --rm -it --ulimit memlock=-1 --ulimit stack=67108864 \
  --gpus=all --ipc=host --network host \
  nvcr.io/nvidia/tensorrt-llm/release:1.3.0rc12 \
  bash -c '
    hf download openai/gpt-oss-120b && \
    hf download nvidia/gpt-oss-120b-Eagle3-long-context \
        --local-dir /opt/gpt-oss-120b-Eagle3/ && \
    cat > /tmp/extra-llm-api-config.yml <<EOF
enable_attention_dp: false
disable_overlap_scheduler: false
enable_autotuner: false
cuda_graph_config:
    max_batch_size: 1
speculative_config:
    decoding_type: Eagle
    max_draft_len: 5
    speculative_model_dir: /opt/gpt-oss-120b-Eagle3/

kv_cache_config:
    free_gpu_memory_fraction: 0.9
    enable_block_reuse: false
EOF
    export TIKTOKEN_ENCODINGS_BASE="/tmp/harmony-reqs" && \
    mkdir -p $TIKTOKEN_ENCODINGS_BASE && \
    wget -P $TIKTOKEN_ENCODINGS_BASE https://openaipublic.blob.core.windows.net/encodings/o200k_base.tiktoken && \
    wget -P $TIKTOKEN_ENCODINGS_BASE https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken
    trtllm-serve openai/gpt-oss-120b \
      --backend pytorch --tp_size 1 \
      --max_batch_size 1 \
      --extra_llm_api_options /tmp/extra-llm-api-config.yml'

服务器运行后，通过从另一个终端进行 API 调用来测试它：

## Test completion endpoint
curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "prompt": "Solve the following problem step by step. If a train travels 180 km in 3 hours, and then slows down by 20% for the next 2 hours, what is the total distance traveled? Show all intermediate calculations and provide a final numeric answer.",
    "max_tokens": 300,
    "temperature": 0.7
  }'

EAGLE-3 投机采样的主要特点

更简单的部署 - EAGLE-3 没有管理单独的草稿模型，而是使用内置的草稿头在内部生成草稿 token。
更高的准确性 - 通过融合模型多层的特征，草稿令牌更有可能被接受，从而减少浪费的计算。
更快的生成 - 每个前向传递并行验证多个令牌，从而减少自回归推理的延迟。

选项 2：Draft-Target

执行以下命令来设置并运行草稿目标投机采样：

docker run \
  -e HF_TOKEN=$HF_TOKEN \
  -v $HOME/.cache/huggingface/:/root/.cache/huggingface/ \
  --rm -it --ulimit memlock=-1 --ulimit stack=67108864 \
  --gpus=all --ipc=host --network host nvcr.io/nvidia/tensorrt-llm/release:1.3.0rc12 \
  bash -c "
#    # Download models
    hf download nvidia/Llama-3.3-70B-Instruct-FP4 && \
    hf download nvidia/Llama-3.1-8B-Instruct-FP4 \
    --local-dir /opt/Llama-3.1-8B-Instruct-FP4/ && \

#    # Create configuration file
    cat <<EOF > extra-llm-api-config.yml
print_iter_log: false
disable_overlap_scheduler: true
speculative_config:
  decoding_type: DraftTarget
  max_draft_len: 4
  speculative_model_dir: /opt/Llama-3.1-8B-Instruct-FP4/
kv_cache_config:
  enable_block_reuse: false
EOF

#    # Start TensorRT-LLM server
    trtllm-serve nvidia/Llama-3.3-70B-Instruct-FP4 \
      --backend pytorch --tp_size 1 \
      --max_batch_size 1 \
      --kv_cache_free_gpu_memory_fraction 0.9 \
      --extra_llm_api_options ./extra-llm-api-config.yml
  "

服务器运行后，通过从另一个终端进行 API 调用来测试它：

## Test completion endpoint
curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nvidia/Llama-3.3-70B-Instruct-FP4",
    "prompt": "解释投机采样的优势：",
    "max_tokens": 150,
    "temperature": 0.7
  }'

草稿目标的主要特点：

高效的资源利用：8B草稿模型加速70B目标模型
灵活配置：可调整草稿 token 长度以进行优化
内存效率：使用 FP4 量化模型来减少内存占用
兼容模型：使用具有一致标记化的 Llama 系列模型

步骤 4. 清理

完成后停止 Docker 容器：

## Find and stop the container
docker ps
docker stop <container_id>

## Optional: Clean up downloaded models from cache
## rm -rf $HOME/.cache/huggingface/hub/models--*gpt-oss*

步骤 5. 后续步骤

尝试不同的 max_draft_len 值（1、2、3、4、8）
监控令牌接受率和吞吐量改进
使用不同的提示长度和生成参数进行测试
阅读有关投机采样这里的更多信息。

步骤1.配置Docker权限

在 Spark A 和 Spark B 上运行：

sudo usermod -aG docker $USER
newgrp docker

步骤 2. 网络设置

按照 Connect Two Sparks 手册中的网络设置说明进行操作。

NOTE

在继续之前，请先完成《连接两个 Spark》手册中的步骤 1-3：

第 1 步：确保两个系统上的用户名相同
步骤 2：物理硬件连接（QSFP 电缆）
步骤 3：网络接口配置
- 使用 选项 2：通过 netplan 配置文件手动分配 IP
- 每个 Spark 有两对网络端口。当您在两个 Spark 之间物理连接电缆时，连接的端口将显示为 Up。您可以使用任一对 - enp1s0f0np0 和 enP2p1s0f0np0，或 enp1s0f1np1 和 enP2p1s0f1np1
- 本剧本假设您使用 enp1s0f1np1 和 enP2p1s0f1np1。如果您的 Up 接口不同，请在以下命令中替换您的接口名称

对于本剧本，我们将使用以下 IP 地址：

Spark A（节点 1）：

enp1s0f1np1：192.168.200.12/24
enP2p1s0f1np1：192.168.200.14/24

Spark B（节点 2）：

enp1s0f1np1：192.168.200.13/24
enP2p1s0f1np1：192.168.200.15/24

完成连接两个 Spark 设置后，返回此处继续 TRT-LLM 容器设置。

步骤 3. 设置容器名称变量

在 Spark A 和 Spark B 上运行：

export TRTLLM_MN_CONTAINER=trtllm-multinode

步骤4.启动TRT-LLM多节点容器

在 Spark A 和 Spark B 上运行：

docker run -d --rm \
  --name $TRTLLM_MN_CONTAINER \
  --gpus '"device=all"' \
  --network host \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  --device /dev/infiniband:/dev/infiniband \
  -e UCX_NET_DEVICES="enp1s0f1np1,enP2p1s0f1np1" \
  -e NCCL_SOCKET_IFNAME="enp1s0f1np1,enP2p1s0f1np1" \
  -e OMPI_MCA_btl_tcp_if_include="enp1s0f1np1,enP2p1s0f1np1" \
  -e OMPI_MCA_orte_default_hostfile="/etc/openmpi-hostfile" \
  -e OMPI_MCA_rmaps_ppr_n_pernode="1" \
  -e OMPI_ALLOW_RUN_AS_ROOT="1" \
  -e OMPI_ALLOW_RUN_AS_ROOT_CONFIRM="1" \
  -e CPATH="/usr/local/cuda/include" \
  -e TRITON_PTXAS_PATH="/usr/local/cuda/bin/ptxas" \
  -v ~/.cache/huggingface/:/root/.cache/huggingface/ \
  -v ~/.ssh:/tmp/.ssh:ro \
  nvcr.io/nvidia/tensorrt-llm/release:1.3.0rc12 \
  bash -c "curl https://raw.githubusercontent.com/NVIDIA/dgx-spark-playbooks/refs/heads/main/nvidia/trt-llm/assets/trtllm-mn-entrypoint.sh | bash"

核实：

docker logs -f $TRTLLM_MN_CONTAINER

最后的预期输出：

total 56K
drwx------ 2 root root 4.0K Jan 13 05:13 .
drwx------ 1 root root 4.0K Jan 13 05:12 ..
-rw------- 1 root root  100 Jan 13 05:13 authorized_keys
-rw------- 1 root root   45 Jan 13 05:13 config
-rw------- 1 root root  411 Jan 13 05:13 id_ed25519
-rw-r--r-- 1 root root  102 Jan 13 05:13 id_ed25519.pub
-rw------- 1 root root  411 Jan 13 05:13 id_ed25519_shared
-rw-r--r-- 1 root root  100 Jan 13 05:13 id_ed25519_shared.pub
-rw------- 1 root root 3.4K Jan 13 05:13 id_rsa
-rw-r--r-- 1 root root  743 Jan 13 05:13 id_rsa.pub
-rw------- 1 root root 5.0K Jan 13 05:13 known_hosts
-rw------- 1 root root 3.2K Jan 13 05:13 known_hosts.old
Starting SSH

步骤 5. 配置 OpenMPI 主机文件

主机文件告诉 MPI 哪些节点参与分布式执行。使用步骤 2 中配置的 enp1s0f1np1 接口的 IP。

在 Spark A 和 Spark B 上，创建主机文件：

cat > ~/openmpi-hostfile <<EOF
192.168.200.12
192.168.200.13
EOF

在 Spark A 和 Spark B 上运行以将主机文件复制到每个容器中：

docker cp ~/openmpi-hostfile $TRTLLM_MN_CONTAINER:/etc/openmpi-hostfile

验证连接：

docker exec -it $TRTLLM_MN_CONTAINER bash -c "mpirun -np 2 hostname"

预期输出：

nvidia@spark-afe0:~$ docker exec -it $TRTLLM_MN_CONTAINER bash -c "mpirun -np 2 hostname"
Warning: Permanently added '[192.168.200.13]:2233' (ED25519) to the list of known hosts.
spark-afe0
spark-ae11
nvidia@spark-afe0:~$

步骤 6. 启动 Eagle3 投机采样

Eagle3 投机采样通过提前预测多个标记，然后并行验证它们来加速推理。与标准自回归生成相比，这可以提供显着的加速。

设置您的 Hugging Face 令牌

export HF_TOKEN=your_huggingface_token_here

在两个节点上下载 Eagle3 投机采样模型

docker exec \
  -e HF_TOKEN=$HF_TOKEN \
  -it $TRTLLM_MN_CONTAINER bash -c "
    mpirun -x HF_TOKEN -np 2 bash -c 'hf download nvidia/Qwen3-235B-A22B-Eagle3 --local-dir /opt/Qwen3-235B-A22B-Eagle3/'
"

创建 Eagle3 投机采样配置

此配置支持使用 3 个草稿 token 和保守的内存设置进行 Eagle 投机采样。

docker exec -it $TRTLLM_MN_CONTAINER bash -c "cat > /tmp/extra-llm-api-config.yml <<EOF
enable_attention_dp: false
disable_overlap_scheduler: false
enable_autotuner: false
enable_chunked_prefill: false
cuda_graph_config:
    max_batch_size: 1
speculative_config:
    decoding_type: Eagle
    max_draft_len: 3
    speculative_model_dir: /opt/Qwen3-235B-A22B-Eagle3/
kv_cache_config:
    free_gpu_memory_fraction: 0.9
    enable_block_reuse: false
EOF
"

使用 Eagle3 投机采样启动服务器

仅在 Spark A 上运行。 这将使用启用了 Eagle3 投机采样的 FP4 基本模型启动 TensorRT-LLM API 服务器。 mpirun 命令协调两个节点之间的执行，因此只需要从 Spark A 启动。最大令牌长度设置为 1024（根据需要调整）。

docker exec \
  -e MODEL="nvidia/Qwen3-235B-A22B-FP4" \
  -e HF_TOKEN=$HF_TOKEN \
  -it $TRTLLM_MN_CONTAINER bash -c '
    mpirun -x CPATH=/usr/local/cuda/include \
           -x TRITON_PTXAS_PATH=/usr/local/cuda/bin/ptxas \
           -x HF_TOKEN \
           trtllm-llmapi-launch \
           trtllm-serve \
           $MODEL \
           --backend pytorch \
           --tp_size 2 \
           --max_num_tokens 1024 \
           --extra_llm_api_options /tmp/extra-llm-api-config.yml \
           --port 8355 --host 0.0.0.0
'

端点就绪时的预期输出：

[01/13/2026-06:16:56] [TRT-LLM] [I] get signal from executor worker
INFO:     Started server process [2011]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

步骤 7. 验证 API

仅在 Spark A 上运行。 服务器正在侦听 Spark A，因此从那里测试端点：

curl -s http://localhost:8355/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nvidia/Qwen3-235B-A22B-FP4",
    "messages": [{"role": "user", "content": "Paris is great because"}],
    "max_tokens": 64
  }'

预期：带有生成文本的 JSON 响应。这证实了具有 Eagle3 投机采样功能的多节点 TensorRT-LLM 服务器正常工作。

步骤 8. 清理

停止容器

在 Spark A 和 B 上运行：

docker stop $TRTLLM_MN_CONTAINER

由于 --rm 标志，容器将被自动删除。

（可选）删除下载的模型

如果您需要释放磁盘空间：

在 Spark A 和 B 上运行：

rm -rf $HOME/.cache/huggingface/hub/models--nvidia--Qwen3*

这将删除模型文件（约数百 GB）。如果您打算再次运行安装程序，请跳过此步骤。

步骤 9. 后续步骤

现在您已经运行了 Eagle3 投机采样，请考虑以下优化和实验：

调整草稿长度： 修改配置中的 max_draft_len （尝试 2-5 之间的值）以平衡推测速度与准确性
尝试不同的模型： 尝试支持 Eagle 投机采样的其他模型对
优化批量大小： 调整 cuda_graph_config 中的 max_batch_size 以实现吞吐量-延迟权衡
了解更多： 查看 TensorRT-LLM 投机采样文档以获取高级调整选项
基准性能： 比较有和没有投机采样的推理速度，以测量加速增益

症状	原因	使固定
“CUDA 内存不足”错误	GPU显存不足	将 `kv_cache_free_gpu_memory_fraction` 减少到 0.9 或使用具有更多 VRAM 的设备
容器无法启动	Docker GPU 支持问题	验证 `nvidia-docker` 已安装并且支持 `--gpus=all` 标志
模型下载失败	网络或身份验证问题	检查 Hugging Face 身份验证和网络连接
无法访问 URL 的门禁仓库	某些 Hugging Face 模型的访问受到限制	重新生成你的 Hugging Face token;并请求在您的网络浏览器上访问 gated model
服务器没有响应	端口冲突或防火墙	检查8000端口是否可用且未被阻塞
`mpirun` 失败并拒绝 SSH 连接	容器或节点之间未配置 SSH	从 Connect Two Sparks playbook 完成 SSH 设置；验证 `ssh <node_ip>` 无需密码即可从两个节点正常工作
`mpirun` 与远程节点的连接挂起或超时	主机文件 IP 与实际节点 IP 不匹配	验证 `/etc/openmpi-hostfile` 中的 IP 与分配给具有 `ip addr show` 的网络接口的 IP 匹配
NCCL 错误：“非套接字上的套接字操作”	指定的网络接口错误	检查 `ibdev2netdev` 输出并确保 `NCCL_SOCKET_IFNAME` 和 `UCX_NET_DEVICES` 与活动接口 `enp1s0f1np1,enP2p1s0f1np1` 匹配
mpirun 期间的 `Permission denied (publickey)`	容器之间不交换 SSH 密钥	从 Connect Two Sparks playbook 重新运行 SSH 设置或手动验证 `/root/.ssh/authorized_keys` 包含来自两个节点的公钥
在多节点设置中模型下载失败且无提示	HF_TOKEN 未传播到 mpirun	将 `-e HF_TOKEN=$HF_TOKEN` 添加到 `docker exec` 命令，将 `-x HF_TOKEN` 添加到 `mpirun` 命令

NOTE

DGX Spark 使用统一内存架构 (UMA)，可实现 GPU 和 CPU 之间的动态内存共享。
由于许多应用程序仍在更新以利用 UMA，因此即使在
DGX Spark 的内存容量。如果发生这种情况，请使用以下命令手动刷新缓冲区缓存：

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