vector-index-tuning

Überblick über den vector-index-tuning Skill

Wofür vector-index-tuning gedacht ist

Der vector-index-tuning Skill hilft dir dabei, Einstellungen für Vektor-Suchindizes anhand realer Produktions-Trade-offs auszuwählen und zu optimieren: Latenz, Recall, Speicherbedarf, Build-Zeit und Skalierung. Am nützlichsten ist er, wenn ein RAG-System grundsätzlich funktioniert, aber Retrieval-Qualität, Abfragegeschwindigkeit oder Infrastrukturkosten nicht mehr akzeptabel sind.

Für wen sich dieser Skill eignet

Dieser vector-index-tuning skill passt besonders gut für:

• Engineers, die semantische Suche oder RAG in Produktion betreiben
• Teams, die zwischen Flat, HNSW, quantisiertem HNSW, IVF+PQ oder disk-basierten Indizes wählen müssen
• Builder, die konkrete Parameterempfehlungen statt allgemeiner Hinweise wie „optimiere deine Embeddings“ brauchen

Wenn du noch prüfst, ob Vektorsuche überhaupt nötig ist, ist das wahrscheinlich zu früh.

Die eigentliche Aufgabe, die gelöst werden soll

Nutzer wollen in der Regel keine „Index-Theorie“, sondern Antworten auf Fragen wie:

• Warum sinkt der Recall nach der Quantisierung?
• Welche HNSW-Einstellungen sollte ich zuerst ausprobieren?
• Ab welcher Datenmenge sollte ich keine exakte Suche mehr verwenden?
• Wie reduziere ich RAM, ohne dass das RAG-Retrieval spürbar schlechter wird?

vector-index-tuning for RAG Workflows ist besonders stark, wenn du die Größe deines Korpus, die Dimensionalität, dein Latenzbudget und den akzeptablen Recall-Verlust bereits kennst.

Was ihn von einem generischen Prompt unterscheidet

Ein normaler Prompt liefert oft vage Vorschläge. vector-index-tuning ist nützlicher, weil der Skill einen praktischen Entscheidungsrahmen vorgibt:

• Indextyp nach Datensatzgröße
• die Rollen der HNSW-Parameter (M, efConstruction, efSearch)
• Quantisierungsoptionen je nach Speicher-/Qualitäts-Trade-off
• produktionsorientiertes Denken für große Collections

So wird aus „unser Retrieval fühlt sich langsam an“ deutlich einfacher ein konkreter Tuning-Plan.

Was du vor der Installation wissen solltest

Dieser Skill besteht aus einer einzelnen SKILL.md-Anleitung ohne Hilfsskripte oder Benchmark-Harness. Das macht die Einführung leichtgewichtig, aber die Umsetzung hängt stark von der Qualität deiner eigenen Metriken und deines Test-Setups ab. Installiere ihn, wenn du strukturierte Tuning-Hinweise willst; erwarte keine fertige Automatisierung.

So verwendest du den vector-index-tuning Skill

vector-index-tuning installieren

Installation aus dem Repository mit:

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

Da der Skill nur aus einem Markdown-Guide besteht, ist die Installation einfach. Die eigentliche Arbeit beginnt danach: Du musst dem Modell genügend Systemdetails geben, damit es sinnvolle Tuning-Empfehlungen machen kann.

Diese Datei zuerst lesen

Starte mit:

• SKILL.md

Es gibt hier keine Support-Skripte, Referenzen oder rules-Ordner, daher steckt fast die gesamte nutzbare Anleitung in dieser einen Datei. Das ist gut für eine schnelle Prüfung, bedeutet aber auch: Du solltest eigene Benchmark-Daten mitbringen, statt auf eingebettete Test-Assets zu hoffen.

Welche Eingaben der Skill für gute Ergebnisse braucht

Für eine starke vector-index-tuning usage solltest du dem Modell Folgendes mitgeben:

