vector-index-tuning

vector-index-tuning skill の概要

vector-index-tuning は何に使うスキルか

vector-index-tuning は、実運用で発生する現実的なトレードオフ――レイテンシ、再現率、メモリ使用量、ビルド時間、スケール――を踏まえて、ベクトル検索インデックスの設定を選び、調整するための skill です。特に、RAG システム自体は成立しているものの、検索品質・クエリ速度・インフラコストのいずれかが許容できなくなってきた段階で真価を発揮します。

この skill を使うべき人

この vector-index-tuning skill は、次のようなケースに向いています。

• semantic search や RAG を本番運用しているエンジニア
• Flat、HNSW、quantized HNSW、IVF+PQ、disk-backed indexes のどれを選ぶべきか見極めたいチーム
• 「embeddings を最適化しましょう」といった抽象論ではなく、具体的なパラメータ指針が必要な開発者

まだ「そもそもベクトル検索が必要か」を検証している段階なら、導入は少し早いかもしれません。

本当に解決したい仕事

多くのユーザーが欲しいのは「インデックス理論」そのものではありません。実際には、次のような疑問に答えたいはずです。

• quantization 後に recall が落ちるのはなぜか
• HNSW の設定は何から試すべきか
• データ量がどの程度になったら exact search をやめるべきか
• RAG の検索品質を目に見えて悪化させずに RAM を減らすにはどうすればよいか

vector-index-tuning for RAG Workflows が特に強いのは、すでに corpus size、次元数、レイテンシ予算、許容できる recall 低下幅が見えている場合です。

一般的なプロンプトと何が違うのか

普通のプロンプトだと、どうしてもふわっとした提案に寄りがちです。vector-index-tuning が実用的なのは、次のような判断軸を具体的に示してくれるからです。

• データセット規模ごとの index type の選び方
• HNSW パラメータの役割（M、efConstruction、efSearch）
• メモリと品質のトレードオフに応じた quantization の選択肢
• 大規模コレクションを前提にした実運用寄りの考え方

そのため、「なんとなく retrieval が遅い」から、実際に試せるチューニング計画へ移りやすくなります。

インストール前に知っておくべきこと

この skill は、補助スクリプトや benchmark harness を含まない、単体の SKILL.md ガイドです。そのぶん導入は軽い一方で、実際の成果は自前のメトリクス設計やテスト環境の質に左右されます。構造化されたチューニング指針が欲しいなら導入価値は高いですが、すぐ使える自動化一式を期待するものではありません。

vector-index-tuning skill の使い方

vector-index-tuning のインストール

リポジトリから次のコマンドでインストールします。

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

この skill は 1 本の markdown ガイドとして提供されているため、インストール自体はシンプルです。実務上の本番作業は導入後に始まります。モデルから適切なチューニング提案を引き出すには、システムの前提条件を十分に渡す必要があります。

最初に読むべきファイル

最初に確認するのは次です。

• SKILL.md

support scripts、references、rules フォルダはないため、実用的な情報のほぼすべてがこの 1 ファイルに集約されています。短時間で全体像を把握しやすい反面、埋め込み済みのテスト資産を期待するのではなく、自前の benchmark data を用意して読む前提になります。

skill をうまく機能させるために必要な入力

vector-index-tuning usage の精度を上げるには、少なくとも次をモデルに渡してください。

• ベクトル数
• embedding dimension
• 現在の index type
• 該当する場合は現在の HNSW 設定
• memory budget
• 目標の p95 または p99 latency
• 必要な recall target、または許容可能な品質低下幅
• 更新パターン: mostly static、batch refresh、または high-write
• RAG retrieval setup: top-k、reranking、filtering、metadata constraints

これらがないと、この skill が返せるのは汎用的な助言にとどまります。

あいまいな目標を使えるプロンプトに変える

弱いプロンプト:

Tune my vector index.

より強いプロンプト:

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.

この書き方が有効なのは、何を最適化したいのか、どこまでのトレードオフを受け入れられるのかが明確になるからです。

vector-index-tuning for RAG Workflows に最適な進め方

実践的な進め方は次の順番です。

