Contratos para aplicações de IA: detectar mudanças de modelo, SDK ou ferramentas antes da produção

Uma demonstração que responde não comprova compatibilidade

Em uma aplicação de IA, uma mudança pode não produzir um erro de transporte e, ainda assim, quebrar o produto. O modelo pode continuar devolvendo texto útil para uma pessoa, mas omitir um campo consumido por um serviço posterior, escolher uma ferramenta não permitida, alterar o significado prático de um rótulo ou fundamentar uma conclusão em um trecho recuperado que não a sustenta. Por isso, verificar que “continua respondendo” não equivale a verificar que preserva o comportamento operacional esperado.

Um contrato é uma especificação verificável das propriedades que precisam ser mantidas em uma fronteira concreta do fluxo. Não é uma promessa de que o modelo sempre redigirá a mesma frase, nem uma tentativa de eliminar a variabilidade generativa. Ele define quais entradas são aceitas, que forma a saída deve ter, quais invariantes de negócio não podem ser violadas, quais ações são autorizadas e quais evidências são necessárias antes de afirmar algo ou executar uma operação.

A unidade de análise deve ser a mudança incompatível concreta. Ela pode ser uma substituição de modelo, uma atualização do SDK, uma modificação no prompt de sistema, uma alteração de esquema, uma nova definição de ferramenta ou uma política atualizada do provedor. O objetivo é responder antes de promover a mudança: o contrato foi preservado? A degradação está dentro de um limite aceito? É preciso adaptar o fluxo? Ou a mudança deve ser bloqueada?

Os contratos complementam as avaliações agregadas de qualidade, mas resolvem outro problema. Uma avaliação pode indicar que a utilidade média continua alta mesmo que um em cada cem casos emita uma ordem de cancelamento sem confirmação. Esse caso isolado é uma incompatibilidade crítica se a ação tem efeitos externos. Da mesma forma, JSON válido não prova que um argumento seja seguro, que uma citação corresponda à fonte ou que uma classificação preserve seu significado.

Inventário de fronteiras e dependências

Antes de escrever testes, desenhe o percurso completo de um caso de usuário. Uma fronteira existe quando um componente entrega uma representação que outro componente interpreta: a solicitação enviada ao provedor, o identificador do modelo, a resposta do modelo, o adaptador do SDK, o recuperador de contexto, a chamada a uma ferramenta, o sistema de destino e a ação externa. Cada fronteira pode ter um contrato diferente e um proprietário diferente.

O inventário deve identificar versões e configurações efetivas, não apenas nomes genéricos. Registre o modelo ou snapshot solicitado, a versão do SDK e da API quando aplicável, o prompt de sistema, os parâmetros de geração, o esquema de saída, a lista de ferramentas, a definição de permissões, a versão do índice de recuperação e os adaptadores internos. Sem essas informações, será difícil atribuir posteriormente uma falha a uma causa concreta.

Nem todas as fronteiras exigem o mesmo tipo de asserção. A solicitação ao modelo exige verificar parâmetros aceitos e valores normalizados. Uma saída estruturada precisa validar o esquema e os campos obrigatórios. A recuperação precisa verificar procedência, atualidade e suficiência de evidência. As ferramentas exigem, além da sintaxe, autorização e simulação de efeitos. O sistema de destino precisa de idempotência, controle transacional ou compensação, conforme o risco.

A documentação dos provedores indica que os ciclos de vida dos modelos e as interfaces podem mudar. Em particular, retiradas de modelos e determinadas alterações de parâmetros podem transformar solicitações antes válidas em erros. Isso torna necessário testar uma migração como mudança de dependência, mesmo que o código de negócio não tenha sido alterado.

O que deve se transformar em contrato

Comece pelos elementos deterministas. Bons candidatos são tipos, campos obrigatórios, limites numéricos, enumerações, identificadores, presença de uma fonte, formato de datas, ferramentas permitidas e regras de autorização. Também são candidatas as invariantes de negócio: um reembolso não pode superar o valor pago, um agente não pode modificar dados de outro cliente e uma operação que exige aprovação humana não pode ser executada sem esse estado.

Em seguida, adicione restrições operacionais. Defina um orçamento de latência e custo por caso, com uma medição especificada: por exemplo, um percentil sobre uma amostra controlada, e não uma impressão isolada. Estabeleça máximos de tentativas, ferramentas por execução, documentos recuperados e tamanho de contexto. Um aumento pode ser tecnicamente compatível e, ainda assim, inaceitável para o produto; o contrato deve separar esses dois planos.

Os rótulos merecem um tratamento semântico explícito. Se uma saída contém `risco_alto`, o contrato precisa explicar quais fatos o justificam e quais consequências ele aciona. Uma coincidência literal do rótulo não basta se o critério de atribuição mudou. Use casos de fronteira com anotação humana e asserções sobre as condições observáveis que devem levar a cada classe.

