【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
| 参数 | 说明 |
|---|---|
--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 Engine Arguments
下面介绍 VLLM 在日常部署和使用中最常用、最关键的参数。
| 参数 | 作用 | 示例 |
|---|---|---|
--model | 指定模型名称或本地路径 | --model Qwen/Qwen2-7B-Instruct |
--gpu-memory-utilization | 控制 GPU 显存利用率（0.0-1.0） | --gpu-memory-utilization 0.7 |
--max-model-len | 最大上下文长度，支持 k/K/m/M 格式 | --max-model-len 256K |
--api-key | 设置 API 访问密钥，提升安全性 | --api-key sk-123456 |
--served-model-name | 为 API 调用定义自定义模型名 | --served-model-name my-qwen |
四、使用 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: nvidiadevice_ids: ["0"] # 精确指定第 0 号 GPUcapabilities: [gpu]command:- "--model"- "Qwen/Qwen3-0.6B" # 模型名称或路径- "--gpu-memory-utilization"- "0.7" # 每张 GPU 允许使用 70% 显存- "--max-model-len"- "2048" # 最大上下文长度（token 数）
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 资源分配。 - 建议挂载模型缓存目录，避免重复下载，节省带宽和启动时间。