快速开始

模型下载

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

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

gptq-Qwen3.5-35B-A3B

apt install git-lfs
git lfs install
git clone https://www.modelscope.cn/potter001/gptq-Qwen3.5-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

服务启动前准备

注意

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

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

source /home/dev/miniforge3/etc/profile.d/conda.sh
conda activate v1.4.1
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、Qwen Instruct 等普通文本生成模型。以下以 gptq-Qwen3-8B 为例：

ENABLE_MUSA_MMA=1 VLLM_USE_V1=1 vllm serve /home/dev/models/gptq-Qwen3-8B \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --quantization gptq \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --trust-remote-code \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

Qwen3-30B-A3B-GPTQ-Int4 专用启动方式

Qwen3-30B-A3B-GPTQ-Int4 建议额外增加 VLLM_MUSA_ATTN=tilelang，配合 MUSA Graph 可提升 decode 性能：

VLLM_MUSA_ATTN=tilelang ENABLE_MUSA_MMA=1 VLLM_USE_V1=1 vllm serve /home/dev/models/Qwen3-30B-A3B-GPTQ-Int4/ \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --quantization gptq \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --trust-remote-code \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

注意

VLLM_MUSA_ATTN=tilelang 当前仅推荐用于 Qwen3-30B-A3B-GPTQ-Int4。不要将该环境变量直接加到通用文本生成示例或 gptq-Qwen3-8B 示例中，否则可能出现 KV Cache dtype 不匹配、MUSA Graph 捕获失败或退化执行。

多模态生成模型

适用于 Qwen-VL、Qwen3-VL 等支持图片输入的多模态模型。图片输入场景需要增加 --limit-mm-per-prompt '{"image":1}'。Qwen3-VL 启动参数按模型配置区分：2B/4B 不增加 --hf-overrides；8B/30B-A3B 需要额外增加 --hf-overrides '{"text_config":{"tie_word_embeddings":false}}'。

ENABLE_MUSA_MMA=1 VLLM_USE_V1=1 vllm serve /home/dev/models/gptq-Qwen3-VL-8B-Instruct-4bit-group \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --quantization gptq \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --trust-remote-code \
  --limit-mm-per-prompt '{"image":1}' \
  --hf-overrides '{"text_config":{"tie_word_embeddings":false}}' \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

提示

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

Embedding / Pooling 模型

bge-m3 属于 embedding/pooling 模型，不应使用通用 chat 启动方式。需要使用 --runner pooling --convert embed，并设置不超过模型配置限制的 --max-model-len。

ENABLE_MUSA_MMA=1 VLLM_USE_V1=1 vllm serve /home/dev/models/bge-m3 \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --max-model-len 4096 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --dtype float16 \
  --served-model-name testmodel \
  --trust-remote-code \
  --runner pooling \
  --convert embed \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

Reranker / Classify 模型

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

ENABLE_MUSA_MMA=1 VLLM_USE_V1=1 vllm serve /home/dev/models/bge-reranker-v2-m3 \
  --host 127.0.0.1 \
  --port 8000 \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --max-model-len 4096 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --dtype float16 \
  --served-model-name testmodel \
  --trust-remote-code \
  --runner pooling \
  --convert classify \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

参数说明

• model：模型路径，需要替换为本地实际模型路径。

• VLLM_USE_V1=1：使用 vLLM V1 Engine。

• ENABLE_MUSA_MMA=1：开启 MUSA MMA 相关优化。

• VLLM_MUSA_ATTN=tilelang：启用 tilelang attention backend。当前仅推荐 Qwen3-30B-A3B-GPTQ-Int4 配合 MUSA Graph 使用，其他模型不要默认开启。

• -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。

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

• --hf-overrides：覆盖 Hugging Face 配置。Qwen3-VL 8B/30B-A3B 需要使用 '{"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 等信息时，表示参数已生效。