Qwen3 用 vLLM 部署并提供 OpenAI 兼容接口

这篇适合谁，读完能做到什么

适合已经会写一点 Python、想把通义千问 Qwen3-8B 部署成本地服务的读者。读完你能用 ModelScope 下载模型，用 vLLM 直接跑一段离线推理，再启动一个兼容 OpenAI 协议的接口，并用 curl 和 Python 两种方式请求它。

vLLM 是什么，和直接用 Transformers 有什么不同

vLLM 是一个面向大语言模型的推理和部署服务系统。它用 PagedAttention 算法管理 KV 缓存，减少显存浪费；支持异步处理和连续批处理（continuous batching），同一时间处理多个请求时吞吐量更高；与 Hugging Face 模型兼容；可以在多块 GPU 上做分布式推理；还自带兼容 OpenAI 的 API 服务器^[1]。

简单说，直接用 Transformers 适合写脚本、做实验；vLLM 更像是为了「把模型当服务跑」准备的引擎。下面两部分正好对应这两种用法：先用它做离线推理，再把它启动成服务。

准备：环境、依赖和模型

测试环境是 Ubuntu 22.04、Python 3.12、CUDA 12.4、PyTorch 2.5.1，并默认你已经配好了带 CUDA 的 PyTorch^[1]。如果还没有，先自己装好它。

安装依赖前，先把 pip 的默认源换成清华镜像，再安装 ModelScope 和 vLLM：

python -m pip install --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

pip install modelscope
pip install vllm

这些命令的顺序不能乱：先升级 pip，再配置源，最后安装两个包^[1]。另外，AutoDL 平台提供了预先配好的 Qwen3 环境镜像，创建实例时选用它可以省去装环境的步骤^[1]。

模型用 ModelScope 下载。snapshot_download 的第一个参数是模型名，cache_dir 是下载目录。下面的脚本会把 Qwen3-8B 下到 /root/autodl-tmp：

from modelscope import snapshot_download

model_dir = snapshot_download('Qwen/Qwen3-8B', cache_dir='/root/autodl-tmp', revision='master')

运行前记得把 cache_dir 改成你自己的下载路径^[1]。下载模型需要一段时间，耐心等它完成。

第一步：离线推理，跑通 vLLM 引擎

离线推理是直接在脚本里调用模型，不经过网络接口。从 vLLM 里导入两个类：LLM 是离线推理的主类，SamplingParams 用来控制生成时的随机性和多样性^[1]。

脚本开头要设置一个环境变量。它告诉 vLLM 从 ModelScope 下载模型，否则默认会去 Hugging Face 拉取^[1]：

# 自动下载模型时，指定使用modelscope; 否则，会从HuggingFace下载
os.environ['VLLM_USE_MODELSCOPE']='True'

封装好的 get_completion 函数有几个默认参数：temperature 为 0.6，top_p 为 0.95，top_k 为 20，min_p 为 0，max_tokens 为 4096，max_model_len 为 8192^[1]。

def get_completion(prompts, model, tokenizer=None, temperature=0.6, top_p=0.95, top_k=20, min_p=0, max_tokens=4096, max_model_len=8192):

思考模式和非思考模式

Qwen3 默认开启思考能力，与 QwQ-32B 相提并论。只要在 tokenizer.apply_chat_template 里设置 enable_thinking=True，或者保留默认值，模型就进入思考模式^[1]。下面这段代码就是思考模式的例子，它先用分词器的聊天模板把提示词格式化成模型需要的输入：

if __name__ == "__main__":
    # 初始化 vLLM 推理引擎
    model='/root/autodl-tmp/Qwen/Qwen3-8B' # 指定模型路径
    tokenizer = AutoTokenizer.from_pretrained(model, use_fast=False) # 加载分词器

    prompt = "给我一个关于大模型的简短介绍。"
    messages = [
        {"role": "user", "content": prompt}
    ]
    text = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True,
        enable_thinking=True  # 是否开启思考模式，默认为 True
    )

代码注释给出了思考模式的推荐采样参数：temperature 0.6，TopP 0.95，TopK 20，MinP 0^[1]。

