Saídas estruturadas com IA: como validar dados antes de os guardar ou agir

Um formato processável não garante dados corretos

Uma saída estruturada é uma resposta de um modelo organizada para que uma aplicação a possa interpretar de forma previsível: por exemplo, um objeto JSON com campos e tipos definidos. Pode ser usada para extrair dados de documentos, classificar pedidos ou preparar informações para outro componente. A sua principal vantagem é reduzir a ambiguidade do formato; por si só, não transforma o conteúdo gerado num facto comprovado.

Convém separar quatro perguntas. É possível analisar a resposta como JSON? Contém os campos e os tipos acordados? Os valores são coerentes entre si e com as informações de origem? É permitido utilizá-la para o fim previsto? Uma resposta pode passar pelas primeiras verificações e falhar em qualquer uma das seguintes. O facto de um objeto incluir uma data no formato esperado não prova que essa data apareça no documento; incluir uma categoria válida não prova que a classificação esteja correta.

Esta distinção também ajuda a escolher o mecanismo de saída. Um modo JSON ou uma geração restringida por esquema destinam-se a produzir uma resposta final com uma determinada forma. Uma chamada a ferramentas, por sua vez, apresenta argumentos para que a aplicação decida se executa uma operação. Argumentos bem formados não autorizam automaticamente essa operação: a execução continua sob o controlo do sistema que integra o modelo.

O foco deste guia é o contrato de dados que se verifica em cada execução. Não substitui a gestão de alterações de modelos, SDKs ou ferramentas, que exige controlar a compatibilidade entre versões. Mesmo que a API não tenha mudado, uma entrada ambígua, um documento incompleto ou uma interpretação errada podem produzir um resultado que não deve ser guardado como confirmado.

Defina o contrato antes de escrever o prompt

Comece pelo uso que receberá a resposta, não por uma lista de campos que pareça conveniente para o modelo. Se outro sistema tiver de guardar o resultado, especifique o que cada campo representa, que tipo de valor contém e o que a aplicação fará com ele. Um contrato útil reduz as interpretações divergentes entre quem gera a resposta e quem a consome.

Para cada campo, decida se é obrigatório, opcional ou se pode ser nulo. Não use uma cadeia vazia, um valor fictício ou o número zero como substituto universal de «desconhecido»: esses valores podem ser confundidos com informações reais. Defina também as unidades — por exemplo, se um montante está expresso numa moeda específica —, os formatos de data, os limites aceitáveis e as enumerações permitidas. Se houver categorias, indique o que cada uma significa e o que fazer quando nenhuma se adequa.

As regras de negócio vão muitas vezes além dos tipos. Um esquema pode permitir que dois montantes sejam números, mas a aplicação pode exigir que o total corresponda à soma das linhas dentro de uma tolerância definida. Pode aceitar que um nível de confiança seja um número, sem que isso estabeleça um limiar adequado para confirmar um dado. Mantenha essas regras explícitas e não parta do princípio de que o modelo as aplicará sempre.

O padrão JSON Schema permite descrever estruturas e restrições, mas cada canal de um fornecedor pode admitir apenas um subconjunto das suas capacidades. Antes de depender de uma palavra-chave específica, verifique a documentação atual do modelo e do modo de saída escolhido. Quando uma restrição não estiver disponível nesse canal, valide-a na aplicação; não a elimine silenciosamente nem parta do princípio de que o modelo a respeitará apenas por constar das instruções do prompt.

Escolha o canal de acordo com o resultado pretendido

A saída estruturada final é adequada quando a aplicação precisa de receber dados organizados como resposta. O modo JSON pode orientar a forma geral; a geração restringida por esquema pode impor restrições adicionais, se o fornecedor, o modelo e o canal as suportarem. Nenhuma destas opções garante a veracidade em todos os casos, nem elimina a necessidade de validar a resposta recebida.

A chamada a ferramentas serve para propor argumentos destinados a uma função conhecida pela aplicação. O fluxo não termina quando esses argumentos são recebidos: o sistema inspeciona-os, decide se os pode executar e, se for caso disso, realiza a operação. Convém manter essa separação visível na conceção. Um campo como «enviar_pagamento» não deve funcionar como uma instrução executada apenas por ter sido produzido pelo modelo.

Antes de colocar uma integração em produção, verifique como o canal representa resultados normais, respostas incompletas e recusas. Esses estados não devem ser tratados como objetos válidos apenas porque surgem durante uma transmissão ou podem ser parcialmente convertidos em texto. Em respostas transmitidas por partes, aguarde até dispor de um resultado final identificável antes de tomar uma decisão de negócio.

Se uma restrição do esquema não for compatível, adote uma alternativa explícita: valide essa restrição localmente, simplifique o contrato sem perder o controlo essencial ou mude para um canal compatível. Registe a diferença. Um contrato que parece rigoroso no prompt, mas não é aplicado pelo canal, pode criar uma falsa sensação de segurança.

Valide por camadas, não com uma única verificação

A primeira camada é o estado da resposta: determine se recebeu uma resposta final processável ou se o fornecedor indicou uma recusa, uma interrupção ou uma resposta incompleta. Se o resultado estiver truncado ou ainda não tiver terminado, não o aceite parcialmente, salvo se o produto tiver definido e testado expressamente esse comportamento.

