通过vllm部署qwen3大模型以及基于 vLLM 的 OpenAI 兼容 API 接口调用方法总结

最新推荐文章于 2025-07-18 12:07:04 发布

原创最新推荐文章于 2025-07-18 12:07:04 发布 · 1.6k 阅读

15 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能 #算法 #linux #vllm #llm

一，通过vllm部署qwen3模型。

1.安装vllm

conda create -n qwen3 python=3.9 -y
conda activate qwen3
pip install vllm

2.下载qwen3模型文件

下载完整模型库

modelscope download --model Qwen/Qwen3-1.7B

下载单个文件到指定本地文件夹（以下载README.md到当前路径下“dir”目录为例）

modelscope download --model Qwen/Qwen3-1.7B README.md --local_dir ./dir

更多相关下载命令如下：

下载整个模型repo（到默认cache地址）#

    modelscope download --model 'Qwen/Qwen2-7b'

下载整个模型repo到指定目录#

    modelscope download --model 'Qwen/Qwen2-7b' --local_dir 'path/to/dir'

指定下载单个文件(以'tokenizer.json'文件为例)#

    modelscope download --model 'Qwen/Qwen2-7b' tokenizer.json

指定下载多个个文件#

    modelscope download --model 'Qwen/Qwen2-7b' tokenizer.json config.json

指定下载某些文件#

    modelscope download --model 'Qwen/Qwen2-7b' --include '*.safetensors'

指定下载cache_dir#

    modelscope download --model 'Qwen/Qwen2-7b' --include '*.json' --cache_dir './cache_dir'

模型文件将被下载到'cache_dir/Qwen/Qwen2-7b'。

指定下载local_dir#

    modelscope download --model 'Qwen/Qwen2-7b' --include '*.json' --local_dir './local_dir'

模型文件将被下载到'./local_dir'。

如果cache_dir和local_dir参数同时被指定，local_dir优先级高，cache_dir将被忽略。

3.通过vllm部署qwen3模型

如果为将模型下载到本地，可以通过以下命令在线下载模型并启动：

VLLM_USE_MODELSCOPE=true vllm serve Qwen/Qwen3-1.7B --enable-reasoning --reasoning-parser deepseek_r1

如果已经将模型下载到本地文件，可以指定文件路径启动：

CUDA_VISIBLE_DEVICES=0 vllm serve local/qwen3-1.7b/ --port 8888 --gpu-memory-utilization 0.3 --host 0.0.0.0

以下是关于这条命令的详细解释：

环境变量设置

CUDA_VISIBLE_DEVICES=0：设置环境变量 CUDA_VISIBLE_DEVICES 的值为 0。这表示只使用系统中编号为 0 的 GPU 来运行 VLLM 服务。如果系统有多个 GPU，这个设置可以指定使用特定的 GPU 来执行模型推理任务。

VLLM 服务启动命令

vllm serve：这是启动 VLLM 服务的命令。它会根据后续的参数和选项来加载指定的模型并启动服务。

模型路径

/home/xugq/qwen3-1.7b/：指定要加载的模型所在的目录。在这个例子中，模型存放在 /home/xugq/qwen3-1.7b/ 目录下。VLLM 会从这个路径加载模型文件和相关配置。

服务配置参数

--port 8102：指定 VLLM 服务监听的端口号为 8102。客户端可以通过这个端口与服务进行通信。

--gpu-memory-utilization 0.3：设置 GPU 显存的利用率限制为 30%。这可以防止模型使用过多的显存资源，适用于需要在多个任务共享 GPU 资源的情况下。

--host 0.0.0.0：指定服务监听的主机 IP 地址为 0.0.0.0，表示服务将接受来自任何 IP 地址的连接。这通常用于允许外部访问服务。

关于vllm启动服务更多相关参数如下：

模型相关参数

--model ：指定模型的名称或路径，告诉 VLLM 哪个模型将被用于服务。

--revision ：如果模型有多个版本（在 Hugging Face Hub 或其他支持版本控制的存储中），可以指定要使用的特定版本。

--tokenizer ：指定自定义的分词器路径或名称，用于对输入文本进行分词和编码，默认使用与模型同名的分词器。

--served-model-name：指定服务名称，并在代码中使用相同的名称调用模型

服务相关参数

--host ：设置服务监听的主机 IP 地址，默认通常是 127.0.0.1（仅本地访问），可以设置为 0.0.0.0 允许外部访问。

