Rollback de base de conhecimento: voltar o índice sem derrubar o atendimento

O padrão que quase todo sistema de RAG adota no primeiro ano é o mais simples possível: existe uma coleção chamada "documentos", um job noturno lê a fonte, gera embeddings e faz upsert sobre os mesmos identificadores. Funciona muito bem enquanto tudo dá certo, e é irrecuperável no dia em que não dá. O upsert destrói o estado anterior por construção, então o rollback deixa de ser uma operação de infraestrutura e vira um reprocessamento completo, que é caro em tempo, caro em chamadas ao modelo de embedding e, o pior de tudo, lento exatamente no momento em que o sistema está errando com o cliente na frente.

Vale enumerar o que exatamente se perde, porque times costumam achar que só o texto do trecho está em jogo. Some o texto do chunk, mas também some a fronteira do chunk, que muda quando o parser muda; some o vetor, que depende do modelo e da versão dele; somem os metadados de filtro, que costumam ser reescritos por regra; e some o mapeamento entre documento de origem e trechos derivados, que é o único jeito de saber depois quais respostas foram fundamentadas em qual versão do material. Cada um desses quatro pode regredir de forma independente, e cada um exige um mecanismo de retorno diferente.

A distinção da terceira linha é a que mais causa incidente prolongado. Misturar vetores de dois modelos de embedding na mesma coleção não gera erro: gera uma busca que retorna resultados sintaticamente válidos e semanticamente aleatórios, porque distância entre vetores de espaços diferentes não significa nada. É o pior tipo de falha, porque não aparece em log, não dispara alerta de exceção e só é percebida como uma queda difusa de qualidade que o time leva dias para atribuir à causa certa.

A mudança estrutural que torna rollback trivial é parar de escrever no índice em produção e passar a construir um índice novo a cada build, identificado por uma versão, com o serviço de leitura apontando para uma versão através de um ponteiro. Publicar passa a ser mover o ponteiro; voltar passa a ser mover o ponteiro de volta. Essa é exatamente a ideia de release imutável aplicada a dados de recuperação, e ela transforma uma operação de horas numa operação de segundos.

O identificador da versão precisa carregar tudo que muda o significado do vetor. Na prática, o que funciona é um hash determinístico sobre a tupla que define a build: revisão do conteúdo de origem, identificador exato do modelo de embedding, dimensão, versão da estratégia de chunking e versão do esquema de metadados. Com esse identificador, duas builds com o mesmo conteúdo mas parsers diferentes são versões diferentes, o que é o comportamento correto, e o sistema ganha de graça a capacidade de recusar uma consulta cujo embedding foi gerado por um modelo diferente do índice apontado.

Publicacao com ponteiro (rollback = mover a seta)

  fonte de conteudo  --> build v3 --> indice kb_a1b2c3  (ativo)
                         build v2 --> indice kb_9f8e7d  (retido, quente)
                         build v1 --> indice kb_44c1aa  (retido, frio)

  ponteiro "producao" ---------------> kb_a1b2c3
                          rollback --> kb_9f8e7d   (segundos)

  regra: consulta so e servida se
    embedding_model(consulta) == embedding_model(indice apontado)

// rag/index-pointer.js
// Publicacao e rollback de base de conhecimento por ponteiro.
// O indice nunca e sobrescrito: cada build cria uma colecao nova e
// publicar/voltar e uma troca atomica de ponteiro no armazenamento de estado.

import { createHash } from 'node:crypto';

// A versao precisa cobrir tudo que muda o significado do vetor.
// Trocar o parser sem trocar o modelo ainda produz um indice incompativel
// com o anterior para fins de comparacao, entao entra no hash.
export function buildIndexVersion({
  contentRevision,
  embeddingModel,
  embeddingDimensions,
  chunkingVersion,
  metadataSchemaVersion,
}) {
  const payload = [
    contentRevision,
    embeddingModel,
    String(embeddingDimensions),
    chunkingVersion,
    metadataSchemaVersion,
  ].join('|');

  return `kb_${createHash('sha256').update(payload).digest('hex').slice(0, 12)}`;
}

