メインコンテンツまでスキップ

実践ガイド

このガイドでは、Apache Doris ANN ベクトル検索のプロダクション指向ワークフローを、スキーマ設計からチューニング、トラブルシューティングまで説明します。

1. スコープと典型的なシナリオ​

Apache Doris 4.x では、以下のようなシナリオで高次元ベクトルの ANN インデックスをサポートしています：

  • セマンティック検索
  • RAG 検索
  • 推薦
  • 画像またはマルチモーダル検索
  • 異常検知

サポートされているインデックス種別：

  • hnsw: 高い再現率とオンラインクエリ性能
  • ivf: 大規模ケースでのメモリ使用量削減と高速ビルド

サポートされている近似距離関数：

  • l2_distance_approximate (ORDER BY ... ASC)
  • inner_product_approximate (ORDER BY ... DESC)

コサイン関数に関する注意：

  • ANN インデックスは metric_type="cosine" を直接サポートしていません。
  • コサインベースの検索には、まずベクトルを正規化してから inner_product を使用してください。

2. 前提条件と制約​

ANN インデックスを使用する前に、以下を確認してください：

  1. Doris バージョン：>= 4.0.0
  2. テーブルモデル：ANN では DUPLICATE KEY のみサポート
  3. ベクトル列：ARRAY<FLOAT> NOT NULL である必要があります
  4. 次元の整合性：入力ベクトルの次元数はインデックスの dim と一致する必要があります

テーブルモデルの例：

CREATE TABLE document_vectors (
  id BIGINT NOT NULL,
  embedding ARRAY<FLOAT> NOT NULL
)
DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 8
PROPERTIES ("replication_num" = "1");

2.1 Doris ANNでのCosine Similarityの使用​

ランキングメトリックがcosine similarityの場合は、このパターンを使用してください：

  1. 取り込み前に全てのベクトルを単位長に正規化します。
  2. metric_type="inner_product"でANNインデックスを構築します。
  3. inner_product_approximate(...)とORDER BY ... DESCでクエリを実行します。

理由：

  • cos(x, y) = (x · y) / (||x|| ||y||)
  • 正規化後は||x|| = ||y|| = 1となるため、cos(x, y) = x · y

これがDoris ANNでcosineランキングがinner productを通じて実装できる理由です。

3. エンドツーエンドワークフロー​

ステップ1: テーブルの作成​

2つのパターンのうちいずれかを選択できます：

  1. テーブル作成時にANNインデックスを定義する。
    • インデックスは取り込み中に構築されます。
    • ロード後のクエリ実行時間が高速です。
    • 取り込みスループットは低速です。
  2. 最初にテーブルを作成し、後でCREATE INDEXとBUILD INDEXを実行する。
    • 大規模なバッチインポートに適しています。
    • コンパクションと構築のタイミングをより細かく制御できます。

例（CREATE TABLEでインデックスを定義）：

CREATE TABLE document_vectors (
  id BIGINT NOT NULL,
  title VARCHAR(500),
  content TEXT,
  category VARCHAR(100),
  embedding ARRAY<FLOAT> NOT NULL,
  INDEX idx_embedding (embedding) USING ANN PROPERTIES (
    "index_type" = "hnsw",
    "metric_type" = "l2_distance",
    "dim" = "768"
  )
)
ENGINE = OLAP
DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 8
PROPERTIES ("replication_num" = "1");

ステップ 2: ANN Indexを設定する​

共通プロパティ:

  • index_type: hnsw、ivf、または ivf_on_disk
  • metric_type: l2_distance または inner_product
  • dim: ベクトル次元
  • quantizer: flat、sq8、sq4、pq (オプション)

HNSW固有:

  • max_degree (デフォルト 32)
  • ef_construction (デフォルト 40)

IVF固有:

  • nlist (デフォルト 1024; ivf と ivf_on_disk の両方で使用される)

例:

CREATE INDEX idx_embedding ON document_vectors (embedding) USING ANN PROPERTIES (
  "index_type" = "hnsw",
  "metric_type" = "l2_distance",
  "dim" = "768",
  "max_degree" = "64",
  "ef_construction" = "128"
);

