Pydantic + OpenAI: a forma mais limpa de obter saídas estruturadas de LLMs

O que muda com essa combinação

Se você já trabalhou com LLMs em produção, conhece a dor: o modelo retorna um JSON, você faz json.loads(), valida os tipos manualmente, acessa campos com colchetes e torce para que nada venha fora do esperado. Maria Mouschoutzi, em artigo no Towards Data Science, mostra como a integração entre Pydantic e o recurso de Structured Outputs da OpenAI elimina toda essa fricção — e entrega objetos Python tipados diretamente da API.

A diferença fundamental é que, com essa abordagem, você não recebe mais uma string JSON ou um dicionário: você recebe um objeto Python com todos os campos validados e tipados automaticamente. O JSON Schema que a API precisa é gerado a partir do seu modelo Pydantic nos bastidores — você nunca precisa escrevê-lo manualmente.

O problema antes do Pydantic

Até agora, tínhamos três abordagens principais para obter respostas estruturadas de LLMs:

• JSON Mode: o modelo tenta retornar JSON válido, mas não há garantia de conformidade com o schema desejado. Você ainda precisa validar tudo do lado Python.
• Function Calling: o modelo segue um schema, mas a resposta ainda é uma string JSON que precisa ser parseada manualmente.
• Structured Outputs da OpenAI: o modelo garante JSON compatível com o schema via constrained decoding — mas você ainda recebe uma string.

Em todos os casos, o trabalho de parsear, validar tipos, acessar campos e tratar valores inesperados ficava com o desenvolvedor. É exatamente essa lacuna que o Pydantic preenche.

A mágica do Pydantic como camada de schema

Pydantic é uma biblioteca Python para validação de dados usando type annotations. Com ela, você define a forma e os tipos dos seus dados como uma classe Python:

from pydantic import BaseModel

class PersonInfo(BaseModel):
    name: str
    age: int
    city: str

Se alguém tentar criar um PersonInfo com age="trinta e dois", o Pydantic levanta um erro claro e descritivo antes que o dado inválido se propague pelo sistema. Quando integrado à API da OpenAI, o modelo Pydantic se torna o schema que o Structured Outputs usa para validação no nível do modelo — e você recebe de volta uma instância da sua classe, com todos os campos acessíveis via ponto (person.name) e tipos garantidos.

Em outras palavras: Pydantic é a camada de definição de schema que fica entre seu código Python e a API da OpenAI, tornando toda a experiência de saída estruturada mais limpa, segura e fácil de manter.

O que você ganha na prática

✅ Um único ponto de verdade para o schema: em vez de duplicar a definição dos campos entre o JSON Schema da API e as validações do Python, você define tudo uma vez na classe Pydantic. Isso reduz bugs de sincronização entre o que a API espera e o que seu código valida.

✅ Validação em duas camadas: a API garante que o JSON retornado segue o schema (constrained decoding). O Pydantic garante que os tipos estejam corretos no lado Python. Se algo passar pela primeira camada, a segunda pega.

✅ Autocomplete e type hints: como você está lidando com objetos Python reais em vez de dicionários, seu editor oferece autocomplete nos campos, e ferramentas como mypy e pyright conseguem verificar a consistência dos tipos em todo o código.

✅ Campos com valor padrão e validação customizada: o Pydantic permite definir defaults, validadores personalizados e constraints como min_length, max_length e regex diretamente nos campos. Tudo isso é refletido no JSON Schema enviado para a API.

Limitações para ter em mente

⚠️ Nem todo provider suporta: a integração direta entre Pydantic e a API da OpenAI é relativamente nova. Se você usa outros providers (Anthropic, Groq, Together), precisará de adaptações ou bibliotecas como o Instructor.

⚠️ Schemas complexos têm custo: modelos Pydantic muito aninhados geram JSON Schemas grandes que aumentam o prompt de sistema e podem elevar ligeiramente o consumo de tokens.

⚠️ Curva de aprendizado do Pydantic v2: a versão 2 do Pydantic trouxe mudanças significativas na API. Se você está migrando da v1, reserve tempo para aprender os novos padrões como model_validate() e field_validator.

O veredito

A combinação de Pydantic com Structured Outputs da OpenAI é, na avaliação da autora, a configuração mais limpa disponível hoje para construir aplicações confiáveis com LLMs em Python. Ela elimina o boilerplate de parsing manual, reduz drasticamente a superfície de bugs relacionados a tipos e permite que você foque no que realmente importa: a lógica da sua aplicação.

Para quem está começando agora com LLMs em produção, esse é provavelmente o padrão que vai se estabelecer nos próximos meses. A OpenAI já trata a integração como first-class, e outras bibliotecas do ecossistema Python estão seguindo o mesmo caminho.