Guardrails AI: Validação de Saída Estruturada com JSON Schema

Guardrails AI é uma biblioteca Python de código aberto projetada para tornar as saídas de LLMs confiáveis e previsíveis. Ela envolve qualquer chamada de API LLM - OpenAI, Anthropic, Cohere, modelos locais - com um pipeline de validação que verifica a resposta do modelo contra um esquema definido pelo usuário e um conjunto de validadores no nível dos campos antes de retornar o resultado ao seu código de aplicação.

A abstração central é o objeto `Guard`. Você constrói um Guard a partir de um modelo Pydantic ou de uma definição JSON Schema, opcionalmente anexa validadores a campos individuais e depois chama o Guard em vez de chamar o LLM diretamente. O Guard cuida da construção do prompt, da análise da resposta, da validação e da nova solicitação automática quando a validação falha - tudo em um único pipeline auditável.

Onde o Guardrails AI se encaixa na pilha LLM

O Guardrails fica entre o seu código de aplicação e o provedor do LLM. Ele não substitui o modelo nem muda como o modelo é chamado - adiciona uma camada de cumprimento de contrato ao redor da chamada. Pense nele como um validador de esquemas para respostas de API, exceto que a "API" é um modelo de linguagem que produz linguagem natural, e a "resposta" precisa ser analisada em dados estruturados antes de poder ser validada.

• Guard: a interface principal - envolve uma chamada LLM e aplica esquema + validadores.
• ValidationOutcome: o objeto de resultado retornado por uma chamada ao Guard - contém a saída validada, o status de aprovação/falha e os erros dos campos.
• Validator: um callable anexado a um campo do esquema que impõe uma regra específica (tipo, intervalo, regex, verificação externa).
• reask: o mecanismo de nova tentativa - quando a validação falha, o Guardrails relança o prompt ao modelo com o contexto do erro.
• Hub: o registro de validadores do Guardrails - uma coleção curada de validadores da comunidade instalável via `guardrails hub install`.

O problema fundamental é que modelos de linguagem são treinados para produzir texto plausível - não para respeitar contratos programáticos. Mesmo quando você instrui um modelo a retornar JSON, ele pode produzir saída com campos ausentes, tipos de valor errados, campos extras que seu código posterior não espera, valores alucinados fora dos intervalos permitidos ou fragmentos de texto ao redor do bloco JSON que quebram a análise por completo.

Os cinco modos de falha de saída LLM não validada

• Falha de análise: o modelo envolve o JSON em delimitadores de código markdown, adiciona comentários antes ou depois, ou produz JSON malformado que não pode ser analisado.
• Campos obrigatórios ausentes: o modelo omite um campo que foi pedido para preencher, causando um KeyError ou erro de referência nula no código posterior.
• Violações de tipo: um campo esperado como número chega como string, ou um booleano chega como a string "true" em vez do literal `true`.
• Violações de restrição de valor: um campo de avaliação retorna 11 quando o intervalo permitido é 1-10, ou um campo enum retorna um valor fora da lista definida.
• Estrutura alucinada: o modelo inventa campos adicionais ou aninha objetos de forma diferente da que o esquema especifica.

Qualquer uma dessas falhas pode corromper silenciosamente dados posteriores, causar exceções em tempo de execução ou permitir que valores ruins se propaguem para a lógica de negócio. Para protótipos de baixo risco, análise otimista é aceitável. Para pipelines de produção - extração de faturas, análise de dados clínicos, sinais de detecção de fraude, enriquecimento de registros de clientes - cada violação de campo é um problema de qualidade de dados que precisa ser capturado e tratado.

O contrato entre sua aplicação e o LLM é tão forte quanto a validação que você impõe a cada resposta. Esperança não é uma estratégia de validação.

JSON Schema é a linguagem que o Guardrails AI usa para descrever como uma resposta LLM válida se parece. Uma definição JSON Schema especifica a estrutura esperada do objeto - quais campos existem, seus tipos, quais são obrigatórios e que restrições se aplicam aos seus valores. Este esquema cumpre dois propósitos: diz ao Guardrails como validar a resposta analisada, e o Guardrails o usa para construir a instrução de prompt que diz ao modelo que forma produzir.

