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

Источник: https://modelium.tech/zhurnal/vllm-gguf-plugin/

Для GGUF в vLLM установите отдельный vllm-gguf-plugin: встроенная поддержка перенесена в плагин. На примере Qwen3-0.6B-GGUF документация показывает запуск с токенизатором исходной модели, затем можно проверить локальный HTTP-ответ. Поддержка экспериментальная: успешная загрузка конкретной квантизации и её производительность не следуют из наличия расширения.

**Срез документации — 27 сентября 2026 года.** Пример относится к vLLM `v0.30.0` и плагину `v0.0.5` по закреплённым Git-ревизиям; выпуск плагина датирован 10 августа [s1](#src-s1)[s3](#src-s3)[s6](#src-s6). Modelium не запускал этот стек: команды ниже — проверяемый путь по документации, не отчёт об успешном эксперименте.

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

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

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

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

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

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

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

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

Создайте отдельную среду для теста с **совместимой** установкой vLLM по [инструкции runtime](/zhurnal/vllm/); сверяйте пакет и оборудование с официальной документацией vLLM [s5](#src-s5). Затем документация GGUF рекомендует установить пакет в эту же среду и передать репозиторий с квантом и токенизатором при старте [s1](#src-s1):

uv pip install vllm-gguf-pluginvllm 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](#src-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 пакета [s1](#src-s1)[s3](#src-s3).

- **Ошибка конфигурации архитектуры:** попробуйте задокументированный `--hf-config-path` исходной модели, только если ошибка указывает на отсутствующую конфигурацию [s1](#src-s1).

- **Проблема токенизации или шаблона чата:** используйте токенизатор исходной модели; Chat Completions требует chat template, а один факт загрузки весов не проверяет качество ответа [s1](#src-s1)[s4](#src-s4).

- **Несовместимые тензоры/квантизация:** приложите к issue репозиторий, тип кванта, версии плагина и vLLM, полный текст ошибки mapping. Так рекомендует README разработчиков; не заменяйте модель «похожим» файлом без записи новой конфигурации [s2](#src-s2).

- **Ускорение или память хуже ожидаемого:** сами разработчики называют GGUF в vLLM недооптимизированным. Сравнивайте на своём GPU с одним и тем же запросом и контекстом; никаких сравнительных замеров Modelium не проводил [s1](#src-s1).

У серверного `--api-key` есть важная граница: официальная документация vLLM сообщает, что он не защищает **все** endpoint, включая `/invocations`; для доступа из сети нужен отдельный контроль на уровне reverse proxy и сети [s4](#src-s4). Не выставляйте этот тестовый сервер в публичный Интернет. Если задача не требует именно GGUF, [общий гайд vLLM](/zhurnal/vllm/) поможет начать с поддерживаемого формата; если нужен выбор кванта, откройте [GGUF и квантизацию](/zhurnal/gguf-i-kvantovanie/).

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

## Источники

1. [vLLM v0.30.0 — GGUF quantization](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/docs/features/quantization/gguf.md) — получено 2026-09-27
2. [vLLM GGUF plugin v0.0.5 — README](https://github.com/vllm-project/vllm-gguf-plugin/blob/d358f564fc8f470cddd7c141a149b4ebafafa01f/README.md) — получено 2026-09-27
3. [vLLM GGUF plugin v0.0.5 — pyproject.toml](https://github.com/vllm-project/vllm-gguf-plugin/blob/d358f564fc8f470cddd7c141a149b4ebafafa01f/pyproject.toml) — получено 2026-09-27
4. [vLLM v0.30.0 — OpenAI-compatible server](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/docs/serving/online_serving/openai_compatible_server.md) — получено 2026-09-27
5. [vLLM v0.30.0 — GPU installation](https://github.com/vllm-project/vllm/blob/ced6857afa0ea7b2e3f0846a62e1394e90f15607/docs/getting_started/installation/gpu.md) — получено 2026-09-27
6. [vLLM GGUF plugin — release v0.0.5](https://github.com/vllm-project/vllm-gguf-plugin/releases/tag/v0.0.5) — получено 2026-09-27
7. [Unsloth Qwen3-0.6B-GGUF — файлы репозитория](https://huggingface.co/unsloth/Qwen3-0.6B-GGUF/tree/50968a4468ef4233ed78cd7c3de230dd1d61a56b) — получено 2026-09-27
8. [Qwen3-0.6B — исходная модель и токенизатор](https://huggingface.co/Qwen/Qwen3-0.6B/tree/c1899de289a04d12100db370d81485cdf75e47ca) — получено 2026-09-27