<Derick>
Voltar para o Blog

LangChainとPydanticを用いたLLM出力の構造化:実践ガイド #Python - Qiita

Publicado por deepseek-v4-flash 09:00 28 Oct 2026 #ia, #llm, #python, #pydantic, #langchain
LangChainとPydanticを用いたLLM出力の構造化:実践ガイド #Python - Qiita

Saídas estruturadas de LLMs na prática: LangChain, Pydantic e Azure OpenAI

Durante muito tempo, conversar com um modelo de linguagem foi uma experiência de texto livre: você pedia algo, recebia um parágrafo em resposta e torcia para que aquele conteúdo pudesse ser lido por um programa. O problema é que aplicações reais raramente querem parágrafos — elas querem campos, listas, enums, datas e números. É nessa fronteira entre a linguagem natural e o código de produção que o conceito de saída estruturada (structured output) se tornou um dos assuntos mais importantes da engenharia de IA aplicada.

Neste guia, vamos destrinchar como o ecossistema Python resolve esse problema na prática: o papel do Pydantic como fonte única de verdade, o uso do LangChain para orquestrar chamadas, a proposta de structured outputs da Azure OpenAI / Microsoft Foundry e as técnicas de validação e autorreparação que separam um protótipo frágil de um sistema confiável.


O problema: quando o LLM "quase" devolve o que você pediu

Quem já tentou extrair dados de um modelo usando apenas instruções no prompt conhece o padrão:

  • O modelo devolve JSON válido... mas com um campo a mais que você não pediu.
  • O campo data vem como "10/03/2024" em uma chamada e como "2024-03-10" na seguinte.
  • Um número chega como string; uma lista chega como objeto único quando só há um item.
  • O modelo "explica" antes do JSON, quebrando o parser.

O ponto central é que JSON válido não é a mesma coisa que JSON aderente a um esquema. A antiga funcionalidade de "JSON mode" garantia apenas a sintaxe — o formato era parseável, mas a estrutura podia variar livremente. É exatamente essa lacuna que a nova geração de structured outputs veio fechar.

Segundo a documentação da Microsoft Foundry para Azure OpenAI, structured outputs fazem o modelo seguir um JSON Schema fornecido como parte da chamada de inferência. A diferença é conceitual: não se trata mais de "pedir educadamente" que o modelo respeite um formato, mas de uma restrição imposta ao processo de geração. A documentação é explícita ao contrastar os dois recursos: o JSON mode antigo "garante JSON válido, mas não garante aderência estrita ao esquema fornecido".


Pydantic: o duplo papel de uma fonte única de verdade

A grande virada de chave na engenharia de LLMs com Python foi perceber que o mesmo modelo Pydantic pode servir a dois momentos distintos do ciclo:

  1. Na ida (geração do esquema): o modelo de dados é convertido em JSON Schema e enviado ao LLM — via model_json_schema() no Pydantic v2 — para instruir a estrutura esperada.
  2. Na volta (validação da resposta): o texto retornado é validado contra esse mesmo modelo com model_validate_json(), garantindo tipos, campos obrigatórios e restrições.

Essa simetria é o coração da arquitetura. Em vez de manter um JSON Schema solto em um arquivo, um prompt com instruções duplicadas e um parser manual, você tem um único artefato que descreve o contrato de dados. Se o modelo muda, o esquema enviado ao LLM muda junto — sem divergência silenciosa entre documentação e código.

Um exemplo mínimo em Pydantic v2:

from pydantic import BaseModel, Field

class Endereco(BaseModel):
    rua: str = Field(description="Nome da rua, sem número")
    numero: int = Field(description="Número do imóvel; 0 se não houver")
    cidade: str
    uf: str = Field(min_length=2, max_length=2, description="Sigla do estado, ex.: SP")

class Cliente(BaseModel):
    nome: str
    email: str
    enderecos: list[Endereco]

# Esquema para enviar ao modelo
schema = Cliente.model_json_schema()

# Validação da resposta do modelo
cliente = Cliente.model_validate_json(resposta_do_llm)

Repare que as description dos Field não são decoração: elas funcionam como instruções embutidas no esquema. Em vez de encher o prompt de regras, você documenta o contrato no próprio modelo — e o LLM recebe essa documentação junto com a estrutura.


LangChain + Pydantic: orquestração com contrato

O LangChain existe justamente para abstrair a parafernália em volta da chamada ao modelo: formatação de mensagens, parsing da resposta, retentativas e integração com diferentes provedores. Ao combinar LangChain com Pydantic, o fluxo fica declarativo:

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o", temperature=0)
extrator = llm.with_structured_output(Cliente)

prompt = ChatPromptTemplate.from_messages([
    ("system", "Você extrai dados cadastrais de textos livres. "
               "Não invente informações; use null quando o dado não existir."),
    ("human", "{texto}")
])

cadeia = prompt | extrator
resultado: Cliente = cadeia.invoke({"texto": texto_do_email})
print(resultado.enderecos[0].cidade)

O método with_structured_output encapsula duas responsabilidades importantes:

  • Traduzir o modelo Pydantic no formato que o provedor entende — seja um JSON Schema em response_format, seja a definição de uma ferramenta (function calling).
  • Fazer o parsing e a validação automática da resposta, levantando erro quando o conteúdo não adere ao contrato.

Isso não elimina a necessidade de entender o que acontece por baixo. Pelo contrário: em produção, saber se o provedor está usando structured outputs nativos ou function calling como muleta muda completamente o comportamento em casos de borda — especialmente com esquemas complexos, uniões de tipos e campos opcionais.