• Anzahl der Vektoren
• Embedding-Dimension
• aktueller Indextyp
• aktuelle HNSW-Einstellungen, falls relevant
• Speicherbudget
• Ziel für p95- oder p99-Latenz
• gewünschter Recall-Zielwert oder akzeptabler Qualitätsverlust
• Update-Muster: überwiegend statisch, Batch-Refresh oder hohe Schreiblast
• RAG-Retrieval-Setup: top-k, Reranking, Filterung, Metadaten-Constraints

Ohne diese Angaben kann der Skill nur generische Empfehlungen liefern.

Aus einem groben Ziel einen brauchbaren Prompt machen

Schwacher Prompt:

Tune my vector index.

Stärkerer Prompt:

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.

Das funktioniert besser, weil es das eigentliche Optimierungsziel und die akzeptable Trade-off-Grenze klar offenlegt.

Bester Workflow für vector-index-tuning for RAG Workflows

Eine praxistaugliche Reihenfolge ist:

1. Beschreibe Korpusgröße und aktuelle Retrieval-Architektur.
2. Nenne zuerst die geschäftliche Nebenbedingung: Latenz, Speicher oder Recall.
3. Bitte den Skill, zuerst eine Indexfamilie zu wählen, bevor feingranulare Parameter optimiert werden.
4. Benchmarke gegen ein festes Query-Set und eine Ground-Truth-Methode.
5. Iteriere immer nur über eine Variablengruppe gleichzeitig.

Das ist wichtig, weil viele Teams direkt mit Parameter-Sweeps starten, ohne zuerst zu prüfen, ob sie für ihre Größenordnung überhaupt den richtigen Indextyp verwenden.

Zuerst die richtige Indexfamilie auswählen

Die zentrale Entscheidungstabelle des Skills ist als erste Filterstufe sehr hilfreich:

• unter ca. 10K Vektoren: Flat Exact Search ist oft einfacher und gut genug
• ca. 10K bis 1M: HNSW ist meist der Standardkandidat
• ca. 1M bis 100M: HNSW plus Quantisierung wird relevant
• über ca. 100M: IVF+PQ oder DiskANN-ähnliche Ansätze werden plausibler

Betrachte das als Ausgangspunkt, nicht als Gesetz. Wenn deine Vektoren stark gefiltert werden, häufig aktualisiert werden oder unter sehr engen Speicherbudgets laufen, kann die beste Wahl anders ausfallen.

So nutzt du die HNSW-Hinweise in vector-index-tuning sinnvoll

Wenn du Hilfe zu HNSW anfragst, gib alle drei zentralen Stellschrauben an:

• M: Graph-Konnektivität, in der Regel besserer Recall bei mehr Speicherverbrauch
• efConstruction: Build-Qualität versus Build-Kosten
• efSearch: Recall zur Query-Zeit versus Latenz

Ein nützliches Prompt-Muster ist:

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.

So bekommst du einen geordneten Tuning-Plan statt einer unsortierten Werteliste.

So setzt du Quantisierungs-Hinweise sinnvoll ein

Wenn Speicher das Hauptproblem ist, bitte den Skill um einen Vergleich von:

• FP32
• FP16
• INT8 scalar quantization
• Product Quantization
• binären Repräsentationen, wenn relevant

Guter 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.

Das ist deutlich stärker als nur zu fragen „should I quantize?“, weil die tolerierbare Kompression direkt mit dem nachgelagerten Reranking verknüpft wird.

Welche Ausgaben du erwarten solltest

Das beste Ergebnis ist nicht ein magischer einzelner Parametersatz, sondern:

• eine eingegrenzte Indexwahl
• ein kleines Grid mit Kandidatenparametern
• ein Evaluationsplan
• testbare Erklärungen zu den Trade-offs

Wenn das Modell nur eine einzige Konfiguration ohne Benchmark-Methode liefert, bitte es, die Antwort in einen Experimentplan zu überarbeiten.

Praktischer Pfad zum Lesen des Repositorys

