Controle de versão de documentos para base de conhecimento de IA

Controle de versão de documentos para base de conhecimento de IA significa dar a cada documento uma identidade estável, um número de versão, uma data de vigência e um status. Depois, o agente passa a buscar apenas documentos marcados como vigentes, a menos que alguém pergunte sobre o passado. As regras precisam estar nos metadados e no filtro de busca, não no bom senso do agente. Com isso, o agente cita a versão exata que usou, e uma pessoa confere a resposta em segundos.

Principais pontos

• Separe a identidade do documento da sua versão, para que o sistema saiba que dois arquivos são o mesmo documento em momentos diferentes.
• Dê a cada versão um status (rascunho, agendada, vigente, substituída ou arquivada) e filtre por ele antes que o agente veja qualquer texto.
• Registre a data de vigência, a data de revisão e a indicação da versão substituída, sempre em formato sem ambiguidade.
• Aposente uma versão mudando seu status e removendo suas cópias, não apagando o histórico. As versões antigas continuam disponíveis para perguntas sobre o passado.
• Faça o agente citar título, versão e data de vigência, e teste-o com perguntas cuja resposta correta mudou entre versões.

Por que o agente de IA cita a versão errada?

A maioria das bases de conhecimento cresce por acúmulo. Uma tabela de preços ganha uma cópia chamada final, depois outra chamada final-revisada, depois uma chamada final-novo, e todas continuam na pasta compartilhada. As pessoas se viram porque carregam contexto: lembram quem atualizou o arquivo na semana passada ou percebem que o mais antigo parece defasado. O agente não tem nenhuma dessas pistas. Ele enxerga trechos de texto e mais nada.

Há também uma razão mecânica. Sistemas de busca costumam ranquear trechos pela proximidade de sentido com a pergunta, não por data ou autoridade. A versão antiga e a nova de uma mesma política têm sentido quase idêntico, então as duas pontuam alto. A diferença entre elas geralmente é uma única frase, e é justamente essa frase que o cliente perguntou.

Na prática, isso produz três falhas recorrentes:

• As duas versões são recuperadas e o agente mistura tudo numa resposta que não corresponde a nenhuma.
• A versão antiga é recuperada porque é mais longa, mais clara ou mais bem formatada, e acaba vencendo.
• A versão certa é recuperada, mas citada sem data, e ninguém consegue saber qual delas o agente usou.

Esse problema é parente próximo do descrito em como evitar que contexto antigo engane seu agente de IA, mas começa antes, nos próprios arquivos, sem que nenhuma memória esteja envolvida. Corrigir na origem custa menos do que remediar depois.

Quais metadados todo documento deve ter?

O controle de versão começa com um conjunto pequeno e fixo de campos que acompanham cada documento. Eles podem ficar em um bloco de cabeçalho, em uma planilha de registro ou nas propriedades da wiki, desde que a camada de busca consiga lê-los e filtrar por eles. Os campos abaixo bastam para a maioria das empresas.

• ID do documento: um nome curto e estável, como termos-de-cancelamento. Nunca muda e nunca é reaproveitado para outro documento.
• Título: o nome legível, idêntico em todas as versões.
• Versão: um número maior e um menor, por exemplo 3.0 ou 3.1.
• Status: rascunho, agendada, vigente, substituída ou arquivada.
• Vigente desde: a data em que esta versão passa a valer.
• Vigente até: vazio enquanto a versão for a atual, preenchido quando ela for aposentada.
• Revisar até: a data em que o responsável deve confirmar que o documento continua correto.
• Substitui: a versão que esta substitui.
• Escopo: os clientes, regiões ou times a que a versão se aplica.
• Responsável: uma pessoa nomeada que pode aprovar mudanças e aposentar versões.

O campo de responsável pesa mais do que parece. Uma versão sem responsável não tem ninguém que possa aposentá-la, e ela vai continuar vigente em silêncio por anos. A rotina para definir responsáveis e revisar documentos está em manutenção da base de conhecimento de IA: responsáveis e rotina, e combina bem com os campos acima.

Como nomear e datar as versões?

Regras de nomenclatura parecem triviais até que duas pessoas as apliquem de maneiras diferentes. Mantenha-as curtas o bastante para que ninguém precise consultá-las.