1. corpus size と現在の retrieval architecture を説明する
2. まずビジネス制約を明示する。レイテンシ、メモリ、recall のどれが最優先かを先に言う
3. 細かいパラメータ調整の前に、まず index family を選ばせる
4. 固定クエリセットと ground-truth method を使って benchmark する
5. 1 回の反復で変更する変数群は 1 つに絞る

ここが重要です。多くのチームは、自分たちのスケールに合った index type かどうかを確かめないまま、いきなり parameter sweep に入ってしまいます。

まず index family をどう選ぶか

この skill の中核にある decision table は、初期判断のフィルタとして有用です。

• ~10K vectors 未満: Flat exact search のほうが単純で十分なことが多い
• ~10K 〜 1M: まず HNSW を標準候補として考えるのが一般的
• ~1M 〜 100M: HNSW に quantization を組み合わせる選択が現実味を帯びる
• ~100M 超: IVF+PQ や DiskANN 系アプローチの可能性が高まる

ただし、これは法則ではなく出発点です。強い filtering が入る、更新頻度が高い、極端に厳しい memory budget がある、といった条件では最適解が変わることがあります。

HNSW の指針を vector-index-tuning で活かす方法

HNSW について相談する場合は、主要な 3 つのノブを必ず含めてください。

• M: グラフの接続性。一般に大きいほど recall は上がりやすいが、メモリも増える
• efConstruction: build quality と build cost のトレードオフ
• efSearch: クエリ時の recall と latency のトレードオフ

有効なプロンプトの型は次のとおりです。

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.

こう聞くと、値の羅列ではなく、順序立てた tuning plan を得やすくなります。

quantization の指針を vector-index-tuning で活かす方法

主な痛点がメモリなら、次の比較を skill に依頼すると効果的です。

• FP32
• FP16
• INT8 scalar quantization
• Product Quantization
• 必要に応じて binary representations

良いプロンプト:

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.

これは単に「quantize すべきですか？」と聞くより優れています。圧縮許容度を downstream reranking と結びつけて判断できるからです。

期待すべき出力

理想的な成果は、魔法のような単一パラメータセットではありません。期待すべきなのは次です。

• index choice の絞り込み
• 短い candidate parameter grid
• evaluation plan
• 検証可能な tradeoff の説明

もしモデルが benchmark method なしで 1 つの設定しか出してこないなら、実験計画の形に修正するよう求めましょう。

実務向けのリポジトリ読解パス

SKILL.md しかないので、次の順番で読むのが効率的です。

1. When to Use This Skill
2. Core Concepts
3. Index Type Selection
4. HNSW Parameters
5. Quantization Types
6. 下部にある code templates

この順番なら、先に意思決定のロジックをつかみ、その後で tuning knobs、最後に実装パターンへ進めます。

導入時によくある詰まりどころ

チームが止まりやすい理由は、だいたい次のどれかです。

• exact search に対する recall baseline がない
• 実行比較用の固定クエリセットがない
• memory budget を決めないまま latency と recall を同時最適化しようとしている
• 実際の RAG クエリに似ていない synthetic benchmarks を使っている

この skill はチューニング判断には役立ちますが、代表性のある評価データそのものを代替することはできません。

vector-index-tuning skill の FAQ

vector-index-tuning は初心者にも向いているか

はい、vector index が何かをすでに理解しているなら有用です。逆に、keyword search、hybrid search、dense retrieval のどれを選ぶべきかをまだ検討している段階には向きません。この skill は、基本的な retrieval architecture の選定を終え、次に tuning guidance が必要な人を前提にしています。

vector-index-tuning が適していないのはどんなときか

本当の問題が次のいずれかなら、vector-index-tuning から始めるべきではありません。

• poor chunking
• bad embeddings
• weak document preprocessing
• missing metadata filters
• 必要なのに reranking が入っていない

インデックスの調整だけでは、上流工程に原因がある relevance の問題は解決できません。

直接 LLM に聞くより優れているか

たいていは yes です。vector-index-tuning skill は、会話を「測定可能なトレードオフ」と「既知のパラメータレバー」に集中させやすく、一般論の最適化アドバイスに流れにくいからです。価値があるのは自動化ではなく、判断の構造化です。

vector-index-tuning for RAG Workflows に特化して役立つか