Da nur SKILL.md vorhanden ist, konzentriere dich in dieser Reihenfolge auf:

1. When to Use This Skill
2. Core Concepts
3. Index Type Selection
4. HNSW Parameters
5. Quantization Types
6. Code-Templates im unteren Bereich

Dieser Leseweg gibt dir zuerst die Entscheidungslogik, dann die Tuning-Stellschrauben und zuletzt die Umsetzungsmuster.

Häufige Hürden bei der Einführung

Teams bleiben meist aus einem dieser Gründe stecken:

• keine Recall-Baseline gegenüber exakter Suche
• kein festes Query-Set zum Vergleichen verschiedener Läufe
• der Versuch, Latenz und Recall ohne Speicherbudget zu optimieren
• synthetische Benchmarks, die realen RAG-Queries nicht ähneln

Der Skill hilft bei Tuning-Entscheidungen, ersetzt aber keine repräsentativen Evaluationsdaten.

FAQ zum vector-index-tuning Skill

Ist vector-index-tuning für Einsteiger geeignet

Ja, wenn du bereits verstehst, was ein Vektorindex ist. Nein, wenn du noch zwischen Keyword Search, Hybrid Search und Dense Retrieval abwägst. Der Skill setzt voraus, dass die grundlegende Auswahl der Retrieval-Architektur bereits erledigt ist und du jetzt Tuning-Hilfe brauchst.

Wann ist vector-index-tuning nicht das richtige Tool

Starte nicht mit vector-index-tuning, wenn dein eigentliches Problem eines davon ist:

• schlechtes Chunking
• schlechte Embeddings
• schwache Dokumentvorverarbeitung
• fehlende Metadatenfilter
• fehlendes Reranking, obwohl es nötig wäre

Index-Tuning behebt keine Relevanzprobleme, die vorgelagert entstehen.

Ist das besser, als direkt ein LLM zu fragen

In der Regel ja, weil der vector-index-tuning skill das Gespräch auf messbare Trade-offs und bekannte Parameterhebel fokussiert, statt auf allgemeine Optimierungsratschläge auszuweichen. Der Mehrwert liegt in der Struktur, nicht in Automatisierung.

Hilft es speziell bei vector-index-tuning for RAG Workflows

Ja. Der Skill ist besonders relevant für First-Stage Retrieval in RAG, wo du häufig Recall und Kosten austarieren musst, bevor ein Reranker übernimmt. Noch nützlicher wird er, wenn du explizit angibst, ob ein Reranker vorhanden ist, welches top-k du verwendest und ob Metadatenfilter die Kandidatenmenge verkleinern.

Enthält der Skill ausführbare Benchmarking-Tools

Nein. Nach der Repository-Struktur zu urteilen ist dieser Skill dokumentationsgetrieben. Du solltest konzeptionelle Anleitung und Code-Beispiele erwarten, aber keinen vollständigen Harness zum Messen von Recall, Build-Zeit und Latenz in deiner Umgebung.

Was ist, wenn meine Collection häufig aktualisiert wird

Nutze den Skill, aber nenne die Update-Frequenz ausdrücklich. Manche Index-Entscheidungen sehen für statische Korpora hervorragend aus und sind bei hoher Schreiblast deutlich weniger attraktiv. Genau hier entstehen besonders leicht Antworten, die klug klingen, aber operativ falsch sind.

So verbesserst du den vector-index-tuning Skill

Gib dem Skill harte Nebenbedingungen, keine Präferenzen

Der schnellste Weg zu besseren vector-index-tuning-Ergebnissen ist, vage Ziele durch Zahlen zu ersetzen:

• „unter 75ms p95“
• „unter 64GB RAM“
• „recall@20 muss über 0.9 bleiben“
• „nächtlicher Rebuild ist akzeptabel“
• „Ingest läuft kontinuierlich, keine langen Offline-Rebuilds“

Numerische Nebenbedingungen erzwingen klarere Empfehlungen.

