Главная / llama.cpp Handbook / Грамматики GBNF и JSON Schema
Грамматики GBNF и JSON Schema
Концепт — Ограниченное декодирование.
GBNF за 5 минут
root ::= answer
answer ::= "Да" | "Нет" | "Не уверен"
# строка в кавычках без внутренних кавычек
str ::= "\"" [^"]* "\""
# целое число
int ::= [0-9]+
# дата ISO
date ::= [0-9]{4} "-" [0-9]{2} "-" [0-9]{2}
root— стартовое правило;::=— определение;|— выбор;[a-z],[^"]— символьные классы;*,+,{m,n}— повторения.- Примеры в комплекте:
grammars/json.gbnf,json_arr.gbnf,list.gbnf,arithmetic.gbnf,chess.gbnf— закуплены.
Использование
# CLI
llama-cli -m model.gguf --grammar-file grammars/json.gbnf -p "Перечисли столицы:"
llama-cli -m model.gguf --grammar 'root ::= [А-Яа-яё Ё]+' -p "Стих о море:"
# JSON Schema вместо GBNF
llama-cli -m model.gguf -j '{"type":"object","properties":{"city":{"type":"string"},"pop":{"type":"integer"}},"required":["city","pop"]}'
llama-cli -m model.gguf -jf schema.json
# Сервер: поля grammar / json_schema в запросе
curl http://127.0.0.1:9931/completion -d '{"prompt":"…","json_schema":{"type":"array","items":{"type":"string"}}}'
В /v1/chat/completions аналогично: "json_schema": … или "grammar": …
(server-api). Карточка — p.grammar.
LLGuidance (опциональный бэкенд)
Сборка с -DLLAMA_LLGUIDANCE=ON (нужен Rust/cargo) — docs/llguidance.md v1.0.0:
- флаги/поля те же; грамматики, начинающиеся с
%llguidance, и все запросы JSON Schema уходят в LLGuidance вместо builtin GBNF-движка; - более полный профиль JSON Schema (
additionalPropertiesи порядок свойств соответствуют стандарту), быстрые маски токенов (~50 µs в среднем); - конвертация старых GBNF → Lark-синтаксис:
gbnf_to_lark.py.
Когда стоит: сложные схемы, где builtin-движок капризничает, или строгие требования к соответствию стандарту.
Ловушки и советы
- Валидно ≠ правильно: схема гарантирует структуру, не содержание.
- Слишком строгие правила + слабый квант → пустые значения; ослабьте схему или поднимите квант.
- Заземлите модель: дайте пример желаемого JSON в промпте — грамматика лишь отрежет лишнее.
- Модель «застревает» на invalid-пути: сократите правила (меньше вложенности), проверьте
на
--temp 0. - Отладка: начните с тривиальной грамматики (
root ::= [a-z]+) и усложняйте; мусор при валидной грамматике чаще значит битый шаблон — chat-templates.
Что читать дальше
Сэмплирование → server-api (поля запроса).
Живые вопросы — ассистенту
Ответы по статьям справочника с цитатами ID источников; моделирование
конфигураций под ваше железо — детерминированным калькулятором.