Como Diagnosticar Falhas de QA em LLMs Customizados em 7 Passos

Notas do Ciclo de Release — Parte VI

Uma suíte de QA pontuada começou a sinalizar o modelo de Q&A médico de um cliente. O número principal — qualidade agregada em todas as fatias — caiu 6 pontos da noite para o dia. A equipe passou dois dias depurando o modelo. Re-executaram fine-tunes. Reverteram para a release anterior. Os números não se moveram.

Na manhã do terceiro dia, alguém percebeu que a suíte de avaliação havia sido atualizada na mesma noite em que a regressão começou. Três novos prompts de dosagem pediátrica haviam sido adicionados ao conjunto de testes, e o modelo nunca tinha visto dosagem pediátrica no treinamento. A “falha de QA” não era uma regressão de modelo. Era um evento de cobertura de fatia: a avaliação começou a perguntar sobre algo que o modelo nunca foi suposto saber.

Nos rollouts dos nossos clientes, esse é o padrão dominante. Um alerta de “falha de QA” é o sintoma. A causa é o modelo aproximadamente uma vez em sete. Nas outras seis vezes, o bug está em algum lugar a montante: no design da avaliação, na calibração do juiz, no SHA do prompt, no pipeline de pré-processamento, na versão do dataset ou no índice de recuperação. Cada uma dessas classes de bug parece idêntica vista do alerta — um número caiu — mas tem uma correção completamente diferente.

Este post é a árvore de diagnóstico que percorremos em ordem quando um alerta dispara. Seis passos que descartam causas não-modelo, antes que o sétimo passo considere o próprio modelo. Cada passo tem uma chamada de API ou consulta concreta que o responde. No momento em que você terminar os seis, ou você sabe exatamente o que corrigir, ou ganhou o direito de olhar para o modelo.

A árvore de decisão

A árvore é sequencial porque os passos vão do barato ao caro. O passo 1 é um git diff da suíte de avaliação; o passo 7 é um ciclo de fine-tune. Você quer gastar dez minutos em cada uma das seis verificações baratas antes de gastar uma semana na cara.

Passo 1 — A avaliação cobria esta fatia?

O sintoma. A qualidade agregada cai, mas a quebra por fatia mostra uma fatia despencando enquanto as outras estão estáveis. Ou — mais confuso ainda — todas as fatias caem ligeiramente, todas em quantidades similares.

O diagnóstico. Faça diff do SHA do manifesto da suíte de avaliação contra o da release anterior. Se a suíte de avaliação mudou e você não mudou o modelo, a regressão está na avaliação, não no modelo.

# Compare o SHA do manifesto da suíte de avaliação entre releases
curl https://api.divinci.ai/v1/releases/rel_a01c66 | jq '.eval_suite_sha256'
curl https://api.divinci.ai/v1/releases/rel_8f72b1 | jq '.eval_suite_sha256'
# Diferentes? Sua avaliação mudou. Audite o que foi adicionado.

A correção. Ou reverta a mudança na suíte de avaliação (se foi não intencional), ou expanda a cobertura de treinamento para corresponder à nova avaliação (se a nova fatia é uma preocupação real de produção). Não envie uma correção de regressão de modelo para um problema de cobertura de avaliação — você vai piorar o modelo no que ele já fazia bem.

Onde isso se esconde no nosso pipeline. Estágio 1 — Registro vincula o SHA da suíte de avaliação ao manifesto da release. O diagnóstico acima é apenas comparar dois manifestos. A razão pela qual o bug tomou dois dias da equipe de Q&A médico é que eles não tinham diff no nível do manifesto — estavam comparando checkpoints do modelo, não manifestos de release.

Passo 2 — O juiz está calibrado com humanos nesta fatia?

O sintoma. Uma fatia nova na suíte de avaliação tem pontuação baixa, mas a revisão humana das saídas do modelo nessa fatia as classifica como adequadas. O juiz acha que o modelo está falhando; humanos não.

O diagnóstico. Calcule o ρ de Spearman entre as avaliações do juiz LLM e uma pequena amostra avaliada por humanos (50 itens) na fatia que falha. Se ρ < 0,4, o juiz não está medindo o que humanos medem nesta fatia.