• Nunca use as palavras final, novo, último ou cópia em um nome de arquivo. Elas descrevem um momento, e o momento passa.
• Monte todo nome com o ID estável, a versão e a data de vigência, por exemplo termos-de-cancelamento_v3-0_a-partir-de-AAAA-MM-DD.
• Escreva as datas com ano primeiro, depois mês, depois dia. Elas ordenam corretamente e não se confundem entre formatos regionais.
• Mude o número maior sempre que uma resposta puder mudar: prazo de aviso, regra de elegibilidade, limite, estrutura de taxas. Mude o número menor apenas em edições que não alteram nenhuma resposta, como erros de digitação ou formatação.
• Nunca edite uma versão publicada no próprio arquivo. Qualquer edição, por menor que seja, gera uma nova versão menor com data própria.

A distinção entre número maior e menor dá um sinal útil. Quando uma versão maior é publicada, o responsável deve rodar as perguntas de teste descritas mais adiante neste artigo. Uma versão menor exige só uma checagem rápida para ver se nada mais mudou.

Mantenha separadas duas datas: a da publicação e a de início da vigência. Um novo conjunto de termos pode ser aprovado semanas antes de valer. Nesse intervalo, o status dele é agendada, e a versão antiga continua vigente. Na data de vigência, os status se invertem. Essa troca deve ser automática, ou ser uma tarefa nomeada do responsável, e não algo que as pessoas lembram de fazer. O agente também precisa saber a data de hoje, senão não consegue compará-la com as datas de vigência.

Como aposentar uma versão sem perder o histórico?

A aposentadoria é onde a maioria dos esquemas de versionamento falha, porque parece tarefa de arrumação. Trate-a como uma mudança de status, com significado claro em cada etapa.

• Rascunho: visível apenas para os autores. Nunca indexado para o agente em produção.
• Agendada: aprovada, mas ainda sem efeito. O agente pode mencioná-la como mudança futura se perguntarem o que vai mudar.
• Vigente: a resposta. Existe exatamente uma versão vigente por ID de documento e escopo.
• Substituída: trocada por uma versão mais nova. Fica fora da busca padrão, mas disponível quando a pergunta cita uma data passada ou pede o que mudou.
• Arquivada: guardada para registro, totalmente fora do índice do agente.

Não apague versões substituídas. Disputas, auditorias e perguntas comuns de clientes muitas vezes dependem do que valia em determinado momento, como os termos em vigor quando o cliente assinou. Se o texto antigo sumiu, ninguém consegue responder, nem pessoa nem agente.

A outra metade da aposentadoria são as cópias. Uma versão raramente está aposentada de fato até que todas as suas cópias estejam. Procure anexos em modelos de e-mail, mensagens fixadas em chats, PDFs exportados, textos colados em prompts e anotações na pasta pessoal de alguém. A regra é um lugar para cada documento, com todos os outros locais guardando um link e não uma duplicata. É o mesmo princípio explicado em como definir fontes oficiais para um agente de IA: um lugar prevalece, e todo o resto aponta para ele.

O que o agente deve fazer ao responder?

O comportamento do agente deve ser especificado como regras, e a mais importante é aplicada pelo sistema, não pedida em um prompt.

• Busque com filtro de status igual a vigente e de datas de vigência que incluam hoje. Aplique o filtro antes do ranqueamento, para que texto substituído nunca concorra.
• Cite título, versão e data de vigência em toda resposta extraída de um documento.
• Diante de uma pergunta sobre o passado, recupere a versão que estava em vigor naquela data e identifique a resposta como histórica.
• Se existirem duas versões vigentes para o mesmo ID e escopo, não escolha uma. Informe que há um conflito e encaminhe ao responsável.
• Se nenhuma versão vigente for encontrada, diga que não consegue confirmar a resposta e indique o responsável.

O filtro é a peça que sustenta tudo. Uma instrução como use a versão mais recente depende de o modelo perceber qual trecho é o mais recente, e isso às vezes falha. O filtro elimina a escolha. Sistemas com geração aumentada por busca (RAG) normalmente consultam um repositório indexado antes de gerar a resposta (veja a arquitetura de referência de RAG do Google Cloud como modelo), e essa etapa de busca é o lugar certo para aplicar status e data.

A citação é a segunda proteção. Versão e data citadas transformam um erro invisível em um erro visível. Um colega que lê a resposta percebe de imediato que ela cita a versão 2 enquanto a versão 3 entrou em vigor no mês passado.

Plano passo a passo para implantar

Você não precisa corrigir a base inteira de uma vez. Comece pelos documentos que alteram respostas e avance a partir deles.

