Agent Retrieval(旧称: ベクトル検索 2.0)は、ETag(エンティティ タグ)を使用したオプティミスティック同時実行制御(OCC)をサポートしています。ETag は、特定のデータ オブジェクト バージョンを表す不透明な識別子です。
リアルタイム API の更新や一括インポート ジョブなど、複数のプロセスが同じデータセットに対して同時にオペレーションを行うと、互いの変更が上書きされるリスクがあります(最後の書き込みが優先されるシナリオ)。ETag を使用すると、データの完全性を保証し、最後に読み取ってから別のプロセスでレコードが変更されていないことを確認できます。
ETag の仕組み
読み取り: データ オブジェクトを作成または取得すると、サーバーはデータ オブジェクトの正確なバージョンを表す ETag 文字列を返します。
変更: データ オブジェクトをローカルで変更します。
書き込み: 最初に受信した ETag を含む update リクエストまたは delete リクエストを Agent Retrieval に返します。
検証: サーバーは、提供された ETag がデータベースに保存されている現在の ETag と一致するかどうかを確認します。
- 一致した場合、オペレーションは成功し、サーバーは更新されたデータ オブジェクトの新しい ETag を返します。
- 一致しない場合、オペレーションはブロックされ、サーバーは
ABORTEDエラー(HTTP 409 Conflict)を返します。
ETag の取得
同時実行制御に ETag を使用する前に、システムから最新バージョンを取得する必要があります。
ETag は次の方法で取得できます。
リアルタイム API レスポンス:
DataObjectServiceで読み取りメソッドまたは書き込みメソッド(GetDataObject、ListDataObjects、CreateDataObject、UpdateDataObjectなど)を呼び出すと、返される Data Object リソースに現在の ETag が含まれます。Import API の出力:
ImportDataObjectsを呼び出すときに、GcsImportConfigフィールドoutput-uriで Cloud Storage の URI 接頭辞を指定できます。インポート ジョブが成功すると、インポートされたデータ オブジェクトの ID と ETag を含む各行を含む JSONL ファイルが作成されます。形式は次のとおりです。{ "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"}Export API(
ExportDataObjects) - Agent Retrieval から Cloud Storage にデータをエクスポートすると、生成される正規 JSONL データファイルには、エクスポートされたすべてのデータ オブジェクトの ETag が含まれます。
データ オブジェクトの作成
CreateDataObject または BatchCreateDataObjects を呼び出す場合、データ オブジェクトがまだ存在しないため、リクエストで指定した ETag は無視されます。
作成リクエストが成功すると、サーバーは新しく生成された ETag を、返された Data Object リソースに含めます。
データ オブジェクトの更新
UpdateDataObject または BatchUpdateDataObjects を使用して既存のレコードを安全に更新するには、リクエストの Data Object リソース内に ETag を直接含めます。
{
"name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
"etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d",
"data": {
"genre": ["science-fiction", "thriller", "action"]
}
}
データ オブジェクトの削除
DeleteDataObject メソッドと BatchDeleteDataObjects メソッドは、ペイロードとして完全な Data Object リソースを受け取らないため、ETag は DeleteDataObjectRequest の最上位フィールドとして指定する必要があります。
{
"name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
"etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"
}
一括取り込み(ImportDataObjects)で ETag を使用する
ImportDataObjects API を使用すると、非同期で実行され、リアルタイムの更新と競合する可能性があります。インポート中に同時実行制御を適用するには、JSONL インポート ファイルに etag フィールドを含めます。
Gemini Enterprise Agent Platform のベクトル検索は、レコードごとに競合解決モードを自動的に検出します。
ETag(OCC)を使用する: ETag が指定され、サーバーの現在のバージョンと一致しない場合、特定のレコードのインポートは失敗します。失敗は指定したエラー URI に記録されますが、インポート ジョブの残りの部分は続行されます。
ETag なし: ETag が省略されている場合、レコードが取り込まれ、既存のデータが上書きされます。これにより、同時実行制御が不要な場合にスループットが最大化されます。
JSONL 形式
次の例に示すように、インポート ファイルの JSON オブジェクトのルートレベルに ETag を含めます。
{ "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d", "data":{ "genre": ["science-fiction", "thriller"] }, "vectors": { ... } }
同時実行エラーの処理
オペレーションが ETag チェックに失敗すると、API は ABORTED(HTTP 409 Conflict)エラーコードを返します。
推奨されるエラー処理:
ABORTED エラーが発生した場合、アプリケーションは次の処理を行う必要があります。
サーバーからデータ オブジェクトの最新バージョンを再取得します。
新しく取得したデータと目的の更新との間のビジネス ロジックの競合を解決します。
新しい ETag を使用してオペレーションを再試行します。
次のステップ
- コレクション インデックスについて学習する。
- データ オブジェクトをクエリして検索する方法を確認する。