4、vLLM官方镜像初探：拉取vLLM官方镜像、运行第一个vLLM容器、验证服务是否启动

好，咱们进入实战环节了。

前面几章我们把环境搭好了，概念也捋清了。现在该干点真活——拉一个vLLM官方镜像下来，跑个容器，看看它到底能不能动。

说实话，我第一次接触vLLM的时候，也是从这一步开始的。当时心里没底，怕拉不下来，怕跑不起来。结果呢？比想象中简单得多。你跟着我走一遍，十分钟就能搞定。

4.1 拉取vLLM官方镜像

先说说镜像仓库。vLLM官方镜像托管在Docker Hub和NVIDIA NGC上。我个人习惯用Docker Hub，因为不用额外登录，直接拉就行。

打开你的终端（SSH连上服务器），执行这条命令：

docker pull vllm/vllm-openai:latest

等等，别急着敲回车。我建议你指定一个具体版本，别用latest。为什么？

我在项目里吃过亏。有一次生产环境出了bug，想回滚到旧版本，结果latest已经更新了好几轮，根本不知道之前用的是哪个版本。从那以后，我所有镜像都指定版本号。

比如这样：

docker pull vllm/vllm-openai:v0.6.3

这个v0.6.3是我写文章时比较稳定的版本。你可以去vLLM的GitHub Release页面看看最新版是多少。

拉取过程大概长这样：

v0.6.3: Pulling from vllm/vllm-openai
a0d0a0d0a0d0: Pull complete
...
Digest: sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Status: Downloaded newer image for vllm/vllm-openai:v0.6.3

看到"Downloaded newer image"就说明拉成功了。镜像大概4-6GB，取决于网络速度，等个几分钟很正常。

4.2 运行第一个vLLM容器

镜像拉下来了，接下来跑容器。

先别急着跑大模型。咱们先跑个轻量级的，验证一下容器本身能不能正常启动。

执行这条命令：

docker run --rm -it \
  --gpus all \
  -p 8000:8000 \
  vllm/vllm-openai:v0.6.3 \
  --help

解释一下参数：

• --rm：容器退出后自动删除，省得你手动清理
• -it：交互式终端，能看到实时输出
• --gpus all：把宿主机所有GPU都挂载进容器
• -p 8000:8000：把容器的8000端口映射到宿主机
• --help：让vLLM打印帮助信息，不加载模型

如果看到一堆启动参数和选项说明，恭喜你——容器跑起来了，vLLM可执行文件没问题。

嗯，这里要注意：如果你没有NVIDIA GPU，或者没装NVIDIA Container Toolkit，容器会报错说找不到GPU。别慌，回去看看第三章，把驱动和toolkit装好。

4.3 加载一个小模型测试

光看帮助信息不过瘾。咱们真正加载一个模型试试。

选个小的。我推荐Qwen/Qwen2.5-0.5B-Instruct，只有5亿参数，显存占用不到2GB，跑起来飞快。

执行：

docker run --rm -it \
  --gpus all \
  -p 8000:8000 \
  -v /home/yourname/models:/models \
  vllm/vllm-openai:v0.6.3 \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --max-model-len 2048

这里多了个-v参数，把宿主机的/home/yourname/models目录挂载进容器。vLLM会把下载的模型缓存到这里，下次启动就不用重新下载了。

启动日志会显示：

INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

看到"Uvicorn running on http://0.0.0.0:8000"就说明服务启动成功了。

4.4 验证服务是否启动

服务跑起来了，怎么验证它真的在工作？

打开另一个终端窗口（或者用浏览器），访问这个地址：

curl http://localhost:8000/v1/models

如果返回类似这样的JSON：

{
  "object": "list",
  "data": [
    {
      "id": "Qwen/Qwen2.5-0.5B-Instruct",
      "object": "model",
      "created": 1700000000,
      "owned_by": "vllm"
    }
  ]
}

说明服务正常，模型已经加载好了。

再试试真正的推理请求：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ]
  }'

等几秒钟，你会看到模型返回一段回答。虽然0.5B模型回答质量一般，但至少证明整个链路通了。

4.5 本章核心逻辑图

我把整个流程画了张图，方便你理解：

4.6 常见问题速查

问题现象	可能原因	解决办法
docker pull 卡住不动	网络问题，镜像太大	配置Docker代理，或使用国内镜像源
容器启动报错"CUDA error"	GPU驱动版本不匹配	检查nvidia-smi输出，升级驱动
模型加载超时	模型下载慢，或显存不足	提前下载模型，或换更小的模型
curl请求返回502	服务还没完全启动	等日志出现"Uvicorn running"再请求