--port ：指定服务监听的端口号，默认可能是 8000，可以根据需要更改。

--workers ：设置处理请求数的并发工作进程数，对于高负载场景可以增加此值以提高吞吐量。

性能和资源控制参数

--gpu-memory-utilization ：控制 GPU 显存利用率，范围在 0 到 1 之间。例如设置为 0.7 表示允许模型使用 GPU 显存的 70%，用于在多个任务共享 GPU 资源时合理分配显存。

--max-gpu-memory ：指定模型在 GPU 上可使用的最大显存总量，如 16GB。这可以防止模型使用过多显存导致其他程序无法运行。

--trust-numpy-loading ：当设置为 true 时，允许从 numpy 文件加载张量数据。在加载本地预训练模型的权重文件（以 numpy 格式存储）时可能需要此参数。

推理控制参数

--max-model-len ：限制模型处理的最大输入或输出序列长度。例如设置为 2048，可以避免处理过长的文本序列导致显存占用过多或计算时间过长。

--sampling-parameters ：包括温度（temperature）、top - k、top - p 等采样参数，用于控制文本生成的随机性和多样性。如 --temperature 0.7 --top-k 50 --top-p 0.9。

--enable-reasoning ：启用模型的推理功能，例如逻辑推理、数学推理等，让模型在生成文本时能够进行一定的逻辑思考。

--reasoning-parser ：指定使用的推理解析器，如 deepseek_r1，用于解析推理过程中的逻辑结构，使模型的输出更符合逻辑和预期的格式。

其他参数

--verbose ：启用详细日志输出，用于调试和了解服务运行过程中的详细信息。

--help ：显示帮助信息，列出所有可用的命令和参数及其简要说明。

4.调用模型

当模型成功部署之后就可以通过符合openapi规范的相关接口调用模型了，以下是通过python代码调用示例：

from openai import OpenAI

# 配置 OpenAI 客户端（兼容 vLLM 的 OpenAPI 接口）
client = OpenAI(
    api_key="EMPTY",  # vLLM 无需认证密钥，任意字符串均可[1,3](@ref)
    base_url="http://localhost:8888/v1"  # 与 vLLM 服务端口一致[1,3](@ref)
)

def translate_english_to_chinese(text: str) -> str:
    """
    调用本地 vLLM 服务进行英译中（符合 OpenAPI 规范）
    
    Args:
        text: 需要翻译的英文文本
    
    Returns:
        str: 翻译后的中文文本
    """
    try:
        response = client.chat.completions.create(
            model="/home/xugq/qwen3-1.7b/",  # 使用模型路径，如通过--served-model-name指定名称需与 vLLM 服务启动时指定的名称一致
            messages=[{
                "role": "user",
                "content": f"请将以下英文翻译为中文：{text}"
            }],
            max_tokens=300,  # 控制生成文本长度[4](@ref)
            temperature=0.7,  # 控制生成随机性（0-1，越高越随机）[4](@ref)
            stream=False
        )
        return response.choices[0].message.content.strip()
    except Exception as e:
        raise RuntimeError(f"API 调用失败：{str(e)}")

# 示例调用
if __name__ == "__main__":
    english_text = """During the Spring Festival, Chinese families gather to make dumplings while elders share stories about Nian, the mythical beast. This tradition, dating back to the Shang Dynasty (1600-1046 BC), symbolizes family unity and the triumph of light over darkness. Red lanterns adorn streets, creating a festive atmosphere recognized by UNESCO as intangible cultural heritage."""
    
    translated_text = translate_english_to_chinese(english_text)
    print("翻译结果：\n", translated_text)

模型回复：

PS python translate.py
翻译结果：
 <think>
好的，用户让我把一段英文翻译成中文。首先，我需要仔细阅读原文，理解每个部分的意思。

第一句是关于春节，中国家庭做饺子，长辈讲关于年兽的故事。这里要注意“make dumplings”翻译成“包饺子”比较合适，而“Nian”是年兽，应该音译为“年兽”或者“年兽”，但通常用“年兽”更常见。

接下来是时间范围，Shang Dynasty（1600-1046 BC），需要准确翻译年份和朝代。注意“dating back to”可以翻译 为“源自”或者“起源于”，这里用“源自”更合适。

然后是象征意义，家庭团结和光明战胜黑暗。这里“symbolizes”翻译成“象征”没问题，但要注意句子的流畅性。    