A segunda camada é a análise sintática e a estrutura. Verifique se o texto pode ser interpretado no formato esperado, se o elemento de raiz tem o tipo acordado e se os campos, tipos, valores permitidos e restrições aplicáveis são válidos. Não omita o tratamento de erros de análise nem converta automaticamente valores de forma ambígua — como texto em número — sem uma regra documentada.

A terceira camada analisa o significado e as relações entre campos. Verifique intervalos, consistência, combinações incompatíveis e condições de negócio. A quarta compara a proposta com a entrada original: uma fatura, um ticket ou um pedido. Sempre que possível, confirme os dados relevantes no documento ou num registo autorizado. A quinta decide se a utilização é permitida: apresentar uma sugestão não tem o mesmo efeito que alterar uma conta ou executar uma operação externa.

Mantenha o valor proposto separado do valor confirmado. Se um campo precisar de revisão, a interface e o armazenamento devem conseguir representá-lo como pendente ou não verificado. Substituir as evidências originais por uma extração duvidosa torna mais difícil corrigir o erro e reconstruir o motivo de uma decisão.

Três percursos práticos

Os exemplos seguintes mostram como a mesma conceção distingue a forma da resposta da sua aceitação. Os campos são ilustrativos: uma implementação real deve ajustá-los aos seus documentos, regras contabilísticas, taxonomia e controlos de acesso.

blocks

Responda às falhas de forma controlada

Nem todas as falhas exigem a mesma resposta. Um erro de formato pode permitir uma nova geração com instruções mais específicas. Uma resposta incompleta pode exigir um novo pedido ou a interrupção do processo. Uma contradição com a fonte pode precisar de revisão humana. A falta de autorização deve bloquear a ação, não desencadear uma nova tentativa destinada a obter uma resposta mais conveniente.

Defina antecipadamente quando aceitar, tentar novamente, colocar em quarentena e rejeitar. Limite as novas tentativas e guarde o resultado falhado para poder compreender o que aconteceu. Se o sistema voltar a tentar, não acumule respostas incompatíveis nem selecione simplesmente a que parecer mais completa. A nova tentativa deve ter um objetivo concreto — por exemplo, corrigir um campo em falta — e passar novamente pelas mesmas validações.

Evite correções silenciosas que possam transformar uma falha visível num dado aparentemente fiável. Normalizar espaços ou uma representação inequívoca pode ser seguro se estiver documentado; inventar um campo em falta, escolher entre dois montantes contraditórios ou ajustar uma categoria para que passe uma regra não é. Preserve informação suficiente para distinguir o valor original do valor normalizado.

Teste e registe o fluxo completo

Um teste útil inclui exemplos comuns e casos-limite: campos em falta, valores nulos, valores fora do intervalo, documentos pouco nítidos ou contraditórios, categorias que não se enquadram, respostas incompletas e pedidos que excedem as permissões disponíveis. Teste também cada etapa separadamente. Assim, poderá distinguir uma falha do canal de geração de um erro do validador ou de uma regra de negócio demasiado restritiva.

Meça a proporção de respostas utilizáveis sem intervenção, os erros por campo, as contradições detetadas, as recusas, as novas tentativas e os casos enviados para revisão. Uma elevada taxa de conformidade com o esquema não equivale a uma elevada taxa de correção semântica. Mantenha essas métricas separadas e analise uma amostra dos resultados aceites, comparando-os com a fonte original.

Para depurar sem armazenar dados desnecessários, conserve a versão do esquema, a identificação do canal e do modelo quando for relevante, o estado final da resposta, o resultado de cada camada de validação e a decisão posterior. Registe a entrada ou uma referência segura a ela apenas quando a política de dados o permitir. Evite guardar informações sensíveis por predefinição se bastarem uma referência, um resumo técnico ou um indicador de erro.

Faça o controlo de versões do contrato e classifique as alterações. Acrescentar um campo opcional pode ser compatível com consumidores preparados para o ignorar; alterar o tipo de um campo, mudar o significado de uma categoria ou tornar obrigatório um campo opcional pode causar incompatibilidades. Teste os consumidores e as migrações antes de implementar alterações, e conserve registos suficientes para saber que versão produziu cada dado.

Critério final: aceite apenas o que foi verificado para o uso pretendido

A decisão de aceitar uma saída depende do seu destino. Um rascunho apresentado a uma pessoa pode tolerar incerteza, desde que esteja claramente identificado; um dado contabilístico confirmado ou uma operação externa exige controlos mais rigorosos. Não há um único esquema que resolva estas diferenças: o contrato descreve a forma, as regras de negócio verificam o significado e as permissões regulam a ação.

Antes de iniciar o fluxo, certifique-se de que consegue responder a estas perguntas: o que é validado, onde é validado, que evidências sustentam cada valor, o que acontece se uma verificação falhar e quem pode autorizar a etapa seguinte. Se a aplicação não conseguir distinguir entre uma proposta, um dado verificado e uma ação aprovada, ainda não está pronta para confiar na saída.

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.