vector-index-tuning

Visão geral da skill vector-index-tuning

Para que serve a vector-index-tuning

A skill vector-index-tuning ajuda você a escolher e ajustar configurações de índices de busca vetorial considerando trade-offs reais de produção: latência, recall, uso de memória, tempo de build e escala. Ela é mais útil quando um sistema de RAG funciona na prática, mas a qualidade da recuperação, a velocidade de consulta ou o custo de infraestrutura deixaram de ser aceitáveis.

Quem deve usar esta skill

A vector-index-tuning skill é indicada para:

• engenheiros que operam busca semântica ou RAG em produção
• times escolhendo entre índices Flat, HNSW, HNSW quantizado, IVF+PQ ou armazenados em disco
• builders que precisam de orientação concreta de parâmetros, e não de conselhos genéricos como “otimize seus embeddings”

Se você ainda está validando se busca vetorial é necessária ou não, talvez seja cedo demais.

O trabalho real que ela resolve

Em geral, os usuários não querem “teoria de índices”. Eles querem respostas para perguntas como:

• Por que o recall caiu depois da quantização?
• Quais configurações de HNSW eu devo testar primeiro?
• Em que tamanho de dados devo parar de usar busca exata?
• Como reduzir RAM sem piorar visivelmente a recuperação no RAG?

vector-index-tuning for RAG Workflows entrega mais valor quando você já conhece o tamanho do corpus, a dimensionalidade, o orçamento de latência e a perda de recall aceitável.

O que a diferencia de um prompt genérico

Um prompt comum costuma gerar sugestões vagas. vector-index-tuning é mais útil porque fornece um framework prático de decisão:

• tipo de índice por escala do dataset
• papel dos parâmetros do HNSW (M, efConstruction, efSearch)
• opções de quantização por trade-off entre memória e qualidade
• visão orientada à produção para coleções grandes

Isso facilita sair de “nossa recuperação está lenta” para um plano concreto de tuning.

O que saber antes de instalar

Esta skill é um único guia em SKILL.md, sem scripts auxiliares nem benchmark harness. Isso torna a adoção leve, mas a execução depende da qualidade das suas próprias métricas e do seu setup de testes. Instale se você quer orientação estruturada de tuning; não espere automação pronta para uso.

Como usar a skill vector-index-tuning

Instalação da vector-index-tuning

Instale a partir do repositório com:

npx skills add https://github.com/wshobson/agents --skill vector-index-tuning

Como a skill existe em um único guia markdown, a instalação é simples. O trabalho prático principal começa depois: fornecer detalhes suficientes do sistema para o modelo gerar boas recomendações de tuning.

Leia este arquivo primeiro

Comece por:

• SKILL.md

Não há scripts de suporte, referências nem pastas de regras aqui, então quase toda a orientação útil está nesse único arquivo. Isso é ótimo para revisão rápida, mas também significa que você deve trazer seus próprios dados de benchmark em vez de esperar assets de teste embutidos.

Quais entradas a skill precisa para funcionar bem

Para um bom vector-index-tuning usage, forneça ao modelo:

• número de vetores
• dimensão do embedding
• tipo de índice atual
• configurações atuais de HNSW, se aplicável
• orçamento de memória
• latência alvo p95 ou p99
• meta de recall exigida ou perda de qualidade aceitável
• padrão de atualização: majoritariamente estático, refresh em lote ou alta taxa de escrita
• setup de recuperação do RAG: top-k, reranking, filtering, restrições de metadata

Sem essas informações, a skill só consegue devolver recomendações genéricas.

Como transformar um objetivo vago em um prompt útil

Prompt fraco:

Tune my vector index.

Prompt melhor:

Use the vector-index-tuning skill. I have 18M vectors at 768 dimensions for a RAG system. Current index is HNSW with M=16, efConstruction=100, efSearch=40. p95 latency is 140ms, RAM is too high, and recall@10 versus brute-force is 0.91. I can tolerate recall@10 down to 0.88 if p95 falls below 80ms and RAM drops by 30%. Recommend index strategy, parameter changes, and a benchmark plan.

Isso funciona melhor porque explicita o alvo real de otimização e o limite aceitável de trade-off.

Melhor fluxo de trabalho para vector-index-tuning for RAG Workflows

Uma sequência prática é:

1. Descrever o tamanho do corpus e a arquitetura atual de recuperação.
2. Informar primeiro a restrição de negócio: latência, memória ou recall.
3. Pedir que a skill escolha primeiro a família de índice, antes de ajustar parâmetros mais finos.
4. Fazer benchmark com um conjunto fixo de queries e um método de ground truth.
5. Iterar um grupo de variáveis por vez.

