vLLM

2026-03-09

vLLM 是一个开源的，专注于大模型的推理和部署服务框架，无缝集成 [[HuggingFace]]，而且兼容 [[OpenAI API]] 格式接口。

部署

通过 [[docker]] 部署：

Terminal window
docker run --gpus all \
      -v ~/.cache/huggingface:/root/.cache/huggingface \
      -p 8000:8000 \
      --ipc=host \
      vllm/vllm-openai:nightly \
      --model Qwen/Qwen3.5-9B
  • --gpus all: 使用所有 GPU
  • -v ~/.cache/huggingface:/root/.cache/huggingface: 挂载 HuggingFace 缓存
  • -p 8000:8000: 映射端口
  • --ipc=host: 使用主机 IPC
  • vllm/vllm-openai:nightly: 使用 vLLM 镜像
  • --model Qwen/Qwen3.5-9B: 使用 Qwen3.5-9B 模型

也可以通过 [[docker-compose]] 进行部署：

services:
  vllm:
    container_name: vllm
    image: vllm/vllm-openai:nightly
    runtime: nvidia
    ports:
      - "8000:8000"
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    environment:
      - CUDA_VISIBLE_DEVICES=0,1,2,3
    ipc: host

Qwen3.5 部署

通过 vLLM 部署 Qwen3.5 模型：

services:
  qwen:
    container_name: qwen
    image: vllm/vllm-openai:nightly
    runtime: nvidia
    ports:
      - "8000:8000"
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    environment:
      - HF_HUB_OFFLINE=1
      - CUDA_VISIBLE_DEVICES=0,1,2,3
    command:
      - Qwen/Qwen3.5-9B
      - --tensor-parallel-size=4
      - --api-key=${VLLM_API_KEY}
      - --reasoning-parser=qwen3
      - --enable-prefix-caching
      - --enable-auto-tool-choice
      - --tool-call-parser=qwen3_coder
      - --max-model-len=65536
      - --gpu-memory-utilization=0.90
      - --mm-encoder-tp-mode=data
      - --mm-processor-cache-type=shm
      - --served-model-name=Qwen3.5-9B
    ipc: host
    shm_size: "16gb"

environment:

  • HF_HUB_OFFLINE=1: 离线模式
  • CUDA_VISIBLE_DEVICES=0,1,2,3: 使用 4 个 GPU

command：

  • Qwen/Qwen3.5-9B: 要运行的模型，无须前缀
  • —tensor-parallel-size=4: 张量并行数，等于使用的 GPU 数量。
  • —api-key=${VLLM_API_KEY}: 使用模型时的 OpenAI API 密钥
  • —reasoning-parser=qwen3: 使用 Qwen3 解析器
  • —enable-prefix-caching: 启用前缀缓存
  • —enable-auto-tool-choice: 启用自动工具选择
  • —tool-call-parser=qwen3_coder: 使用 Qwen3 工具调用解析器
  • —max-model-len=65536: 最大上下文长度（Token 数）
  • —gpu-memory-utilization=0.90: GPU 显存使用比例上限，剩余的留给系统和 CUDA 本身使用
  • —mm-encoder-tp-mode=data: 设置 MM 编码器 TP 模式
  • —mm-processor-cache-type=shm: 多模态（图片/视频）特征缓存类型
    • shm: 共享内存
  • —served-model-name=Qwen3.5-9B: 对外的模型名称

参数

gpu-memory-utilization

表示 vLLM 最多用掉每张 GPU 显存的比例，范围在 (0 ~ 1 之间)。

  • 值越大
    • 可用于 KV cache 的显存更多
    • 支持更高的并发、上下文和吞吐量（同时处理的 Token 增多）

这个值不会影响模型权重，但是必须要高于 模型权重 / 显存。

显存使用：

  • 模型权重
  • KV Cache = 显存 * gpu-memory-utilization - 模型权重 - (CUDA + 多模态视觉编码 + 缓存等)
  • CUDA + 多模态视觉编码 + 缓存等

max-model-len

max-model-len 表示单次请求允许的最长上下文，也就是 token 上限。

  • 128K: 131072
  • 256K: 262144
  • 1M: 1000000

参考

# vLLM
# 大模型
# self-hosted