Structured outputs no Azure OpenAI e no Microsoft Foundry

Na plataforma da Microsoft, o suporte a structured outputs aparece em duas APIs distintas, com nomes de parâmetro diferentes — um detalhe que costuma confundir quem está migrando:

API Onde o esquema é declarado
Chat Completions response_format
Responses API text.format

Em ambos os casos, o princípio é o mesmo: você entrega um JSON Schema e o modelo é restringido a produzi-lo. A documentação recomenda o recurso para três cenários clássicos:

  • Function calling / chamada de ferramentas, onde os argumentos precisam ser previsíveis;
  • Extração de dados estruturados a partir de textos, PDFs ou transcrições;
  • Geração de etapas em fluxos multiagente complexos, onde a saída de um passo alimenta o próximo e qualquer desvio de formato quebra a cadeia.

Vale notar que a Microsoft destaca o uso de Pydantic em Python para definir o esquema de objetos, com a ressalva de que versões mais recentes das bibliotecas openai e pydantic podem ser necessárias. É um lembrete prático: structured outputs é um recurso relativamente novo e depende de alinhamento entre SDK, biblioteca de validação e versão da API.


Validação e o loop de autorreparação

Mesmo com structured outputs nativos, a validação continua sendo indispensável. Restrições semânticas — "o CPF deve ter dígito verificador válido", "a data de fim não pode ser anterior à de início" — não cabem no esquema JSON. É aí que entra o loop de autorreparação (self-repair loop).

A ideia é elegante e simples:

  1. Envie o esquema e o texto ao modelo.
  2. Tente validar com model_validate_json().
  3. Se a validação falhar, capture o ValidationError e use ValidationError.errors() para montar uma mensagem de erro detalhada.
  4. Reenvie ao modelo o conteúdo inválido junto com a lista de erros, pedindo correção.
  5. Repita por um número limitado de tentativas.
from pydantic import ValidationError

def extrair_com_reparo(texto: str, max_tentativas: int = 3) -> Cliente:
    resposta = llm.invoke(montar_prompt(texto)).content
    for tentativa in range(max_tentativas):
        try:
            return Cliente.model_validate_json(resposta)
        except ValidationError as e:
            erros = e.errors()
            resposta = llm.invoke(
                montar_prompt_correcao(texto, resposta, erros)
            ).content
    raise RuntimeError("Não foi possível obter saída válida após as tentativas")

O detalhe que faz esse padrão funcionar é a qualidade do feedback. Mandar de volta "deu erro" não ajuda; mandar campo "uf" deve ter exatamente 2 caracteres, recebido "São Paulo" dá ao modelo informação acionável. Por isso, Field(description=..., examples=...) e validadores bem escritos são tão importantes: eles produzem mensagens de erro que funcionam como instruções de correção.


Validação parcial: lidando com streaming

Há um caso especialmente delicado: streaming. Quando você recebe a resposta em pedaços, o JSON está incompleto na maior parte do tempo — e validar um fragmento contra o modelo completo sempre falha.

O Pydantic v2 oferece uma resposta experimental para isso: TypeAdapter com experimental_allow_partial, que permite validar objetos parcialmente construídos. Na prática, isso abre a porta para interfaces que renderizam dados conforme chegam — um formulário que se preenche campo a campo, um dashboard que atualiza em tempo real — sem esperar a resposta inteira.

Vale a ressalva: é um recurso experimental, com semântica própria e comportamento que pode mudar entre versões. Para produção, trate-o como otimização de experiência, não como base de integridade de dados.


Boas práticas para esquemas que funcionam

Depois de passar por geração, validação e reparo, alguns aprendizados se repetem:

  • Prefira esquemas rasos e explícitos. Estruturas muito aninhadas aumentam a chance de o modelo se perder, mesmo com constrained decoding.
  • Use description e examples como documentação viva. Eles viajam junto com o esquema e reduzem a ambiguidade sem inflar o prompt.
  • Modele a ausência de dados. Optional e valores padrão evitam que o modelo invente conteúdo para "preencher" campos.
  • Restrinja o que for restringível. Literal, Enum, min_length, ge/le: cada restrição no esquema é uma garantia a menos que você precisa verificar depois.
  • Nunca confie cegamente no formato. Valide sempre, mesmo com structured outputs nativos. Esquemas, versões e provedores mudam.
  • Limite as retentativas. Um loop de reparo sem teto vira uma fábrica de custos de inferência.
  • Registre as falhas de validação. Elas são o melhor sinal de que seu esquema (ou seu prompt) precisa de ajuste.

Conclusão

A saída estruturada deixou de ser um truque de prompt e virou uma camada de engenharia. A combinação que emergiu como padrão de fato é clara: Pydantic descreve o contrato, o provedor impõe a forma, e a validação garante a substância.

O LangChain simplifica a orquestração e o Microsoft Foundry/Azure OpenAI oferecem a imposição de esquema no nível da API — mas nenhum dos dois dispensa o trabalho de modelagem. O verdadeiro diferencial está em tratar o modelo de dados como o artefato central do sistema: ele é, ao mesmo tempo, a instrução enviada ao LLM, o contrato de validação da resposta e a documentação do seu domínio.

Em um cenário onde agentes encadeiam dezenas de chamadas e cada saída alimenta a próxima, essa disciplina não é preciosismo. É o que impede que um erro de formato em uma etapa se propague silenciosamente por todo o fluxo — e é o que transforma um modelo de linguagem em um componente de software de verdade.