Como estruturar JSON em LLMs com Pydantic para APIs

O desafio de obter dados estruturados de modelos de linguagem

Quando conversamos com um modelo de inteligência artificial, o retorno costuma ser texto livre em formato de narrativa. Em aplicações reais de software, no entanto, precisamos que esses dados cheguem organizados em estruturas rígidas, como um objeto JSON, para serem consumidos por bancos de dados e APIs. Na prática, isso significa que se a inteligência artificial esquecer uma vírgula ou inventar uma chave diferente, todo o fluxo do sistema pode quebrar por causa de um erro de leitura.

Para resolver esse problema, as principais plataformas de modelos de linguagem introduziram o recurso de chamada de funções, conhecido como function calling. Esse mecanismo instrui o modelo a ignorar a prosa e preencher os campos de um esquema pré-definido. Contudo, confiar apenas na boa vontade do modelo nem sempre é suficiente em ambientes críticos, pois variações sutis no texto ainda podem escapar das verificações básicas de formato. É exatamente nesse ponto que entra a engenharia de validação de dados em nível de código.

Antes de avançarmos na implementação, vale lembrar que estruturar dados com segurança guarda semelhanças com as técnicas que discutimos em nosso guia de blindagem de agentes de IA com guardrails, onde o objetivo principal é impor limites rígidos ao comportamento dos modelos. Sem essas barreiras de contenção, construir fluxos automatizados complexos torna-se uma aposta arriscada. Vamos ver como blindar essa comunicação usando uma das ferramentas mais populares do ecossistema Python.

O papel do Pydantic na validação de esquemas

O Pydantic é uma biblioteca voltada para a validação de dados e gerenciamento de configurações em Python que utiliza dicas de tipos nativas da linguagem. Na prática, ele age como um fiscal rigoroso na entrada de qualquer informação, recusando imediatamente qualquer dado que viole as regras estipuladas. Quando combinamos essa ferramenta com modelos de linguagem, criamos um contrato inegociável entre a inteligência artificial e o nosso backend.

Definir uma estrutura com Pydantic é simples e direto, exigindo apenas que você declare uma classe herdando de BaseModel e especifique os tipos esperados para cada campo. Se o modelo de linguagem tentar retornar uma string onde deveria existir um número inteiro, o Pydantic intercepta o erro antes que ele chegue ao banco de dados e avisa exatamente onde a estrutura falhou. Essa abordagem reduz drasticamente a quantidade de código de tratamento de exceções que você precisaria espalhar pelo sistema.

Além disso, essa clareza na modelagem dos dados facilita a integração com outros componentes do ecossistema de inteligência artificial, como a arquitetura de subagentes complexos com LangGraph, onde múltiplos blocos de software trocam informações estruturadas o tempo todo. Manter um padrão rígido de comunicação evita que um agente interprete mal o resultado gerado por outro.

Implementando Function Calling com validação estrita

Para colocar a mão na massa, vamos criar um exemplo prático de extração de dados onde a inteligência artificial precisa ler um texto desestruturado e transformá-lo em um objeto validado. Primeiro, definimos a estrutura dos dados esperados utilizando as classes do Pydantic com seus respectivos tipos e descrições detalhadas para orientar o modelo.

As descrições inseridas nos campos servem como dicas contextuais vitais para que o modelo entenda exatamente qual tipo de informação preencher em cada atributo. Veja abaixo um exemplo funcional de como configurar essa estrutura em um projeto Python moderno:

from pydantic import BaseModel, Field

class ExtractedUser(BaseModel):
    name: str = Field(description='Nome completo do cliente')
    age: int = Field(description='Idade em anos completos')
    active: bool = Field(description='Status da conta do usuário')

# Exemplo de uso simulado com o esquema definido
schema_json = ExtractedUser.model_json_schema()
print(schema_json)

Esse esquema gerado em formato JSON é enviado diretamente para a API do modelo de linguagem durante a requisição. Quando o modelo processa a entrada, ele é forçado a mapear a resposta para as chaves exatas definidas no código, garantindo a interoperabilidade com o restante da aplicação.

Tratando falhas e garantindo resiliência em produção

Mesmo com esquemas bem definidos e instruções claras, redes instáveis e modelos sob alta carga podem ocasionalmente retornar respostas truncadas ou incompletas. Por isso, uma engenharia robusta em produção exige que o seu código esteja preparado para capturar falhas de validação e tentar novamente de forma controlada. O uso de blocos de tentativa e captura em conjunto com as exceções específicas do Pydantic é indispensável para evitar quebras abruptas.

Outra boa prática recomendada é implementar mecanismos de auto-correção, onde a mensagem de erro gerada pelo Pydantic é devolvida para a inteligência artificial na rodada seguinte, instruindo-a a corrigir o campo defeituoso. Essa técnica eleva consideravelmente a taxa de sucesso na extração de dados complexos, transformando um erro de processamento em uma oportunidade de ajuste automático. Para aprofundar esses conceitos na prática em produção, confira também nossa análise técnica sobre Gemini no Apple CarPlay: Como usar a IA do Google no carro.

Considerações finais

Garantir que as respostas das inteligências artificiais retornem estruturas de dados consistentes deixou de ser um luxo e virou requisito básico para sistemas em produção. Ao unir o poder de geração dos modelos de linguagem com a rigidez de validação do Pydantic, construímos pontes confiáveis entre o texto livre e as APIs corporativas. Essa disciplina de engenharia não apenas economiza tempo de desenvolvimento, mas também eleva a confiabilidade de toda a infraestrutura automatizada que você decidir colocar no ar.