Isso importa porque muitos times partem direto para varreduras de parâmetros sem confirmar antes se estão usando o tipo de índice certo para a escala que têm.

Como escolher primeiro a família de índice

A tabela de decisão central da skill é útil como filtro inicial:

• abaixo de ~10K vetores: busca exata com Flat costuma ser mais simples e suficiente
• de ~10K a 1M: HNSW geralmente é o candidato padrão
• de ~1M a 100M: HNSW com quantização passa a fazer sentido
• acima de ~100M: abordagens como IVF+PQ ou no estilo DiskANN se tornam mais plausíveis

Trate isso como ponto de partida, não como regra fixa. Se seus vetores têm filtros pesados, atualizações frequentes ou rodam com orçamento de memória muito apertado, a melhor escolha pode ser outra.

Como aproveitar bem a orientação de HNSW

Ao pedir ajuda com HNSW, inclua os três principais controles:

• M: conectividade do grafo, normalmente com melhor recall ao custo de mais memória
• efConstruction: qualidade de build versus custo de build
• efSearch: recall em tempo de consulta versus latência

Um padrão de prompt útil é:

Use the vector-index-tuning skill to propose a minimal test matrix for M, efConstruction, and efSearch that fits my latency and recall targets, and explain which parameter I should lock first.

Assim, você recebe um plano de tuning ordenado em vez de uma lista solta de valores.

Como usar bem a orientação sobre quantização

Se memória é o principal problema, peça que a skill compare:

• FP32
• FP16
• INT8 scalar quantization
• Product Quantization
• representações binárias, quando fizer sentido

Bom prompt:

I need a 2-4x memory reduction for 50M vectors and can accept modest recall loss in first-stage retrieval because a reranker follows. Use the vector-index-tuning skill to compare FP16, INT8, and PQ for this RAG pipeline.

Isso é mais forte do que perguntar “devo quantizar?” porque conecta a tolerância à compressão ao reranking downstream.

Que tipo de saída você deve esperar

O melhor resultado não é um conjunto mágico de parâmetros. É:

• uma escolha de índice mais estreita
• uma grade curta de parâmetros candidatos
• um plano de avaliação
• explicações de trade-off que você possa testar

Se o modelo devolver apenas uma configuração sem método de benchmark, peça que ele refaça a resposta como um plano de experimentos.

Caminho prático para leitura do repositório

Como só existe SKILL.md, foque nestas seções, nesta ordem:

1. When to Use This Skill
2. Core Concepts
3. Index Type Selection
4. HNSW Parameters
5. Quantization Types
6. templates de código perto do final

Esse caminho de leitura dá primeiro a lógica de decisão, depois os controles de tuning e por fim os padrões de implementação.

Bloqueios comuns na adoção

Os times normalmente travam por um destes motivos:

• não há baseline de recall contra busca exata
• não existe um conjunto fixo de queries para comparar execuções
• tentam otimizar latência e recall sem um orçamento de memória
• usam benchmarks sintéticos que não se parecem com queries reais de RAG

A skill ajuda nas decisões de tuning, mas não substitui dados de avaliação representativos.

FAQ da skill vector-index-tuning

A vector-index-tuning é boa para iniciantes?

Sim, se você já entende o que é um índice vetorial. Não, se ainda está decidindo entre busca por palavra-chave, busca híbrida e dense retrieval. A skill assume que você já passou da fase de escolher a arquitetura básica de recuperação e agora precisa de orientação de tuning.

Quando vector-index-tuning não é a ferramenta certa?

Não comece com vector-index-tuning se o seu problema real for:

• chunking ruim
• embeddings ruins
• pré-processamento de documentos fraco
• ausência de filtros de metadata
• falta de reranking onde ele é necessário

Tuning de índice não corrige problemas de relevância causados a montante.

Isso é melhor do que perguntar diretamente a um LLM?

Na maioria dos casos, sim, porque a vector-index-tuning skill mantém a conversa centrada em trade-offs mensuráveis e alavancas de parâmetros conhecidas, em vez de conselhos genéricos de otimização. O ganho está na estrutura, não na automação.

Ela ajuda especificamente com vector-index-tuning for RAG Workflows?

Sim. A skill é especialmente relevante para a recuperação de primeiro estágio em RAG, em que muitas vezes você precisa equilibrar recall e custo antes do reranking. Ela fica ainda mais útil quando você informa explicitamente se existe um reranker, qual top-k você usa e se o metadata filtering reduz o conjunto de candidatos.