はい。特に RAG の first-stage retrieval では、reranking 前の段階で recall とコストのバランスを取る必要があるため、この skill は非常に相性が良いです。reranker の有無、使用している top-k、metadata filtering で候補集合がどの程度絞られるかを明示すると、さらに有益になります。

この skill に実行可能な benchmarking tools は含まれるか

いいえ。リポジトリ構成を見る限り、この skill は documentation-driven です。期待すべきなのは概念的なガイダンスと code examples であり、あなたの環境で recall、build time、latency を測るための完全な harness ではありません。

コレクションの更新頻度が高い場合はどうするか

その場合でも skill は使えますが、更新頻度は必ず明示してください。静的 corpus には非常に優秀でも、write 負荷が高い運用では魅力が落ちる index choice は少なくありません。ここを伝えないと、もっともらしく見えても運用上は外している答えを引きやすくなります。

vector-index-tuning skill を改善する方法

好みではなくハード制約を渡す

vector-index-tuning の結果を最も速く改善する方法は、あいまいな目標を数値に置き換えることです。

• “under 75ms p95”
• “under 64GB RAM”
• “recall@20 must stay above 0.9”
• “nightly rebuild is acceptable”
• “ingest is continuous, no long offline rebuilds”

数値制約があると、提案は一気に明確になります。

ベースラインと目標差分を示す

より良い入力例:

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

こうした情報があると、skill は実際の出発点をもとに考えられます。baseline metrics がないと、出力は信頼しづらい一般論になりがちです。

単一回答ではなく benchmark matrix を求める

価値の高いプロンプト例:

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

これは「best settings を教えて」と頼むより、現場ではるかに役立つことが多いです。ベクトルインデックスの性能は、データ分布と workload の影響を強く受けるためです。

retrieval quality と最終回答品質を分けて考える

RAG では、index の変更を最終的な answer quality だけで評価してしまうことがよくあります。改善したいなら、skill に次を切り分けて考えさせてください。

• raw retrieval recall
• latency
• memory footprint
• downstream reranker impact
• end-task quality

こうすることで、アプリケーションが本当に最適化していない指標に対して index を過剰調整するのを避けられます。

filtering によって探索空間が変わるかを明示する

検索前または検索中に tenant、language、date、product などの filter を適用しているなら、その点を必ず伝えてください。filtered search では、最適な index decision が大きく変わることがあります。これは multi-tenant system における vector-index-tuning for RAG Workflows で特に重要です。

よくある失敗パターンに注意する

代表的なミスは次のとおりです。

• HNSW graph quality が本当のボトルネックか確認しないまま efSearch だけを上げる
• recall floor を決める前に圧縮を強くかけすぎる
• 異なる query set で index を比較する
• スケールだけを理由に IVF/PQ を選び、query distribution を検証しない
• build cost と refresh cost を無視する

こうしたケースでは、一見速く見える構成が本番で期待外れになることが少なくありません。

最初の出力のあとにどう反復するか

最初の提案を受けたら、結果を次のようなコンパクトな表で返しましょう。

• configuration
• RAM
• build time
• p95 latency
• recall@k
• retrieval errors に関するメモ

そのうえで次のように依頼します。

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

この 2 回目以降のループで、skill は one-shot のプロンプトよりも明確に役立つものになります。

明示的な tradeoff ラベルを求めて信頼性を上げる

各提案に次のラベルを付けるよう依頼すると有効です。

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

こうしておくと優先順位を付けやすくなり、理想条件でしか成立しない提案をそのまま採用してしまうリスクも下げられます。

自前の exact-search ground truth と組み合わせる

vector-index-tuning usage を大きく改善する一番効果的な方法は、代表的なクエリに対する小規模な exact-search benchmark を持つことです。ラベル付きでも brute-force 評価でも、数百件程度あるだけで判断の質は大きく上がります。すべての tuning recommendation を、既知の recall baseline に対して検証できるようになるためです。

成功の状態とは何か

vector-index-tuning をうまく使えた状態では、最終的に次がそろっています。

• 根拠のある index family choice
• 短い parameter shortlist
• recall、speed、memory に関する benchmark evidence
• 自分たちの RAG workload に合った deployment decision

もし手元にテスト可能な計画が残っていないなら、skill に対して「説明寄りではなく、もっと運用に落ちる形で出してほしい」と求めるべきです。