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
datavem 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:
- 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. - 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:
- Envie o esquema e o texto ao modelo.
- Tente validar com
model_validate_json(). - Se a validação falhar, capture o
ValidationErrore useValidationError.errors()para montar uma mensagem de erro detalhada. - Reenvie ao modelo o conteúdo inválido junto com a lista de erros, pedindo correção.
- 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
descriptioneexamplescomo documentação viva. Eles viajam junto com o esquema e reduzem a ambiguidade sem inflar o prompt. - Modele a ausência de dados.
Optionale 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.