Para trocar o modelo de embeddings sem degradar a busca, crie uma geração separada de vetores, reconstrua os documentos nessa geração e só então direcione consultas para ela. A consulta e os documentos precisam usar o mesmo contrato de geração: modelo, dimensões, preparação do texto e métrica. Conservar o índice antigo durante a transição permite comparar resultados e reverter o tráfego.
Não basta alterar o nome do modelo na chamada da API. Mesmo quando dois modelos devolvem vetores do mesmo tamanho, suas coordenadas não devem ser tratadas como intercambiáveis. A migração é uma mudança no mecanismo de recuperação inteiro, com controle de versões, atualização de documentos e critérios de qualidade. O procedimento abaixo é uma proposta de arquitetura para equipes que já têm uma busca funcionando.
Resumo rápido
- Identifique cada geração por um contrato imutável, incluindo modelo e dimensões.
- Mantenha armazenamento e índices separados para a geração antiga e a nova.
- Valide os vetores recebidos antes da gravação e novamente no banco.
- Reconstrua o acervo sem perder alterações e exclusões feitas durante o processo.
- Compare relevância e latência antes do corte; preserve uma rota de retorno.
Defina o contrato da geração de embeddings
Embedding é uma representação numérica usada para comparar textos. Se essa base ainda não está clara, veja a explicação de embeddings em busca e recomendação. Aqui, o ponto é operacional: um vetor sem sua origem é um dado incompleto. Registre fornecedor, identificador do modelo, dimensão solicitada, dimensão efetiva, métrica, normalização e versão do processamento do texto.
Inclua também a estratégia de divisão em trechos, chamada de chunking. Mudar de parágrafos inteiros para blocos pequenos altera o que a busca consegue recuperar, mesmo sem trocar o modelo. Para investigar a causa de uma melhora ou piora, prefira avaliar mudanças separadamente. Quando forem inseparáveis, declare que a nova geração representa o conjunto das mudanças.
A documentação de embeddings da OpenAI permite configurar dimensões nos modelos compatíveis. Isso não autoriza cortar qualquer vetor de qualquer fornecedor de forma arbitrária. Use o mecanismo documentado para o modelo escolhido e confirme o tamanho retornado. Registre essa configuração na aplicação e no trabalho de reconstrução. A página de integração com OpenAI e ChatGPT reúne o contexto desse fornecedor no site.
Crie um identificador interno como busca_catalogo_g2. Esse nome aponta para um contrato fechado, não para um campo que alguém pode editar silenciosamente. O cadastro da geração também deve conter estado operacional, responsável e data de aprovação. O documento continua tendo seu identificador de negócio; a geração identifica como sua representação foi calculada.
Escolha como separar vetores e índices
A escolha depende da estrutura existente. Uma tabela nova por geração simplifica a inspeção e a remoção futura. Uma única tabela com geração na chave facilita algumas consultas administrativas, mas exige mais cuidado com filtros e índices. O objetivo é impedir que uma consulta da geração nova alcance documentos representados pela antiga.
| Desenho | Vantagem | Cuidado na migração |
|---|---|---|
| Tabelas separadas | Isolamento visível e retorno simples | Duplicar políticas de acesso e monitoramento |
| Colunas separadas | Documento e duas representações na mesma linha | Evitar linhas parcialmente preenchidas e acoplamento de esquema |
| Tabela com identificador de geração | Histórico centralizado | Filtrar a geração em toda consulta e escolher índices compatíveis |
| Substituição imediata | Menor armazenamento temporário | Remove a comparação paralela e dificulta reversão |
O projeto pgvector documenta o uso de dimensões fixas e índices parciais para conjuntos compatíveis. Diferencie a capacidade de armazenar um vetor da capacidade de indexá-lo pelo método escolhido. Confira os limites do tipo, do índice e da versão instalada antes de escolher a dimensão. Não deduza compatibilidade apenas porque a inserção foi aceita.
Para uma aplicação pequena, tabelas distintas costumam tornar o procedimento mais legível. Este guia não repete a instalação do banco ou a escolha inicial de índice, cobertas no texto sobre pgvector no Supabase. O foco é manter duas gerações coerentes durante uma mudança controlada.
Reconstrua o acervo com validação e progresso durável
Faça um inventário dos documentos ativos e de suas revisões. Cada tarefa de reconstrução deve carregar o identificador do documento, a revisão de origem, o contrato de geração e uma chave de idempotência. Idempotência significa que repetir o mesmo trabalho não cria registros adicionais. Um hash do texto preparado ajuda a detectar alterações, mas não substitui a identificação do documento e de sua revisão.
Antes de gravar, verifique se o vetor tem exatamente a quantidade esperada de elementos, se todos os valores são numéricos e finitos e se a resposta corresponde ao item solicitado. Falhas devem ir para uma fila de revisão, sem produzir um registro aparentemente pronto. Na aplicação, confira ainda se o contrato usado pelo trabalhador é igual ao cadastrado para o destino.
O esquema abaixo é ilustrativo: pressupõe a extensão instalada e uma geração planejada com 768 dimensões. O número representa uma decisão do exemplo, não a dimensão recomendada para todos os modelos. A tabela de documentos de origem e as políticas de acesso não estão incluídas.
CREATE TABLE busca_g2 (
documento_id bigint NOT NULL,
revisao bigint NOT NULL,
trecho_id integer NOT NULL,
texto_hash text NOT NULL,
embedding vector(768) NOT NULL,
PRIMARY KEY (documento_id, revisao, trecho_id)
);
CREATE INDEX busca_g2_cosine_idx
ON busca_g2 USING hnsw (embedding vector_cosine_ops);Uma dimensão fixa bloqueia vetores de tamanho incompatível. Ela não comprova que o modelo certo foi usado. A defesa completa combina esquema, contrato e testes. Para cosine distance, valide também que não foi produzido um vetor nulo, sem direção útil. Mantenha a métrica escolhida consistente entre avaliação, índice e consulta.
Durante a reconstrução, documentos continuam mudando. Capture eventos de inclusão, atualização e exclusão em um registro durável, como uma outbox transacional. A gravação do documento e do evento precisa ocorrer na mesma transação local. Trabalhadores independentes atualizam cada geração; duas chamadas externas em sequência não constituem uma transação conjunta.
Antes de aceitar o resultado de um trabalho, confira se sua revisão continua vigente. Se o documento foi excluído ou revisado, descarte o resultado atrasado. Caso contrário, uma tarefa antiga pode ressuscitar conteúdo removido. O mecanismo deve ser compatível com a política descrita em exclusão de documentos, vetores e cache em RAG.
Avalie recuperação, cobertura e custo operacional
Separe um conjunto de perguntas representativas, com documentos relevantes identificados por pessoas da operação. Inclua termos técnicos, abreviações, erros de digitação e pedidos em português usados pelos clientes. Execute cada pergunta duas vezes: uma com o contrato antigo e outra com o novo, mantendo permissões e documentos elegíveis equivalentes.
Compare a presença dos documentos relevantes entre os primeiros resultados, o comportamento de consultas sem resposta e a ordenação de trechos conflitantes. Avalie a resposta final do sistema separadamente. Um gerador de texto pode esconder uma recuperação ruim escrevendo uma resposta plausível; por isso, examinar apenas a fluência não é suficiente.
Não reutilize automaticamente o limite numérico de similaridade da geração antiga. Um valor que separava resultados úteis em uma representação pode ter outro comportamento na nova. Calibre os cortes com perguntas rotuladas, inclusive perguntas que deveriam retornar ausência de evidência. Registre os critérios antes de escolher a versão vencedora.
Meça também cobertura por revisão, quantidade de documentos pendentes, erros de dimensão, atraso de atualização, espaço ocupado e latência sob carga. O custo temporário inclui duas estruturas e processamento adicional. Um ensaio pequeno serve para estimar a migração; não é evidência de que o acervo inteiro caberá na mesma janela de manutenção.
Faça o corte preservando consistência e reversão
Comece com consultas em modo sombra: a nova busca roda para avaliação, mas não determina a resposta entregue. Use dados minimizados nos registros e evite dobrar o conteúdo sensível enviado a serviços sem necessidade. Depois, libere a geração para um grupo pequeno e estável, definido por configuração no servidor.
A seleção da geração deve acontecer antes de produzir o embedding da consulta. Transporte o identificador escolhido até o banco e inclua-o na chave do cache. Se uma requisição começar na geração antiga, ela deve terminar nela. Trocar o destino no meio do caminho pode enviar um vetor correto ao índice errado.
Para índices em tabelas ativas, consulte as condições de CREATE INDEX no PostgreSQL. A construção concorrente tem regras próprias e não deve ser inserida cegamente em qualquer transação de migração. Uma tabela nova, ainda sem leitores, pode permitir um procedimento diferente. Verifique o estado final do índice antes de ampliar o tráfego.
Defina critérios objetivos de retorno: perda de cobertura, erros de consulta ou degradação relevante no conjunto aprovado. A documentação de bloqueios explícitos do PostgreSQL ajuda a planejar alterações que disputam recursos com a operação. Reverta a configuração de roteamento quando necessário; preserve a geração antiga atualizada enquanto essa possibilidade existir.
Exemplo: distribuidora de peças em Joinville
Considere uma distribuidora de peças industriais em Joinville cuja equipe pesquisa manuais e fichas técnicas. O cenário é ilustrativo. A busca atual encontra descrições gerais, mas confunde peças com nomes parecidos. A equipe decide testar outro modelo sem interromper o atendimento.
O responsável reúne perguntas reais anonimizadas e marca quais manuais deveriam aparecer. Cria a geração nova com o mesmo recorte de documentos e mantém as restrições por cliente. Durante a reconstrução, uma ficha corrigida recebe outra revisão; o trabalhador descarta a tarefa antiga e processa a versão válida.
No piloto, os atendentes comparam resultados sem saber qual geração os produziu. A aprovação depende de recuperar a ficha correta e respeitar as permissões. Uma consulta sem documentação suficiente deve continuar mostrando essa ausência. A troca não recebe um selo de sucesso por encontrar mais textos: precisa encontrar os textos adequados ao pedido.
Erros comuns
- Validar apenas a dimensão. Vetores do mesmo tamanho podem vir de contratos diferentes.
- Trocar o índice e esquecer o cache. Inclua a geração nas entradas de cache e nos registros de rastreamento.
- Ignorar documentos alterados durante o trabalho. Use revisões e capture eventos duráveis.
- Comparar notas brutas de modelos distintos. Calibre limiares e avalie relevância com exemplos rotulados.
- Apagar a geração antiga cedo demais. Combine um período de observação e um critério de descarte com o responsável.
Perguntas frequentes
Posso aproveitar os vetores antigos no modelo novo?
Não presuma essa possibilidade. Recalcule a representação a partir do texto de origem, salvo se o fornecedor documentar uma transformação compatível e você a validar para seu caso.
Preciso reconstruir todos os documentos de uma vez?
Não. Processe em lotes, com progresso persistido. Só encaminhe consultas para o conjunto aprovado quando ele tiver a cobertura necessária para aquele público.
Uma dimensão menor sempre deixa a busca pior?
O efeito depende do modelo e dos dados. Compare configurações suportadas usando suas perguntas. Espaço, latência e relevância precisam entrar na mesma decisão.
Quando posso excluir a estrutura anterior?
Depois de encerrar formalmente a janela de reversão, confirmar a cobertura e verificar que nenhum cliente, tarefa ou cache ainda depende dela. Preserve o registro do contrato para auditoria.