Step 3: データのロード​

一括ワークロードの推奨順序:

  1. テーブルを作成（ANNインデックスなし、またはBUILD INDEXをまだ実行しない状態）
  2. データをバッチでインポート（Stream Load、S3 TVF、またはSDK）
  3. インデックスビルドをトリガー

本番環境では、Stream LoadやSDKバッチ挿入などのバッチロード手法を推奨します。

Step 4: インデックスのビルドと監視​

テーブル作成後にインデックスが作成された場合は、手動でBUILD INDEXを実行してください:

BUILD INDEX idx_embedding ON document_vectors;
SHOW BUILD INDEX WHERE TableName = "document_vectors";

ビルド状態にはPENDING、RUNNING、FINISHED、CANCELLEDが含まれます。

4. クエリパターン​

TopN検索​

SELECT id, title,
       l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
FROM document_vectors
ORDER BY dist
LIMIT 10;

範囲検索​

SELECT id, title
FROM document_vectors
WHERE l2_distance_approximate(embedding, [0.1, 0.2, ...]) < 0.5;

フィルターを使用した検索​

SELECT id, title,
       l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
FROM document_vectors
WHERE category = 'AI'
ORDER BY dist
LIMIT 10;

Doris はベクトル検索プランで事前フィルタリングを使用し、混合フィルタシナリオでの再現率の維持に役立ちます。

5. チューニングチェックリスト​

クエリ側パラメータ​

  • HNSW: hnsw_ef_search (高い再現率 vs 高いレイテンシ)
  • IVF: nprobe (または ivf_nprobe、バージョン/セッション変数による)

例:

SET hnsw_ef_search = 100;
SET nprobe = 128;
SET optimize_index_scan_parallelism = true;

ビルド側の推奨事項​

  1. 大規模データセットでは最終的なインデックス構築前にcompactionを実行する。
  2. 高いrecallを目標とする場合、過大なセグメントを避ける。
  3. 同じデータセットで複数のパラメータグループ（max_degree、ef_construction、ef_search）をベンチマークする。

キャパシティプランニング​

実用的なベースラインとして、dim * 4 bytes * row_countでベクターメモリを見積もり、その後ANN構造のオーバーヘッドを追加し、非ベクターカラムと実行オペレータ用にメモリヘッドルームを確保する。
10M/100Mスケールでの単一ノードおよび分散サイジングの参考については、Large-scale Performance Benchmarkを参照。

6. Index Operations​

一般的な管理SQL：

SHOW INDEX FROM document_vectors;
SHOW DATA ALL FROM document_vectors;
ALTER TABLE document_vectors DROP INDEX idx_embedding;

インデックスパラメータを変更する際は、削除と再作成のワークフローを使用し、その後インデックスを再構築してください。

7. トラブルシューティング​

インデックスが使用されない​

確認項目:

  1. インデックスが存在するか: SHOW INDEX
  2. 構築が完了しているか: SHOW BUILD INDEX
  3. 正しい関数を使用しているか: _approximate 関数を使用する

低い再現率​

確認項目:

  • HNSWパラメータ (max_degree, ef_construction, hnsw_ef_search)
  • IVF probe パラメータ (nprobe/ivf_nprobe)
  • セグメントサイズと圧縮後の再構築

高いレイテンシ​

確認項目:

  • コールドクエリ vs ウォームクエリの動作（インデックス読み込み）
  • 過度に大きな hnsw_ef_search
  • 並列スキャン設定
  • BEメモリ圧迫

データインポートエラー​

一般的な原因:

  • 次元の不一致 (dim vs 実際のデータ)
  • nullベクトル値
  • 無効な配列形式

8. Hybrid Search パターン​

同じテーブル内でANNと転置インデックスの両方を定義し、テキスト述語でフィルタリングしてベクトル距離で順序付けすることで、ANNとテキスト検索を組み合わせることができます。これは本番環境のRAGパイプラインでよく使われるアプローチです。