DGXspark实践下来最好的Qwen3.6-35B-A3B-NVFP4 vLLM 部署指南
·
目录
1. 硬件与软件要求
1.1 硬件要求
| 组件 | 要求 | 说明 |
|---|---|---|
| GPU | NVIDIA GPU (≥80GB 显存) | 支持 FP8 的 GPU (A100/H100/L40S/RTX 4090 等) |
| 内存 | ≥64GB | 建议 128GB 以上以获得更好性能 |
| 存储 | ≥100GB 可用空间 | 模型权重约 23GB (NVFP4) |
| 网络 | 可选 | 如需下载模型需要网络连接 |
1.2 软件要求
| 组件 | 版本要求 | 说明 |
|---|---|---|
| NVIDIA Driver | ≥535.x | 支持 CUDA 12.x |
| Docker | ≥20.10 | NVIDIA Container Toolkit |
| CUDA | 12.4+ | 推荐 CUDA 12.8+ |
| vLLM | ≥0.19.1 | 推荐 nvcr.io/nvidia/vllm:26.06-py3 或更新版本 |
2. 环境准备
2.1 配置 Docker 权限
# 将当前用户添加到 docker 组（避免每次使用 sudo）
sudo usermod -aG docker $USER
newgrp docker
# 验证 Docker 可访问
docker ps
2.2 安装 NVIDIA Container Toolkit
# 添加 NVIDIA Docker 仓库
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
sudo tee /etc/apt/sources.list.d/nvidia-docker.list
# 安装
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
# 重启 Docker
sudo systemctl restart docker
2.3 拉取 vLLM 镜像
⚠️ 关键：使用 NVIDIA 官方 NGC 镜像以获得最佳性能
# 拉取 vLLM 镜像 (推荐)
docker pull nvcr.io/nvidia/vllm:26.06-py3
# 或者使用 vLLM 官方镜像
docker pull vllm/vllm-openai:latest
3. 模型下载与准备
3.1 下载模型权重
方式一：通过 HuggingFace (需要 Token)
# 安装 huggingface-cli
pip install -U huggingface_hub
# 设置 Token (从 https://huggingface.co/settings/tokens 获取)
export HF_TOKEN="your_huggingface_token"
# 下载官方 NVFP4 模型
huggingface-cli download nvidia/Qwen3.6-35B-A3B-NVFP4 \
--local-dir /home/bob/project/models/qwen36b_nvfp4
# 或者下载 RedHatAI 版本
huggingface-cli download RedHatAI/Qwen3.6-35B-A3B-NVFP4 \
--local-dir /home/bob/project/models/qwen36b_nvfp4
方式二：通过 ModelScope (中国大陆推荐)
pip install modelscope
python -c "
from modelscope import snapshot_download
snapshot_download('vllm-ascend/Qwen3.6-35B-A3B',
cache_dir='/home/bob/project/models')
"
方式三：通过 Unsloth 优化版本
huggingface-cli download unsloth/Qwen3.6-35B-A3B-NVFP4 \
--local-dir /home/bob/project/models/qwen36b_nvfp4_unsloth
3.2 验证模型文件
# 检查模型目录结构
ls -la /home/bob/project/models/qwen36b_nvfp4/
# 预期文件列表：
# - config.json
# - model.safetensors (或分片文件)
# - model.safetensors.index.json
# - tokenizer.json
# - tokenizer_config.json
# - chat_template.jinja (可选)
4. Docker 容器配置
4.1 创建启动脚本
创建文件 start_vllm_qwen36b.sh：
#!/bin/bash
# ============================================================
# vLLM Qwen3.6-35B-A3B-NVFP4 启动脚本
# ============================================================
set -e
# ========== 配置 ==========
MODEL_DIR="/home/bob/project/models/qwen36b_nvfp4"
PORT=8040
CONTAINER_NAME="vllm_qwen36b"
IMAGE="nvcr.io/nvidia/vllm:26.06-py3"
# ========== 检查 ==========
if [ ! -d "$MODEL_DIR" ]; then
echo "❌ 模型目录不存在: $MODEL_DIR"
echo "请先下载模型到该目录"
exit 1
fi
# 检查容器是否已在运行
if docker ps --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
echo "⚠️ 容器 '$CONTAINER_NAME' 已在运行中"
echo "查看日志: docker logs -f $CONTAINER_NAME"
echo "停止容器: docker stop $CONTAINER_NAME"
exit 0
fi
# ========== 启动容器 ==========
echo "🚀 启动 vLLM Qwen3.6-35B-A3B-NVFP4 服务..."
echo " 模型路径: $MODEL_DIR"
echo " 端口: $PORT"
echo " 容器名: $CONTAINER_NAME"
docker run -d --rm --gpus all \
--ipc=host \
--ulimit memlock=-1 \
--ulimit stack=67108864 \
--name ${CONTAINER_NAME} \
-p ${PORT}:${PORT} \
-v "$MODEL_DIR:/model:ro" \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--entrypoint vllm \
${IMAGE} \
serve /model \
--host 0.0.0.0 \
--port ${PORT} \
--served-model-name RedHatAI/Qwen3.6-35B-A3B-NVFP4 \
--tensor-parallel-size 1 \
--trust-remote-code \
--kv-cache-dtype fp8 \
--attention-backend flashinfer \
--moe-backend marlin \
--gpu-memory-utilization 0.4 \
--max-model-len 262144 \
--max-num-seqs 4 \
--max-num-batched-tokens 8192 \
--enable-chunked-prefill \
--async-scheduling \
--enable-prefix-caching \
--load-format fastsafetensors \
--reasoning-parser qwen3 \
--tool-call-parser qwen3_coder \
--enable-auto-tool-choice
echo "✅ 容器已启动: $CONTAINER_NAME"
echo ""
echo "📋 常用命令："
echo " 查看日志: docker logs -f $CONTAINER_NAME"
echo " 停止服务: docker stop $CONTAINER_NAME"
echo " 健康检查: curl http://localhost:${PORT}/health"
echo " 模型列表: curl http://localhost:${PORT}/v1/models"
4.2 赋予执行权限
chmod +x start_vllm_qwen36b.sh
5. vLLM 服务启动
5.1 启动服务
# 启动 vLLM 服务 (后台运行)
bash start_vllm_qwen36b.sh
# 实时查看日志 (观察模型加载进度)
docker logs -f vllm_qwen36b
5.2 预期启动日志
(APIServer pid=1) INFO 07-17 07:07:45 [utils.py:344] vLLM version 0.22.1+7b9cb5b7.dev
(APIServer pid=1) INFO 07-17 07:08:07 [model.py:617] Resolved architecture: Qwen3_5MoeForConditionalGeneration
(APIServer pid=1) INFO 07-17 07:08:08 [cache.py:261] Using fp8 data type to store kv cache.
(APIServer pid=1) INFO 07-17 07:08:22 [model.py:617] Resolved architecture: Qwen3_5MoeMTP
(APIServer pid=1) INFO 07-17 07:08:22 [scheduler.py:239] Chunked prefill is enabled with max_num_batched_tokens=8192.
(APIServer pid=1) INFO 07-17 07:08:22 [vllm.py:986] Asynchronous scheduling is enabled.
(APIServer pid=1) INFO 07-17 07:28:55 [api_server.py:592] Supported tasks: ['generate']
(APIServer pid=1) INFO 07-17 07:29:23 [api_server.py:596] Starting vLLM server on http://0.0.0.0:8040
6. 验证部署
6.1 基础健康检查
# 健康检查
curl http://localhost:8040/v1/models | jq .
# 预期输出
{
"object": "list",
"data": [
{
"id": "RedHatAI/Qwen3.6-35B-A3B-NVFP4",
"object": "model",
"created": 1719500000,
"owned_by": "vllm",
"root": "RedHatAI/Qwen3.6-35B-A3B-NVFP4",
"parent": null,
"permission": [...]
}
]
}
6.2 基础聊天测试
# 简单数学测试
curl http://localhost:8040/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "RedHatAI/Qwen3.6-35B-A3B-NVFP4",
"messages": [{"role": "user", "content": "12*17"}],
"max_tokens": 500
}' | jq .
6.3 中文对话测试
curl http://localhost:8040/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "RedHatAI/Qwen3.6-35B-A3B-NVFP4",
"messages": [
{"role": "system", "content": "你是一个有帮助的AI助手。"},
{"role": "user", "content": "请用简短的语言介绍什么是大语言模型？"}
],
"max_tokens": 1024,
"temperature": 0.7
}' | jq .
6.4 Thinking 模式测试
curl http://localhost:8040/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "RedHatAI/Qwen3.6-35B-A3B-NVFP4",
"messages": [
{"role": "user", "content": "一个水池有两个水管，单开甲管6小时能注满，单开乙管8小时能注满。如果同时打开两个水管，几小时能注满？请详细思考。"}
],
"max_tokens": 2048,
"temperature": 0.6,
"chat_template_kwargs": {"enable_thinking": true}
}' | jq .
6.5 工具调用测试
curl http://localhost:8040/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "RedHatAI/Qwen3.6-35B-A3B-NVFP4",
"messages": [
{"role": "user", "content": "北京现在的天气怎么样？"}
],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
}
},
"required": ["city"]
}
}
}],
"tool_choice": "auto",
"max_tokens": 1024
}' | jq .
7. 性能调优建议
7.1 内存配置参考
| 参数 | 推荐值 | 说明 |
|---|---|---|
--gpu-memory-utilization |
0.4-0.7 | 根据显存大小调整，单卡 80GB 建议 0.4-0.5 |
--max-model-len |
262144 | 最大上下文长度 (256K) |
--max-num-seqs |
4-8 | 并发请求数，根据显存调整 |
--max-num-batched-tokens |
8192 | 批处理 token 数 |
7.2 关键参数说明
推荐使用的参数
# KV Cache 配置 (必须)
--kv-cache-dtype fp8 \ # FP8 KV Cache 减少内存占用
# MoE 后端配置 (推荐)
--moe-backend marlin \ # NVFP4 MoE 后端，性能最优
# 注意力后端 (推荐)
--attention-backend flashinfer \ # FlashInfer 注意力优化
# 性能优化参数 (推荐)
--enable-prefix-caching \ # 相同前缀请求加速
--enable-chunked-prefill \ # 长上下文优化
--async-scheduling \ # 异步调度提升吞吐
--load-format fastsafetensors \ # 快速加载模型
# 工具调用解析器 (Qwen3.6 必需)
--tool-call-parser qwen3_coder \ # Qwen3.6 专用解析器
# 推理解析器 (支持 thinking 模式)
--reasoning-parser qwen3 \
可选的高级参数
# 推测解码 (MTP) - 可提升生成速度 1.5-2x
--speculative-config '{"method":"mtp","num_speculative_tokens":3,"moe_backend":"triton"}'
# 注意: MTP 推测解码在某些场景下可能影响工具调用稳定性
# 如果遇到工具调用问题，建议移除该参数
7.3 不推荐使用的参数
| 参数 | 原因 |
|---|---|
--distributed-executor-backend ray |
单卡不需要 |
--enforce-eager |
除非出现内存尖峰，否则影响性能 |
7.4 性能参考指标
| 指标 | 预期值 |
|---|---|
| 模型加载时间 | 5-10 分钟 (含编译) |
| 内存占用 | ~23GB (模型) + ~30-50GB (KV Cache) |
| TTFT (首 Token 延迟) | 50-200ms |
| 生成吞吐量 | 20-50 tokens/s |
| 最大并发请求 | 4-8 |
8. 常见问题排查
8.1 工具调用 XML 解析错误
问题现象：
WARNING [qwen3xml_tool_parser.py:303] Error when parsing XML elements: not well-formed (invalid token)
原因：使用了错误的 tool-call-parser
解决方案：
# ❌ 错误
--tool-call-parser qwen3_xml
# ✅ 正确 (Qwen3.6 专用)
--tool-call-parser qwen3_coder
8.2 容器启动后立即退出
问题现象：docker ps 看不到运行中的容器
排查步骤：
# 查看容器日志
docker logs vllm_qwen36b
# 常见原因：
# 1. 模型路径不存在
# 2. 端口被占用
# 3. GPU 驱动问题
解决方案：
# 检查端口占用
netstat -tlnp | grep 8040
# 检查 GPU 可用性
nvidia-smi
# 检查模型目录
ls -la /home/bob/project/models/qwen36b_nvfp4/
8.3 内存不足 (OOM)
问题现象：
torch.cuda.OutOfMemoryError: CUDA out of memory
解决方案：
# 降低 GPU 内存利用率
--gpu-memory-utilization 0.3
# 减少并发请求数
--max-num-seqs 2
# 减少批处理 token 数
--max-num-batched-tokens 4096
# 缩短最大上下文长度
--max-model-len 131072
8.4 FlashInfer 相关错误
问题现象：
FlashInfer ... not available
解决方案：
# 使用正确的镜像
docker pull nvcr.io/nvidia/vllm:26.06-py3
# 或设置环境变量 (DGX Spark 必需)
-e VLLM_USE_FLASHINFER_MOE_FP4=0 \
-e VLLM_FP8_MOE_BACKEND=flashinfer_cutlass \
-e FLASHINFER_DISABLE_VERSION_CHECK=1 \
8.5 推理速度慢
排查步骤：
# 检查 GPU 利用率
nvidia-smi dmon -s u -d 1
# 查看 vLLM 日志中的吞吐量指标
docker logs vllm_qwen36b | grep "throughput"
优化建议：
- 确保使用
--kv-cache-dtype fp8 - 确保使用
--moe-backend marlin - 适当增加
--max-num-seqs提高并发 - 启用
--async-scheduling提升吞吐
附录
A. 完整启动脚本
#!/bin/bash
# save as: start_vllm_qwen36b.sh
set -e
MODEL_DIR="/home/bob/project/models/qwen36b_nvfp4"
PORT=8040
CONTAINER_NAME="vllm_qwen36b"
IMAGE="nvcr.io/nvidia/vllm:26.06-py3"
if [ ! -d "$MODEL_DIR" ]; then
echo "❌ 模型目录不存在: $MODEL_DIR"
exit 1
fi
if docker ps --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then
echo "⚠️ 容器 '$CONTAINER_NAME' 已在运行中"
exit 0
fi
docker run -d --rm --gpus all \
--ipc=host \
--ulimit memlock=-1 \
--ulimit stack=67108864 \
--name ${CONTAINER_NAME} \
-p ${PORT}:${PORT} \
-v "$MODEL_DIR:/model:ro" \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--entrypoint vllm \
${IMAGE} \
serve /model \
--host 0.0.0.0 \
--port ${PORT} \
--served-model-name RedHatAI/Qwen3.6-35B-A3B-NVFP4 \
--tensor-parallel-size 1 \
--trust-remote-code \
--kv-cache-dtype fp8 \
--attention-backend flashinfer \
--moe-backend marlin \
--gpu-memory-utilization 0.4 \
--max-model-len 262144 \
--max-num-seqs 4 \
--max-num-batched-tokens 8192 \
--enable-chunked-prefill \
--async-scheduling \
--enable-prefix-caching \
--load-format fastsafetensors \
--reasoning-parser qwen3 \
--tool-call-parser qwen3_coder \
--enable-auto-tool-choice
echo "✅ vLLM Qwen3.6-35B 服务已启动"
echo "📋 API 端点: http://localhost:${PORT}/v1/chat/completions"
B. 常用管理命令
# 查看日志
docker logs -f vllm_qwen36b
# 停止服务
docker stop vllm_qwen36b
# 重启服务
docker restart vllm_qwen36b
# 进入容器 (调试用)
docker exec -it vllm_qwen36b bash
# 查看资源使用
docker stats vllm_qwen36b
C. 参考链接
更多推荐
7
0- 0
已为社区贡献3条内容
所有评论(0)