---

在 Docker 中部署与使用 vLLM：高性能大模型推理的容器化实践

随着大型语言模型（LLMs）的飞速发展，如何高效、稳定地进行模型推理成为了一个关键挑战。vLLM 作为一款专为 LLMs 推理设计的高性能库，凭借其创新的 PagedAttention 机制，显著提升了吞吐量和降低了延迟。而 Docker 作为容器化技术的领导者，提供了隔离、可移植和标准化的运行环境。将 vLLM 部署在 Docker 容器中，不仅能够简化复杂的依赖管理，确保环境一致性，还能极大地提升部署的灵活性和便捷性。

本文将深入探讨在 Docker 中部署和使用 vLLM 的全过程，从基础概念到实际操作，再到进阶配置和常见问题排查，为您提供一份全面的指南。

1. vLLM 简介：为何选择它进行大模型推理？

大模型的参数量动辄数十亿、千亿甚至万亿，其计算量和显存占用巨大。传统的推理方法在处理大量并发请求时往往效率低下，存在显存碎片化、批处理效率不足等问题。

vLLM (Virtual Large Language Model) 的出现正是为了解决这些痛点。其核心创新在于：

1. PagedAttention: 借鉴了操作系统的内存分页思想，将 attention key 和 value 缓存（KV cache）分块存储。这使得不同请求的 KV cache 可以共享物理显存块，有效避免了显存碎片化，提高了显存利用率，从而允许在同一批次中处理更多请求（更大的批处理大小）。
2. Continuous Batching (持续批处理): vLLM 支持在推理过程中持续地将新的请求加入到正在执行的批次中，而不是等待当前批次完全结束后再处理新的请求。这极大地减少了 GPU 的空闲时间，提高了 GPU 的利用率和整体吞吐量。
3. 高度优化: vLLM 底层使用了高度优化的 CUDA 核函数，针对 Transformer 模型结构进行了特别优化，进一步提升了计算效率。
4. 易用性: 提供了简洁的 Python API 和 HTTP 服务接口，方便集成和部署。
5. 广泛兼容性: 支持 Hugging Face Transformers 库中的众多主流模型，如 Llama、Mistral、Falcon、Qwen 等。

总而言之，vLLM 能够显著提升 LLMs 的推理吞吐量（QPS）和降低平均请求延迟，特别是在高并发场景下，是进行 LLM 在线服务部署的理想选择。

2. Docker 简介：为何在容器中运行 vLLM？

Docker 是一种开源的平台，用于自动化部署、扩展和管理应用程序，通过使用容器技术。容器是一种轻量级、可移植、自给自足的软件包，它包含了运行应用程序所需的一切：代码、运行时、系统工具、系统库等。

在 Docker 中运行 vLLM 带来诸多优势：

1. 环境隔离与一致性: LLMs 及其推理库（如 vLLM、PyTorch/TensorFlow、CUDA、cuDNN 等）依赖于特定的 Python 版本、库版本和驱动版本。在宿主机上直接安装这些依赖常常会导致版本冲突或与其他应用程序的依赖冲突。Docker 将 vLLM 及其所有依赖打包在一个独立的容器中，与其他宿主机环境完全隔离，确保无论在何处运行，环境都一致。
2. 简化依赖管理: vLLM 的安装过程可能涉及编译自定义 CUDA 核函数，这依赖于特定的 CUDA Toolkit 版本和构建工具。Dockerfile 可以自动化这些复杂的构建步骤，用户只需通过简单的命令即可获取或构建一个包含所有必要依赖的、可直接运行的镜像。
3. 可移植性: Docker 镜像可以在任何安装了 Docker 并满足硬件要求的机器上运行，无需重新配置环境。这极大地简化了从开发到测试再到生产环境的部署流程。
4. 资源控制: Docker 提供了资源限制（CPU、内存、GPU）的功能，可以更精细地管理 vLLM 容器所使用的资源，避免其占用过多宿主机资源。
5. 快速部署与扩展: 基于 Docker 镜像，可以快速启动多个 vLLM 容器实例，方便进行水平扩展以应对流量增长。容器的启动速度远快于虚拟机。
6. 版本管理: Docker 镜像提供了内建的版本管理机制（通过 Tag），方便回滚到旧版本或部署新版本。

