用 Docker 和 FastAPI 部署 vLLM 接口

用 Docker 运行 vLLM，核心是启动官方 vllm/vllm-openai 镜像提供的 OpenAI 兼容 HTTP 服务，再让 FastAPI 应用连接它；你可以把业务路由和鉴权放在 FastAPI 中，模型推理仍由容器内服务完成。部署顺序是准备 GPU 与 Docker 环境、启动模型服务、核验模型列表，最后检查 FastAPI 到模型服务的请求链路。

准备 Linux、GPU 与 Docker 环境

先确认 GPU 满足要求。vLLM 的 NVIDIA GPU 安装文档要求 NVIDIA GPU 的 CUDA compute capability 为 7.5 或更高。

Docker 访问 GPU 前，需要在主机安装 NVIDIA 驱动并重启，再安装 NVIDIA Container Toolkit；这是 Docker GPU 访问文档列出的准备步骤。完成后可运行：

docker run -it --rm --gpus all ubuntu nvidia-smi

这个检查只确认容器能否看到 GPU。如果命令无法运行，应先处理驱动或容器运行时问题，不必继续排查模型接口。

用 Docker 启动模型服务

按 vLLM 的 Docker 文档，启动命令需要映射端口、挂载 Hugging Face 缓存、传入 HF_TOKEN，并配置共享内存：

docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=$HF_TOKEN" \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen3-0.6B

这里，-p 8000:8000 把容器服务映射到主机端口，挂载目录用于保留下载的模型文件。--ipc=host 让容器使用主机共享内存；如果主机策略不允许，也可以采用文档列出的 --shm-size，容量需要结合机器配置确定。

引擎参数必须放在镜像标签之后，因此 --model Qwen/Qwen3-0.6B 位于 vllm/vllm-openai:latest 后面。该命令启动的是模型服务，并不是 FastAPI 应用；FastAPI 应作为业务层另行运行并连接它。

FastAPI 如何连接 vLLM

vLLM 的 OpenAI 兼容服务器文档记录了 /v1/completions 和 /v1/chat/completions：前者用于文本生成模型，后者用于聊天请求。/v1/completions 不支持 suffix 参数，聊天接口会忽略 user 参数，因此不能把所有客户端参数都视为完全兼容。

vLLM 快速开始给出的客户端基础地址是：

openai_api_key = "EMPTY"
openai_api_base = "http://localhost:8000/v1"

这些值应放入 FastAPI 应用的配置或服务客户端中。它们不是 FastAPI 路由定义；vLLM 官方文档也没有规定业务路由的名称、鉴权方式或入参结构，这些应由你的 FastAPI 项目自行设计。

如果 FastAPI 与模型服务不在同一网络位置，不要照抄 localhost，而应把 openai_api_base 设置为 FastAPI 进程实际能够访问的模型服务地址。

验证模型列表与请求链路

先在模型服务所在主机检查模型列表：

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

能够返回模型列表，说明 HTTP 服务已经监听，且模型已注册。随后从 FastAPI 后端完成同样的连通检查：先确认能够访问 /v1/models，再通过客户端向 /v1/completions 或 /v1/chat/completions 发送实际请求，并确认响应能够进入业务解析逻辑。

如果第一步失败，优先检查端口映射、Docker GPU 配置和进程状态；如果模型列表正常但生成请求失败，再检查接口类型、模型能力、请求参数与聊天模板。

常见出错点

GPU 在容器中不可见

重新运行前面的 nvidia-smi 容器检查。驱动、容器工具链或运行时未配置正确时，不要继续调整模型参数。

容器共享内存或参数位置不对

对照官方命令检查 --ipc=host 是否保留，以及 --model 等引擎参数是否位于镜像标签之后。采用 --shm-size 时，要确认容器确实获得了足够的共享内存。

聊天请求提示缺少模板

服务默认使用 tokenizer 中保存的聊天模板；没有模板时无法处理聊天请求。--chat-template 可以接收模板文件路径或模板字符串，具体配置应按 vLLM 在线服务文档处理。

FastAPI 请求被拒绝

服务可通过 --api-key 或 VLLM_API_KEY 启用请求头中的 API key 检查，也可以在 --api-key 后传入多个 key 进行轮换。FastAPI 发出的请求头必须携带其中一个已配置的 key，具体规则见 vLLM 快速开始。

以上步骤按文中链接的官方文档整理，使用前请对照当前版本复核。

资料来源

• vLLM Docker 文档
• vLLM NVIDIA GPU 安装文档
• Docker GPU 访问文档
• vLLM 快速开始
• vLLM OpenAI 兼容服务器文档
• vLLM 在线服务文档