Saídas estruturadas com IA: como definir, impor e validar o formato sem perder confiabilidade

1. Projete o esquema a partir do uso downstream

Uma saída estruturada é uma resposta do modelo ajustada a um formato de dados previsto, como um objeto JSON com campos definidos. O objetivo não é apenas fazer a resposta «parecer JSON»: é permitir que o sistema receptor a interprete de forma consistente. Para isso, comece pelo consumidor downstream e trabalhe de trás para frente: identifique quais campos ele precisa, o que fará com eles e como deve agir quando a entrada não contiver a informação solicitada.

Mantenha o esquema tão pequeno quanto o caso de uso permitir. Para cada campo, documente o tipo, se é obrigatório, os valores aceitos, as unidades e a procedência esperada. Decida também como representar dados ausentes. Um valor nulo, uma string vazia e um campo omitido podem ter significados distintos; não os trate como equivalentes sem uma regra explícita. Se uma data for alimentar um banco de dados, por exemplo, prefira um formato normalizado e um fuso horário definido, em vez de aceitar expressões como «na sexta-feira».

Separe a estrutura das instruções semânticas. O esquema pode exigir que `data` seja uma string, mas isso, por si só, não impede o modelo de inventar uma data. As descrições dos campos e o prompt podem orientar a extração, mas a aplicação precisa definir quais evidências são aceitáveis e o que fazer quando não forem encontradas. Uma opção segura é permitir um estado explícito, como `não_encontrado`, ou um campo de evidência, em vez de forçar uma resposta afirmativa.

A documentação do Azure OpenAI descreve o uso de uma definição de esquema JSON em uma chamada de inferência e apresenta exemplos com Pydantic e Zod. A documentação do Gemini também mostra respostas JSON ajustadas a um esquema e exemplos com modelos de dados. Essas capacidades documentadas se aplicam às APIs e configurações descritas; não demonstram que todos os esquemas, modelos ou provedores aceitem exatamente as mesmas restrições.

2. Escolha o mecanismo de saída conforme a tarefa e o provedor

Há três abordagens comuns, mas elas não são equivalentes. O prompting puro pede ao modelo, por meio de instruções em linguagem natural, que devolva um formato específico. Pode bastar para um protótipo ou quando a saída será lida apenas por uma pessoa, mas o formato pode se degradar: podem surgir explicações fora do JSON, chaves inesperadas ou valores com tipos incorretos. Se o resultado alimentar código, considere essa opção menos controlável e sempre valide a resposta.

O modo JSON solicita uma resposta JSON. A documentação do Azure diferencia esse modo das saídas estruturadas por esquema: o primeiro garante JSON válido, mas não garante a conformidade estrita com o esquema fornecido. Portanto, conseguir analisar a resposta como JSON não prova que ela tenha as chaves, os tipos ou as restrições exigidos pela aplicação.

As saídas estruturadas com esquema permitem fornecer uma definição que orienta o formato da resposta. A documentação do Azure mostra esse mecanismo nos campos de formato da resposta, além de exemplos de integração com Pydantic e Zod. O Gemini também documenta a configuração de uma resposta JSON baseada em esquema e apresenta exemplos de extração e classificação. A disponibilidade específica depende da API, do modelo e da configuração escolhidos: consulte a documentação atual do endpoint que realmente usará, em vez de supor que produtos com nomes parecidos se comportem da mesma forma.

Chamadas de função ou ferramenta são úteis quando o modelo precisa propor argumentos para uma operação disponível na aplicação, como consultar um pedido. Isso não equivale a executar a função nem a verificar se a ação é segura: o servidor deve validar os argumentos e aplicar seus próprios controles antes de agir. No uso de saídas estruturadas para chamadas de função descrito pelo Azure, a documentação informa que chamadas paralelas não são compatíveis e recomenda desativá-las nessa configuração. Não estenda essa limitação a outras APIs sem confirmá-la.

Como regra prática: use uma saída com esquema quando o objetivo principal for produzir um objeto conforme uma definição; use uma chamada de função quando o modelo precisar selecionar uma operação e propor seus argumentos; e reserve o prompting puro para contextos de menor risco ou tarefas em que a validação local rigorosa compense a menor imposição de formato. Em todos os casos, a resposta deve passar pelos controles da aplicação antes de chegar ao sistema downstream.

3. Valide a estrutura antes de processar a resposta

A primeira barreira é analisar a resposta com um parser do formato esperado. Para JSON, o parser deve rejeitar texto inválido, valores truncados e conteúdo que não possa ser convertido em um objeto. Se o provedor entregar uma resposta já analisada pelo SDK, verifique também o estado de conclusão, as recusas e os campos que possam indicar uma resposta incompleta; não presuma que sempre recebeu um resultado utilizável.