结合 vLLM 的高性能和大模型推理需求，Docker 提供了一个理想的运行和管理平台。

3. 前提条件

在开始之前，请确保您的系统满足以下条件：

1. 硬件:
   • NVIDIA GPU: vLLM 严重依赖 NVIDIA GPU 进行加速计算。您的 GPU 需要支持 CUDA，并且具有足够的显存来加载您计划使用的模型。模型的显存需求是选择 GPU 的主要考量因素。
   • 足够的内存和存储空间: 宿主机需要足够的系统内存和磁盘空间来存储 Docker 镜像和模型文件。
2. 软件:
   • 已安装 Docker: 确保您的宿主机上已经安装了 Docker Engine。您可以按照 Docker 官方文档的指引进行安装。
   • 已安装 NVIDIA 驱动: 宿主机上需要安装与您的 GPU 兼容的最新 NVIDIA 驱动。
   • 已安装 nvidia-container-toolkit: 为了让 Docker 容器能够访问宿主机的 NVIDIA GPU，需要安装 nvidia-container-toolkit（以前称为 nvidia-docker2）。请按照 NVIDIA 官方文档的指引进行安装。安装完成后，重启 Docker 服务 (sudo systemctl restart docker 或 sudo service docker restart)。

请务必先确保这些前提条件已满足，尤其是 NVIDIA 驱动和 nvidia-container-toolkit 的正确安装，这是 Docker 容器访问 GPU 的关键。

4. 获取 vLLM Docker 镜像

有两种主要方式获取 vLLM 的 Docker 镜像：使用预构建镜像或自行构建。

4.1. 使用预构建镜像 (推荐)

vLLM 官方在 Docker Hub 上提供了预构建的镜像，这些镜像通常包含了稳定版本的 vLLM、必要的依赖和编译好的 CUDA 核函数。这是最简单、最快速的入门方式。

1. 拉取镜像: 打开终端，使用 docker pull 命令拉取最新的 vLLM 镜像。通常镜像名称为 vllm/vllm-openai 或类似的名称，它提供了兼容 OpenAI API 的服务。

   bash
docker pull vllm/vllm-openai:latest

   或者指定特定版本或基于不同 CUDA 版本的镜像（如果可用）。例如，一个基于 CUDA 12.1 的镜像：

   bash