Em respostas com evidência, o contrato deve diferenciar entre ter uma citação e estar respaldado por ela. No mínimo, verifique que a fonte recuperada é admissível para o domínio, que sua data atende à política de atualidade, que a passagem contém evidência suficiente para a afirmação e que o fluxo declara insuficiência quando falta base. A atribuição não deve se tornar uma decoração gerada no final do processo.

Classificar a mudança antes de discutir os resultados

Classifique cada modificação proposta em quatro grupos. Uma mudança compatível preserva todos os contratos aplicáveis. Uma mudança compatível com degradação aceitável não cumpre um objetivo não crítico, mas permanece dentro de um limite aprovado, como uma variação limitada de latência. Uma mudança incompatível viola uma propriedade obrigatória, como uma permissão de ação ou um campo exigido. Uma mudança desconhecida é aquela para a qual faltam casos, fixtures, telemetria ou uma definição suficiente para concluir.

A classificação não deve depender de quem propõe a mudança nem de uma demonstração parecer convincente. Ela deve estar vinculada a regras de promoção previamente publicadas. Se a equipe descobrir que uma regra já não reflete a necessidade do produto, pode modificar o contrato, mas essa decisão deve ser explícita, revisada e versionada; não deve ficar implicitamente aceita por um teste que falhou.

Fixar uma versão concreta do modelo reduz uma fonte de variação e facilita reproduzir os resultados. Aliases ou modelos sujeitos a atualizações podem modificar o comportamento sem que o código do cliente mude. A documentação da OpenAI recomenda fixar versões de modelo e executar avaliações porque os snapshots podem variar no comportamento de prompting. Portanto, um contrato deve registrar tanto o identificador solicitado quanto a política de atualização aceita pela equipe.

Projetar uma bateria mínima que seja diagnóstica

Uma bateria útil não precisa tentar representar toda conversa humana possível. Ela deve conter casos fixos que cubram os caminhos críticos, os casos de borda e os contraexemplos históricos. Cada caso deve declarar entrada, estado inicial, configuração do fluxo, resultado esperado, severidade e asserções. Mantenha os dados de teste sem informações sensíveis e assegure que possam ser executados repetidamente.

Use fixtures para as ferramentas e dependências externas. Uma fixture deve retornar estados controlados, registrar as chamadas e evitar efeitos reais. Assim, você pode verificar que o modelo escolheu a ferramenta correta, que os argumentos foram interpretados pelo adaptador e que não houve tentativa de executar uma alternativa proibida. Um ambiente de testes que chama a produção não é uma fixture: ele mistura compatibilidade com risco operacional.

Snapshots são adequados para artefatos deliberadamente estáveis, como uma solicitação normalizada, um esquema de ferramenta ou uma lista ordenada de identificadores recuperados. Eles são frágeis para uma prosa completa produzida por um modelo. Para linguagem natural, prefira asserções semânticas delimitadas: presença de fatos obrigatórios, ausência de afirmações proibidas, correspondência com a evidência e comportamento de abstenção diante de dados insuficientes.

Algumas medidas não são deterministas. A taxa de sucesso, a distribuição de latência e a frequência de uma classificação podem exigir várias execuções, uma amostra fixa e um intervalo ou tolerância predefinidos. Não transforme uma pequena diferença estatística em uma regressão crítica, nem permita que a incerteza estatística esconda uma violação determinista de segurança.

Saídas estruturadas e chamadas de ferramentas: esquema não é autorização

Uma saída estruturada deve ser validada duas vezes: primeiro contra sua representação e depois contra seu significado. A primeira validação verifica JSON, tipos, campos obrigatórios, intervalos e valores permitidos. A segunda verifica relações entre campos e estado externo. Por exemplo, que uma data de início seja anterior à data de término, que o valor pertença ao pedido indicado e que um código de motivo seja coerente com o caso.

As interfaces de ferramentas dos provedores podem descrever parâmetros por meio de JSON Schema e oferecer modos estritos de adesão ao esquema. Isso é uma ajuda relevante para reduzir argumentos malformados, mas não substitui a validação da aplicação. Um argumento pode estar corretamente tipado e indicar uma conta errada, uma operação fora da política ou uma ação que exige aprovação. O executor deve aplicar autorização, pré-condições e limites antes de produzir efeitos.

O contrato também deve fixar a ordem. Em um fluxo que consulta elegibilidade e depois emite um reembolso, não aceite uma sequência invertida só porque as duas chamadas são válidas individualmente. Registre as ferramentas permitidas por etapa, o máximo de invocações, os argumentos normalizados, a resposta da fixture e a ausência de chamadas não autorizadas. Isso permite detectar mudanças nas quais o modelo parece resolver a tarefa, mas toma um atalho operacional perigoso.

