Guardrails AI: Валидация структурированного вывода с JSON Schema

Guardrails AI — это open-source библиотека Python, созданная, чтобы сделать выводы LLM надёжными и предсказуемыми. Она оборачивает любой вызов LLM API — OpenAI, Anthropic, Cohere, локальные модели — пайплайном валидации, который проверяет ответ модели по заданному пользователем схеме и набору валидаторов на уровне полей, прежде чем вернуть результат в код вашего приложения.

Ключевая абстракция — объект `Guard`. Вы создаёте Guard из модели Pydantic или определения JSON Schema, при желании прикрепляете валидаторы к отдельным полям, а затем вызываете Guard вместо прямого вызова LLM. Guard берёт на себя построение промпта, парсинг ответа, валидацию и автоматический повторный промпт при провале валидации — всё в одном проверяемом пайплайне.

Место Guardrails AI в стеке LLM

Guardrails стоит между вашим прикладным кодом и провайдером LLM. Он не заменяет модель и не меняет способ вызова модели — он добавляет слой принудительного исполнения контракта вокруг вызова. Думайте о нём как о валидаторе схем для ответов API, только «API» здесь — языковая модель, порождающая естественный язык, а «ответ» нужно распарсить в структурированные данные, прежде чем валидировать.

• Guard: главный интерфейс — оборачивает вызов LLM и применяет схему + валидаторы.
• ValidationOutcome: объект результата, возвращаемый вызовом Guard — содержит валидированный вывод, статус успеха/провала и ошибки полей.
• Validator: вызываемый объект, прикреплённый к полю схемы и обеспечивающий конкретное правило (тип, диапазон, regex, внешняя проверка).
• reask: механизм повтора — при провале валидации Guardrails повторяет промпт модели с контекстом ошибки.
• Hub: реестр валидаторов Guardrails — курированный набор общественных валидаторов, устанавливаемых через `guardrails hub install`.

Фундаментальная проблема в том, что языковые модели обучены порождать правдоподобный текст, а не соблюдать программные контракты. Даже когда вы просите модель вернуть JSON, она может выдать вывод с отсутствующими полями, неверными типами значений, лишними полями, которых не ожидает ваш последующий код, галлюцинированными значениями вне допустимых диапазонов или текстовыми фрагментами вокруг JSON-блока, ломающими парсинг целиком.

Пять режимов отказа невалидированного вывода LLM

• Сбой парсинга: модель оборачивает JSON в markdown-кодовые ограждения, добавляет комментарии до или после либо выдаёт искажённый JSON, который нельзя распарсить.
• Отсутствуют обязательные поля: модель пропускает поле, которое просили заполнить, вызывая KeyError или ошибку нулевой ссылки в последующем коде.
• Нарушения типов: поле, ожидаемое числом, приходит строкой, или boolean приходит строкой "true" вместо литерала `true`.
• Нарушения ограничений значений: поле рейтинга возвращает 11, когда допустимый диапазон 1-10, или enum-поле возвращает значение вне заданного списка.
• Галлюцинированная структура: модель выдумывает дополнительные поля или вкладывает объекты иначе, чем предписывает схема.

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

Контракт между вашим приложением и LLM ровно настолько прочен, насколько строга валидация, которую вы применяете к каждому ответу. Надежда — не стратегия валидации.

JSON Schema — язык, которым Guardrails AI описывает, как выглядит корректный ответ LLM. Определение JSON Schema задаёт ожидаемую структуру объекта: какие поля существуют, их типы, какие обязательны и какие ограничения применяются к значениям. Эта схема решает две задачи: она говорит Guardrails, как валидировать распарсенный ответ, и Guardrails использует её для построения инструкции промпта, сообщающей модели, какую форму выдавать.

Что JSON Schema покрывает для валидации LLM

Для случаев структурированного вывода самые полезные ключевые слова JSON Schema — контроль типов, списки обязательных полей, значения enum, форматы строк и числовые диапазоны. Вместе они покрывают большинство правил уровня полей, которые нужно обеспечить задачам извлечения или генерации.

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "type": "object",
  "required": ["product_name", "rating", "sentiment", "summary"],
  "additionalProperties": false,
  "properties": {
    "product_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "rating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "sentiment": {
      "type": "string",
      "enum": ["positive", "neutral", "negative"]
    },
    "summary": {
      "type": "string",
      "minLength": 20,
      "maxLength": 500
    },
    "pros": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    },
    "cons": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    }
  }
}

