vLLM怎么部署？从本地模型加载到OpenAI兼容API调用的实用指南

一、先确认vLLM是否适合你的场景

vLLM适合把受支持的大模型部署为推理服务，供内部聊天工具、知识库应用或其他后端通过HTTP调用。本文以单机、单模型、Linux与NVIDIA GPU环境为主线，不涉及训练和多机部署。

开始前用nvidia-smi检查GPU与驱动是否可见，再按所安装vLLM版本的要求核对Python、驱动和CUDA兼容性。其他硬件后端有各自的安装条件，不能直接照搬本例。模型架构、权重格式及量化方式也必须受支持，并非任意模型目录都能加载。

二、安装依赖并准备本地模型

建议使用独立虚拟环境，避免已有PyTorch依赖冲突。依次执行：

python -m venv .venv

source .venv/bin/activate

python -m pip install -U pip

pip install vllm openai huggingface_hub

下面以Qwen/Qwen2.5-1.5B-Instruct演示下载流程；它只是示例，不代表任意设备都能运行。下载前确认模型许可证、网络访问条件与磁盘空间。

hf download Qwen/Qwen2.5-1.5B-Instruct --local-dir ./models/Qwen2.5-1.5B-Instruct

模型目录应包含配置、分词器文件和完整权重，而不只是某个权重分片。若从其他工作目录启动服务，建议改用绝对路径。

三、启动OpenAI兼容服务

在模型目录的上一级执行以下命令，将接口先绑定到本机：

vllm serve ./models/Qwen2.5-1.5B-Instruct --served-model-name local-chat --host 127.0.0.1 --port 8000 --api-key replace-with-a-long-random-key --max-model-len 4096 --max-num-seqs 4 --gpu-memory-utilization 0.85

把示例密钥替换成长随机密钥。等待日志显示服务已启动后再发送请求；首次加载权重和初始化可能需要时间。

• 模型路径：第一个参数指向本地模型目录。--served-model-name定义对外名称，调用时使用local-chat，而不是目录路径。
• 上下文长度：--max-model-len限制单次请求的总上下文长度，包含输入与生成内容。这里的4096是示例配置，不能超过模型与当前运行配置的有效范围。
• 显存：--gpu-memory-utilization控制GPU内存使用预算，并不是权重压缩比例。显存还要容纳权重、KV缓存及运行开销，不能仅凭模型文件大小判断。
• 并发：--max-num-seqs限制同时处理的序列数。提高并发或上下文长度通常会增加资源压力，应先跑通单请求再调整。

四、用curl和Python调用

先检查模型列表，确认端口、密钥和服务名称：

curl http://127.0.0.1:8000/v1/models -H 'Authorization: Bearer replace-with-a-long-random-key'

然后发送非流式聊天请求：

curl http://127.0.0.1:8000/v1/chat/completions -H 'Authorization: Bearer replace-with-a-long-random-key' -H 'Content-Type: application/json' -d '{"model":"local-chat","messages":[{"role":"user","content":"用一句话解释什么是本地推理。"}],"max_tokens":128,"stream":false}'

成功后，可在响应的choices[0].message.content中读取文本。Python可复用OpenAI客户端，下面这段代码可保存为脚本运行：

from openai import OpenAI; client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="replace-with-a-long-random-key"); result = client.chat.completions.create(model="local-chat", messages=[{"role": "user", "content": "用一句话解释什么是本地推理。"}], max_tokens=128); print(result.choices[0].message.content)

兼容接口不等于完整复刻官方OpenAI API。工具调用、多模态和结构化输出等能力，要分别核对模型支持情况及vLLM配置。

五、接入内部应用前的检查

同机应用保留127.0.0.1绑定即可。若需跨机器访问，可绑定指定内网地址或0.0.0.0，但后者会监听所有可用网络接口，必须配合防火墙、鉴权和访问范围限制；容器中还需配置端口映射。不要把无保护接口直接暴露到公网，跨不可信网络应通过HTTPS反向代理接入。

启动失败先看服务端日志：核对模型文件、架构支持和GPU状态。显存不足时，检查其他进程占用，再降低上下文长度或并发，必要时选择更小模型。401响应先查密钥，连接失败先查监听地址与端口；聊天请求失败则检查model名称、聊天模板及请求长度。上线前用实际业务输入验证输出质量与资源占用。