docker pull vllm/vllm-openai:latest-cu121

   您可以访问 vLLM 的 Docker Hub 页面 (https://hub.docker.com/r/vllm/vllm-openai/tags) 查看所有可用的 Tag 和版本。

   这个过程会从 Docker Hub 下载镜像到您的宿主机本地。等待下载完成。

2. 验证镜像: 下载完成后，可以使用 docker images 命令查看本地已有的 Docker 镜像列表，确认 vLLM 镜像已成功拉取。

   bash
docker images

   您应该能看到 vllm/vllm-openai 及其对应的 Tag 出现在列表中。

4.2. 自行构建镜像 (适用于特定需求)

如果您需要使用最新的 vLLM 代码、特定的 Python 版本、安装额外的库，或者对构建过程有完全的控制，您可以选择自行构建 Docker 镜像。

1. 克隆 vLLM 仓库:

   bash
git clone https://github.com/vllm-project/vllm.git
cd vllm

2. 编写或修改 Dockerfile: vLLM 仓库通常包含用于构建 Docker 镜像的 Dockerfile。您可以在仓库根目录或 docker 目录下找到它们。您可以根据需要修改 Dockerfile，例如更换基础镜像、安装额外的依赖等。

3. 构建镜像: 在包含 Dockerfile 的目录中执行 docker build 命令。

   bash
docker build -t my-vllm-image .

   这里的 -t my-vllm-image 为您要构建的镜像指定一个名称和 Tag（这里是 my-vllm-image:latest）。后面的 . 表示 Dockerfile 位于当前目录。

   构建过程可能需要一些时间，因为它会下载基础镜像、安装依赖、编译 CUDA 核函数等。请确保您的机器有足够的计算资源和网络连接。

4. 验证镜像: 构建完成后，同样使用 docker images 命令验证您的自定义镜像是否存在。

   bash
docker images

   您应该能看到 my-vllm-image 出现在列表中。

自行构建镜像提供了最大的灵活性，但也需要更多时间和对 Docker 构建过程的了解。对于大多数用户而言，使用官方预构建镜像已经足够。

5. 运行 vLLM Docker 容器

获取镜像后，就可以开始运行 vLLM 容器了。最常见的用法是启动一个 vLLM 的 HTTP 服务，通常兼容 OpenAI API。

使用 docker run 命令来启动容器。以下是关键的命令组成部分和选项：

bash
docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

在运行 vLLM 容器时，我们需要特别关注以下几个选项：

• --gpus all: 这是最关键的选项，它告诉 Docker 容器需要访问宿主机的所有 GPU。如果只想访问特定的 GPU，可以使用 --gpus '"device=GPU-UUID1,GPU-UUID2"' 或 --gpus '"device=0,1"' 来指定。这依赖于 nvidia-container-toolkit。
• -p HOST_PORT:CONTAINER_PORT: 将容器内部的端口映射到宿主机上的端口。vLLM 的 HTTP 服务默认在容器内部的 8000 端口监听，我们通常需要将其映射到宿主机上的一个端口，以便从外部访问。
• -v HOST_PATH:CONTAINER_PATH: 挂载宿主机的目录或文件到容器内部。这对于持久化数据、共享文件或加载模型文件非常有用。例如，可以将 Hugging Face 模型缓存目录挂载到容器内部，避免每次启动容器都重新下载模型。
• -e VAR_NAME=VAR_VALUE: 设置容器内部的环境变量。虽然 vLLM 服务的主要配置通过命令行参数传递，但有时也可能需要设置特定的环境变量。
• --name CONTAINER_NAME: 为容器指定一个易于识别的名称。
• -d: 在后台运行容器（分离模式）。
• --rm: 容器停止后自动删除。这在测试或临时运行时很有用，可以避免产生大量的停止容器。

5.1. 基本示例：运行一个简单的模型服务

让我们运行一个最简单的示例，使用一个预构建的镜像启动一个服务，加载一个小型模型（例如 facebook/opt-125m）。

bash
docker run --gpus all -p 8000:8000 vllm/vllm-openai:latest \
--model facebook/opt-125m

• docker run: 运行一个新的容器。
• --gpus all: 允许容器访问所有可用的 GPU。
• -p 8000:8000: 将宿主机的 8000 端口映射到容器内部的 8000 端口。
• vllm/vllm-openai:latest: 使用我们之前拉取的最新 vLLM OpenAI 镜像。
• --model facebook/opt-125m: 这是传递给容器内部 vLLM 服务启动脚本的参数，告诉它加载 facebook/opt-125m 这个模型。如果模型不在容器内，vLLM 会自动从 Hugging Face Hub 下载。

运行这个命令后，您会看到容器启动的日志输出。vLLM 会下载或加载模型，并在 8000 端口启动 HTTP 服务。如果模型需要下载，请确保网络连接正常。

5.2. 使用卷挂载模型：处理大型模型

对于大型模型（如 Llama-2 7B），每次启动容器都下载模型是不现实的，而且会浪费带宽和时间。更推荐的做法是将模型文件存储在宿主机上，然后通过卷挂载的方式让容器访问。

1. 在宿主机上下载模型: 您可以使用 Hugging Face 的 transformers 库或 huggingface_hub 库将模型下载到宿主机的某个目录。例如，下载 Llama-2 7B Chat 模型：

   “`python
   from transformers import AutoModelForCausalLM, AutoTokenizer

   model_name = “meta-llama/Llama-2-7b-chat-hf” # 或其他您有权限访问的模型

   需要先安装 transformers 和 torch: pip install transformers torch

   对于 Llama-2 系列模型，需要先在 Hugging Face 上申请访问权限并登录

   huggingface-cli login

   指定下载路径

   download_path = “/path/to/your/model/cache/Llama-2-7b-chat-hf”

   下载 tokenizer

   tokenizer = AutoTokenizer.from_pretrained(model_name)
   tokenizer.save_pretrained(download_path)

   下载 model (只需下载权重文件)

   AutoModelForCausalLM.from_pretrained(model_name).save_pretrained(download_path)

   或者更推荐使用 huggingface_hub 下载

   from huggingface_hub import snapshot_download
   snapshot_download(repo_id=model_name, local_dir=download_path, local_dir_use_symlinks=False)

   print(f”Model and tokenizer downloaded to {download_path}”)
   ``
请将/path/to/your/model/cache` 替换为您实际希望存储模型的宿主机路径。确保该路径存在且有足够的空间。

2. 运行 Docker 容器并挂载卷:

   “`bash

   假设模型下载到了宿主机的 /data/huggingface_models/Llama-2-7b-chat-hf 路径

   HOST_MODEL_PATH=”/data/huggingface_models/Llama-2-7b-chat-hf”
   CONTAINER_MODEL_PATH=”/app/models/Llama-2-7b-chat-hf” # 容器内部访问模型的路径

   docker run –gpus all \
   -p 8000:8000 \
   -v ${HOST_MODEL_PATH}:${CONTAINER_MODEL_PATH} \
   vllm/vllm-openai:latest \
   –model ${CONTAINER_MODEL_PATH}
   “`

   • -v ${HOST_MODEL_PATH}:${CONTAINER_MODEL_PATH}: 这一行将宿主机的 ${HOST_MODEL_PATH} 目录挂载到容器内部的 ${CONTAINER_MODEL_PATH} 目录。这样，容器内部就可以访问宿主机上下载好的模型文件了。
   • --model ${CONTAINER_MODEL_PATH}: 传递给 vLLM 服务的参数，告诉它从容器内部的 ${CONTAINER_MODEL_PATH} 路径加载模型。

   使用这种方式，无论您多少次启动或停止容器，只要不删除宿主机上的模型文件，vLLM 都能快速加载模型，无需重复下载。

5.3. 后台运行与命名容器

为了方便管理，通常会将容器放在后台运行，并为其指定一个名称。

“`bash
HOST_MODEL_PATH=”/data/huggingface_models/Llama-2-7b-chat-hf”
CONTAINER_MODEL_PATH=”/app/models/Llama-2-7b-chat-hf”

docker run -d –name vllm-llama7b-service –gpus all \
-p 8000:8000 \
-v ${HOST_MODEL_PATH}:${CONTAINER_MODEL_PATH} \
vllm/vllm-openai:latest \
–model ${CONTAINER_MODEL_PATH} \
–tensor-parallel-size 1 # 根据需要调整并行度
“`

• -d: 在后台运行。
• --name vllm-llama7b-service: 将容器命名为 vllm-llama7b-service。

您可以使用 docker ps 查看正在运行的容器，使用 docker logs vllm-llama7b-service 查看容器的日志输出，使用 docker stop vllm-llama7b-service 停止容器，使用 docker start vllm-llama7b-service 启动已停止的容器，使用 docker rm vllm-llama7b-service 删除容器。

6. 使用 vLLM API (容器内外)

一旦 vLLM 容器启动并服务正在运行，您就可以通过映射的端口与其进行交互。vLLM 的 OpenAI 兼容服务提供了类似于 OpenAI Completion 和 Chat Completion 的 API 接口。

假设您将容器内部的 8000 端口映射到了宿主机的 8000 端口。API 的基础 URL 将是 http://localhost:8000/v1。

6.1. 使用 curl 进行测试

您可以使用 curl 命令快速测试 API 是否正常工作。

Completion API:

bash
curl http://localhost:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{
"model": "/app/models/Llama-2-7b-chat-hf",
"prompt": "Hello, my name is",
"max_tokens": 50,
"temperature": 0.7
}'

