解决MiniCPM-V项目中使用vLLM API时的模型名称问题

在使用MiniCPM-V大模型项目时，许多开发者选择通过vLLM框架来部署和调用模型。然而，在实际操作过程中，经常会遇到一个典型问题：当通过vLLM API方式调用模型时，系统提示找不到模型名称。

问题现象分析

开发者通常会按照标准流程部署vLLM服务，使用类似如下的命令启动服务：

CUDA_VISIBLE_DEVICES=1 vllm serve /path/to/model --host 0.0.0.0 --port 9998

服务启动后，通过OpenAI客户端库进行API调用时，却收到404错误，提示"模型不存在"。这种问题的根源在于vLLM服务的模型名称识别机制与API调用时的模型名称匹配出现了偏差。

根本原因

vLLM服务在启动时，默认情况下会将模型路径作为模型名称注册到服务中。然而，当API调用时，如果直接使用完整的本地路径作为模型名称，vLLM无法正确识别这个名称，导致找不到模型的错误。

解决方案

正确的做法是在启动vLLM服务时，显式指定一个简化的服务模型名称。具体步骤如下：

1. 启动服务时指定模型名称：

NAME="MiniCPM-V-2_6" && \
vllm serve /path/to/model \
    --served-model-name $NAME \
    --host 0.0.0.0 \
    --port 8001 \
    --trust-remote-code

关键参数--served-model-name用于指定服务注册时使用的模型名称。

2. API调用时使用相同的名称：

from openai import OpenAI

client = OpenAI(
    api_key='EMPTY_API_KEY',
    base_url='http://localhost:8001/v1'
)

response = client.chat.completions.create(
    model='MiniCPM-V-2_6',  # 必须与--served-model-name一致
    messages=[...]
)

注意事项

1. 服务端和客户端使用的模型名称必须完全一致，包括大小写
2. 模型名称中避免使用特殊字符和路径分隔符
3. 对于MiniCPM-V这类多模态模型，vLLM当前版本(0.4.1)尚不支持视频和多图输入

扩展建议

对于生产环境部署，建议考虑以下优化：

• 使用容器化部署确保环境一致性
• 配置适当的GPU内存利用率参数(--gpu-memory-utilization)
• 根据硬件配置调整tensor并行度(--tensor-parallel-size)

通过正确配置模型名称，开发者可以顺利地在MiniCPM-V项目中使用vLLM的高性能推理能力，充分发挥这一先进多模态大模型的潜力。