快速开始

模型下载

当前 AIBook AIOS 1.5.0 系统环境预装 vLLM-MUSA 1.4.2，基于 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

gptq-Qwen3.5-9B-full-int4-group

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

服务启动前准备

warning

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

启动服务前可选清理系统缓存：

sudo sh -c "echo 3 > /proc/sys/vm/drop_caches"

服务启动

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

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

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

tip

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

文本生成模型

适用于 Qwen、Qwen Instruct 等普通文本生成模型。以下以 gptq-Qwen3-8B 为例：

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

多模态生成模型

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

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.5 \
  --quantization gptq \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --limit-mm-per-prompt '{"image":1}' \
  --hf-overrides '{"text_config":{"tie_word_embeddings":false}}' \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

tip

如果多模态模型可以正常启动并完成文本对话，但简单图片问答结果不符合预期，通常属于模型输出质量或测试提示词问题，不一定代表 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.3 \
  --dtype float16 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --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.3 \
  --dtype float16 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --no-enable-prefix-caching \
  --runner pooling \
  --convert classify \
  --enforce-eager

参数说明

环境变量

• VLLM_MUSA_STARTUP_WARMUP=0：关闭 vLLM-MUSA 启动阶段 warmup。当前建议用于 bge-m3、bge-reranker-v2-m3 等 pooling 模型，避免启动阶段 warmup 触发不必要的问题。

启动参数

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

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

• --served-model-name：指定服务对外暴露的模型名称。设置后，客户端请求中的 model 字段需要与该名称一致。

• --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 等信息时，表示参数已生效。