NVIDIA frontend-crates: парсеры вызова инструментов на Rust для ИИ-агентов

Вызов инструмента в ответе большой языковой модели редко приходит одним куском: аргумент может обрываться, служебная разметка — попадать внутрь строки, а сам вызов — делиться между чанками стрима. NVIDIA выложила frontend-crates — переиспользуемые компоненты на Rust, которые превращают такой вывод (ID токенов или декодированный текст) в упорядоченные события: видимый текст, рассуждения и вызовы инструментов. Это те самые парсеры, что стоят за вызовами инструментов в NVIDIA Dynamo.

Где ломается разбор вызова инструмента

Пример из статьи — запрос погоды в Париже. Модель генерирует рассуждение, затем вызов get_weather с аргументом city. Фронтенд готовит и токенизирует промпт, движок инференса выдаёт токены, парсер разделяет рассуждение, видимый текст и вызовы, а адаптер протокола собирает из событий ответ, совместимый с OpenAI. Один и тот же путь разбора работает и для пакетного JSON, и для стриминговых обновлений.

Сложность — в границах. Вызов может быть некорректным или незавершённым, маркер — встретиться внутри аргумента, а обычный текст — окружать вызов. Парсер обязан не терять данные, не дублировать вызовы и не выпускать наружу служебную разметку модели. В статье показаны две разные ошибки NVIDIA Nemotron.

Синтаксическая: аргумент и рамка вызова не закрываются, поэтому целый вызов разобрать нельзя.

</think><tool_call>
<function=get_weather><parameter=city>Par

Семантическая: рамка корректна, но названного инструмента нет в запросе.

</think><tool_call>
<function=unknown_tool><parameter=city>Paris</parameter></function>
</tool_call>

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

Conformance Corpus: одни тесты для разных моделей

Диапазон входных данных не ограничен, поэтому при невалидном вводе парсер следует документированным правилам восстановления, а не угадывает намерение модели. Даже синтаксически корректный и соответствующий схеме вызов может быть неверным выбором для запроса пользователя. Чтобы проверять такие решения, frontend-crates сопоставляет вывод модели с ожидаемым результатом в общем Conformance Corpus.

Фикстуры — YAML, не привязанный к языку: фиксированный вход и ожидаемый выход, так что парсеры на Rust и референсные реализации на Python прогоняют одни и те же случаи. Регрессионный тест на утёкшую разметку, дубли вызовов или потерянные аргументы переносится на другие семейства моделей после адаптации к их грамматике.

Для нового парсера начинают со всех случаев UNIFIED.* по семействам моделей: они покрывают полные, некорректные, усечённые, множественные и перемежающиеся вызовы, границы стрима и поведение в конце ввода. Входы адаптируют под грамматику своей модели и настройки запроса, добавляют специфичные крайние случаи и объясняют исключения.

Случай UNIFIED.1-tool_only из Parser Conformance Table связывает четыре модельных входа с одним ожидаемым результатом — get_weather с city = Paris. Маркеры у Beam, GPT-OSS, Muse Spark и NVIDIA Nemotron 3 разные, а поведение проверяется одно и то же.

Как собрать парсер для новой модели с помощью ИИ-агента

Учебный сценарий в статье рассчитан на модель, которую frontend-crates пока не поддерживает. Грамматику задаёт спецификация модели, а общие случаи дают набор проверяемых поведений. Нужны checkout frontend-crates, Rust с Cargo и зависимости для conformance-тестов. Упражнение с парсером идёт на CPU с фиксированными фикстурами — GPU не требуется. Сквозное тестирование уже требует рабочего рантайма Dynamo, сервисов обнаружения и железа под модель.

Порядок такой: грамматика модели, правила восстановления и проверенные ожидания GOLDEN; агент пишет или правит парсер, гоняет тесты и по падениям выбирает следующее изменение. Если он предлагает поменять ожидаемое поведение — это решение проверяет человек.

Стартовый промпт для агента:

In the frontend-crates checkout, follow .agents/skills/tool-parser-generator/SKILL.md to create a v2 Unified parser for [MODEL_NAME]. Research its grammar and prepare the GOLDEN test set, adapting applicable UNIFIED.* cases. Pause for human review. After approval, implement, validate, and provide the local conformance report URL for human inspection.

