Elasticsearch:ベクトルクラスターリコールモード

単一のスライス重心の登録

次のリクエストは、スライス cluster-a の重心を登録します：

PUT /_slice_collection/products/slices/cluster-a
{
  "vector": [0.9, 0.1]
}

HTTP 応答が成功しても、重心が作成されたことは保証されません。「登録結果の確認 (単一およびバッチ)」で説明されているように、トップレベルの errors フィールドと、items 内のすべての要素の result を確認してください。

スライス重心のバッチ登録

オフラインのクラスタリングジョブは通常、複数のベクトルクラスターの重心を同時に生成します。バッチ API を使用して、1 つのリクエストでそれらを登録できます：

PUT /_slice_collection/products/slices
{
  "slices": [
    { "slice": "cluster-b", "vector": [0.1, 0.9] },
    { "slice": "cluster-c", "vector": [0.6, 0.4] }
  ]
}

各アイテムのスライス名は slice または slice_id で指定できますが、同じアイテム内ではどちらか一方しか使用できません。1 回のリクエストで最大 20,480 個のスライスを登録でき、スライス名はリクエスト内で一意である必要があります。

登録結果の確認 (単一およびバッチ)

単一登録 API とバッチ登録 API の両方で、HTTP 200 応答においてアイテムレベルのエラーを報告できます。これには、重心の次元と config.vector_dims の不一致などが含まれます。HTTP リクエストが成功したからといって、すべてのベクトルクラスターが正常に登録されたわけではありません。2xx 以外の応答を処理することに加えて、トップレベルの errors フィールドと、items 内のすべての要素の result を確認する必要があります：created は重心が作成されたこと、updated は重心が更新されたこと、noop は内容が変更されなかったこと、failed は失敗したことを示します。失敗したアイテムには文字列型の error フィールドが含まれ、成功したアイテムに含まれる backing_index フィールドは含まれません。

{
  "acknowledged": true,
  "errors": false,
  "items": [
    {
      "slice_id": "cluster-b",
      "result": "created",
      "backing_index": ".sc-products-...-00000"
    },
    {
      "slice_id": "cluster-c",
      "result": "created",
      "backing_index": ".sc-products-...-00001"
    }
  ]
}

各重心の次元は config.vector_dims と一致する必要があります。重心のないスライスは明示的にアクセスできますが、候補スライスの自動選択には参加しません。同じ名前のスライスを再度登録すると、重心が変更された場合は updated が返され、変更されていない場合は noop が返されます。どちらの場合も、すでに書き込まれているドキュメントは移動されません。

routing_field を使用したドキュメントの書き込み

routing_field を設定すると、システムはドキュメントのトップレベルフィールドからスライスを読み取るため、_slice を渡す必要はなくなります：

PUT /products/_doc/product-1
{
  "cluster_id": "cluster-a",
  "name": "example-product",
  "embedding": [0.92, 0.08]
}

明示的に _slice=cluster-a を指定することもできます。また、互換性のある API は routing=cluster-a も受け入れます。スライスを明示的に指定する場合、その値は routing_field (この例では cluster_id) で指定されたドキュメントフィールドの値と一致する必要があります。一致しない場合、HTTP 400 エラーが返されます。

ドキュメントの更新

routing_field を設定した後、スクリプトによる更新はサポートされません。一部のフィールドのみを変更するには、doc リクエストボディを持つ _update API を使用し、一致する _slice を明示的に指定します。古い値から新しい値を計算する必要がある場合は、アプリケーションで古い値を読み取り、新しい値を計算して書き戻します。他のリクエストによる更新を上書きしないように、同時実行制御には if_seq_no と if_primary_term を使用してください。

Copy または Branch 後のドキュメントの書き戻し

Copy 機能と Branch 機能はどちらも、ドキュメント内の routing_field の値を保持します。後でドキュメントを宛先スライスに書き戻す場合は、宛先を明示的に指定し、書き込まれるドキュメントのルーティングフィールドが宛先と一致することを確認してください。これにより、ドキュメントがソーススライスに書き戻されたり、検証エラーがトリガーされたりするのを防ぎます。詳細については、「データコピーのセマンティクス」をご参照ください。