curl -X POST https://api.divinci.ai/v1/judges/<judge_id>/calibrate \
  -d '{ "slice": "pediatric-oncology-dosing", "human_ratings_csv": "..." }'
# → { "spearman_rho": 0.31, "interpretation": "judge_uncalibrated_for_slice" }

A correção. Ou selecione um modelo de juiz diferente para esta fatia, ou use uma cadeia de juízes com um árbitro. MT-Bench^[1] mostra que GPT-4-como-juiz concorda com humanos em >80% em média, mas com variância por categoria de 86% (programação) a 36–44% (escrita/humanidades). A variância é o número operativo; “bom em média” esconde fatias onde o juiz erra.

Onde isso se esconde no nosso pipeline. Estágio 2 — Gate exige um juiz calibrado por fatia. O post Calibrando o Juiz de IA documenta o procedimento. Se a fatia foi adicionada à avaliação sem um passo de calibração, você tem um gate estruturalmente não-confiável.

Passo 3 — O SHA do template do prompt bate com produção?

O sintoma. A qualidade cai, mas o model_ref e o dataset_ref estão inalterados. Nada sobre o treinamento mudou. O modelo é o mesmo modelo. E mesmo assim.

O diagnóstico. Compare o SHA do prompt_template_ref no manifesto da release que falhou contra o da release anterior. Uma edição de 38 caracteres em um prompt de sistema que “melhora a brevidade” pode mudar o comportamento downstream mais do que um retreinamento completo.

curl https://api.divinci.ai/v1/releases/rel_a01c66 | jq '.prompt_template_ref'
curl https://api.divinci.ai/v1/releases/rel_8f72b1 | jq '.prompt_template_ref'
# Diferentes? Puxe o diff. Olhe com cuidado.

A correção. Trate prompts como código. O post sobre as 10 falhas de release cobre o modo de falha de edição via dashboard — o postmortem da Mentira do Semver de Tianpan^[2] nomeia isso como o padrão de falha dominante de 2026. Se você consegue provar que o prompt mudou, você achou seu bug.

Passo 4 — O pipeline de pré-processamento bate com produção?

O sintoma. O modelo passa na avaliação local. O mesmo modelo falha na mesma avaliação em produção. Mesmo model_ref, mesmo prompt, mesmo dataset.

O diagnóstico. Puxe o SHA do preprocessing_ref do manifesto de produção e verifique que a avaliação rodou com o mesmo. O caso clássico: o treinamento normaliza espaços em branco e converte para minúsculas; a produção não. A avaliação passou pelo pré-processamento de produção; tudo conferiu. Até que alguém atualizou o pré-processamento de apenas um lado.

curl https://api.divinci.ai/v1/releases/rel_a01c66 | jq '.preprocessing_ref'
# Compare com o pré-processamento que seu harness de treinamento/avaliação realmente usou.

A correção. Containerize o pré-processamento como um artefato versionado. Referencie-o no manifesto. Recuse-se a fazer deploy se o SHA de pré-processamento do gate diferir do de produção.

Passo 5 — O SHA do dataset bate com produção?

O sintoma. As pontuações do gate-eval da release que falhou são diferentes das pontuações do gate-eval do mesmo modelo no dia anterior.

O diagnóstico. Faça diff do campo dataset_version entre as duas releases. A suíte de avaliação manteve o mesmo nome, mas o conteúdo do dataset foi atualizado e re-tagueado. Mesmo nome, SHA diferente, pontuações diferentes.

diff <(curl .../rel_a01c66 | jq '.dataset_version') \
     <(curl .../rel_8f72b1 | jq '.dataset_version')

A correção. Faça hash de conteúdo dos seus datasets. O nome do dataset não é uma versão; o SHA é.

Passo 6 — O SHA do índice de recuperação bate com produção?

O sintoma. Apenas para cargas RAG. A qualidade cai em perguntas que dependem de contexto recuperado. Perguntas de resposta direta estão inalteradas.

