11. Вызов инструментов: шаблоны чата, грамматики, JSON Schema
Зачем эта глава. Модель не «вызывает функции» — она пишет текст. Весь вызов инструментов держится на договорённости: шаблоне чата, формате сообщений и парсере. Если договорённость нарушена, агент ломается, даже когда модель умная.
За 30 секунд
- Модель не вызывает функции, а пишет текст в формате, которому её обучили; сервер находит эту разметку и превращает её в
tool_calls.- Связующее звено — шаблон чата: неправильный шаблон ломает tool calling даже у сильной модели.
- Грамматика и JSON Schema гарантируют синтаксис ответа, но не правильность значений и не выбор инструмента.
- Агентский цикл ограничивают шагами, бюджетом и проверкой аргументов; всё, что пришло извне, считается недоверенным.
11.1 Модель пишет текст, сервер разбирает
Механика вызова инструментов:
- Приложение описывает доступные инструменты: имя, назначение, параметры.
- Сервер подставляет эти описания в промпт через шаблон чата (chat template) в формате, на котором модель обучалась.
- Модель отвечает специальной разметкой, например:
<tool_call>{"name": "get_weather", "arguments": {"city": "Москва"}}</tool_call>
- Сервер парсит разметку и отдаёт приложению стандартные OpenAI-совместимые
tool_calls. - Приложение выполняет инструмент и отправляет результат обратно сообщением с ролью
tool.
Важно: никакого встроенного механизма вызова у модели нет. Есть только обучение на текстовых форматах и парсер на сервере.
Весь круг одного вызова целиком:
sequenceDiagram
participant App as Приложение
participant Srv as Сервер (шаблон + парсер)
participant LLM as Модель
participant Tool as Инструмент
App->>Srv: messages + описания tools (JSON)
Srv->>LLM: промпт, собранный шаблоном чата
LLM-->>Srv: текст: #lt;tool_call#gt;{"name": "get_weather", ...}#lt;/tool_call#gt;
Srv-->>App: tool_calls (OpenAI-совместимый JSON)
App->>Tool: get_weather(city="Москва")
Tool-->>App: {"temp_c": 12, ...}
App->>Srv: история + сообщение с ролью tool
Srv->>LLM: тот же префикс + результат (кэш промпта, гл. 7)
LLM-->>Srv: обычный текст ответа
Srv-->>App: content без tool_calls — цикл окончен
Модель общается только с сервером и только текстом. Сам инструмент вызывает приложение — и именно приложение отвечает за проверку аргументов и права доступа.
11.2 Шаблон чата
Chat template — правило, как роли (system, user, assistant, tool), сообщения и описания инструментов превращаются в последовательность токенов. Он хранится в метаданных модели (в GGUF — внутри файла) и обычно написан на Jinja.
Пример упрощённо:
<|system|>
Ты — помощник. Доступные инструменты: ...
<|user|>
Какая погода в Москве?
<|assistant|>
<tool_call>...
Что ломается, если шаблон неправильный:
- модель не понимает, где заканчивается сообщение;
- описания инструментов попадают не туда;
- специальные токены превращаются в обычный текст;
- модель отвечает в формате другой модели.
В современных сборках llama.cpp Jinja включена по умолчанию. Флаг --jinja имеет смысл явно указывать для старых сборок или для совместимости; отключить шаблон можно --no-jinja. Если нужен свой шаблон, а не тот, что лежит в метаданных модели, используйте --chat-template (строка) или --chat-template-file (файл). Если шаблон неправильный или отключён, сервер может применить упрощённый формат, и tool calling перестанет работать.
Минимальный пример: от запроса до tool_calls
Клиент отправляет инструменты в OpenAI-совместимом формате:
{
"model": "local-model",
"messages": [{"role": "user", "content": "Какая погода в Москве?"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Погода в городе",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}],
"tool_choice": "auto"
}
Сервер подставляет описание в шаблон, модель отвечает разметкой, парсер превращает её в:
{
"choices": [{
"message": {
"role": "assistant",
"content": null,
"tool_calls": [{
"id": "call_1",
"type": "function",
"function": {"name": "get_weather", "arguments": "{\"city\":\"Москва\"}"}
}]
},
"finish_reason": "tool_calls"
}]
}
Приложение выполняет get_weather, добавляет результат и отправляет новый запрос:
{"role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\": 12, \"condition\": \"облачно\"}"}
Дальше цикл повторяется, пока модель не вернёт обычный content без tool_calls.
11.3 Форматы tool calls
Разные семейства моделей обучены на разных форматах:
- JSON в специальных токенах;
- XML-подобные теги;
- отдельные маркеры ролей;
- массивы вызовов для параллельных инструментов.
Сервер знает формат благодаря шаблону и парсеру. Если вы меняете модель, проверьте:
- совместим ли шаблон с вашим клиентом;
- поддерживает ли сервер парсинг именно этого формата;
- как выглядят параллельные вызовы;
- что происходит при ошибке парсинга.
Универсального формата нет; «OpenAI-совместимость» — это про API, а не про внутренний текст модели.
11.4 Грамматики и JSON Schema
Даже хорошая модель иногда ломает JSON. Есть жёсткое решение: constrained decoding (ограниченное декодирование).
Идея: на каждом шаге парсер знает, какие токены допустимы в текущем состоянии грамматики, и запрещает все остальные: их логиты заменяются на минус бесконечность, то есть после softmax вероятность становится нулевой. Тогда синтаксически неверный JSON невозможно сгенерировать.
В llama.cpp для этого есть:
- GBNF — грамматика в нотации, похожей на BNF;
--grammarи--grammar-file;response_format: {"type": "json_schema", ...}— JSON Schema, преобразованная в грамматику;- серверный
--json-schema.
Другие реализации:
- Outlines — компиляция регулярных выражений и JSON Schema в маски;
- XGrammar — быстрый движок структурированной генерации;
- в vLLM — strict tool schema и guided decoding.
Что гарантирует грамматика:
- синтаксис (валидный JSON, нужные поля, типы);
- отсутствие «болтовни» вокруг JSON.
Чего она не гарантирует:
- правильность значений (модель может поставить выдуманное число);
- соответствие схеме по смыслу (например, «дата» может быть неверной);
- что модель выберет правильный инструмент;
- что аргументы будут полными по смыслу, а не только по форме.
Грамматика — это ремень безопасности, а не замена проверке.
Warning
Грамматика не спасает от обрыва по лимиту длины. Если
max_tokensзакончился посреди объекта, вы получите незакрытый JSON — синтаксически неверный, хотя каждый токен был «разрешён». Проверяйтеfinish_reason: значениеlengthозначает, что ответ обрезан.
11.5 Производительность грамматик
Ограниченное декодирование добавляет накладные расходы:
- на каждом шаге нужно вычислить маску допустимых токенов;
- сложные схемы (глубокая вложенность, большие перечисления) замедляют;
- некоторые реализации кэшируют состояния, другие пересчитывают.
На практике для типичной схемы на 10–20 полей overhead невелик, но на очень больших схемах может быть заметен. Если скорость критична, упрощайте схему.
11.6 Дизайн инструментов
Хорошая схема повышает надёжность сильнее, чем любая магия промптинга.
Правила:
- Мало инструментов. 5–15 лучше, чем 50. Каждый инструмент — это текст в промпте и шанс ошибиться.
- Ясные имена и описания. Модель выбирает по описанию, а не по вашему замыслу.
- Плоские аргументы. Глубокая вложенность увеличивает число ошибок.
- Enums вместо свободного текста. Если значение из фиксированного набора — перечислите его.
- Обязательные поля — действительно обязательные. Не делайте всё optional.
- Ошибки как данные. Возвращайте структурированную ошибку, чтобы модель могла исправиться.
- Ограничивайте размер результата. Огромный вывод инструмента съедает контекст и ломает кэш.
Посчитай сам. Каждое описание инструмента занимает в промпте около 150 токенов [пример]. Сколько prefill добавят 15 и 50 инструментов при скорости обработки промпта 1000 ток/с — без кэша промпта и с ним?
Решение
15 инструментов: 15 × 150 = 2 250 токенов → 2,25 с на каждый запрос
50 инструментов: 50 × 150 = 7 500 токенов → 7,5 с на каждый запрос
С кэшем промпта (глава 7) это время платится один раз — если описания стоят в начале и не меняются. Без кэша агент из 30 шагов с 50 инструментами потратит на перечитывание одних только описаний почти 4 минуты. И это не считая того, что модели труднее выбрать правильный инструмент из 50.
11.7 Цикл агента
Типичный цикл:
while not done and steps < max_steps:
response = model(messages, tools)
if response has tool_calls:
for call in tool_calls:
result = execute(call)
messages.append(tool_result)
else:
done
Проблемы, которые надо предусмотреть:
- модель не вызывает
finishи крутится до лимита; - повторяет один и тот же вызов;
- вызывает несуществующий инструмент;
- передаёт битые аргументы;
- теряет цель на длинной истории;
- переполняет контекст результатами инструментов.
Лечения:
- явное условие завершения и инструмент
finish; - лимит шагов и бюджета токенов;
- валидация аргументов на стороне приложения;
- напоминания о формате при ошибке;
- сжатие или суммаризация истории (осторожно с кэшем промпта);
- грамматика для аргументов.
11.8 Безопасность
Вызов инструментов — это исполнение действий. Даже локальная модель может:
- выполнить опасную команду, если инструмент ей это позволяет;
- передать данные из документа в нежелательное место;
- поддаться prompt injection в тексте документа или результате инструмента.
Правила:
- минимальные права у инструментов;
- подтверждение опасных действий человеком;
- изоляция файловой системы и сети;
- валидация входных данных, а не доверие модели;
- логирование вызовов.
Отдельно про prompt injection: вредоносная инструкция может прийти не от пользователя, а из документа, результата поиска, OCR-текста или ответа инструмента. Модель не всегда отличает данные от команд. Поэтому:
- считайте всё, что пришло из внешнего мира, недоверенным;
- не давайте инструментам больше прав, чем нужно для задачи;
- проверяйте пути к файлам и аргументы команд, а не только их наличие;
- ограничивайте сетевой доступ инструментов;
- для MCP-серверов и плагинов используйте отдельный процесс/контейнер и allowlist.
Секреты не должны попадать в промпт: модель может их повторить, а логи — сохранить. Ключи храните в переменных окружения или хранилище, а в промпт передавайте только необходимый минимум.
Локальность модели не делает её безопасной: она лишь убирает утечку в облако.
11.9 Как измерять качество вызова инструментов
Метрики:
- доля синтаксически валидных вызовов;
- доля вызовов с правильным инструментом;
- доля с правильными аргументами;
- среднее число шагов до завершения;
- доля незавершённых задач;
- доля повторных/зацикленных вызовов.
Прогоняйте на реальных сценариях, а не на одном примере. Полезны публичные бенчмарки (например, BFCL), но они не заменяют ваш домен.
Ключевые идеи
- Вызов инструментов — это текст плюс парсер, а не встроенная функция модели.
- Шаблон чата определяет формат; без правильного шаблона tool calling ломается.
- Грамматика и JSON Schema гарантируют синтаксис, но не смысл.
- Хороший дизайн инструментов важнее сложных промптов.
- Агентский цикл нужно ограничивать шагами, бюджетом и проверкой аргументов.
Проверь себя
- Почему модель «не знает», что у неё есть инструменты, без шаблона чата?
- Что гарантирует грамматика JSON и чего она не гарантирует?
- Почему 50 инструментов хуже 10?
- Как prompt injection может повлиять на агента с инструментами?
- Какую метрику вы бы смотрели в первую очередь при отладке tool calling?
Ответы
- Описания инструментов и формат вызова передаются модели только через промпт, собранный шаблоном. Без шаблона модель не получает ни описаний, ни разметки, на которой обучена.
- Гарантирует синтаксис: валидный JSON, нужные поля, типы. Не гарантирует правильность значений, выбор инструмента и смысловое соответствие.
- Каждый инструмент занимает место в промпте и увеличивает число вариантов. Модели труднее выбрать, растёт вероятность ошибки и стоимость prefill.
- Вредоносный текст в документе или результате инструмента может убедить модель вызвать инструмент с опасными аргументами. Модель не отличает данные от инструкций, если это не предусмотрено дизайном.
- Долю валидных вызовов с правильным инструментом и аргументами, а также долю задач, завершённых без зацикливания. Синтаксическая валидность без правильного инструмента бесполезна.
Источники главы
- Patil et al., «Gorilla: Large Language Model Connected with Massive APIs» (2023) — arXiv:2305.15334. Обучение моделей вызову API.
- Schick et al., «Toolformer» (2023) — arXiv:2302.04761. Модель учится вызывать инструменты.
- Willard & Louf, «Efficient Guided Generation for Large Language Models» (2023) — arXiv:2307.09702. Outlines и маскирование логитов.
- Dong et al., «XGrammar» (2024) — arXiv:2411.15100. Быстрая структурированная генерация.
- llama.cpp,
docs/function-calling.md— GitHub.--jinja,tool_choice, параллельные вызовы. - llama.cpp,
grammars/README.md— GitHub. Синтаксис GBNF. - Berkeley Function Calling Leaderboard — gorilla.cs.berkeley.edu. Публичный бенчмарк вызова функций.
- vLLM, «Tool Calling» — docs.vllm.ai. Строгие схемы и
tool_choice.