【LLM】VLLM：容器运行 ModelScope 模型

本文介绍如何通过 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

启动成功后，服务将监听在 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 Engine Arguments

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

四、使用 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 # 模型文件缓存挂载到宿主机，避免重复下载
    volumes:
      - ./modelscope_cache:/root/.cache/modelscope  # 模型缓存目录
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ["0"]  # 精确指定第 0 号 GPU
              capabilities: [gpu]
    command:
      - "--model"
      - "Qwen/Qwen3-0.6B"            # 模型名称或路径
      - "--gpu-memory-utilization"
      - "0.7"                         # 每张 GPU 允许使用 70% 显存
      - "--max-model-len"
      - "2048"                        # 最大上下文长度（token 数）

3. 启动与管理服务

五、总结

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