• Passo 1: Liste os documentos que o agente pode ler. Agrupe os arquivos que são versões da mesma coisa. Comece por termos, tabelas de preços, procedimentos e regras de elegibilidade.
• Passo 2: Atribua um ID de documento e um responsável nomeado a cada grupo.
• Passo 3: Com cada responsável, decida qual versão é a vigente. Onde dois arquivos fizerem afirmações conflitantes, pergunte ao responsável e registre a decisão. Não adivinhe.
• Passo 4: Adicione os campos de metadados e marque todas as versões mais antigas como substituídas, com a data de vigente até.
• Passo 5: Configure a busca para filtrar por status e datas antes do ranqueamento e para excluir conteúdo em rascunho e arquivado.
• Passo 6: Mude a rotina de publicação para que lançar uma nova versão e aposentar a antiga aconteçam na mesma ação, pela mesma pessoa.
• Passo 7: Escreva um conjunto de perguntas de teste cujas respostas diferem entre versões e rode-o após cada publicação maior. O método está descrito em como testar a qualidade da busca em uma base de IA.

Se só der para fazer uma coisa esta semana, faça o passo 3. Combinar o que de fato está vigente costuma expor divergências que nenhum agente conseguiria resolver.

Cenário ilustrativo: os termos de cancelamento

Este é um cenário ilustrativo, não um caso real. Uma empresa de serviços revisa seus termos de cancelamento. A nova versão encurta o prazo de cancelamento gratuito e entra em vigor no início do próximo mês. Os dois PDFs estão na pasta compartilhada, chamados termos-final e termos-final-novo. O arquivo mais antigo tem exemplos práticos mais claros.

Um cliente pergunta ao agente se ainda pode cancelar sem multa. O agente recupera o arquivo antigo, porque os exemplos dele se parecem muito com a pergunta, e responde com a regra velha. Ninguém percebe até o cliente contestar uma cobrança.

Agora aplique as regras. Os novos termos são registrados sob um único ID de documento como uma versão maior agendada, e os termos antigos continuam vigentes até a data de início. Nessa data, os status se invertem, e a versão antiga recebe uma data de vigente até. O agente filtra pelo status vigente, responde com base nos novos termos e cita título, versão e data de vigência. Se um cliente que assinou sob os termos antigos perguntar o que valia para ele, o agente recupera a versão vigente na data da assinatura e identifica a resposta como histórica. Os mesmos dois arquivos passam a gerar duas respostas corretas, cada uma para a pergunta certa.

Como a Be Human trata o versionamento de documentos

No primeiro projeto, a Be Human define o papel que o agente vai exercer e os documentos de que ele precisa, e então combina os campos de metadados, as regras de status e o responsável nomeado de cada documento antes de indexar qualquer coisa. A busca é configurada para filtrar por status e datas de vigência, e o agente é ajustado para citar versão e data. Na operação gerenciada, as avaliações recorrentes incluem perguntas de teste sensíveis a versão, e as rotinas de revisão verificam se o conteúdo aposentado foi removido de todos os lugares que o agente consegue ler. A aprovação de publicação continua com os seus responsáveis, e o agente não tem permissão para promover um rascunho a vigente por conta própria.

Perguntas frequentes

Preciso de um software específico para fazer controle de versão de documentos para uma base de conhecimento de IA? Não. Uma pasta compartilhada ou uma wiki com metadados consistentes pode funcionar, desde que a camada de busca consiga filtrar por esses metadados. Ferramentas dedicadas ajudam com aprovações e histórico, mas as regras importam mais do que a plataforma, e o agente deve ler de um único local indexado.

O agente deve ler versões substituídas? Sim, em dois casos: quando a pergunta se refere a uma data passada e quando alguém pergunta o que mudou. A busca padrão deve excluir conteúdo substituído, e qualquer resposta tirada dele deve ser identificada como histórica, para que ninguém a confunda com a regra atual.

Com que frequência as versões devem ser revisadas? Cada documento tem uma data de revisão definida pelo responsável, de acordo com a frequência com que os fatos mudam. Documentos que sustentam respostas a clientes merecem intervalos menores. Na revisão, o responsável confirma que a versão continua vigente ou publica uma nova.

E se dois times publicarem versões conflitantes da mesma política? Primeiro confira o campo de escopo, porque as duas podem estar corretas para clientes ou regiões diferentes. Se houver conflito de verdade, o agente não deve escolher uma. Ele deve sinalizar o conflito ao responsável, que decide, e a decisão deve ser registrada como uma nova versão.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.