O diagnóstico. Puxe o SHA do retrieval_index_ref do manifesto. Compare contra o índice de recuperação da avaliação do gate. O índice RAG foi atualizado durante a noite (uma nova execução de ingestão); a avaliação do gate cacheou uma recuperação antiga; o canário de produção usou a nova.

curl https://api.divinci.ai/v1/releases/rel_a01c66 | jq '.retrieval_index_ref'

A correção. Vincule o SHA do índice de recuperação ao manifesto, exatamente como vinculamos o pré-processamento. A cadência de rotação automatizada de índice do AutoRAG torna isso especialmente digno de checar — o índice vai atualizar em você quer você tenha autorizado ou não, se você não estiver fixando-o.

Passo 7 — O modelo em si, finalmente

Seis passos adentro. A avaliação cobre a fatia. O juiz está calibrado. O SHA do prompt bate. O pré-processamento bate. O dataset bate. O índice de recuperação bate.

Agora — e somente agora — você ganhou o direito de olhar para o modelo.

O diagnóstico para este passo é uma comparação de Spearman por fatia contra a release anterior, com ambas as releases avaliadas contra o mesmo dataset fixado no manifesto, pré-processamento e recuperação. O número que você produz é um sinal limpo: uma regressão real por fatia, sem fatores de confusão a montante.

curl -X POST https://api.divinci.ai/v1/releases/<failing_id>/diff-eval \
  -d '{ "baseline_release_id": "<prior_id>", "slices": ["legal-IP-licensing"] }'
# → { "spearman_rho_failing": 0.41, "spearman_rho_baseline": 0.68, "delta": -0.27 }

Se o delta confirma uma regressão real: o auto-rollback dispara (se você já não o invocou manualmente), e o modelo que falhou é re-treinado contra um corpus expandido de cobertura de fatias. Se o gate que promoveu essa release perdeu a fatia em primeiro lugar, o gate também é o bug — capacidade 4 faltando no seu pipeline de release.

Como a distribuição realmente se parece

A formulação “1 em 7” anterior não era um recurso retórico. É aproximadamente a distribuição que vemos nos rollouts dos clientes. A cada sete alertas de QA:

As duas maiores fatias são lacuna de cobertura de avaliação e descalibração do juiz. Juntas elas respondem por metade dos alertas de QA. Nenhuma das duas é um problema de modelo. Ambas são problemas de como você mede o modelo.

O que isso não resolve

Três limitações honestas:

A distribuição é nossa, não sua. As porcentagens acima vêm do nosso conjunto de clientes e da tooling do nosso pipeline. Se você roda um tipo diferente de carga — pesada em multi-modal, pesada em orquestração de agentes, pesada em geração single-shot — sua distribuição vai parecer diferente. A ordem do diagnóstico deve continuar valendo; os números por trás de cada passo não vão.

A “lacuna de cobertura de avaliação” do Passo 1 é a mais difícil de corrigir. Adicionar a fatia faltante ao seu corpus de treinamento, construir um juiz calibrado para ela e re-executar o canário é em si um projeto de várias semanas. O diagnóstico é rápido; a remediação não.

Uma regressão real pode pegar carona em um bug não-modelo. Os casos em que você tem tanto drift de prompt QUANTO uma regressão real de modelo são os piores, porque o passo 3 encontra o drift de prompt, você o corrige, e o alerta dispara de novo. A ordem de diagnóstico neste post lida com eles mas adiciona tempo decorrido. Não há atalho para “o bug estava em dois lugares ao mesmo tempo.”

FAQ

Por que meu LLM produz saídas diferentes para prompts similares?

A sensibilidade a prompt é real, mas nem sempre é a causa de um alerta de QA — às vezes é um sintoma de um bug a montante. Percorra o diagnóstico. Se o SHA do template do prompt bate e o pré-processamento bate e o dataset bate, então sim — o modelo tem grande variância nessa fatia e você precisa de um caminho de decodificação mais determinístico ou de um juiz diferente. Se algo a montante mudou, corrija isso primeiro.

Com que frequência você deve re-avaliar seus benchmarks de LLM?