O que o JSON Schema cobre para validação de LLM

Para casos de uso de saída estruturada, as palavras-chave JSON Schema mais úteis são imposição de tipos, listas de campos obrigatórios, valores enum, formatos de string e intervalos numéricos. Juntas, elas cobrem a maioria das regras de nível de campo que uma tarefa de extração ou geração precisa impor.

{
  "$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
    }
  }
}

Este esquema diz ao Guardrails para rejeitar qualquer resposta em que `rating` esteja fora de 1-5, `sentiment` não seja um dos três valores permitidos, ou `summary` tenha menos de 20 caracteres. Campos listados em `required` devem estar presentes. `additionalProperties: false` rejeita qualquer campo extra que o modelo adicione por conta própria.

Gerando um esquema a partir de uma resposta de exemplo

Ao projetar uma nova tarefa de extração, acertar o esquema inicial leva tempo. Um atalho prático: execute seu prompt uma vez sem validação, examine o JSON bruto que o modelo retorna e depois use o Gerador de JSON Schema para inferir automaticamente um esquema Draft-07 a partir dessa amostra. O esquema gerado captura tipos, campos obrigatórios e estrutura aninhada. Depois você o refina - apertando comprimentos de string, adicionando restrições enum, definindo limites numéricos - em vez de escrever cada palavra-chave do zero.

Entender o pipeline de validação ajuda a depurar falhas e configurar a estratégia de resposta certa para cada campo. O pipeline roda em uma ordem fixa para cada chamada ao Guard: injeção de prompt, análise da resposta, validação JSON Schema, execução de validadores de campo e montagem do resultado.

O Guardrails AI suporta dois estilos de definição de esquema: o formato legado Rail spec e a abordagem moderna com modelos Pydantic. Conhecer ambos é útil porque você encontrará Rail specs em bases de código antigas e exemplos da comunidade, enquanto Pydantic é o caminho recomendado para todos os projetos novos a partir do Guardrails v0.4+.

Modelos Pydantic como esquemas do Guard

