Como Usar Instructor e Pydantic para Extrair Dados Estruturados de LLMs

Processar texto não estruturado e transformá-lo em dados legíveis por código sempre foi um grande desafio na engenharia de software. Quando usamos LLMs para extrair informações de notas fiscais, e-mails ou contratos, o retorno padrão em texto livre ou JSON malformado costuma quebrar a aplicação em produção.

Para resolver a falta de determinismo na saída dos modelos, a biblioteca Instructor combinada com o Pydantic tornou-se o padrão de mercado em Python. Neste artigo, você verá como essa dupla garante tipos exatos, validações personalizadas e correções automáticas nas respostas de IA.

O Que É o Instructor e Por Que Ele Supera Chamadas Nativas de JSON

Embora as APIs de modelos de linguagem ofereçam modos nativos de saída em JSON ou Function Calling, esses métodos ainda exigem código manual para fazer conversão de tipos, tratar chaves ausentes ou validar regras de negócio. O Instructor atua como uma camada fina sobre SDKs populares (como OpenAI, Anthropic e Ollama), injetando esquemas do Pydantic diretamente na chamada do modelo.

A grande vantagem dessa abordagem é a tipagem forte e a capacidade de retentativas automáticas (re-asking). Se a IA gerar um dado em formato incorreto ou violar uma regra do Pydantic, o Instructor intercepta o erro e reenvia a mensagem solicitando a correção antes de devolver a resposta ao seu código Python.

Os 4 Passos para Implementar Instructor e Pydantic no Seu Projeto

Para transformar respostas brutas de inteligência artificial em objetos Python prontos para uso em bancos de dados ou APIs, siga esta estrutura essencial:

1. Defina o Esquema de Dados com Pydantic

Crie uma classe herdando de BaseModel, declarando campos tipados e adicionando descrições claras via Field do Pydantic, pois o LLM utiliza esses textos para entender o que deve extrair.

2. Envolva o Cliente do LLM com o Instructor

Utilize a função de patching do Instructor sobre o cliente nativo da API para habilitar a injeção de esquema e o tratamento de validações.

3. Solicite a Resposta Usando response_model

Faça a chamada ao método de geração passando a sua classe Pydantic no parâmetro response_model, garantindo que o retorno seja uma instância direta do seu objeto.

4. Configure Validações Personalizadas e Re-asking

Adicione validações com a anotação field_validator e defina o parâmetro max_retries para que o Instructor peça correções automáticas à IA caso alguma regra falhe.

Exemplo Prático: Extração de Dados de Notas Fiscais

Considere um fluxo que recebe o texto bruto de uma nota fiscal via OCR e precisa converter esses dados em um objeto estruturado para inclusão no ERP:

• Modelagem com Pydantic: Define-se a classe NotaFiscal com os atributos cnpj_emissor, valor_total (float) e data_emissao, incluindo um validador personalizado para checar se o CNPJ possui apenas dígitos.
• Execução com Instructor: O cliente faz a requisição passando o texto bruto e informando max_retries=3 para garantir resiliência contra saídas fora do padrão.
• Correção automática de erros: Caso a IA retorne o CNPJ formatado com pontos e traços, o Pydantic rejeita e o Instructor reenvia a mensagem pedindo apenas os números, entregando o objeto limpo.

Com poucas linhas de código, você substitui dezenas de blocos try/except e expressões regulares por uma estrutura fortemente tipada.

Erros Comuns ao Usar Instructor e Pydantic

• Omitir descrições nos campos. Deixar de incluir o atributo description no Field reduz drasticamente a acurácia do modelo, pois ele perde o contexto semântico daquele dado.
• Criar validadores rígidos demais. Escrever regras que o prompt de origem não explicou pode causar um loop de retentativas desnecessário, consumindo mais tokens sem resolver o problema.
• Não limitar o max_retries. Deixar o limite de retentativas muito alto ou indefinido pode elevar a latência da aplicação quando o documento de entrada estiver incompleto.

Como Aplicar Essa Solução em Produção

Adotar Instructor e Pydantic é o método mais eficiente para construir integrações com LLMs que não quebram em cenários reais. Ao migrar de chamadas manuais para saídas validadas, sua aplicação ganha previsibilidade, segurança e alinhamento com as boas práticas de engenharia de software.