vLLM served-model-name: почему API не находит загруженную модель

Параметр served-model-name задаёт имя, по которому клиент обращается к модели в API vLLM. Если клиент передаёт другое значение в поле model, сервер может вернуть ошибку, хотя веса успешно загружены. Сначала получите список /v1/models и сопоставьте идентификатор с запросом. Переустановка CUDA такую ошибку маршрутизации не исправляет.

Разделите checkpoint и имя API

Checkpoint определяет загружаемые веса и конфигурацию. Имя API — договорённость с клиентом. Например, оператор может загрузить репозиторий определённой версии, а для локального приложения использовать понятный псевдоним. От изменения псевдонима веса, качество и размер контекста не меняются.

Справочник vLLM serve описывает --served-model-name. Сохраните отдельно исходный идентификатор репозитория и выбранное публичное имя. Иначе после обновления модели будет трудно понять, какой артефакт действительно отвечал под прежним обозначением.

Проверьте минимальный пример

Следующий пример показывает назначение параметра для уже совместимой среды:

vllm serve Qwen/Qwen3-0.6B \
  --served-model-name local-qwen \
  --max-model-len 4096

После готовности выполните curl http://127.0.0.1:8000/v1/models. В клиентском запросе используйте local-qwen, если именно такой идентификатор объявил сервер. Для контейнера аргумент передают движку после имени образа, как показано в инструкции Docker.

Пример не устанавливает библиотеку и не проверяет доступность GPU. Эти стадии должны быть завершены отдельно. Он также не создаёт несколько загруженных моделей: несколько имён могут обозначать один и тот же артефакт, а не независимые копии.

Найдите несовпадение на границе клиента

Посмотрите фактическое тело HTTP-запроса без секретных заголовков. Некоторые приложения сохраняют старое имя в настройках или передают его из переменной окружения. Другие показывают удобную подпись в интерфейсе, но отправляют иной идентификатор. Важно проверить отправленное поле, а не только видимый пользователю текст.

Если между клиентом и vLLM есть прокси, повторите запрос напрямую к локальному серверу. Успешный прямой запрос и неуспешный через прокси указывают на отдельную границу настройки. Путь API, базовый адрес и имя модели проверяйте независимо, чтобы не менять сразу несколько условий.

Не выдавайте псевдоним за совместимость

Название, похожее на модель другого поставщика, не добавляет поддержку её поведения. Параметры, шаблон сообщений и формат специальных ответов зависят от реально загруженного checkpoint и движка. Открывающийся endpoint ещё не означает, что все ожидания клиентской библиотеки выполнены.

Проверьте обычный и потоковый запрос, ограничение выхода и обработку неверного имени. Документация online serving описывает интерфейсы vLLM. Отдельный сценарий потока приведён в практическом тесте streaming.

После переименования проверьте старое и новое значение отдельными запросами. Так становится ясно, обновился ли нужный процесс и какие идентификаторы он действительно принимает сейчас.

Запишите имена в паспорт пилота

В таблице запуска нужны три поля: checkpoint с версией, имя API и адрес сервера. После обновления повторите запрос к списку моделей и контрольную генерацию. Так проверяется, что приложение обращается к нужному процессу и не использует старый сервер на соседнем порту.

Владельцу GPU это помогает передать воспроизводимый endpoint для проверки оборудования. Партнёру — оценить объём настройки интеграции отдельно от покупки карты.