快速开始

模型下载

当前 AIModule 1.4.2 版本基于 vLLM 0.16.0，可直接使用 Hugging Face 或 ModelScope 上的开源模型。对于 GPTQ INT4（W4A16）量化模型，启动服务时需要增加 --quantization gptq 参数。

gptq-Qwen3.6-35B-A3B-4bit-group

apt install git-lfs
git lfs install
git clone https://www.modelscope.cn/potter001/gptq-Qwen3.6-35B-A3B-4bit-group.git

gptq-Qwen3-VL-8B

apt install git-lfs
git lfs install
git clone https://www.modelscope.cn/potter001/gptq-Qwen3-VL-8B-Instruct-4bit-group.git

gptq-Qwen3-8B

apt install git-lfs
git lfs install
git clone https://www.modelscope.cn/hiruyun/gptq-Qwen3-8B.git

Qwen3-30B-A3B-GPTQ-Int4

apt install git-lfs
git lfs install
git clone https://www.modelscope.cn/Qwen/Qwen3-30B-A3B-GPTQ-Int4.git

服务启动前准备

注意

以下命令中的模型路径需要替换为本地实际模型路径。

建议每次启动服务前先配置运行环境并清理缓存：

source /home/dev/miniforge3/etc/profile.d/conda.sh
conda activate v1.4.2
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
export TRITON_CACHE_DIR="/tmp/triton"
sudo sh -c "echo 3 > /proc/sys/vm/drop_caches"

服务启动

建议根据模型任务类型选择对应启动命令，不同类型模型不要混用启动方式。

本版本建议使用 MUSA Graph 启动。启动命令中增加以下参数后，会开启 MUSA Graph 图捕获能力：

--compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

提示

使用 MUSA Graph 时不要再增加 --enforce-eager，否则会强制使用 eager 模式，无法进行图捕获。

文本生成模型

适用于 Qwen、Hunyuan 等普通文本生成模型。将 <MODEL_PATH> 替换为本地实际模型路径即可。

通用启动模板

vllm serve <MODEL_PATH> \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --dtype bfloat16 \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --trust-remote-code \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

GPTQ INT4（W4A16）模型

GPTQ INT4（W4A16）模型通常表示权重为 4 bit、激活为 16 bit。Dense GPTQ 模型在通用模板基础上增加：

--quantization gptq

适用模型示例：

• gptq-Qwen3-8B
• gptq-Qwen3.5-9B-full-int4-group
• gptq-Qwen3.5-4B-full-int4-group
• Qwen3.6-27B-gptq-v1

Qwen3.6-27B-gptq-v1 是 Dense GPTQ 模型，不属于 MoE 模型，不需要使用下方 MoE 专用的 VLLM_MUSA_ATTN=tilelang 启动方式。

Qwen3-30B-A3B-GPTQ-Int4

Qwen3-30B-A3B-GPTQ-Int4 建议在通用模板基础上使用以下差异项：

VLLM_MUSA_TILELANG_KVREUSE=1 VLLM_MUSA_ATTN=tilelang vllm serve <MODEL_PATH> \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --quantization gptq \
  --dtype float16 \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --trust-remote-code \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

gptq-Qwen3.6-35B-A3B-4bit-group

gptq-Qwen3.6-35B-A3B-4bit-group 建议在通用模板基础上使用以下差异项：

VLLM_MUSA_ATTN=tilelang vllm serve <MODEL_PATH> \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --quantization gptq \
  --dtype bfloat16 \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --trust-remote-code \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

注意

VLLM_MUSA_ATTN=tilelang 当前仅推荐用于上方已验证的 MoE 量化模型。不要直接加到普通 Dense 文本生成示例中，否则可能出现 KV Cache dtype 不匹配、MUSA Graph 捕获失败或退化执行。

多模态与 OCR 模型

适用于 Qwen3-VL、OCR 等支持图片输入的模型。将 <MODEL_PATH> 替换为本地实际模型路径即可。

通用启动模板

vllm serve <MODEL_PATH> \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --dtype bfloat16 \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --trust-remote-code \
  --limit-mm-per-prompt '{"image":1}' \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

Qwen3-VL 8B / 30B-A3B

gptq-Qwen3-VL-8B-Instruct-4bit-group 和 gptq-Qwen3-VL-30B-A3B-Instruct-4bit-group 在通用模板基础上增加：

--hf-overrides '{"text_config":{"tie_word_embeddings":false}}'

DeepSeek-OCR-2

DeepSeek-OCR-2 在通用模板基础上将上下文长度设置为：

--max-model-len 8192

提示

