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

実践ガイド

このガイドでは、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におけるコサイン類似度の使用​

ランキングメトリックがコサイン類似度の場合、以下のパターンを使用してください：

  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でコサインランキングを内積により実装できる理由です。

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

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

以下の2つのパターンのうち1つを選択できます：

  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_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;

インデックスパラメータを変更する場合は、drop-and-recreateワークフローを使用してから、インデックスを再構築してください。

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

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

確認事項：

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

再現率が低い​

確認事項：

  • HNSWパラメータ（max_degree、ef_construction、hnsw_ef_search）
  • IVFプローブパラメータ（nprobe/ivf_nprobe）
  • セグメントサイズとコンパクション後の再構築

高いレイテンシ​

確認事項：

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

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

一般的な原因：

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

8. ハイブリッド検索パターン​

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