Migra entre versões de modelos de embedding usando índices paralelos, vetores versionados, backfill controlado, cutover e rollback sem recuperação de versões mistas ou regressão silenciosa de qualidade.
Status do pacote: Pacote de referência assistido por IA. A validação estática do pacote foi aprovada; cenários de implementação ainda não foram executados e revisão humana do domínio é necessária antes da adoção estável.
Decisão
As atualizações do modelo de embedding são executadas como uma migração de índice duplo em vez de uma sobrescrição no local. O índice antigo continua servindo até que um novo índice seja preenchido, avaliado e cortado sob gates explícitos. A ingestão durante a migração grava em duplicidade ou enfileira trabalhos de re-embedding para que novos documentos não fiquem presos na versão que está sendo aposentada. Consultas em produção nunca misturam vetores de duas versões em um conjunto de resultados ranqueados. O rollback permanece disponível enquanto o índice anterior for mantido. Gates de qualidade comparam métricas de recuperação offline antes que o cutover seja permitido.
Escopo
- Índices de embedding versionados, trabalhos de backfill e máquina de estado de migração.
- Comportamento de gravação dupla ou equivalente durante a ingestão na migração.
- Pré-requisitos para cutover, aprovação do operador e troca de serviço.
- Gatilhos de rollback e política de retenção de índice.
- Observabilidade para progresso do backfill e detecção de versões mistas.
Fora deste bloco
- Aplicação de ACL na recuperação.
- Mudanças na política de chunking simultâneas ao re-embedding.
- Escolha do fornecedor do modelo de embedding.
Contrato
- Cada registro de vetor carrega uma tag de versão de embedding; consultas em produção direcionam exatamente uma versão de serviço por vez.
- Durante o estado de gravação dupla, novas ingestões preenchem o índice alvo enquanto o serviço ao usuário permanece no índice fonte até a conclusão do cutover.
- O cutover requer a conclusão do backfill e aprovação no gate de qualidade documentada no estado da migração; cutover com backfill parcial é rejeitado.
- Avaliação offline compara métricas de recuperação entre versões; gates que falham bloqueiam a transição para pronto para cutover.
- Rollback de v2-primário para v1-primário requer que o índice v1 retido esteja intacto, aprovação do operador e congelamento temporário da ingestão em v2; o serviço troca para somente v1 sem consultas de versões mistas.
- Recuperação de versões mistas em uma única consulta do usuário dispara alertas operacionais e é tratada como defeito de configuração.
Orientação de implementação
- Mantenha o estado da migração em metadados operacionais consumidos por workers de ingestão e roteadores de consulta.
- Faça backfill em lote com checkpointing e alertas de atraso; regule para proteger APIs de embedding upstream.
- Execute consultas sombra contra o índice candidato durante dual-read-eval sem expor resultados misturados aos usuários.
Tratamento de falhas e salvaguardas
- Falhas na API de embedding durante o backfill são re-tentadas com chaves de chunk idempotentes. Exaurir o orçamento de tentativas move o lote ou migração para estado explícito de falha/incompleto; nunca marca a versão alvo como completa, e o cutover permanece bloqueado.
- Se a taxa de erro em v2 disparar após o cutover, execute o playbook de rollback e congele novas ingestões para v2 até que a causa raiz seja identificada.
- Descomissione v1 somente após expirar a janela de retenção e drills de rollback confirmarem a estabilidade de v2.
Verificação e operações
- Acompanhe percentual de backfill, eventos de cutover, eventos de rollback e contagem de alertas de versões mistas.
- Teste fixtures de transições de estado em
migration-states.yaml. - Verifique que a exaustão de tentativas produz
backfill-failed, preserva seu checkpoint e não satisfaz o gate de backfill-completo. - Compare recall-at-k ou métrica offline equivalente antes e depois do cutover para um conjunto de consultas golden.
Os exemplos com aparência executável neste pacote são fixtures e contratos de aceitação. Execute validação estática na estrutura e metadados do pacote, depois implemente e execute os cenários no repositório alvo.
Suposições para adoção
- Nomes e valores numéricos em
example.yamlsão um perfil de adoção, não padrões universais. - Documentações de embedding Pinecone e OpenAI ilustram padrões de migração; nenhum banco de dados vetorial é obrigatório.
- Métricas e limiares do gate de qualidade são escolhas de perfil vinculadas ao risco do produto.