Se o provedor modificar o modelo, a definição da ferramenta ou o adaptador do SDK, execute as mesmas fixtures. Um teste de JSON válido detectaria um objeto malformado; esta bateria pode detectar que uma ferramenta diferente foi escolhida, que a consulta prévia foi omitida ou que o sistema tentou repetir uma ação já confirmada.

Contratos para recuperação e respostas com fontes

Em um fluxo RAG, o contrato começa antes da redação. Estabeleça quais coleções o caso pode consultar, quais metadados mínimos cada trecho deve retornar e como a atualidade é resolvida. Se uma resposta depende de uma política atual, um documento antigo pode ser tecnicamente recuperável, mas inadmissível para fundamentá-la. O teste deve inspecionar a procedência, não apenas o texto final.

Defina uma evidência mínima para cada tipo de afirmação. Uma conclusão normativa pode exigir uma passagem explícita de uma fonte autorizada; uma síntese pode exigir vários trechos coerentes; um número pode exigir correspondência exata com o documento. Se os resultados não satisfizerem essa condição, o comportamento correto pode ser pedir mais contexto, declarar incerteza ou não responder à afirmação. Essa abstenção é uma saída contratual, e não um erro de experiência por padrão.

Teste contradições e contexto insuficiente. Inclua fixtures com documentos desatualizados, fontes de menor autoridade, trechos que mencionam termos semelhantes e conjuntos que contêm informação conflitante. O contrato deve indicar se o fluxo prioriza uma fonte, expõe o conflito ou encaminha para revisão. Não é razoável afirmar que uma citação está correta apenas porque compartilha palavras com a resposta.

Conserve, para cada execução, o conjunto de documentos candidatos, os selecionados, seus identificadores e metadados relevantes, a versão do índice, a consulta transformada e o resultado final. Essa telemetria permite distinguir se o descumprimento surgiu na recuperação, na interpretação do modelo ou na representação da evidência.

Integração em CI/CD, decisão e reversão

Execute a bateria quando qualquer um dos artefatos registrados mudar: versão de modelo, SDK, prompt de sistema, parâmetros, esquema, definição de ferramentas, recuperador, índice ou política. A mudança deve produzir um manifesto comparável que inclua versões, hashes ou identificadores internos, resultados por caso, duração, consumo medido quando disponível e rastros de ferramentas e recuperação. Evite que uma atualização implícita fique fora do controle de mudanças.

Organize as portas de CI por severidade. As asserções críticas, como autorizações, efeitos não permitidos, isolamento entre clientes ou evidência obrigatória, devem bloquear. As de severidade alta normalmente bloqueiam até existir uma adaptação aprovada. Métricas de qualidade ou desempenho com tolerância podem exigir revisão. Um resultado desconhecido não deve se tornar automaticamente compatível por falta de sinal.

Quando um contrato falhar, primeiro localize a fronteira. Compare a solicitação normalizada, o artefato do modelo, a resposta bruta, a adaptação do SDK, os documentos recuperados e o registro das ferramentas. Em seguida, escolha entre corrigir a integração, adaptar o contrato porque uma necessidade legítima mudou, versionar o fluxo para manter os dois comportamentos ou rejeitar a mudança. Documente por que a decisão é válida e quem a aprovou.

A reversão deve ser projetada antes da promoção. Conserve a configuração anterior que permita restaurar um modelo, prompt, esquema, ferramentas e adaptadores compatíveis. Se o provedor retirar uma versão, talvez não exista uma reversão exata; nesse caso, a alternativa é um fluxo versionado com adaptação testada. As políticas de retirada publicadas pelos provedores são mais uma razão para planejar migrações antes da data-limite, e não depois de detectar um incidente.

Modelo de manifesto de contrato por fluxo

Um manifesto breve transforma a intenção em um artefato revisável. Ele deve viver ao lado do fluxo e ser alterado pelo mesmo processo de revisão aplicado ao código. Não precisa conter segredos nem todas as conversas de teste; deve apontar para identificadores internos de fixtures e definir com precisão quais propriedades governa.

Inclua: nome e finalidade do fluxo; proprietário técnico e de produto; versão do contrato; identificadores de modelo, SDK e configurações; prompt ou referência à sua versão; esquema de saída; ferramentas permitidas e permissões; dependências de recuperação; lista de casos; limites de desempenho e custo; severidade de cada regra; política de promoção; telemetria exigida; estratégia de reversão; e data de revisão. Se uma regra não tiver proprietário ou critério de falha, ela ainda não é um contrato operacional.

O modelo não elimina o julgamento técnico. As fontes disponíveis documentam mecanismos de versionamento, retirada, esquemas e uso estrito de ferramentas, mas não podem decidir qual evidência é suficiente para seu domínio nem qual ação exige aprovação humana. Essas decisões cabem à equipe responsável e devem ser formuladas como políticas verificáveis. A vantagem do manifesto é obrigar que elas se tornem visíveis antes que uma atualização as contradiga.

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.