routing_field を使用しないドキュメントの書き込み

routing_field が設定されていない場合、データの書き込みは名前空間モードと同じ方法で行われます。つまり、すべての書き込みリクエストまたは Bulk アイテムは _slice を明示的に指定する必要があります。Bulk、リフレッシュの可視性、_update_by_query、_delete_by_query などの他の書き込み動作については、「ドキュメントの書き込み、読み取り、クエリ操作」をご参照ください。

クエリの実行

クエリベクトルを使用して、候補スライスを自動的に選択します：

POST /products/_search?query_slice_count=2
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.91, 0.09],
    "k": 10,
    "num_candidates": 100
  }
}

timed_out=false と _shards.failed=0 であること、および hits.hits にこの例で書き込まれた product-1 が含まれていることを確認します。

次の表は、候補スライスの自動選択に関するパラメーターを説明しています：

リクエストは、設定されたパスによって選択された 1 つのクエリベクトルのみを使用して、リクエスト全体の候補スライスを決定します。複数の KNN 句が個別にスライスを選択し、選択されたスライスセットの UNION を取ることはありません。他の KNN クエリやハイブリッドクエリ句も、この候補スライスのセットに制限されます。

query_slice_count が明示的にゼロ以外の値に設定されている場合、その値は 1 から max_query_slice_count の範囲内である必要があります。そうでない場合、HTTP 400 エラーが返されます。

リクエストが _slice または互換性のある routing パラメーターを明示的に指定する場合、クエリは指定された範囲内で実行されます。これらのスライスが重心を登録しているかどうかは関係ありません。重心の要件は、候補スライスの自動選択にのみ適用されます。つまり、登録された重心を持つスライスのみが考慮されます。

クラスター設定 apack.slice_collection.search.default_to_all_slices が無効 (デフォルト) の場合、設定されたパスにクエリベクトルがないと HTTP 400 エラーが返されます。この場合、_slice を明示的に指定してください。この設定を有効にすると、クエリベクトルが見つからない場合はすべてのスライスをクエリするフォールバック動作になります。通常の運用クエリでは、この設定を無効のままにし、全スライスフォールバックに依存しないでください。無効なパス、クエリベクトルの提供に query_vector_builder を使用した場合、またはクエリベクトルの次元が vector_dims と一致しない場合は、依然として HTTP 400 エラーが返され、この設定ではこれらのエラーをバイパスできません。この設定の詳細については、「クエリ範囲の指定」をご参照ください。

Count API (_count) のリクエストボディには、スライスの自動選択に必要なインラインクエリベクトルが含まれていないため、スライスを自動的に選択できません。全スライスフォールバックがデフォルトで無効になっている間は、_slice を明示的に指定する必要があります。クエリベクトルを含まない他のクエリも、範囲を明示的に指定する必要があります。

既知の候補スライスのプレウォーム (任意)

どのクラスターにアクセスされるかを予測できる場合は、事前にプレウォームすることで、コールドデータに対する最初のクエリのレイテンシーを短縮できます。この例では、cluster-a には 1 つのドキュメントしか書き込まれていないため、一度プレウォームできます：

POST /products/_warm_slice?_slice=cluster-a&wait_for_completion=true&timeout=60s

リクエストが成功し、_shards.failed=0 であることを確認します。_shards.total=0 の場合は、まずクエリシャードが利用可能であることを確認し、実際のクエリを使用してデータが検索可能であることを確認してから、必要に応じてプレウォームを再試行してください。この例ではデータはすでに書き込まれています。同期待機は、この例を検証するためにのみ使用されます。本番環境では、予測可能なアクセス範囲を事前に非同期でプレウォームし、同時実行数を制御してください。クラスターの自動選択クエリの前に、すべてのクラスターを反復処理してプレウォームしないでください。詳細については、「スライスキャッシュのウォームアップ」をご参照ください。