GGUF в vLLM: плагин, токенизатор и проверка локального API

Почему обычной установки vLLM для GGUF недостаточно?

В документации vLLM для GGUF прямо указано, что поддержку перенесли в внешний плагин vllm-gguf-plugin; без него попытку загрузки GGUF нельзя считать корректной проверкой этой конфигурации s1. В pyproject.toml плагин регистрируется как vllm.general_plugins.gguf, то есть это отдельный пакет со своим циклом версий, а не любой произвольный GGUF, «поддерживаемый vLLM из коробки» s3.

Разработчики vLLM называют GGUF-режим экспериментальным и недостаточно оптимизированным; предупреждают о возможной несовместимости с другими возможностями s1. README плагина перечисляет модели и квантизации, покрытые тестами самого репозитория, но отдельно предупреждает: общая поддержка архитектуры в vLLM не гарантирует корректный перевод имён весов конкретного GGUF s2. Это заявления разработчиков, не независимые замеры Modelium. Если вам нужна модель, которой нет в проверяемой конфигурации, не переносите успешный пример на неё без локальной проверки.

Как выбрать модель, токенизатор и железо для пробы?

Официальный пример GGUF-документации берёт unsloth/Qwen3-0.6B-GGUF:Q4_K_M и отдельно задаёт --tokenizer Qwen/Qwen3-0.6B s1. В закреплённой ревизии репозитория Unsloth действительно присутствует файл Qwen3-0.6B-Q4_K_M.gguf, а исходная модель Qwen сохранена под отдельной ревизией s7s8. Метаданные обеих карточек указывают apache-2.0, но для коммерческого применения читайте тексты лицензий и происхождение конкретных весов отдельно; метка не является юридическим заключением s7s8.

Причина отдельного токенизатора практическая: vLLM предупреждает, что конвертация токенизатора из GGUF бывает долгой и нестабильной, особенно при большом словаре s1. Если Hugging Face не выводит конфигурацию архитектуры из метаданных GGUF, документация предлагает дополнительно --hf-config-path Qwen/Qwen3-0.6B, но это путь диагностики конкретной ошибки, не универсальный обязательный флаг s1.

Выбирайте совместимую среду по официальной инструкции vLLM для своего GPU: базовая страница установки описывает Linux и отдельные ветви CUDA/ROCm, а Windows не поддерживается нативно s5. README плагина для сборки из исходников требует CUDA либо ROCm toolkit и рекомендует сборку против той же установки PyTorch, что использует vLLM, с --no-build-isolation s2. Это не означает, что любой GPU автоматически запустит данный квант. Размер скачанного файла GGUF не равен минимальной VRAM: на размещение влияют модель, runtime, контекст и другие данные; перед загрузкой сравните ресурсы своей машины с разбором видеокарты.

Как установить плагин и получить ответ локального API?

Создайте отдельную среду для теста с совместимой установкой vLLM по инструкции runtime; сверяйте пакет и оборудование с официальной документацией vLLM s5. Затем документация GGUF рекомендует установить пакет в эту же среду и передать репозиторий с квантом и токенизатором при старте s1:

uv pip install vllm-gguf-plugin
vllm serve unsloth/Qwen3-0.6B-GGUF:Q4_K_M \
--tokenizer Qwen/Qwen3-0.6B \
--host 127.0.0.1 --port 8000

Команды скачивают зависимости и веса из сети; не запускайте их на закрытых данных или машине без согласованного доступа. uv pip install без фиксации версии в этом примере следует текущему реестру пакетов, поэтому для воспроизводимого прогона запишите vllm --version, версию vllm-gguf-plugin, сведения о PyTorch и зафиксируйте скачанные ревизии. Параметры --host и --port ограничивают адрес примера локальным интерфейсом; это редакционный выбор для теста, а не доказательство отсутствия сетевых обращений. Закреплённые коммиты документов и HF-ревизии не делают такую незафиксированную команду установки побайтово воспроизводимой.

После запуска в другом терминале выполните тестовый запрос без секретов к документированному endpoint Chat Completions. Он подходит текстовой модели при наличии chat template; vLLM не обещает, что каждый GGUF даст такой ответ s4:

curl -fsS http://127.0.0.1:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"unsloth/Qwen3-0.6B-GGUF:Q4_K_M","messages":[{"role":"user","content":"Ответь одним словом: тест"}],"max_tokens":32}'

Критерий проверки на вашей машине: HTTP без ошибки, JSON с непустым choices[0].message.content, в серверном логе — подтверждение загрузки ожидаемой модели/плагина. Запишите полный код/тело ошибки, если вместо ответа нет choices; не считайте работающий /health доказательством корректного GGUF-инференса. Modelium не получал такой ответ сам и не утверждает, что команды отработают на любой карте.

Что делать, если GGUF не загрузился?

• Сообщение об отсутствии поддержки GGUF: проверьте, что плагин установлен в той же среде Python, что и vLLM, и записана версия пакета; регистрация расширения видна в metadata пакета s1s3.
• Ошибка конфигурации архитектуры: попробуйте задокументированный --hf-config-path исходной модели, только если ошибка указывает на отсутствующую конфигурацию s1.
• Проблема токенизации или шаблона чата: используйте токенизатор исходной модели; Chat Completions требует chat template, а один факт загрузки весов не проверяет качество ответа s1s4.
• Несовместимые тензоры/квантизация: приложите к issue репозиторий, тип кванта, версии плагина и vLLM, полный текст ошибки mapping. Так рекомендует README разработчиков; не заменяйте модель «похожим» файлом без записи новой конфигурации s2.
• Ускорение или память хуже ожидаемого: сами разработчики называют GGUF в vLLM недооптимизированным. Сравнивайте на своём GPU с одним и тем же запросом и контекстом; никаких сравнительных замеров Modelium не проводил s1.

У серверного --api-key есть важная граница: официальная документация vLLM сообщает, что он не защищает все endpoint, включая /invocations; для доступа из сети нужен отдельный контроль на уровне reverse proxy и сети s4. Не выставляйте этот тестовый сервер в публичный Интернет. Если задача не требует именно GGUF, общий гайд vLLM поможет начать с поддерживаемого формата; если нужен выбор кванта, откройте GGUF и квантизацию.

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