Набор GOLDEN агент генерирует в conformance/fixtures-unified-v2/families/<name>/inputs_and_golden.yaml независимо от результатов парсера. Каждый случай сопоставляет вход с ожидаемым выходом; если ожидания неверны, парсер может пройти тесты и всё равно работать неправильно. Формат:

family: nemotron_v3
cases:
  UNIFIED.tool_only.nemotron_v3:
    input: |-
      </think><tool_call>
      <function=get_weather>
      <parameter=city>Paris</parameter>
      </function></tool_call>
    golden:
      - kind: tool_call
        name: get_weather
        arguments: {city: Paris}

Набор стоит заказать агенту на состязательную проверку и пройти вручную, случай за случаем, сверяясь со спецификацией формата и API модели, референсной реализацией, другими парсерами (включая vLLM и SGLang), грамматикой, схемой инструментов и настройками запроса, обсуждениями на форумах и тикетами, а также потребностями вызывающей стороны и ценой восстановления в задержке и сложности. Где источники расходятся, придётся принять решение: записать правило восстановления и причину, задокументировать любое изменение GOLDEN. Ожидания следуют решению, а не выводу парсера.

Дальше агенту поручают собрать парсер, прогнать все применимые случаи UNIFIED.* и общие регрессионные тесты, исправить падения, заново снять результаты и локально сгенерировать conformance/CONFORMANCE_v2.html. Отчёт открывают в браузере: у него тот же интерфейс, что у опубликованной Parser Conformance Table, но с локальными результатами. По каждому случаю видно вход, настройки запроса, GOLDEN и записанный выход; зелёный означает совпадение с GOLDEN, то есть всё упирается в проверенные вами ожидания.

Guided decoding не отменяет проверок

Шаг реализации охватывает и guided decoding: генерация ограничивается маркерами модели и схемой аргументов, что снижает число некорректных вызовов. Агенту велят следовать разделам «Add and validate structural tags» в README парсера и «Implement and validate» в навыке агента — там регистрация билдера, тесты грамматики и квалификация бэкенда. Выбрать правильный город или предотвратить усечение guided decoding не может, поэтому проверки восстановления в парсере остаются.

Скорость, стриминг и память

Прохождение тестов на корректность — только начало. Реализация агента может оказаться медленной или слишком прожорливой по памяти. Проверяют обычный текст, вызовы инструментов, длинные аргументы и некорректный ввод на больших и крошечных чанках; измеряют пропускную способность, время до первого события и расход памяти на одной сборке и железе. Удвоение длины входа показывает код, который заново сканирует или копирует уже прочитанное.

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

Отдельно поток обрывают посреди маркера или аргумента: восстановление должно идти по документированному правилу без утечки разметки, дублей вызовов и потери валидного текста. Парсер обрабатывает полученное, не догадываясь о недостающем. Текст с примерами формата модели проверяют наравне с реальными вызовами по задокументированной грамматике и политике обработки кавычек: текущий дефолт v2 считает распознанные маркеры структурными даже внутри цитируемой прозы, так что одни кавычки полный пример вызова в обычном тексте не удержат. Настроенную политику фиксируют и тестируют.

Парсер в своём проекте на Rust

Пример в статье использует готовый парсер NVIDIA Nemotron и разрывает между чанками и маркер, и название города. Проверено на Rust 1.96.1 и dynamo-parsers-v2 0.10.3. После cargo new parser-demo и cd parser-demo в Cargo.toml добавляют зависимости:

anyhow = "1"
dynamo-parsers-v2 = "=0.10.3"
serde_json = "1"

Затем src/main.rs заменяют на:

use dynamo_parsers_v2::{
    Tool, UnifiedParserInit, UnifiedParserOutput, create_unified_parser_for_family,
};
use serde_json::json;