请注意，"model" 参数在这里通常需要与启动容器时 --model 参数指定的值匹配（即容器内部的模型路径或模型名称）。

Chat Completion API:

bash
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "/app/models/Llama-2-7b-chat-hf",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the capital of France?"}
],
"max_tokens": 100,
"temperature": 0.7
}'

如果一切正常，您将收到包含模型生成文本的 JSON 响应。

6.2. 使用 Python requests 库

在实际应用中，您通常会使用编程语言与 API 交互。使用 Python 的 requests 库是一个常见的选择。

首先确保安装 requests：

bash
pip install requests

然后编写 Python 代码：

“`python
import requests
import json

API_URL = “http://localhost:8000/v1/completions” # 或 http://localhost:8000/v1/chat/completions
MODEL_NAME = “/app/models/Llama-2-7b-chat-hf” # 与容器启动时 –model 参数一致

Completion API 示例

def generate_completion(prompt, max_tokens=100, temperature=0.7):
headers = {“Content-Type”: “application/json”}
data = {
“model”: MODEL_NAME,
“prompt”: prompt,
“max_tokens”: max_tokens,
“temperature”: temperature,
# 更多参数请参考 vLLM OpenAI API 文档
# “top_p”: 0.95,
# “presence_penalty”: 0.5,
# “frequency_penalty”: 0.5
}

try:
    response = requests.post(API_URL, headers=headers, data=json.dumps(data))
    response.raise_for_status() # 如果请求失败（非2xx状态码），抛出异常
    result = response.json()
    # print(json.dumps(result, indent=2)) # 打印完整响应
    if result and result.get("choices"):
        return result["choices"][0].get("text", "").strip()
    else:
        return "No text generated."
except requests.exceptions.RequestException as e:
    print(f"API request failed: {e}")
    return None

Chat Completion API 示例

API_CHAT_URL = “http://localhost:8000/v1/chat/completions”

def generate_chat_completion(messages, max_tokens=100, temperature=0.7):
headers = {“Content-Type”: “application/json”}
data = {
“model”: MODEL_NAME,
“messages”: messages,
“max_tokens”: max_tokens,
“temperature”: temperature,
# 更多参数请参考 vLLM OpenAI API 文档
}

try:
    response = requests.post(API_CHAT_URL, headers=headers, data=json.dumps(data))
    response.raise_for_status()
    result = response.json()
    # print(json.dumps(result, indent=2))
    if result and result.get("choices"):
        return result["choices"][0].get("message", {}).get("content", "").strip()
    else:
        return "No response message."
except requests.exceptions.RequestException as e:
    print(f"API request failed: {e}")
    return None

示例调用

if name == “main“:
# Completion example
prompt_text = “The quick brown fox jumps over the lazy”
completion_text = generate_completion(prompt_text, max_tokens=30)
print(f”Prompt:\n{prompt_text}”)
print(f”Completion:\n{completion_text}\n”)

# Chat Completion example
chat_messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the best way to learn a new language?"}
]
chat_response = generate_chat_completion(chat_messages, max_tokens=150)
print(f"Chat Messages:\n{chat_messages}")
print(f"Chat Response:\n{chat_response}")

“`