A segunda barreira é validar a resposta com um esquema local. O JSON Schema permite expressar tipos, campos obrigatórios, enumerações, limites de comprimento e regras para propriedades adicionais, entre outras condições. Bibliotecas de validação podem transformar essas regras em erros acionáveis antes que a saída chegue a um banco de dados ou a uma API. A implementação depende da linguagem e da versão do esquema: verifique se a biblioteca escolhida é compatível com as palavras-chave e o dialeto usados pelo contrato e teste essa combinação na integração contínua.

Não copie sem revisão o esquema aceito pelo provedor como contrato definitivo da aplicação. O provedor pode aceitar apenas um subconjunto das regras ou transformar um modelo de dados de uma biblioteca em uma definição compatível com a API. Mantenha uma fonte de verdade para o contrato e, se o provedor exigir uma representação reduzida, gere ou adapte o esquema da chamada sem remover as regras críticas da validação local.

A validação deve ser rigorosa nos limites do sistema. Rejeite propriedades inesperadas se elas puderem alterar o comportamento; converta tipos somente quando a conversão for inequívoca e estiver documentada; e evite «consertar» automaticamente valores duvidosos. Se um campo precisa ser um inteiro, converter `12,5` em `12` não é um reparo inofensivo: pode mudar o significado. Registre o erro, o identificador da solicitação e a versão do esquema para diagnosticar falhas sem aceitar silenciosamente dados defeituosos.

4. Verifique o conteúdo e represente a incerteza

Uma resposta estruturalmente correta ainda pode ser semanticamente falsa. Para medir essa diferença, avalie os campos com base na entrada original e nas fontes de referência disponíveis, não na fluência da explicação do modelo. Em extrações, preserve evidências textuais suficientes para localizar o dado no documento. Em classificações, registre a regra ou o sinal que levou à categoria. Em enriquecimentos, identifique quais valores vêm da entrada e quais dependem de uma fonte externa autorizada.

Projete uma representação explícita para a incerteza. Conforme o caso, ela pode ser um valor nulo acompanhado de um estado, uma lista de candidatos ou uma marca de revisão. Evite pedir uma porcentagem de confiança sem definir o que ela significa e como será calibrada: um número produzido pelo próprio modelo não é, por si só, uma probabilidade comprovada. Se usar uma pontuação, meça-a com um conjunto rotulado e defina os limites considerando o custo dos erros e das revisões, não a intuição.

A revisão humana deve ser uma etapa normal do pipeline, não uma exceção improvisada. Encaminhe para revisão os casos ambíguos, sem evidências, que violem regras de negócio ou envolvam decisões de alto impacto. O revisor precisa ver a entrada, a saída proposta, as evidências e o motivo do encaminhamento. Se uma correção humana for armazenada como dado de treinamento ou exemplo de regressão, registre também sua procedência e a política aplicável.

As evidências disponíveis aqui respaldam capacidades de saída baseada em esquema para Azure OpenAI e Gemini, mas não quantificam taxas de erro de formato em comparação com erros semânticos. Também não permitem estabelecer um limite universal de confiança. Por isso, meça ambas as classes de falha na sua própria tarefa: uma baixa taxa de JSON inválido não demonstra que a extração esteja correta, e um bom resultado em uma amostra pequena não garante o comportamento em produção.

5. Teste o sistema e monitore seu comportamento em produção

Monte um conjunto de regressão com exemplos representativos e casos-limite antes de publicar alterações no prompt, no esquema, no modelo ou no SDK. Inclua entradas limpas, incompletas e contraditórias, caracteres inesperados, documentos longos e casos em que a resposta correta seja «não encontrado». Para cada caso, mantenha uma expectativa verificável: resultado esperado, campos que devem ficar ausentes e condições que exigem encaminhamento para revisão.

Meça separadamente a validade sintática, a conformidade com o esquema, a precisão de cada campo e a taxa de encaminhamento para revisão. Uma única métrica agregada pode ocultar que o sistema produz JSON perfeito, mas classifica mal; ou que acerta a maioria dos campos e falha justamente nos de maior impacto. Segmente os resultados por tipo de entrada, versão do modelo, modelo de prompt e versão do esquema.

Em produção, registre métricas capazes de detectar degradações: respostas não analisáveis, erros de validação, campos nulos, valores fora do intervalo, divergências em relação a fontes de referência e proporção de revisões humanas. Defina alertas e uma estratégia de recuperação, como reter registros duvidosos ou voltar a uma versão anterior. Não armazene nos logs dados sensíveis desnecessários; conserve apenas o que for preciso para depuração, auditoria e cumprimento da política aplicável.

Antes de mudar de provedor ou mecanismo, repita os testes com a mesma amostra e os mesmos critérios de aceitação. Os recursos documentados não são intercambiáveis em todos os detalhes, e uma migração pode alterar quais restrições são aceitas ou como as respostas são representadas. Trate a configuração de produção como parte do contrato: provedor, endpoint, modelo, esquema, SDK, prompt e política de novas tentativas devem ser versionados e auditáveis.

Continue a explorar

Correções e transparência

Se encontrar informação incorreta ou desatualizada, envie-nos a página e a fonte que devemos rever.