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

vLLM отвечает, но API сообщает model not found? Проверяем served-model-name, список /v1/models, запрос клиента и отличие имени от checkpoint.

Автор: Команда Retrivium
Обновлено: 2026-11-01
Канонический URL: https://retrivium.ai/ru/journal/vllm-served-model-name/
Language: ru

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

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

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

[Справочник vLLM serve](https://docs.vllm.ai/en/stable/cli/serve/) описывает `--served-model-name`. Сохраните отдельно исходный идентификатор репозитория и выбранное публичное имя. Иначе после обновления модели будет трудно понять, какой артефакт действительно отвечал под прежним обозначением.

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

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

```bash
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](/ru/journal/vllm-docker-first-launch/).

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

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

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

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

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

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

Проверьте обычный и потоковый запрос, ограничение выхода и обработку неверного имени. [Документация online serving](https://docs.vllm.ai/en/stable/serving/online_serving/) описывает интерфейсы vLLM. Отдельный сценарий потока приведён в [практическом тесте streaming](/ru/journal/vllm-openai-streaming-test/).

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

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

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

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