这段代码展示了如何通过 HTTP POST 请求向 vLLM 服务发送请求并处理响应。您可以将其集成到您的应用程序或服务中。

7. 进阶配置与使用

vLLM 提供了许多命令行参数来控制模型的加载和推理行为。在 Docker 中运行服务时，这些参数直接跟在镜像名称后面。

bash
docker run --gpus all -p 8000:8000 -v /path/to/models:/app/models vllm/vllm-openai:latest \
--model /app/models/YourModel \
--tokenizer /app/models/YourModel # 通常与 --model 相同
--tensor-parallel-size N # 使用 N 块 GPU 进行张量并行
--quantization QUANT # 使用量化模型，例如 'awq', 'gptq', 'squeezellm'
--dtype auto # 模型权重的数据类型 (auto, half, float)
--max-model-len M # 模型支持的最大上下文长度
--trust-remote-code # 允许加载自定义模型代码 (谨慎使用)
--download-dir /app/cache # 指定模型下载目录 (如果未挂载模型)
--max-num-seqs S # 并发处理的最大序列数
--max-paged-attention-tokens N # PagedAttention 缓存的最大 token 数
--gpu-memory-utilization FACTOR # GPU 显存使用率 (0.0 - 1.0)
--enforce-eager # 强制使用 eager 模式 (用于调试)
--hostname 0.0.0.0 # 监听所有网络接口
--port 8000 # 服务监听端口 (容器内部)
# ... 更多参数请参考 vLLM 文档