如果多模态模型可以正常启动并完成文本对话，但简单图片问答结果不符合预期，通常属于模型输出质量或测试提示词问题，不一定代表 vLLM 服务启动失败。建议结合真实图片再做验证。

Embedding / Pooling 模型

bge-m3 属于 embedding/pooling 模型，不应使用通用 chat 启动方式。需要使用 --runner pooling --convert embed。

VLLM_MUSA_STARTUP_WARMUP=0 vllm serve <MODEL_PATH> \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --dtype float16 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --trust-remote-code \
  --runner pooling \
  --convert embed \
  --enforce-eager

Reranker / Classify 模型

bge-reranker-v2-m3 属于 reranker/cross-encoder 打分模型，需要使用 --runner pooling --convert classify，服务调用时使用 /v1/score 接口。

VLLM_MUSA_STARTUP_WARMUP=0 vllm serve <MODEL_PATH> \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --dtype float16 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --trust-remote-code \
  --runner pooling \
  --convert classify \
  --enforce-eager

参数说明

环境变量

• VLLM_MUSA_STARTUP_WARMUP=0：关闭 vLLM-MUSA 启动阶段 warmup。当前建议用于 bge-m3、bge-reranker-v2-m3 等 pooling 模型，避免启动阶段 warmup 触发不必要的问题。
• VLLM_MUSA_ATTN=tilelang：启用 tilelang attention backend。当前仅推荐上文已验证的 MoE 量化模型配合 MUSA Graph 使用，其他模型不要默认开启。
• VLLM_MUSA_TILELANG_KVREUSE=1：启用 tilelang KV reuse 相关优化。当前仅随 Qwen3-30B-A3B-GPTQ-Int4 专用启动方式一起使用。

启动参数

• model：vllm serve 后面的模型路径，需要替换为本地实际模型路径。

• --host：服务监听地址。本机验证建议使用 127.0.0.1。

• --port：服务监听端口，默认示例使用 8000。

• -tp / --tensor-parallel-size：张量并行参数，目前仅支持 1。

• --pipeline-parallel-size：流水线并行参数，当前仅支持默认值 1，一般无需配置。

• --gpu_memory_utilization：用于预留模型加载和运行所需显存。当前 vLLM-MUSA patch 后，显存不再主要通过该参数严格控制，只需设置到足够模型加载即可。

• --num-gpu-blocks-override：手动指定 KV Cache 使用的 GPU block 数量，是当前控制 KV Cache 容量的关键参数。若遇到 OOM，可尝试减小此值，同时需减小 --max-model-len 以保证正常启动。

• --block_size：每个 KV Cache block 可容纳的 token 数，需使用 32。

• --max-model-len：单条请求允许的最大上下文长度，包含输入和输出 token。该值需要满足：

  max-model-len <= num-gpu-blocks-override * block_size / max-num-seqs

• --max-num-seqs：最大并发序列数，可理解为服务端同时处理的最大请求序列数，默认值为 256。单并发场景建议显式设置为 1。

• --swap_space：CPU swap 空间大小，当前端侧场景建议设置为 0。

• --quantization：量化方式，GPTQ 模型需要设置为 gptq。

• --dtype：模型权重和计算使用的数据类型，支持默认值 auto、float16、bfloat16。bge 类 pooling 模型建议使用 float16。

• --kv-cache-dtype：KV Cache 使用的数据类型，当前建议保持默认值 auto。

• --trust-remote-code：允许加载模型仓库中的自定义代码。Qwen、Qwen-VL、bge 等模型示例均建议保留。

• --no-enable-prefix-caching：关闭 prefix caching。当前 bge embedding/reranker 示例建议增加该参数。

• --limit-mm-per-prompt：限制单条请求中的多模态输入数量，例如 '{"image":1}' 表示每条请求最多 1 张图片；Qwen3-VL 图片输入均需要该参数。

• --hf-overrides：覆盖 Hugging Face 配置。Qwen3-VL 8B 需要使用 '{"text_config":{"tie_word_embeddings":false}}'；Qwen3-VL 2B/4B 不需要该参数。

• --runner pooling：将模型作为 pooling 类任务启动，适用于 embedding、reranker 等模型。

• --convert embed：将 pooling 模型作为 embedding 服务使用，对应 /v1/embeddings 接口。

• --convert classify：将 pooling 模型作为 classify/reranker 服务使用，对应 /v1/score 接口。

• --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'：开启 MUSA Graph 图捕获能力。启动日志中出现 simple_cuda_graph: True、cudagraph_capture_sizes: [1] 或 Capturing CUDA graphs 等信息时，表示参数已生效。