最后一句提到红灯笼，UNESCO的非物质文化遗产。这里“adorn streets”翻译成“点缀街道”比较自然，“intangible cultural heritage”是“非物质文化遗产”，需要确认是否常用这个翻译。

检查一下有没有专有名词需要特别处理，比如“Nian”是否要加注释，但用户可能不需要，直接音译即可。另外，注意时间的准确性，比如1600到1046 BC，是否要写成“公元前1600年至公元前1046年”更清晰。

二，可能遇到的问题...

1.ValueError: To serve at least one request with the model's max seq len (40960), (4.38 GiB KV cache is needed, which is larger than the available KV cache memory (2.67 GiB).

该报错说明KV缓存所需的内存超过了可用的显存，KV缓存的计算涉及模型层数、序列长度和批次大小等因素，模型默认设置的max_seq_len是40960，

这大大超过了服务器的负载上限，应该降低通过调整--max_model_len参数以减少KV缓存需求。

CUDA_VISIBLE_DEVICES=0 vllm serve ./qwen3-1.7b/ --port 8888 --max-model-len 2048

2.openai.NotFoundError: Error code: 404 - {'detail': 'Not Found'}

发生该错误是因为/v1/models接口必须确认实际加载的模型名称，避免因名称不匹配导致404错误。

3.模型生成结果被截断

模型返回结果被截断可能是由于max_tokens参数设置过小，可以通过修改参数配置生成文本的长度限制：

response = client.chat.completions.create(

•      model="/home/xugq/qwen3-1.7b/",  # 使用模型名称（非路径），需与 vLLM 服务启动时指定的名称一致[3](@ref)

•      messages=[{

•        "role": "user",

•        "content": f"请将以下英文翻译为中文：{text}"

•      }],

•      max_tokens=1000,  # 增加生成文本长度限制以防止截断

•      temperature=0.7,  # 控制生成随机性（0-1，越高越随机）[4](@ref)

•      stream=False

•    )

三，基于 vLLM 的 OpenAI 兼容 API 接口调用方法

一、初始化客户端配置

所有接口调用前需配置 OpenAI 客户端，指向本地 vLLM 服务：

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",  # vLLM 无需密钥，任意字符串即可
    base_url="http://localhost:8102/v1"  # 端口需与启动命令一致
)

二、文本生成接口

1. 同步文本生成 (`/v1/completions`)

适用场景：非对话式文本生成（如问答、续写）

response = client.completions.create(
    model="模型名称（如 deepseek-ai/DeepSeek-R1-Distill-Qwen-7B）",
    prompt="输入文本",
    temperature=0.7,  # 控制生成随机性
    max_tokens=100,   # 生成最大长度
    stream=False      # 是否流式输出
)
print(response.choices[0].text)

2. 流式文本生成

启用流式传输实现逐词返回：

response = client.completions.create(
    model="模型名称",
    prompt="输入文本",
    stream=True
)
for chunk in response:
    print(chunk.choices[0].text, end="", flush=True)

三、对话交互接口 (`/v1/chat/completions`)

适用场景：多轮对话（如聊天机器人）

python

复制

response = client.chat.completions.create(
    model="模型名称",
    messages=[
        {"role": "system", "content": "你是一个助手"},
        {"role": "user", "content": "你好，介绍一下量子计算"}
    ],
    temperature=0.8,
    max_tokens=200
)
print(response.choices[0].message.content)

四、其他功能接口

1. 模型信息查询 (`/v1/models`)

获取已加载模型信息：

models = client.models.list()
print(models.data[0].id)  # 输出模型名称

2. 嵌入向量生成 (`/v1/embeddings`)

文本向量化处理：

response = client.embeddings.create(
    model="模型名称",
    input=["需要向量化的文本"]
)
print(response.data[0].embedding)

3. 健康检查 (`/health`)

服务状态监控：

curl http://localhost:8102/health

五、直接使用 CURL 调用

适用于非 Python 环境或快速测试：

# 文本生成示例
curl http://localhost:8102/v1/completions \
-H "Content-Type: application/json" \
-d '{
"model": "模型名称",
"prompt": "AI的未来是",
"max_tokens": 50
}'

# 对话生成示例
curl http://localhost:8102/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "模型名称",
"messages": [{"role": "user", "content": "写一首关于春天的诗"}]
}'