其中一些常用且重要的参数解释：

• --tensor-parallel-size N: 如果您有多块 GPU 并且模型无法完全加载到单块 GPU 的显存中，或者您希望利用多块 GPU 加速推理，可以设置此参数。它会将模型的张量计算分布到 N 块 GPU 上。需要确保这些 GPU 可以通过 NVLink 或 PCIe 互联，并且您的驱动和 CUDA Toolkit 支持。
• --quantization QUANT: 如果您使用量化过的模型（如 AWQ, GPTQ, SqueezeLLM 等），需要指定对应的量化方式。vLLM 支持多种量化格式，这可以显著减少模型的显存占用。
• --gpu-memory-utilization FACTOR: 控制 vLLM 预留多少 GPU 显存用于 KV cache 和其他内部结构。默认值通常是 0.9（即预留 90% 显存）。如果您发现显存不足，可以适当降低此值，但这可能会限制并发请求的数量。如果您知道模型本身需要占用多少显存，可以将其设置为一个略高于模型权重所需显存比例的值。
• --max-model-len M: 设置模型能够处理的最大输入序列长度（prompt + generated tokens）。这取决于模型的架构和预训练时的设置。
• --max-num-seqs S: 设置 vLLM 可以同时激活处理的最大序列数。这个值越大，理论上吞吐量越高，但会消耗更多显存，并且可能受 max-paged-attention-tokens 的限制。
• --dtype: 控制模型权重的加载精度。auto 会尝试检测模型文件的精度，half (FP16/BF16) 是常见的推理精度，float (FP32) 占用显存最多且推理速度较慢，通常不用于推理。

示例：运行一个使用量化模型并利用两块 GPU 的服务

假设您有一个 70B 参数的量化模型（如 GPTQ 格式），并且您有两块 GPU (--tensor-parallel-size 2)。

“`bash
HOST_MODEL_PATH=”/data/huggingface_models/Llama-2-70b-chat-hf-gptq”
CONTAINER_MODEL_PATH=”/app/models/Llama-2-70b-chat-hf-gptq”

docker run -d –name vllm-llama70b-gptq –gpus all \
-p 8000:8000 \
-v ${HOST_MODEL_PATH}:${CONTAINER_MODEL_PATH} \
vllm/vllm-openai:latest \
–model ${CONTAINER_MODEL_PATH} \
–quantization gptq \
–tensor-parallel-size 2 \
–max-model-len 4096 \
–gpu-memory-utilization 0.85 # 适当降低显存使用率以防溢出
“`

请根据您实际的模型、硬件和需求调整这些参数。查阅 vLLM 官方文档获取完整的参数列表和详细说明是非常重要的。

8. 管理容器

了解一些基本的 Docker 容器管理命令，对于部署和维护 vLLM 服务至关重要：

• docker ps: 列出当前正在运行的容器。
• docker ps -a: 列出所有容器（包括已停止的）。
• docker logs CONTAINER_NAME_OR_ID: 查看容器的日志输出。这对于调试非常有用。
• docker stop CONTAINER_NAME_OR_ID: 停止指定的容器。
• docker start CONTAINER_NAME_OR_ID: 启动已停止的容器。
• docker restart CONTAINER_NAME_OR_ID: 重启容器。
• docker rm CONTAINER_NAME_OR_ID: 删除指定的容器（容器必须是停止状态）。
• docker exec -it CONTAINER_NAME_OR_ID /bin/bash: 在运行中的容器内部执行命令（例如进入容器的 shell 环境进行检查）。

使用 docker ps 可以获取容器的名称或 ID，然后将其用于其他命令。

9. 故障排除常见问题

在 Docker 中部署 vLLM 时，可能会遇到一些问题。以下是一些常见问题及其排查思路：