Эта схема велит Guardrails отклонять любой ответ, где `rating` вне 1-5, `sentiment` не равен одному из трёх допустимых значений, или `summary` короче 20 символов. Поля, перечисленные в `required`, должны присутствовать. `additionalProperties: false` отклоняет любые дополнительные поля, которые модель добавляет самовольно.

Генерация схемы из примера ответа

При проектировании новой задачи извлечения выработка правильной исходной схемы требует времени. Практический сокращённый путь: запустите промпт один раз без валидации, изучите сырой JSON, который вернёт модель, а затем используйте Генератор JSON Schema, чтобы автоматически вывести схему Draft-07 из этой выборки. Сгенерированная схема захватывает типы, обязательные поля и вложенную структуру. Затем вы её дорабатываете — ужесточаете длины строк, добавляете enum-ограничения, задаёте числовые границы — вместо того чтобы писать каждое ключевое слово с нуля.

Понимание пайплайна валидации помогает отлаживать сбои и настраивать правильную стратегию реагирования для каждого поля. Пайплайн выполняется в фиксированном порядке при каждом вызове Guard: инъекция промпта, парсинг ответа, валидация JSON Schema, исполнение валидаторов уровня полей и сборка результата.

Guardrails AI поддерживает два стиля определения схем: устаревший формат Rail spec и современный подход с моделями Pydantic. Знать оба полезно, потому что Rail-спецификации встретятся вам в старых кодовых базах и примерах сообщества, а Pydantic — рекомендуемый путь для всех новых проектов начиная с Guardrails v0.4+.

Модели Pydantic как схемы Guard

Самый чистый способ определить схему вывода Guardrails в Python — подкласс `BaseModel` из Pydantic. Модели Pydantic имеют нативный экспорт в JSON Schema, проверку типов в IDE и привычный синтаксис Python. Валидаторы Guardrails прикрепляются через `Field()` из Pydantic с пользовательскими метаданными либо прямым импортом классов валидаторов из `guardrails`.

from pydantic import BaseModel, Field
from guardrails import Guard
from guardrails.hub import ValidRange, ValidChoices

class ProductReview(BaseModel):
    product_name: str = Field(description="Name of the product reviewed")
    rating: int = Field(
        description="Rating from 1 to 5",
        validators=[ValidRange(min=1, max=5, on_fail="reask")]
    )
    sentiment: str = Field(
        description="Overall sentiment of the review",
        validators=[ValidChoices(
            choices=["positive", "neutral", "negative"],
            on_fail="reask"
        )]
    )
    summary: str = Field(description="One paragraph summary of the review")

# Build the Guard from the Pydantic model
guard = Guard.from_pydantic(ProductReview)

# Call the LLM through the Guard
outcome = guard(
    openai.chat.completions.create,
    model="gpt-4o",
    messages=[{"role": "user", "content": f"Extract a review from: {raw_text}"}],
    num_reasks=2,
)

if outcome.validation_passed:
    review: ProductReview = outcome.validated_output
else:
    print(outcome.error)

Пайплайн Pydantic → JSON Schema

Под капотом Guardrails вызывает `model.model_json_schema()`, чтобы экспортировать вашу модель Pydantic в JSON Schema, и затем использует эту схему как для инъекции промпта, так и для валидации ответа. Это значит, что любая модель Pydantic, которую вы можете написать, автоматически является корректным контрактом Guardrails. Вы можете сами осмотреть сгенерированную схему — вставьте пример ответа в Генератор JSON Schema, чтобы увидеть эквивалентную схему, и сравните её с выводом вашей Pydantic-модели.

Если ваше приложение на TypeScript, но вызывает Python-сервис Guardrails, Конвертер JSON в Zod Schema генерирует соответствующую схему Zod из того же примера JSON — полезно для валидации того же контракта на стороне клиента без ручного дублирования определения схемы.

Rail-спецификации — устаревший формат

Rail-спецификации — это XML-файлы, где каждый элемент `<output>` описывает поле с атрибутом `type` и одним или несколькими дочерними элементами `<validator>`. Они появились раньше интеграции с Pydantic и менее эргономичны для Python-разработчиков, но по-прежнему полностью поддерживаются. Если вы унаследовали кодовую базу Guardrails с файлами `.rail`, можете мигрировать каждую спецификацию в модель Pydantic постепенно — поведение валидации эквивалентно.