fn main() -> anyhow::Result<()> {
    let tools = [Tool {
        name: "get_weather".into(),
        description: None,
        parameters: json!({"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}),
        strict: None,
    }];
    let mut parser = create_unified_parser_for_family("nemotron_v3", &tools)?;
    parser.initialize_request(UnifiedParserInit::default())?;
    let mut output = UnifiedParserOutput::default();
    for chunk in [
        "Check the forecast.</think><tool_",
        "call><function=get_weather><parameter=city>Par",
        "is</parameter></function></tool_call>",
    ] {
        let mut delta = UnifiedParserOutput::default();
        parser.parse_into(chunk, &mut delta)?;
        output.append(&mut delta);
    }
    output.append(&mut parser.finish()?);
    println!("{}", serde_json::to_string(&output.assembled())?);
    Ok(())
}

После cargo generate-lockfile и cargo run --locked результат содержит рассуждение и вызов get_weather с city = Paris:

[{"kind":"reasoning","text":"Check the forecast."},
 {"kind":"tool_call","name":"get_weather","arguments":{"city":"Paris"}}]

На каждый запрос держат один инициализированный парсер: create_unified_parser_for_family выбирает грамматику, initialize_request задаёт начальное состояние, parse_into потребляет чанк. finish() вызывают один раз — при усечении, отмене или конце транспортного потока; finish_at_eos() — только для подтверждённого бэкендом сигнала конца последовательности (EOS), завершающего грамматику. assembled() отдаёт упорядоченный результат. В стриминговом приложении события из delta.events пересылают после каждого parse_into, как и события из finish(). Перед выполнением инструментов завершённые вызовы проверяют на доступность инструмента, авторизацию, схему и политику вызовов.

Парсеры можно использовать и в собственном проекте на Rust, и в составе NVIDIA Dynamo — фреймворка инференса, который применяет frontend-crates. Перед началом стоит свериться с последними инструкциями репозитория. В issue или pull request включают точный падающий вход, идентификатор случая и результаты тестов, чтобы поведение можно было воспроизвести.

Разбор вызовов инструментов — часть более широкой темы: о том, как оценивать надёжность агентов от вызова инструмента до выполнения задачи, spbcomputers.ru писал отдельно, а облегчённый вариант парсера для вызова инструментов разбирался на примере модели Needle 2. Если вы работаете с NVIDIA Dynamo, полезна и статья про Agent Substrate — запуск агентов в масштабе Kubernetes.

Частые вопросы

Что именно даёт frontend-crates?

Переиспользуемые компоненты на Rust, которые разбирают вывод LLM (ID токенов или декодированный текст) в упорядоченные события: видимый текст, рассуждения и вызовы инструментов. Это парсеры, стоящие за вызовами инструментов в NVIDIA Dynamo.

Чем синтаксическая ошибка вызова отличается от семантической?

При синтаксической аргумент и рамка вызова не закрываются, и целый вызов разобрать нельзя. При семантической рамка корректна, но названного инструмента нет в запросе — парсер сообщает вызов как есть, а доступность, авторизацию, схему и политику проверяет слой обслуживания.

Почему парсер не исправляет имя недоступного инструмента?

Подмена скрыла бы, что именно сгенерировала модель. Валидация инструмента — задача слоя обслуживания, а не разбора.

Зачем нужен Conformance Corpus?

Это YAML-фикстуры, не привязанные к языку: вход и ожидаемый выход. Парсеры на Rust и референсные реализации на Python прогоняют одни и те же случаи, а регрессионные тесты переносятся на другие семейства моделей после адаптации к их грамматике.

Что покрывают случаи UNIFIED.*?

Полные, некорректные, усечённые, множественные и перемежающиеся вызовы, границы стрима и поведение в конце ввода. С них начинают при создании парсера для новой модели.

Нужна ли GPU, чтобы написать парсер?

Нет. Упражнение идёт на CPU с фиксированными фикстурами. GPU, рабочий рантайм Dynamo и сервисы обнаружения нужны только для сквозного тестирования на реальной модели.

Guided decoding избавляет от проверок восстановления?

Нет. Он снижает число некорректных вызовов, ограничивая генерацию маркерами модели и схемой аргументов, но не гарантирует правильный выбор аргумента и не предотвращает усечение.

Как проверить, что парсер не тормозит на стриме?

Проиграть короткие фикстуры во всех точках разрыва, затем чанки по одному символу и смешанные, включая разрывы внутри маркеров и аргументов, и убедиться, что события приходят по порядку и аргументы целы. Отдельно измерить пропускную способность, время до первого события и память при удвоении длины входа.

Что будет, если поток оборвётся посреди аргумента?

Парсер применит документированное правило восстановления: без утечки разметки, дублей вызовов и потери валидного текста, не додумывая недостающие куски.

Как прислать сообщение об ошибке парсера?

В issue или pull request указать точный падающий вход, идентификатор случая и результаты тестов — так поведение воспроизводимо.

Источник: developer.nvidia.com