A skill inclui ferramentas executáveis de benchmark?

Não. Pela estrutura do repositório, esta skill é orientada por documentação. Espere orientação conceitual e exemplos de código, não um harness completo para medir recall, tempo de build e latência no seu ambiente.

E se minha coleção for atualizada com frequência?

Use a skill, mas mencione explicitamente a frequência de atualização. Algumas escolhas de índice parecem excelentes para corpora estáticos e bem menos atraentes sob cargas pesadas de escrita. Essa é uma das formas mais fáceis de receber uma resposta que parece inteligente, mas está errada do ponto de vista operacional.

Como melhorar a skill vector-index-tuning

Dê restrições duras para a skill, não preferências

A forma mais rápida de melhorar os resultados de vector-index-tuning é trocar objetivos vagos por números:

• “abaixo de 75ms p95”
• “abaixo de 64GB de RAM”
• “recall@20 deve ficar acima de 0.9”
• “rebuild noturno é aceitável”
• “ingestão é contínua, sem longos rebuilds offline”

Restrições numéricas forçam recomendações mais claras.

Forneça um baseline e uma delta-alvo

Entrada melhor:

Current HNSW index uses 92GB RAM, p95 is 110ms, recall@10 is 0.93. Need 30% lower memory and under 85ms p95.

Isso permite que a skill raciocine a partir de um ponto de partida real. Sem métricas de baseline, a saída tende a ser genérica demais para inspirar confiança.

Peça uma matriz de benchmark, não uma resposta única

Um prompt de alto valor é:

Use the vector-index-tuning skill to produce a 6-run benchmark matrix prioritized by information gain, not exhaustiveness.

Em geral, isso gera resultados práticos melhores do que pedir as “best settings”, porque o desempenho de índices vetoriais depende fortemente da distribuição dos dados e da carga de trabalho.

Separe qualidade de recuperação da qualidade da resposta final

Em RAG, muitas vezes os usuários julgam mudanças no índice apenas pela qualidade da resposta final. Para melhorar os resultados, peça que a skill separe:

• recall bruto da recuperação
• latência
• footprint de memória
• impacto do reranker downstream
• qualidade na tarefa final

Isso evita over-tuning do índice para uma métrica que seu aplicativo não otimiza de fato.

Informe se filtros alteram o espaço de busca

Se seu sistema aplica filtros por tenant, idioma, data ou produto antes ou durante a busca, diga isso. Busca filtrada pode mudar de forma material qual é a melhor decisão de índice. Isso é especialmente importante para vector-index-tuning for RAG Workflows em sistemas multi-tenant.

Modos de falha comuns para observar

Os erros mais comuns são:

• aumentar efSearch sem verificar se a qualidade do grafo HNSW é o verdadeiro gargalo
• comprimir de forma agressiva demais antes de estabelecer um piso mínimo de recall
• comparar índices com conjuntos de queries diferentes
• escolher IVF/PQ apenas por escala sem validar a distribuição das queries
• ignorar custos de build e refresh

São exatamente esses casos em que uma configuração aparentemente mais rápida acaba performando pior em produção.

Como iterar depois da primeira resposta

Após a primeira recomendação, responda com os resultados em uma tabela compacta:

• configuração
• RAM
• tempo de build
• latência p95
• recall@k
• notas sobre erros de recuperação

Depois pergunte:

Revise the tuning plan using these measurements and eliminate dominated configurations.

É nesse loop de segunda passada que a skill fica materialmente melhor do que um prompt one-shot.

Melhore a confiança pedindo linguagem explícita de trade-off

Peça que a skill rotule cada recomendação como:

• likely win
• risky but high upside
• low effort
• requires benchmark confirmation

Isso facilita priorizar mudanças e reduz a chance de copiar uma sugestão que só funciona sob premissas ideais.

Combine a skill com seu próprio ground truth de busca exata

O melhor upgrade isolado para vector-index-tuning usage é um pequeno benchmark de busca exata com queries representativas. Mesmo algumas centenas de queries rotuladas ou avaliadas por brute-force já melhoram drasticamente a qualidade da decisão, porque cada recomendação de tuning pode ser testada contra um baseline conhecido de recall.

Como é o sucesso na prática

Um bom uso de vector-index-tuning termina com:

• uma escolha justificada de família de índice
• uma shortlist curta de parâmetros
• evidência de benchmark para recall, velocidade e memória
• uma decisão de deploy alinhada à sua carga de trabalho de RAG

Se você não sair com um plano testável, peça que a skill seja mais operacional e menos descritiva.