Надёжный workflow Guardrails сочетает офлайн-проектирование схем, локальное тестирование и мониторинг в продакшене. Фаза проектирования схемы — где вы определяете, как выглядит корректный вывод, — самый важный шаг, и она больше всего выигрывает от специализированных инструментов.

Шаг 1: Спроектируйте схему офлайн

Прежде чем писать код Guardrails, определите схему вывода как отдельный документ JSON Schema. Работа сначала в JSON Schema позволяет итерировать контракт независимо от вызова LLM — вы можете валидировать примеры пейлоадов, корректировать ограничения и убеждаться в корректности схемы, не тратя кредиты API на тесты.

Валидатор JSON Schema на Aback Tools позволяет вставить JSON Schema и кандидат-пейлоад и сразу увидеть ошибки валидации на уровне полей. Используйте его, чтобы убедиться, что ваши массивы `required`, списки enum и числовые диапазоны работают как ожидается, прежде чем переводить схему в модель Pydantic. JSON Форматировщик и Валидатор полезен, чтобы проверить, что сам файл схемы является синтаксически корректным JSON, прежде чем ссылаться на него.

Шаг 2: Сгенерируйте Pydantic из JSON

Если вы собрали примеры ответов LLM во время прототипирования, Конвертер JSON в Python Dataclass / Pydantic за один шаг генерирует модель Pydantic из примера JSON-пейлоада. Инструмент выводит типы полей, обрабатывает вложенные объекты и применяет `Optional` там, где поля могут отсутствовать. Используйте вывод как отправную точку и добавьте валидаторы Guardrails к каждому полю по ограничениям вашего JSON Schema.

Шаг 3: Тестируйте локально с мок-ответами

Guards в Guardrails можно вызывать с любым вызываемым объектом Python, а не только с живыми API LLM. Во время разработки передайте мок-функцию, возвращающую фиксированный строковый ответ, чтобы протестировать пайплайн валидации без API-вызовов. Это делает быстрые и бесплатные итерации по изменениям схемы, конфигурациям валидаторов и промптам reask до подключения к платному эндпоинту модели.

Рекомендуемый workflow схем с Aback Tools

• Генератор JSON Schema - выводит исходную схему из примера ответа LLM.
• Валидатор JSON Schema - валидирует кандидат-пейлоады по вашей схеме офлайн.
• JSON Форматировщик и Валидатор - проверяет, что файлы схем являются корректным JSON до использования.
• JSON в Python Dataclass - генерирует модель Pydantic из примера пейлоада.
• JSON в Zod Schema - генерирует контракт на стороне TypeScript для клиентской валидации.

Guardrails AI заметно повышает надёжность структурированного вывода, но не гарантирует корректности. Понимание ограничений помогает проектировать пайплайн с подходящими запасными вариантами, а не доверять Guard безусловно.

Циклы reask сходятся не всегда

Когда модель стабильно проваливает конкретный валидатор, добавление повторных reask-попыток не помогает — это лишь стоит больше кредитов API за тот же результат. Некоторые режимы отказа систематичны: модель действительно не понимает ограничение, или ограничение слишком строгое, чтобы модель надёжно его выполняла при данном вводе. Аудитируйте частоты отказов ваших валидаторов и считайте валидаторы с высокой частотой отказов сигналом пересмотреть либо определение ограничения, либо промпт.

JSON Schema не ловит семантические ошибки

Схема может подтвердить, что `sentiment` один из `["positive", "neutral", "negative"]`, но не может проверить, что присвоенная тональность действительно верна для входного текста. JSON Schema и валидаторы обеспечивают структурные и синтаксические контракты — они не заменяют человеческую проверку или последующие проверки качества для точности содержания. Используйте Guardrails для контроля формата и структуры вывода, а для корректности содержания применяйте отдельные метрики оценки.

Накладные расходы на задержку и стоимость

Каждая попытка reask — это дополнительный вызов API LLM по полной токен-стоимости. Для Guard с `num_reasks=3` худший сценарий извлечения может вызвать четыре вызова LLM до провала. В высокопроизводительных пайплайнах эти накладные расходы значительны. Профилируйте частоту reask вашего Guard на стейджинге перед развёртыванием в продакшен и ставьте `num_reasks=0` для некритичных полей, где действия on_fail `filter` или `noop` — приемлемая альтернатива повтору.