本指南详细说明了如何在 TensorRT LLM 框架上部署 Qwen3-Next 模型。内容基于经验证的默认配置，帮助快速完成部署流程。进阶性能调优和扩展特性将在后续更新中提供。
前置条件
在开始之前,请确保你的环境满足以下条件:
- GPU：NVIDIA Blackwell 或 Hopper 架构的 GPU 显卡
- 操作系统：Linux（暂不支持 Windows）
- CUDA 驱动：版本 575 或更高
- Docker：需要安装 NVIDIA 容器工具包
- Python 环境：Python3 和 pip（可选，用于精度评估）
模型准备
本指南使用以下模型版本：
- Qwen3-Next-80B-A3B-Thinking（BF16 精度）
- 下载地址：Hugging Face 模型库
部署步骤
步骤 1：启动 Docker 容器
构建并启动 Docker 容器，为后续部署准备运行环境。
cd TensorRT-LLM
make -C docker release_build IMAGE_TAG=qwen3-next-local
make -C docker release_run IMAGE_NAME=tensorrt_llm IMAGE_TAG=qwen3-next-local LOCAL_USER=1
步骤 2：配置服务器参数
创建配置文件 /tmp/config.yml，用于配置 TensorRT LLM 服务器的运行参数：
EXTRA_LLM_API_FILE=/tmp/config.yml
cat << EOF > ${EXTRA_LLM_API_FILE}
enable_attention_dp: false
cuda_graph_config:
enable_padding: true
max_batch_size: 720
moe_config:
backend: TRTLLM
stream_interval: 20
num_postprocess_workers: 4
kv_cache_config:
enable_block_reuse: false
free_gpu_memory_fraction: 0.6
EOF
步骤 3：启动服务器
执行以下命令启动加载 Qwen3-Next 模型的 TensorRT LLM 服务器：
trtllm-serve Qwen/Qwen3-Next-80B-A3B-Thinking \
--host 0.0.0.0 \
--port 8000 \
--max_batch_size 16 \
--max_num_tokens 4096 \
--tp_size 4 \
--pp_size 1 \
--ep_size 4 \
--trust_remote_code \
--extra_llm_api_options ${EXTRA_LLM_API_FILE}
服务器启动完成后即可开始发送请求。
配置参数说明
以下为 trtllm-serve 命令的主要参数说明：
--tp_size（张量并行度）
指定用于模型推理的 GPU 数量。通常设置为可用 GPU 的数量。
--ep_size（专家并行度）
用于 MoE（混合专家）模型的并行度设置，通常与可用 GPU 数量相同。对于非 MoE 模型，此参数无效。
--kv_cache_free_gpu_memory_fraction（KV 缓存内存占比）
控制为 KV 缓存保留的显存比例，取值范围为 0 到 1。设置缓冲区可避免内存溢出。
注意：若发生显存溢出（OOM），可尝试将此值降低至 0.7 或更小。
--max_batch_size（最大批处理大小）
单次推理的最大批处理请求数。实际批处理大小还受单个请求长度（输入+输出）的影响。
--max_num_tokens（最大 Token 数）
单次批处理中所有请求的最大总 Token 数。
--max_seq_len（最大序列长度）
单个请求的最大 Token 长度（输入+输出）。该参数通常由系统根据模型配置自动推断，一般无需手动设置。
--trust_remote_code（信任远程代码）
启用此参数允许 TensorRT LLM 从 Hugging Face 下载模型和分词器文件。
YAML 配置文件中的高级选项
YAML 配置文件允许进行更细致的性能调优。通过 --extra_llm_api_options 参数传递给服务器：
cuda_graph_config（CUDA 图优化）
CUDA 图配置用于性能优化：
enable_padding：启用后输入自动填充至指定批处理大小，可显著提升性能。默认为false，建议启用。max_batch_size：CUDA 图的最大批处理大小，默认为0（禁用）。建议与命令行参数--max_batch_size保持一致。
moe_config（MoE 模型配置）
MoE 模型的相关配置：
backend：MoE 运算的后端实现，默认为CUTLASS。
更多高级配置选项详见 TorchLlmArgs 类说明。
服务器测试
健康检查
运行以下命令检查服务器是否就绪：
curl -s -o /dev/null -w "Status: %{http_code}\n" "http://localhost:8000/health"
返回 Status: 200 表示服务器已就绪。首次查询可能较慢，因为系统需要进行初始化和编译。
服务器显示"应用程序启动完成"消息后，可发送推理请求：
curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{
"model": "Qwen/Qwen3-Next-80B-A3B-Thinking",
"messages": [
{
"role": "user",
"content": "Where is New York?"
}
],
"max_tokens": 1024,
"top_p": 1.0
}' -w "\n"
成功的响应格式如下（内容可能较长，仅展示结构示例）：
{"id":"chatcmpl-64ac201c77bf46a7a3a4eca7759b1fd8","object":"chat.completion","created":1759022940,"model":"Qwen/Qwen3-Next-80B-A3B-Thinking","choices":[{"index":0,"message":{"role":"assistant","content":"好的，用户在问"纽约在哪里？"嗯，这似乎很简单，但我需要小心。纽约可能意味着不同的东西——也许他们对城市与州感到困惑。\n\n第一个想法：他们是计划旅行的游客吗？或者也许是在做家庭作业的学生？甚至可能是只在电影中听过"纽约"并不确定它是城市还是州的国外人。\n\n我应该立即澄清两种可能性。人们经常混淆它们。就像，如果有人说"我要去纽约"，他们可能是在谈论纽约市，但严格来说纽约州更大。\n\n让我分解一下：\n- 纽约市（NYC）是著名的——曼哈顿、摩天大楼、时代广场。\n- 然后是纽约州（NY）整个州，其中包括纽约市，但也包括州北部的地区，如奥尔巴尼（州首府）、布法罗，甚至阿迪朗达克山脉。\n\n等等，我应该提到纽约市在纽约州内吗？是的，这很重要。否则他们可能认为这是两个独立的地方。还有，这个州位于哪里？美国东北部，与其他州接壤，如宾夕法尼亚州、新泽西州……也许提几个邻邦来提供背景。\n\n哦！城市与州的混淆非常普遍。就像人们说"纽约的热狗"意思是纽约市，但忘记了它是更大州的一部分。我应该举个例子吗？\n- "如果有人说'纽约的热狗'，他们指的是纽约市"\n- 但是"纽约州警察"覆盖整个州"\n\n……也许加一个有趣的事实？比如纽约市只是州内的一个城市？或者州首府不是纽约市而是奥尔巴尼？是的，这将有助于消除混淆。\n\n还要——用户可能在字面上询问坐标吗？不太可能，但以防万一，我可以添加："地理上，纽约市位于大约北纬40.7°和西经74°..."但只有在答案感觉太干燥的情况下。对于州，大约北纬42°至45°？嗯，可能没有必要。坚持地标：毗邻伊利湖、大西洋沿岸……\n\n等等——用户可能在字面上询问 GPS 坐标？不太可能，但以防万一。\n\n优先级：清晰、简单、正确。不要假设先验知识。说"纽约可以指..."然后分为两种情况。以"当人们在随意交谈中说'纽约'时，他们通常指的是这个城市"结尾。这是关键的外卖。\n\n...反复检查：奥尔巴尼真的是州首府吗？是的。而纽约市是最大的城市但不是首府。明白了。另外，纽约州按面积排名第27？也许无关。坚持基础知识。\n\n最终结构：\n1. "纽约可以指两样东西：城市或州。"\n2. 对于城市：\n - 它在哪里（美国东北部）\n - 在纽约州内部\n - 著名的部分（曼哈顿等）\n3. 对于州：\n - 更大的区域，包括城市\n - 边界（宾州、新泽西州、康州、马萨诸塞州、佛蒙特州、加拿大）\n - 首府是奥尔巴尼（不是纽约市！）\n4. 清晰的总结："在日常交谈中，'纽约'通常指的是纽约市。"\n\n是的。这涵盖了一切，而不会压倒他们。没有降价，只是纯英文。保持温暖——在最后加上"希望有帮助！"\n\n那是一个常见的困惑点！**"纽约"可以指两样不同的东西**，重要的是要区分它们：\n\n### 1. **纽约市（NYC）**\n - **它是什么**：美国最大和最著名的城市，以时代广场、中央公园、自由女神像和华尔街等地标而闻名。\n - **它在哪里**：\n - 位于**美国东北部**。\n - 位于**哈德逊河**与**大西洋**相遇的河口处。\n - **纽约州**的一部分（见下文）。\n - **地理细节**：\n - 坐标：大约**北纬 40.7°，西经 74.0°**。\n - 由**5 个自治区**组成：曼哈顿（大多数人想象的"城市"）、布鲁克林、皇后区、布朗克斯和史坦顿岛。\n - 纽约市的全景视图（包括布鲁克林和新泽西州天际线）：","reasoning_content":null,"reasoning":null,"tool_calls":[]},"logprobs":null,"finish_reason":"length","stop_reason":null,"mm_embedding_handle":null,"disaggregated_params":null,"avg_decoded_tokens_per_iter":1.0}],"usage":{"prompt_tokens":15,"total_tokens":1039,"completion_tokens":1024},"prompt_token_ids":null}
故障排查
| 问题 | 解决方案 |
|---|---|
| 显存溢出 | 减小 max_batch_size 或 max_seq_len |
| 模型加载失败 | 验证模型文件完整性和格式 |
| 性能不佳 | 运行 nvidia-smi 检查 GPU 利用率 |
| 容器启动失败 | 验证 NVIDIA 容器工具包安装 |
| 连接失败 | 检查 8000 端口是否被占用 |
性能基准测试
TensorRT LLM 提供基准测试工具用于性能评估。创建测试脚本 bench.sh：
cat <<'EOF' > bench.sh
#!/usr/bin/env bash
set -euo pipefail
concurrency_list="1 2 4 8 16 32 64 128 256"
multi_round=5
isl=1024
osl=1024
result_dir=/tmp/qwen3_output
for concurrency in ${concurrency_list}; do
num_prompts=$((concurrency * multi_round))
python -m tensorrt_llm.serve.scripts.benchmark_serving \
--model Qwen/Qwen3-Next-80B-A3B-Thinking \
--backend openai \
--dataset-name "random" \
--random-input-len ${isl} \
--random-output-len ${osl} \
--random-prefix-len 0 \
--random-ids \
--num-prompts ${num_prompts} \
--max-concurrency ${concurrency} \
--ignore-eos \
--tokenize-on-client \
--percentile-metrics "ttft,tpot,itl,e2el"
done
EOF
chmod +x bench.sh
性能调优建议：启用注意力 DP 时，建议将并发度扫描至 max_batch_size * GPU 数量。
保存测试结果，可添加以下参数：
--save-result \
--result-dir "${result_dir}" \
--result-filename "concurrency_${concurrency}.json"
更多测试参数详见 benchmark_serving.py 源代码。
执行测试脚本：
./bench.sh
注意：完整的并发测试可能耗时较长。