要关掉思考模式，就把 enable_thinking 设为 False。注释里给出的非思考模式推荐参数是：temperature 0.7，TopP 0.8，TopK 20，MinP 0^[1]。

开启思考模式时，模型的回答分两部分：推理过程放在 <think> 和 </think> 之间，</think> 之后才是最终答案^[1]。

跑完脚本，在终端执行：

python vllm_model.py

第二步：启动兼容 OpenAI 的服务

vllm serve 可以直接启动 OpenAI 协议的服务器。默认监听 http://localhost:8000，一次只托管一个模型，提供模型列表、completions 和 chat completions 三类接口^[1]。

completions 做基本的文本续写，模型在给定的提示后接着生成。
chat completions 面向对话，适合做聊天机器人^[1]。

启动参数里，--host 和 --port 设置地址，--model 指定模型，--chat-template 指定聊天模板，--served-model-name 设置对外暴露的模型名，--max-model-len 设置最大长度^[1]。

要开启思考模式，加上 --enable-reasoning。它要求同时指定 --reasoning-parser。推理模型的响应里会多出一个 reasoning_content 字段，装着推理步骤；deepseek_r1 解析器可以处理 <think> ... </think> 格式的内容^[1]。

启动 Qwen3-8B 的完整命令是：

VLLM_USE_MODELSCOPE=true vllm serve /root/autodl-tmp/Qwen/Qwen3-8B --served-model-name Qwen3-8B --max_model_len 8192 --enable-reasoning --reasoning-parser deepseek_r1

加载完成后，终端会出现服务已启动的提示。

第三步：用 curl 和 Python 测试接口

先查看模型列表：

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

再测试 Completions 接口。下面的请求让模型续写一个算术问题：

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen3-8B",
        "prompt": "我想问你，5的阶乘是多少？<think>\n",
        "max_tokens": 1024,
        "temperature": 0
    }'

Chat Completions 接口是对话格式，消息放在 messages 里：

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen3-8B",
        "messages": [
            {"role": "user", "content": "我想问你，5的阶乘是多少？<think>\n"}
        ]
    }'

如果要在程序里调用，可以直接用 OpenAI 的 Python SDK，只需把 base_url 指向本地服务^[1]：

# vllm_openai_chat_completions.py
from openai import OpenAI
openai_api_key = "sk-xxx" # 随便填写，只是为了通过接口参数校验
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

chat_outputs = client.chat.completions.create(
    model="Qwen3-8B",
    messages=[
        {"role": "user", "content": "什么是深度学习？"},
    ]
)
print(chat_outputs)

python vllm_openai_chat_completions.py

客户端示例里的 sk-xxx 只是占位字符串，注释说明它只为了通过接口参数校验^[1]。如果你要把接口开放给别人使用，需要另外做访问控制。

服务端运行时，会在控制台打印每个请求对应的日志和统计信息，排查问题时先看这里^[1]。

常见问题

启动时报错找不到模型怎么办？ 检查命令里的模型路径是否和下载目录一致。示例路径是 /root/autodl-tmp/Qwen/Qwen3-8B，下载脚本里 cache_dir 指向 /root/autodl-tmp^[1]。

**开了 --enable-reasoning 却没有推理内容？** 这个参数必须和 --reasoning-parser 一起使用，并且解析器要和模型输出格式匹配。教程示例用的是 deepseek_r1^[1]。

思考模式的回答太长？ 可以调低 max_tokens，或者用 enable_thinking=False 关掉思考模式。get_completion 的 max_tokens 默认是 4096^[1]。

API key 要不要真的申请？ 不需要。示例中的 sk-xxx 只用来通过客户端的参数检查^[1]。

限制

这篇以 8B 模型为例，给出的是一套具体的环境版本，换成更大的模型、更新的 CUDA 或 PyTorch，都可能要调整。max_model_len 设得越大，显存占用越多，要根据自己的显卡来定。另外，使用的是 ModelScope 下载的模型，如果你改用 Hugging Face，需要同步修改 VLLM_USE_MODELSCOPE 相关的设置^[1]。