export function createIndexPointer({ store, vectorDb, metrics, logger }) {
  // store: chave-valor com compare-and-set. Sem CAS, duas publicacoes
  // simultaneas podem deixar o ponteiro apontando para um indice incompleto.
  async function publish({ version, expectedCurrent, manifest }) {
    const health = await vectorDb.describe(version);

    if (!health.exists) {
      throw new Error(`indice ${version} nao existe`);
    }
    // Guarda contra a falha classica: publicar um indice que a build
    // deixou pela metade porque o job morreu no meio do upsert.
    if (health.vectorCount < manifest.expectedVectorCount) {
      throw new Error(
        `indice ${version} incompleto: ${health.vectorCount}/${manifest.expectedVectorCount}`,
      );
    }
    if (health.dimensions !== manifest.embeddingDimensions) {
      throw new Error(`dimensao divergente em ${version}`);
    }

    const swapped = await store.compareAndSet('kb:pointer:production', expectedCurrent, {
      version,
      embeddingModel: manifest.embeddingModel,
      publishedAt: new Date().toISOString(),
      previousVersion: expectedCurrent?.version ?? null,
    });

    if (!swapped) {
      throw new Error('ponteiro mudou durante a publicacao, refaca a leitura');
    }

    metrics.increment('kb.pointer.publish', { version });
    logger.info({ version, from: expectedCurrent?.version }, 'indice publicado');
    return version;
  }

  // Rollback nao reindexa nada: ele volta para a versao anterior registrada
  // no proprio ponteiro. Se essa versao ja foi coletada, falha alto em vez
  // de degradar silenciosamente para um indice qualquer.
  async function rollback({ reason }) {
    const current = await store.get('kb:pointer:production');
    const target = current?.previousVersion;

    if (!target) {
      throw new Error('sem versao anterior registrada para rollback');
    }

    const health = await vectorDb.describe(target);
    if (!health.exists) {
      throw new Error(`versao anterior ${target} nao esta mais retida`);
    }

    await store.compareAndSet('kb:pointer:production', current, {
      version: target,
      embeddingModel: health.embeddingModel,
      publishedAt: new Date().toISOString(),
      previousVersion: current.version,
      rolledBackFrom: current.version,
      reason,
    });

    metrics.increment('kb.pointer.rollback', { from: current.version, to: target });
    logger.warn({ from: current.version, to: target, reason }, 'rollback de indice');
    return target;
  }

  // A leitura carrega o modelo junto com a versao: quem gera o embedding da
  // consulta precisa usar exatamente o mesmo modelo do indice apontado.
  async function resolveForQuery() {
    const pointer = await store.get('kb:pointer:production');
    if (!pointer) throw new Error('ponteiro de producao ausente');
    return pointer;
  }

  return { publish, rollback, resolveForQuery };
}

Dois detalhes desse código merecem atenção porque são os que separam um mecanismo que funciona de um que dá a impressão de funcionar. O primeiro é a verificação de contagem de vetores antes de publicar: o modo de falha mais comum de um pipeline de indexação não é gerar vetores errados, é morrer no meio e deixar um índice com setenta por cento do material, o que produz um agente que responde bem para alguns assuntos e alucina para outros. O segundo é o compare-and-set: sem ele, uma publicação manual disparada durante o job noturno pode deixar o ponteiro apontando para um índice que já foi substituído, e o rollback vai levar o sistema para um lugar que ninguém previu.

Quando alguém pede para voltar a base de conhecimento, quase sempre está pedindo uma de duas coisas muito diferentes, e tratar as duas com o mesmo procedimento é o que faz o rollback demorar mais do que precisava. O primeiro caso é o conteúdo estar errado: alguém publicou uma versão desatualizada do manual, ou uma migração corrompeu o campo de política. O segundo é a representação estar errada: o conteúdo está correto, mas o parser novo quebrou tabelas, o chunking novo perdeu o cabeçalho da seção ou o modelo de embedding mudou e a recuperação piorou.

A distinção importa porque o rollback de conteúdo é seletivo e o de representação não é. Se apenas doze documentos da área fiscal regrediram, reindexar esses doze com o conteúdo antigo é a operação certa: rápida, barata e sem tocar no resto. Já se o problema é o modelo de embedding ou a estratégia de chunking, reindexar parcialmente é a pior escolha possível, porque cria exatamente o índice misto que produz busca semanticamente aleatória. Nesse caso a única operação correta é trocar o ponteiro inteiro para a versão anterior, mesmo que isso signifique voltar também conteúdo que estava certo.

1. Identifique se o que regrediu é o conteúdo, a representação ou a configuração de busca, porque cada um tem um procedimento diferente e misturá-los prolonga o incidente.
2. Se for configuração de busca, como pesos, topK ou reranker, faça rollback de configuração e nem toque no índice.
3. Se for conteúdo em poucos documentos, reindexe apenas esses documentos com a revisão anterior da fonte, mantendo modelo e chunking idênticos aos do índice ativo.
4. Se for chunking, parser ou modelo de embedding, troque o ponteiro para a versão anterior inteira, nunca de forma parcial.
5. Registre no ponteiro o motivo e a versão de origem, para que a próxima publicação não repita a build que causou a regressão.
6. Só depois de estabilizar, corrija a causa e publique uma versão nova, em vez de tentar consertar a versão quebrada em produção.

