pygbnf: грамматики для llama.cpp без головной боли с зависимостями

Зачем кому-то еще одна библиотека для грамматик?

Вы пытаетесь заставить вашу скачанную в GGUF модель выдавать строгий JSON. Пишете GBNF-грамматику вручную. Потом добавляете еще одну для другого типа ответа. Вскоре у вас папка с дюжиной файлов, которые конфликтуют между собой, потому что один поменял версию llama-cpp-python, а другой требует старую. Знакомо? Именно эту боль решает pygbnf.

Что это за зверь и как его приручить

Pygbnf – это библиотека на Python, которая позволяет строить контекстно-свободные грамматики (CFG) для llama.cpp как из Lego. Вы создаете небольшие, переиспользуемые блоки, а потом собираете из них сложные структуры. Главный трюк – она работает поверх стандартного GBNF-формата, но полностью изолирует вас от проблем с зависимостями и версиями.

Что умеет pygbnf, чего не могут другие

Вот что выделяет его на фоне ручного кодинга в текстовом редакторе:

• Композиция грамматик. Можно импортировать одну грамматику в другую. Создал правило для email – используй его в форме пользователя, в заявке на поддержку, где угодно.
• Проверка на лету. Не нужно ждать, пока модель начнет генерировать ерунду. Библиотека сразу покажет, если в грамматике синтаксическая ошибка или несовместимость.
• Генерация чистого GBNF. Внутри она превращает ваши Python-объекты в валидный GBNF-код, который можно скормить llama.cpp напрямую. Никакой магии, только стандарт.
• Отсутствие жестких зависимостей. Pygbnf не тащит за собой тонны пакетов. Он легкий и focused. Это решает главную проблему – когда обновление одной библиотеки ломает весь стек.

1 Установка – дело одной команды

Никаких танцев с бубном. Просто:

pip install pygbnf

Всё. Никаких дополнительных компиляций, как иногда бывает с встраиванием llama.cpp прямо в проект. Работает из коробки.

2 Создаем первую грамматику

Вот как выглядит простой пример – грамматика для ответа «да/нет» с пояснением.

from pygbnf import Grammar, Rule, Choice, Terminal, NonTerminal

# Определяем базовые правила
grammar = Grammar(name="yes_no_grammar")
grammar.rules.extend([
    Rule("answer", Choice([Terminal("Да"), Terminal("Нет")])),
    Rule("explanation", NonTerminal("string")),  # Используем встроенный тип 'string'
    Rule("root", NonTerminal("answer") + " потому что " + NonTerminal("explanation"))
])

# Генерируем GBNF
print(grammar.generate())

На выходе получите чистый GBNF, который можно передать в llama.cpp. Никаких скрытых зависимостей от конкретной версии llama-cpp-python.

Сравнение: pygbnf против ручного труда и других вариантов

Главный конкурент pygbnf – это ваше терпение и текстовый редактор. И он всегда проигрывает.

Реальный пример: собираем грамматику для API-ответа

Допустим, мы делаем систему, где модель должна возвращать структурированные данные о пользователе. Без pygbnf пришлось бы копировать куски кода между файлами. С ним – создаем модульные компоненты.

from pygbnf import Grammar, Rule, Sequence, Choice, Terminal, NonTerminal, Optional

# Граматика для email (переиспользуемый компонент)
email_grammar = Grammar(name="email_component")
email_grammar.rules.append(
    Rule("email", NonTerminal("string") )  # Упрощенно, можно детализировать regex
)

# Основная грамматика пользователя
user_grammar = Grammar(name="user_response")
user_grammar.import_grammar(email_grammar)  # Импортируем компонент!

user_grammar.rules.extend([
    Rule("status", Choice([Terminal("active"), Terminal("inactive"), Terminal("banned")])),
    Rule("user",
        Sequence([
            "{\"name\": \"", NonTerminal("string"), "\", ",
            "\"email\": \"", NonTerminal("email"), "\", ",
            "\"status\": \"", NonTerminal("status"), "\"}"
        ])
    )
])

# Используем с llama-cpp-python
import llama_cpp
llm = llama_cpp.Llama(model_path="./llama-3.3-8b-instruct.Q4_K_M.gguf")

# Получаем GBNF строку и передаем в generate
gbnf_str = user_grammar.generate()
response = llm.create_completion(
    "Сгенерируй данные тестового пользователя",
    grammar=gbnf_str,
    max_tokens=100
)
print(response['choices'][0]['text'])

Попробуйте сделать то же самое, копируя куски GBNF по файлам. Через неделю вы забудете, где что лежит, а при обновлении llama-cpp-python что-то может сломаться. Pygbnf устраняет этот хаос.

Кому стоит присмотреться к pygbnf, а кто может пройти мимо

Эта библиотека – не для всех. Она решит проблемы конкретной группе людей:

• Разработчикам, которые всерьез работают со структурированным выводом из локальных LLM. Если вы устали от того, что модель "болтает" вместо выдачи JSON, и уже читали про способы заставить модель парсить, pygbnf станет вашим основным инструментом.
• Командам, где несколько человек пишут грамматики. Композируемость и четкая структура позволяют делиться компонентами как библиотеками кода.
• Тем, кто развертывает свои решения на разных машинах. Проблема "а у меня работает" из-за разной версии llama-cpp-python уходит. GBNF-код, сгенерированный pygbnf, всегда совместим с движком.

А вот если вы запускаете модель раз в месяц через LM Studio или другой GUI-инструмент, и вам не нужен строгий вывод – pygbnf будет избыточен. Возможно, вам хватит встроенных возможностей LM Studio или других обёрток.

Что дальше? Прогноз от 2026 года

Тренд на структурированный вывод только усиливается. Модели становятся умнее, но без грамматик они все равно склонны к галлюцинациям в формате. Я предсказываю, что такие инструменты, как pygbnf, станут стандартом де-факто для продакшн-систем на локальных LLM. Следующим шагом будет интеграция с системами валидации по типу Pydantic – когда грамматика генерируется автоматически из моделей данных. Пока же pygbnf – это самый прямой путь перестать бороться с зависимостями и начать собирать грамматики как взрослый.

Совет напоследок: начните с малого. Возьмите одну свою самую надоевшую грамматику, перепишите ее на pygbnf и ощутите, как исчезает необходимость помнить, в какой строке вы поставили лишнюю кавычку. После этого вы уже не сможете вернуться к текстовым файлам.

Подписаться на канал