本文介绍如何通过 Docker 快速运行 VLLM 并加载 ModelScope 模型，适合需要 GPU 加速推理和大模型部署的场景。

一、环境准备

1. 安装 Docker

建议使用官方安装方式：

• Docker 官方安装指南
• Docker Compose 安装文档

一键安装脚本（不推荐，需自行判断风险）：

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

---

2. 安装 NVIDIA Container Toolkit

本文使用的 VLLM 需要使用 NVIDIA GPU 推理，需要配置 NVIDIA Container Toolkit。

• 官方安装指南：
  https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

验证 GPU 是否可见：

docker run --gpus all nvidia/cuda:11.0-base nvidia-smi

---

3. 拉取 VLLM Docker 镜像

如果拉取速度慢，建议开启科学上网或使用国内镜像源。

sudo docker pull vllm/vllm-openai:v0.10.1.1

• 当前版本：v0.10.1.1（截至 2025-09-12 最新官方版本）
• 显卡驱动要求：CUDA 12.8 或以上

请确保宿主机 NVIDIA 驱动版本满足要求，否则容器内无法识别 GPU。

---

二、测试与运行

使用以下命令启动 vLLM 推理服务：

sudo docker run --gpus all \
  --env "VLLM_USE_MODELSCOPE=true" \
  -v ~/.cache/modelscope:/root/.cache/modelscope \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen3-0.6B \
  --gpu-memory-utilization 0.7 \
  --max-model-len 2048

参数	说明
--gpus all	启用宿主机所有 GPU 设备
--env "VLLM_USE_MODELSCOPE=true"	使用 ModelScope 下载模型，国内网络更稳定
-v ~/.cache/modelscope:/root/.cache/modelscope	挂载本地缓存目录，避免重复下载模型文件
-p 8000:8000	将容器 8000 端口映射到宿主机 8000 端口
--ipc=host	共享宿主机的 IPC 空间，减少显存碎片问题
vllm/vllm-openai:latest	vLLM 官方最新镜像
--model Qwen/Qwen3-0.6B	指定要加载的模型
--gpu-memory-utilization 0.7	限制单 GPU 最大显存占用比例，避免 OOM
--max-model-len 2048	设置最大上下文长度（tokens）

启动成功后，服务将监听在 http://127.0.0.1:8000，并且完全兼容 OpenAI API 规范。

---

2. 测试 API

使用 curl 发送测试请求，确认服务是否正常工作。

curl http://127.0.0.1:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "Qwen/Qwen3-0.6B",
        "prompt": "请用一句话解释人工智能。",
        "max_tokens": 100
      }'

示例返回结果：

{
    "id": "cmpl-8328abddc08f4c7c8500a407d92b793a",
    "object": "text_completion",
    "created": 1757669109,
    "model": "Qwen/Qwen3-0.6B",
    "choices": [
        {
            "index": 0,
            "text": " 人工智能是通过计算机系统模拟人类智能的理论、方法、应用技术或其组合体。\n\n人工智能是通过计算机系统模拟人类智能的理论、方法、应用技术或其组合体。这句话是否正确？如果正确，那么这句话中的“计算机系统”是否正确？\n\n这句话是否正确？如果正确，那么这句话中的“计算机系统”是否正确？\n\n这句话是否正确？如果正确，那么这句话中的“计算机系统”是否正确？\n\n这句话是否正确？如果正确，那么",
            "logprobs": null,
            "finish_reason": "length",
            "stop_reason": null,
            "prompt_logprobs": null
        }
    ],
    "service_tier": null,
    "system_fingerprint": null,
    "usage": {
        "prompt_tokens": 6,
        "total_tokens": 106,
        "completion_tokens": 100,
        "prompt_tokens_details": null
    },
    "kv_transfer_params": null
}

好的，以下是更新后的 VLLM 常用参数表格，在你原有内容的基础上，补充了其他在生产部署中非常实用的常用参数，并保持格式统一、清晰。

---

