第3章 vLLM快速上手

3、vLLM快速上手：加载模型与启动API服务

好，咱们进入实操环节。前面聊了那么多架构和原理，现在该动手了。这一章我会带你走一遍完整的流程——从加载模型到启动服务，再到用curl验证推理效果。我以Llama和Qwen这两个主流模型为例，你跟着做一遍，基本就能掌握vLLM的日常用法。

3.1 环境准备与模型选择

动手之前，先把环境搭好。我个人习惯用Python 3.10+，vLLM对CUDA 11.8和12.1都支持得不错。你直接用pip安装就行：

pip install vllm

嗯，这里要注意。如果你在K8s里跑，建议用官方Docker镜像。我遇到过有人直接在宿主机装，结果依赖冲突搞了半天。用镜像省心很多：

docker pull vllm/vllm-openai:latest

模型方面，我选了两个有代表性的：

Llama-2-7b-chat-hf：Meta的经典开源模型，社区生态好
Qwen-7B-Chat：阿里的通义千问，中文表现优秀

你想想看，这两个模型一个偏英文生态，一个偏中文场景，正好覆盖大部分使用场景。我在项目中经常两个都部署，根据业务需求切换。

注意：模型下载需要huggingface的token。如果你在国内，建议配置镜像源。我曾经因为网络问题卡了一下午，后来换了hf-mirror.com才搞定。

3.2 使用vLLM加载模型

加载模型其实就一行代码。但这一行背后，vLLM做了大量优化工作。咱们先看代码：

from vllm import LLM, SamplingParams

# 加载Llama模型
llm = LLM(model="meta-llama/Llama-2-7b-chat-hf", 
          tensor_parallel_size=1,
          dtype="auto")

# 加载Qwen模型
llm_qwen = LLM(model="Qwen/Qwen-7B-Chat",
               tensor_parallel_size=1,
               dtype="auto")

这里有几个参数我解释一下：

参数	说明	我的建议
model	模型名称或路径	优先用huggingface模型名，本地路径也行
tensor_parallel_size	张量并行数	单卡设1，多卡按GPU数量设
dtype	数据类型	auto自动选择，显存紧张用float16

加载过程中，vLLM会做几件事：下载模型权重、构建KV cache、预热CUDA kernel。我第一次跑的时候，看到日志里一堆"Loading..."还以为卡住了。其实它在后台做内存分配和算子编译，耐心等一会儿就好。

小技巧：如果你显存不够，可以加max_model_len=4096限制最大序列长度。我在一个4GB显存的卡上试过，把长度砍到2048，照样能跑7B模型。

3.3 启动OpenAI兼容的API服务

模型加载好了，接下来启动API服务。vLLM内置了OpenAI兼容的接口，这意味着你可以直接用openai的Python包或者curl来调用。启动命令很简单：

python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-2-7b-chat-hf \
    --port 8000 \
    --host 0.0.0.0

服务启动后，你会看到类似这样的输出：

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

这时候，你的API服务就准备好了。它支持以下几个核心接口：

/v1/chat/completions：聊天补全（最常用）
/v1/completions：文本补全
/v1/models：查看可用模型

我个人习惯先调一下/v1/models接口，确认服务正常：

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

返回的JSON里会列出你加载的模型名称。如果看到404，八成是端口没开或者服务没起来。

避坑指南：我曾经在K8s里部署时，忘了设置--host 0.0.0.0，结果服务只监听localhost，外部死活调不通。排查了半天才发现是这个问题。你部署到容器里一定要加上这个参数。

3.4 使用curl测试推理接口

服务跑起来了，咱们用curl测一下推理效果。先试个简单的聊天请求：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-2-7b-chat-hf",
    "messages": [
      {"role": "user", "content": "请用中文介绍一下深度学习"}
    ],
    "temperature": 0.7,
    "max_tokens": 200
  }'

返回结果大概长这样：

{
  "id": "cmpl-xxx",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "深度学习是机器学习的一个分支..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 180,
    "total_tokens": 195
  }
}

注意看usage字段，它告诉你这次请求用了多少token。这个数据对计费和性能分析很有用。我在做成本优化时，就是靠这个字段来估算每token的成本。

如果你想测Qwen模型，把model字段改成Qwen/Qwen-7B-Chat就行。接口完全兼容，不需要改其他参数。

调试技巧：如果返回结果乱码或者内容不对，检查一下temperature参数。设得太高（比如1.5）模型容易胡说八道。我一般设0.7，平衡创造性和准确性。

3.5 核心流程总结

这一套流程走下来，其实就三步：加载模型、启动服务、调用接口。为了让你更直观地理解，我画了一张流程图：

这张图把整个流程串起来了。你从左边开始，一步步走到右边，就能跑通一个完整的推理服务。说白了，vLLM把最复杂的显存管理和调度都封装好了，你只需要关心模型选择和参数配置。

嗯，这一章的内容就到这里。你跟着操作一遍，应该能感受到vLLM的便捷性。下一章我们会深入K8s部署，到时候会涉及更复杂的配置和优化策略。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

3、vLLM快速上手：加载模型与启动API服务

3.1 环境准备与模型选择

3.2 使用vLLM加载模型

3.3 启动OpenAI兼容的API服务

3.4 使用curl测试推理接口

3.5 核心流程总结