O quinto item costuma ser tratado como burocracia e é o que evita o incidente repetido. Sem registro de motivo, o pipeline noturno roda de novo na noite seguinte, reconstrói exatamente a mesma build defeituosa e republica sobre o rollback que alguém fez às três da manhã. Um travamento simples resolve: enquanto existir um rollback ativo sem uma causa marcada como resolvida, a publicação automática fica bloqueada e exige aprovação explícita.

Rollback rápido só é útil se a decisão de voltar for rápida, e ela não é quando o sinal de que algo piorou vem de reclamação de cliente. Entre a build ruim e a primeira reclamação costumam passar horas, e nesse intervalo o agente já respondeu errado para centenas de pessoas. O que encurta esse intervalo é um portão de qualidade entre construir o índice e publicá-lo, rodando contra a versão candidata antes de ela receber tráfego, e um conjunto pequeno de sinais em produção que comparam o comportamento depois da troca com o de antes.

O portão de recuperação é mais barato e mais sensível que um eval de resposta completa, e por isso é o que deve rodar em toda build. Ele usa um conjunto congelado de consultas com os documentos que deveriam ser recuperados, mede acerto nas primeiras posições contra o índice candidato e compara com o índice ativo. Como não chama o modelo de geração, custa quase nada e roda em segundos, o que permite executá-lo em toda reindexação e não apenas nas grandes.

// rag/index-gate.js
// Portao de qualidade entre construir o indice e publicar o ponteiro.
// Compara a versao candidata com a ativa usando um conjunto congelado de
// consultas rotuladas. Nao chama o modelo de geracao: mede so recuperacao.

const MIN_RECALL_AT_5 = 0.85;      // piso absoluto aceitavel
const MAX_RECALL_DROP = 0.03;      // queda maxima tolerada versus o ativo
const MAX_LATENCY_RATIO = 1.5;     // candidato nao pode ser 50% mais lento

export function createIndexGate({ vectorDb, embed, goldenSet, metrics, logger }) {
  async function measure({ version, embeddingModel }) {
    let hits = 0;
    let totalMs = 0;

    for (const item of goldenSet) {
      // O embedding da consulta precisa vir do mesmo modelo do indice medido,
      // senao a comparacao entre candidato e ativo nao significa nada.
      const vector = await embed(item.query, { model: embeddingModel });
      const from = Date.now();
      const results = await vectorDb.search(version, vector, { topK: 5 });
      totalMs += Date.now() - from;

      const returnedIds = new Set(results.map((r) => r.documentId));
      if (item.expectedDocumentIds.some((id) => returnedIds.has(id))) {
        hits += 1;
      }
    }

    return {
      recallAt5: hits / goldenSet.length,
      avgLatencyMs: totalMs / goldenSet.length,
    };
  }

  async function evaluate({ candidate, active }) {
    const candidateScore = await measure(candidate);
    // Sem indice ativo (primeira publicacao) so o piso absoluto se aplica.
    const activeScore = active ? await measure(active) : null;

    const reasons = [];

    if (candidateScore.recallAt5 < MIN_RECALL_AT_5) {
      reasons.push(
        `recall@5 ${candidateScore.recallAt5.toFixed(3)} abaixo do piso ${MIN_RECALL_AT_5}`,
      );
    }

    if (activeScore) {
      const drop = activeScore.recallAt5 - candidateScore.recallAt5;
      if (drop > MAX_RECALL_DROP) {
        reasons.push(`queda de recall de ${drop.toFixed(3)} versus o indice ativo`);
      }

      const ratio = candidateScore.avgLatencyMs / Math.max(activeScore.avgLatencyMs, 1);
      if (ratio > MAX_LATENCY_RATIO) {
        reasons.push(`busca ${ratio.toFixed(2)}x mais lenta que o indice ativo`);
      }
    }

    metrics.gauge('kb.gate.recall_at_5', candidateScore.recallAt5, {
      version: candidate.version,
    });

    const approved = reasons.length === 0;
    logger.info({ candidate: candidate.version, approved, reasons }, 'portao de indice');

    return { approved, reasons, candidateScore, activeScore };
  }

  return { evaluate };
}

A comparação contra o índice ativo, e não apenas contra um piso fixo, é o que dá ao portão a capacidade de pegar regressão gradual. Um piso de oitenta e cinco por cento deixa passar uma build que caiu de noventa e sete para oitenta e seis, que é exatamente o tipo de degradação que ninguém percebe até acumular três delas. Já o limite de queda relativa pega essa build no mesmo dia, e o custo de rodar as duas medições é baixo o suficiente para não ser motivo de discussão.

Em produção, o sinal mais barato e mais rápido é a taxa de recuperação vazia ou de baixa pontuação por rota, comparada com a janela equivalente antes da publicação. Quando um parser quebra tabelas ou o chunking perde cabeçalhos, a busca continua respondendo, mas a melhor pontuação por consulta cai de forma visível e a taxa de consultas sem nenhum trecho acima do limiar sobe. Esses dois números se mexem em minutos após a troca do ponteiro, muito antes de qualquer métrica de satisfação, e servem bem como gatilho de rollback automático quando cruzam o limiar por alguns minutos seguidos.