1. 错误: docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: OCI runtime exec failed: exec: "nvidia-container-runtime": executable file not found in $PATH: unknown.

   • 原因: nvidia-container-toolkit 未正确安装或 Docker 服务未重启。
   • 解决: 确保已安装 nvidia-container-toolkit，并重启 Docker 服务 (sudo systemctl restart docker)。

2. 错误: docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]].

   • 原因: --gpus all 参数未正确识别，通常也是 nvidia-container-toolkit 配置问题。
   • 解决: 检查 nvidia-container-toolkit 安装和配置，重启 Docker 服务。确认宿主机 NVIDIA 驱动正常工作 (nvidia-smi)。

3. 错误: CUDA related errors inside the container (e.g., CUDA driver version is insufficient for CUDA runtime version).

   • 原因: 宿主机 NVIDIA 驱动版本与容器内部 CUDA Toolkit 版本不兼容。
   • 解决: 确保您的宿主机 NVIDIA 驱动版本高于或等于容器镜像所使用的 CUDA Toolkit 版本。可以尝试拉取与您的驱动更兼容的 vLLM 镜像版本，或者升级您的 NVIDIA 驱动。

4. 错误: OSError: Does not appear to be a consistent VLLM model directory... or ValueError: Not a valid model name or path.

   • 原因: --model 参数指定的路径不正确，或者挂载的模型目录不包含完整的模型文件。
   • 解决: 检查您的 -v HOST_PATH:CONTAINER_PATH 挂载是否正确，确保 HOST_PATH 指向的模型目录在宿主机上是正确的，并且在容器内部，CONTAINER_PATH 能够访问到完整的模型文件。同时，确认 --model 参数的值与 CONTAINER_PATH 或模型名称一致。对于 Hugging Face 模型，确保下载的是模型的所有必要文件（权重、tokenizer、config 等）。

5. 错误: CUDA out of memory. Tried to allocate N GiB (GPU N; M GiB total; O GiB free; P GiB used)

   • 原因: GPU 显存不足以加载模型或处理当前批次的请求。
   • 解决:
     • 使用参数量更小的模型。
     • 使用量化版本的模型 (--quantization)。
     • 如果使用多 GPU，增加 --tensor-parallel-size。
     • 适当降低 --gpu-memory-utilization 参数值（谨慎，可能影响性能）。
     • 降低 max_tokens 或 max_num_seqs（在 API 请求或服务参数中）。

6. 容器启动后立即退出 (docker ps -a 显示 Exited)。

   • 原因: 容器内的启动命令执行失败。可能是参数错误、模型加载失败、依赖问题等。
   • 解决: 使用 docker logs CONTAINER_NAME_OR_ID 查看容器的日志输出，找出具体的错误信息。

7. 无法访问容器映射的端口。

   • 原因: 防火墙阻止了宿主机的端口，或者端口映射不正确。
   • 解决: 检查宿主机的防火墙设置，确保映射的端口是开放的。使用 netstat -tulnp | grep PORT 查看宿主机端口是否被其他进程占用。确认 docker run -p 参数正确。

在排查问题时，docker logs 命令是您的最佳工具，它能显示容器内部启动 vLLM 服务时的详细输出和任何发生的错误。

10. 总结

通过将 vLLM 部署在 Docker 容器中，我们能够充分利用 vLLM 的高性能推理能力和 Docker 提供的环境隔离、可移植性优势。从拉取预构建镜像到运行容器、挂载模型卷、配置服务参数，再到通过 HTTP API 进行交互，整个流程变得标准化和可重复。

本文详细介绍了在 Docker 中部署 vLLM 的关键步骤、常用配置以及如何使用其 OpenAI 兼容 API。掌握这些技术，您可以更高效、更可靠地将大型语言模型集成到您的应用或服务中，应对不断增长的 LLM 推理需求。

请记住，LLM 推理对硬件资源，尤其是 GPU 显存有较高要求。在实际部署时，务必根据您选择的模型和预期的流量规模，合理配置硬件资源和 vLLM 的相关参数。

希望本文能为您在 Docker 中部署和使用 vLLM 提供有价值的参考和帮助。祝您部署顺利！

---