Re-avalie o conteúdo do benchmark sempre que a forma do tráfego de uma fatia de produção mudar de modo significativo. Re-avalie a calibração do juiz do benchmark trimestralmente, no mínimo — modelos de juiz derivam mais rápido do que se imagina. A maior fonte de falsos alertas de QA é um benchmark cuja última validação foi há 18 meses e que agora mede algo que sua produção já não faz mais.

O que causa alucinações em modelos de linguagem customizados?

Alucinações têm múltiplas causas a montante — falhas de recuperação (passo 6 na árvore acima), lacunas de cobertura de treinamento (passo 1, indiretamente) e problemas no caminho de decodificação (uma preocupação real do modelo no passo 7). O AutoRAG endereça as causas do lado da recuperação vinculando o índice de recuperação ao manifesto da release e re-fixando-o em cada release. As outras duas exigem correções de nível de pipeline a montante do modelo.

Como saber se seus dados de treinamento são o problema?

Se o SHA do dataset na release que falhou bate com o SHA do dataset na release anterior boa (passo 5 da árvore), os dados não são a causa imediata. Se diferem, você o encontrou. A pergunta mais difícil — “o dataset está completo para a cobertura de fatias da nossa produção?” — é o que o passo 1 testa. Um dataset completo para a avaliação mas incompleto para o tráfego de produção é um problema de cobertura de fatias.

Você consegue corrigir falhas de QA sem retreinar o modelo inteiro?

Sim — seis em cada sete vezes, a correção não é um retreinamento. Os passos 1–6 da árvore têm correções que não tocam o modelo: atualizar a avaliação, recalibrar o juiz, re-registrar o SHA do prompt, corrigir o pré-processamento, re-fixar o dataset ou re-fixar o índice de recuperação. Retreinar é o passo 7, a correção mais cara, reservada para regressões reais de modelo. A trilha de auditoria do pipeline de release te permite fazer essas correções a montante com a mesma disciplina de proveniência que você usaria para uma mudança de modelo.

References

1. LLM-as-judge per-category variance. Zheng et al., Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena (NeurIPS 2023). >80% overall GPT-4-vs-human agreement with per-category variance from coding (86%) down to writing (36–44%). Anchor for step 2 — why judge calibration has to be measured per slice rather than assumed from a published headline number.
2. The Semver Lie. Tianpan — The Semver Lie: how an LLM minor update breaks production (April 2026). The dominant 2026 failure-mode writeup. Names dashboard-edit prompt drift as the most-cited cause of production LLM incidents. Anchor for step 3.
3. NIST AI RMF — Measure function. NIST AI Risk Management Framework. The "Measure" function explicitly covers benchmark-validity and evaluation-coverage as part of governance, not as a separate engineering concern. Cited as the institutional anchor for treating eval design as the first diagnostic step.
4. RAGAS — retrieval-augmented generation evaluation. Es et al., RAGAS: Automated Evaluation of Retrieval Augmented Generation (arXiv:2309.15217). The reference framework for RAG-side evaluation. Anchor for step 6 — separating retrieval failures from generation failures requires a RAG-aware eval discipline.
5. Internal — root-cause distribution across customer rollouts. The percentages in the pie chart are our internal observation across Divinci customer rollouts, not from a controlled benchmark. Your distribution will vary by workload type, fine-tune cadence, and team discipline. The relative ordering (steps 1–2 dominating) is stable across the cohort we've measured; the exact percentages are not portable to your environment without your own data.
6. The four-stage release pipeline. How to Build an LLM CI/CD Pipeline With Divinci AI. Each diagnostic step in this post corresponds to a manifest field bound at Stage 1 — Register. Without the manifest discipline upstream, the diagnostic loses its grip; you can't diff what you didn't bind.

Próximo da série: Testes de Regressão Automatizados para LLMs Customizados em 2026. Este post é sobre diagnóstico após um alerta de QA disparar. O próximo é sobre a disciplina de teste de regressão que conduziu o alerta em primeiro lugar — o que colocar na avaliação, como mantê-la honesta e o que fazer quando o teste de regressão começa a discordar do seu juiz.