三、VLLM 的常用参数

参考文档：VLLM Engine Arguments

下面介绍 VLLM 在日常部署和使用中最常用、最关键的参数。

参数	作用	示例
--model	指定模型名称或本地路径	--model Qwen/Qwen3-0.6B
--gpu-memory-utilization	控制 GPU 显存利用率（0.0–1.0），避免 OOM	--gpu-memory-utilization 0.8
--max-model-len	最大上下文长度，支持 k/K/m/M 格式（如 32K = 32768）	--max-model-len 32K
--api-key	设置 API 访问密钥，用于身份验证和安全性控制	--api-key sk-proj-xxxxx
--served-model-name	自定义对外暴露的模型名称，用于 OpenAI 兼容接口	--served-model-name qwen3-instruct
--tensor-parallel-size	设置张量并行度，通常等于使用的 GPU 数量	--tensor-parallel-size 8
--dtype	指定模型计算精度，影响速度与显存	--dtype half 或 --dtype auto
--quantization	启用量化方式（如 awq, gptq, fp8）	--quantization awq
--enable-chunked-prefill	启用分块预填充，支持超长上下文输入	--enable-chunked-prefill
--max-num-seqs	控制并发处理的最大序列数，影响吞吐与延迟	--max-num-seqs 256

四、使用 Docker Compose 组织

在实际部署中，手动输入长命令启动容器既麻烦又不利于维护，建议使用 Docker Compose 来管理 vLLM 服务。

通过 docker-compose.yml 文件，可以更直观地定义模型服务、端口映射、本地缓存挂载等配置。

---

1. 创建目录结构

建议创建一个独立目录，用于存放配置文件和缓存：

mkdir -p ~/vllm
cd ~/vllm
mkdir -p modelscope_cache

目录结构示例：

~/vllm/
│
├── docker-compose.yml      # vLLM 服务配置文件
└── modelscope_cache/       # 本地缓存目录

---

2. 编写 docker-compose.yml

在 ~/vllm-compose 目录下新建 docker-compose.yml 文件：

services:
  vllm:
    image: vllm/vllm-openai:latest  # vLLM 官方提供的 OpenAI 接口兼容镜像
    container_name: vllm_service  # 容器名称
    restart: unless-stopped  # 自动重启策略：除非手动停止，否则容器会自动重启
    ports:
      - "8000:8000"  # 将容器的 8000 端口映射到宿主机 8000 端口
    environment:
      - VLLM_USE_MODELSCOPE=true  # 使用 ModelScope 作为模型下载源
      - VLLM_ALLOW_LONG_MAX_MODEL_LEN=1  # 允许设置较大的 max-model-len
    volumes:
      - ./models:/root/.cache/modelscope/hub/models  # 模型缓存目录（建议改为 /root/.cache/modelscope）
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]  # 精确指定第 0 号 GPU（如需多卡，请修改为 ["0","1",...]）
              capabilities: [gpu]
    ipc: host  # 必须！用于多进程共享内存
    command: >
      --model Qwen/Qwen3-0.6B
      --tensor-parallel-size 1
      --gpu-memory-utilization 0.8
      --max-model-len 2048

---

3. 启动与管理服务

操作	命令	说明
启动服务	docker compose up -d	后台启动并创建容器（-d 表示 detached 模式）
停止服务	docker compose down	停止并移除容器、网络，但保留卷（Volume）
查看特定服务日志	docker compose logs -f <service_name>	跟踪指定服务的日志
查看服务状态	docker compose ps	列出所有服务的容器运行状态
重启特定服务	docker compose restart <service_name>	重启指定服务

五、总结

• 通过 VLLM 配合 ModelScope，可以快速拉取并部署国内外大模型。
• 使用 Docker Compose 可以方便管理服务、缓存和端口映射。
• 生产环境建议设置 --api-key 保护接口安全，并明确 GPU 资源分配。
• 建议挂载模型缓存目录，避免重复下载，节省带宽和启动时间。