Rollback por ponteiro só funciona se a versão anterior ainda existir, e manter índices vetoriais vivos custa dinheiro real, principalmente quando o serviço cobra por memória. Por isso a política de retenção precisa ser explícita e escalonada, em vez de uma decisão implícita tomada pelo primeiro job de limpeza que alguém escreveu. A regra que costuma equilibrar bem é manter a versão anterior quente por alguns dias, uma ou duas versões mais antigas em armazenamento frio, e o manifesto de todas elas para sempre, já que o manifesto é barato e é o que permite reconstruir uma versão específica se preciso.

A escolha da janela quente deve vir de um dado que quase ninguém mede: quanto tempo o time leva, historicamente, entre publicar uma build ruim e perceber. Se a mediana desse intervalo é de dois dias, uma retenção quente de vinte e quatro horas é decorativa, porque a versão boa já terá sido coletada quando alguém finalmente identificar o problema. Medir esse intervalo é mais útil do que discutir a janela em abstrato, e normalmente o próprio ato de medir empurra o time a investir no portão de qualidade em vez de na retenção, que é a decisão mais barata das duas.

Há uma armadilha específica quando o provedor de embeddings é gerenciado e o identificador do modelo é um apelido estável em vez de uma versão fixada. Nesse cenário, o mesmo nome de modelo pode passar a produzir vetores de outra distribuição sem nenhuma mudança do seu lado, o que significa que reconstruir uma versão a partir do manifesto pode não reproduzir o índice original. É o argumento mais forte para fixar a versão exata do modelo no manifesto e para manter retenção real do índice em vez de confiar em reconstrução, especialmente para qualquer material que sustente resposta com peso contratual.

Voltar o índice conserta as respostas futuras e não faz nada pelas que já saíram, e é justamente nas respostas já entregues que costuma estar o dano real: o cliente que recebeu o prazo errado, o vendedor que citou o preço antigo, o registro que virou base de uma reclamação. Um mecanismo de rollback que para na troca do ponteiro resolve metade do problema e deixa a metade cara sem tratamento.

O que fecha esse buraco é gravar a versão do índice em cada interação, junto com os identificadores dos trechos recuperados. Com esse campo, delimitar o estrago é uma consulta: todas as conversas atendidas entre a publicação e o rollback, filtradas pelas que usaram os documentos afetados. Sem esse campo, a única alternativa é revisar por janela de tempo bruta, o que joga na fila de revisão dez vezes mais conversas do que o necessário e faz o time desistir no meio.

// rag/impact-query.js
// Delimita o impacto de uma build ruim usando a versao de indice gravada
// em cada interacao. Sem esse campo, so resta filtrar por janela de tempo
// e revisar dez vezes mais conversas do que o necessario.

export async function findAffectedConversations({ db, badVersion, affectedDocumentIds }) {
  const rows = await db.query(
    `SELECT c.conversation_id,
            c.answered_at,
            c.channel,
            c.retrieved_document_ids
       FROM agent_interactions c
      WHERE c.index_version = $1
        AND c.retrieved_document_ids && $2::text[]
      ORDER BY c.answered_at ASC`,
    [badVersion, affectedDocumentIds],
  );

  // Priorizar o que teve consequencia fora do chat: uma resposta errada que
  // virou pedido ou promessa formal precisa de contato ativo, nao de nota.
  return rows.map((row) => ({
    conversationId: row.conversation_id,
    answeredAt: row.answered_at,
    channel: row.channel,
    needsOutreach: row.retrieved_document_ids.some((id) => affectedDocumentIds.includes(id)),
  }));
}

Guardar a versão do índice na interação custa uma coluna e resolve muito mais do que rollback. É o mesmo campo que permite atribuir uma queda de qualidade no eval a uma build específica, que permite comparar duas versões de chunking com tráfego real e que responde à pergunta de auditoria mais desconfortável que existe, que é "com base em qual material o sistema afirmou isso naquele dia". Se houver um único item deste artigo para implementar antes dos outros, é esse, porque ele é barato hoje e impossível de reconstruir depois.

Vale terminar com o desconforto que esse trabalho revela. Tratar o índice como artefato versionado transforma o rollback numa operação de segundos, mas ele continua sendo uma operação que precisa de alguém decidindo, e a decisão é sempre entre voltar um conteúdo que estava certo junto com o que estava errado ou conviver com a regressão até a correção sair. Não existe procedimento que elimine essa escolha. O que a versão por ponteiro faz é tirar as três horas de reindexação do meio dela, e é exatamente essa demora que costuma empurrar times para o pior caminho, que é remendar o índice em produção enquanto o cliente espera.