A forma mais limpa de definir um esquema de saída Guardrails em Python é uma subclasse de `BaseModel` do Pydantic. Modelos Pydantic têm exportação nativa para JSON Schema, verificação de tipos no IDE e sintaxe Python familiar. Você anexa validadores do Guardrails usando o `Field()` do Pydantic com metadados personalizados, ou importando classes de validadores diretamente de `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)

O pipeline Pydantic para JSON Schema

Por baixo dos panos, o Guardrails chama `model.model_json_schema()` para exportar seu modelo Pydantic como JSON Schema e depois usa esse esquema tanto para injeção de prompt quanto para validação da resposta. Isso significa que todo modelo Pydantic que você consiga escrever é automaticamente um contrato Guardrails válido. Você pode inspecionar o esquema gerado você mesmo - cole uma resposta de exemplo no Gerador de JSON Schema para ver o esquema equivalente e depois compare-o com a saída do seu modelo Pydantic.

Se sua aplicação é baseada em TypeScript mas chama um serviço Guardrails em Python, o Conversor JSON para Zod Schema gera um esquema Zod correspondente a partir do mesmo JSON de exemplo - útil para validar o mesmo contrato no lado do cliente sem duplicar manualmente a definição do esquema.

Rail specs - o formato legado

Rail specs são arquivos XML onde cada elemento `<output>` descreve um campo com um atributo `type` e um ou mais elementos filhos `<validator>`. Eles precedem a integração com Pydantic e são menos ergonômicos para desenvolvedores Python, mas ainda são totalmente suportados. Se você herdar uma base de código Guardrails que usa arquivos `.rail`, pode migrar cada especificação para um modelo Pydantic de forma incremental - o comportamento de validação é equivalente.

Um fluxo de trabalho Guardrails confiável combina design de esquema offline, testes locais e monitoramento em produção. A fase de design do esquema - onde você define como uma saída válida se parece - é a etapa mais importante e a que mais se beneficia de ferramentas dedicadas.

Etapa 1: Projete o esquema offline

Antes de escrever qualquer código Guardrails, defina seu esquema de saída como um documento JSON Schema independente. Trabalhar primeiro em JSON Schema permite iterar no contrato independentemente da chamada LLM - você pode validar payloads de amostra, ajustar restrições e confirmar que o esquema está correto antes de gastar créditos de API em testes.

O Validador de JSON Schema da Aback Tools permite colar um JSON Schema e um payload candidato, e ver imediatamente os erros de validação no nível dos campos. Use-o para confirmar que seus arrays `required`, listas enum e intervalos numéricos se comportam como esperado antes de traduzir o esquema para um modelo Pydantic. O Formatador & Validador JSON é útil para verificar se o próprio arquivo de esquema é JSON sintaticamente válido antes de referenciá-lo.

Etapa 2: Gere Pydantic a partir de JSON

Se você coletou respostas LLM de exemplo durante a prototipagem, o Conversor JSON para Dataclass / Pydantic Python gera um modelo Pydantic a partir de um payload JSON de exemplo em uma etapa. A ferramenta infere tipos de campo, lida com objetos aninhados e aplica `Optional` onde campos podem estar ausentes. Use a saída como ponto de partida e adicione validadores Guardrails a cada campo com base nas restrições do seu JSON Schema.

Etapa 3: Teste localmente com respostas simuladas

Guards do Guardrails podem ser chamados com qualquer callable Python, não apenas APIs LLM ao vivo. Durante o desenvolvimento, passe uma função simulada que retorne uma resposta de string fixa para testar o pipeline de validação sem chamadas de API. Isso torna rápida e gratuita a iteração sobre mudanças de esquema, configurações de validadores e prompts de reask antes de conectar a um endpoint de modelo pago.

Fluxo de esquemas recomendado com Aback Tools

• Gerador de JSON Schema - infere um esquema inicial a partir de uma resposta LLM de exemplo.
• Validador de JSON Schema - valida payloads candidatos contra seu esquema offline.
• Formatador & Validador JSON - verifica se os arquivos de esquema são JSON válido antes de usar.
• JSON para Dataclass Python - gera um modelo Pydantic a partir de um payload de exemplo.
• JSON para Zod Schema - gera um contrato do lado TypeScript para validação no cliente.

O Guardrails AI melhora significativamente a confiabilidade da saída estruturada, mas não é uma garantia de correção. Entender as limitações ajuda você a projetar seu pipeline com fallbacks apropriados em vez de confiar no Guard incondicionalmente.

Laços de reask nem sempre convergem

Quando um modelo falha consistentemente em um validador específico, adicionar mais tentativas reask não ajuda - apenas custa mais créditos de API pelo mesmo resultado. Alguns modos de falha são sistemáticos: o modelo genuinamente não entende uma restrição, ou a restrição é muito estrita para o modelo satisfazê-la de forma confiável dado o input. Audite suas taxas de falha de validadores e trate validadores com alta taxa de falha como sinais para revisar a definição da restrição ou o prompt.

JSON Schema não captura erros semânticos

Um esquema pode confirmar que `sentiment` é um de `["positive", "neutral", "negative"]`, mas não pode verificar que o sentimento atribuído está realmente correto para o texto de entrada. JSON Schema e validadores impõem contratos estruturais e sintáticos - eles não substituem revisão humana nem verificações de qualidade posteriores para a precisão do conteúdo. Use o Guardrails para impor o formato e a estrutura da saída, e aplique métricas de avaliação separadas para a correção do conteúdo.

Sobrecarga de latência e custo

Cada tentativa de reask é uma chamada adicional de API LLM com custo total de tokens. Para um Guard configurado com `num_reasks=3`, uma extração no pior caso pode disparar quatro chamadas LLM antes de falhar. Em pipelines de alto volume, essa sobrecarga é significativa. Perfle a taxa de reask do seu Guard em staging antes de implantar em produção, e defina `num_reasks=0` para campos não críticos onde as ações on_fail `filter` ou `noop` são alternativas aceitáveis à nova tentativa.