Liefere eine Baseline und ein Ziel-Delta

Bessere Eingabe:

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

So kann der Skill von einem realen Ausgangspunkt aus argumentieren. Ohne Baseline-Metriken ist die Ausgabe zu generisch, um ihr wirklich zu vertrauen.

Bitte um eine Benchmark-Matrix, nicht um eine Einzelantwort

Ein besonders wertvoller Prompt ist:

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

Das liefert in der Praxis meist bessere Ergebnisse als die Frage nach den „best settings“, weil die Performance von Vektorindizes stark von Datenverteilung und Workload abhängt.

Trenne Retrieval-Qualität von finaler Antwortqualität

In RAG beurteilen Nutzer Indexänderungen oft nur anhand der finalen Antwortqualität. Bessere Ergebnisse bekommst du, wenn du den Skill explizit bittest, zu unterscheiden zwischen:

• rohem Retrieval-Recall
• Latenz
• Speicherbedarf
• Einfluss des nachgelagerten Rerankers
• Qualität der Endaufgabe

So vermeidest du, den Index auf eine Metrik zu überoptimieren, die deine Anwendung tatsächlich gar nicht direkt optimiert.

Sag, ob Filterung den Suchraum verändert

Wenn dein System Tenant-, Sprach-, Datums- oder Produktfilter vor oder während der Suche anwendet, solltest du das angeben. Gefilterte Suche kann die beste Indexentscheidung substanziell verändern. Das ist besonders wichtig für vector-index-tuning for RAG Workflows in Multi-Tenant-Systemen.

Häufige Fehlermuster, auf die du achten solltest

Die häufigsten Fehler sind:

• efSearch zu erhöhen, ohne zu prüfen, ob die HNSW-Graphqualität der eigentliche Engpass ist
• zu aggressiv zu komprimieren, bevor eine Recall-Untergrenze festgelegt wurde
• Indizes auf unterschiedlichen Query-Sets zu vergleichen
• IVF/PQ allein wegen der Skalierung zu wählen, ohne die Query-Verteilung zu validieren
• Build- und Refresh-Kosten zu ignorieren

Genau in diesen Fällen unterperformt ein vermeintlich schnelleres Setup später in Produktion.

So iterierst du nach der ersten Ausgabe weiter

Antworte nach der ersten Empfehlung mit Ergebnissen in einer kompakten Tabelle:

• Konfiguration
• RAM
• Build-Zeit
• p95-Latenz
• recall@k
• Hinweise zu Retrieval-Fehlern

Frage dann:

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

In dieser zweiten Schleife wird der Skill materiell besser als ein One-Shot-Prompt.

Mehr Vertrauen schaffen, indem du explizite Trade-off-Sprache anforderst

Bitte den Skill, jede Empfehlung zu kennzeichnen als:

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

So kannst du Änderungen leichter priorisieren und reduzierst das Risiko, einen Vorschlag zu übernehmen, der nur unter idealen Annahmen funktioniert.

Kombiniere den Skill mit deiner eigenen Exact-Search-Ground-Truth

Das beste Upgrade für eine gute vector-index-tuning usage ist ein kleiner Exact-Search-Benchmark auf repräsentativen Queries. Schon einige hundert gelabelte oder per Brute-Force ausgewertete Queries verbessern die Entscheidungsqualität deutlich, weil sich jede Tuning-Empfehlung gegen eine bekannte Recall-Baseline testen lässt.

Woran Erfolg zu erkennen ist

Eine gute Nutzung von vector-index-tuning endet mit:

• einer begründeten Wahl der Indexfamilie
• einer kurzen Parameter-Shortlist
• Benchmark-Evidenz für Recall, Geschwindigkeit und Speicher
• einer Deployment-Entscheidung, die zu deinem RAG-Workload passt

Wenn du am Ende keinen testbaren Plan hast, bitte den Skill, operativer und weniger beschreibend zu werden.