このページでは、Gemini Enterprise Agent Platform の RAG Engine が RagManagedDb を使用する方法について説明します。これは、ドキュメントのベクトル表現の保存と管理に使用されるエンタープライズ対応のベクトル データベースです。ベクトル データベースは、指定されたクエリに対するドキュメントの意味的な類似性に基づいて、関連するドキュメントを取得するために使用されます。
また、このページでは CMEK を実装する方法についても説明します。
取得戦略を管理する
RagManagedDb は、RAG のユースケースをサポートするために、次の取得戦略を提供します。
| 取得戦略 | 説明 | |
|---|---|---|
| k 個の最近傍（KNN）（デフォルト） | RAG コーパス内のすべてのデータポイントを比較して、正確な最近傍を見つけます。RAG コーパスの作成時に戦略を指定しない場合、KNN がデフォルトの取得戦略として使用されます。 |
|
| 近似最近傍探索（ANN） | 近似手法を使用して、KNN 手法よりも高速で類似した近傍を検索します。 |
|
KNN RagManagedDb を使用して RAG コーパスを作成する
このコードサンプルは、KNN RagManagedDb を使用して RAG コーパスを作成する方法を示しています。
Python
from vertexai.preview import rag
import vertexai
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)
vector_db = rag.RagManagedDb(retrieval_strategy=rag.KNN())
rag_corpus = rag.create_corpus(
display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))
REST
次の変数を置き換えます。
- PROJECT_ID: プロジェクト ID。
- LOCATION: リクエストを処理するリージョン。
- CORPUS_DISPLAY_NAME: RAG コーパスの表示名。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
"display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
"vector_db_config": {
"ragManagedDb": {
"knn": {}
}
}
}'
ANN RagManagedDb を使用して RAG コーパスを作成する
ANN 機能を提供するために、RagManagedDb はツリーベースの構造を使用してデータをパーティショニングし、高速な検索を可能にします。最適な再現率とレイテンシを実現するには、このツリーの構造をデータサイズと分布に合わせて実験的に構成する必要があります。RagManagedDb を使用すると、ツリーの tree_depth と leaf_count を構成できます。
tree_depth は、ツリー内のレイヤまたはレベルの数を決定します。次のガイドラインに従って操作してください。
- RAG コーパスに約 10,000 個の RAG ファイルがある場合は、この値を 2 に設定します。
- RAG ファイルがそれより多い場合は、3 に設定します。
tree_depthが指定されていない場合、RAG Engine はこのパラメータにデフォルト値の 2 を割り当てます。
leaf_count は、ツリーベースの構造のリーフノードの数を決定します。各リーフノードには、密接に関連するベクトルのグループと、対応するセントロイドが含まれます。次のガイドラインに従って操作してください。
- 推奨値は
10 * sqrt(num of RAG files in your RAG corpus)です。 指定しない場合、RAG Engine はこのパラメータにデフォルト値の 500 を割り当てます。
Python
from vertexai.preview import rag
import vertexai
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
TREE_DEPTH = YOUR_TREE_DEPTH # Optional: Acceptable values are 2 or 3. Default is 2.
LEAF_COUNT = YOUR_LEAF_COUNT # Optional: Default is 500.
# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)
ann_config = rag.ANN(tree_depth=TREE_DEPTH, leaf_count=LEAF_COUNT)
vector_db = rag.RagManagedDb(retrieval_strategy=ann_config)
rag_corpus = rag.create_corpus(
display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))
REST
次の変数を置き換えます。
- PROJECT_ID: プロジェクト ID。
- LOCATION: リクエストを処理するリージョン。
- CORPUS_DISPLAY_NAME: RAG コーパスの表示名。
- TREE_DEPTH: ツリーの深さ。
- LEAF_COUNT: リーフ数。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME
TREE_DEPTH=TREE_DEPTH
LEAF_COUNT=LEAF_COUNT
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
"display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
"vector_db_config": {
"ragManagedDb": {
"ann": {
"tree_depth": '"${TREE_DEPTH}"',
"leaf_count": '"${LEAF_COUNT}"'
}
}
}
}'
ANN RagManagedDb へのデータのインポート
ImportRagFiles API または UploadRagFile API を使用して、データを ANN RagManagedDb にインポートできます。ただし、KNN 取得戦略とは異なり、ANN アプローチでは、最適な再現率を実現するために、基盤となるツリーベースのインデックスを少なくとも 1 回再構築する必要があります。また、大量のデータをインポートした後に再構築することもできます。RAG Engine で ANN インデックスを再構築するには、ImportRagFiles API リクエストで rebuild_ann_index を true に設定します。
次の点が重要です。
- RAG コーパスをクエリする前に、ANN インデックスを少なくとも 1 回再構築する必要があります。
- 各ロケーションのプロジェクトでサポートされる同時インデックス再構築は 1 つのみです。
ローカル ファイルを RAG コーパスにアップロードするには、RAG ファイルをアップロードするをご覧ください。RAG コーパスにデータをインポートして ANN インデックスの再構築をトリガーするには、Cloud Storage からインポートする方法を示す次のコードサンプルをご覧ください。サポートされているデータソースについては、RAG でサポートされるデータソースをご覧ください。
Python
from vertexai.preview import rag
import vertexai
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]
REBUILD_ANN_INDEX = REBUILD_ANN_INDEX # Choose true or false.
# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)
corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
corpus_name=corpus_name,
paths=PATHS,
rebuild_ann_index=REBUILD_ANN_INDEX
)
# Wait for the import to complete.
await response.result()
REST
GCS_URI=GCS_URI
REBUILD_ANN_INDEX=<true/false>
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${CORPUS_ID}/ragFiles:import \
-d '{
"import_rag_files_config": {
"gcs_source": {
"uris": '\""${GCS_URI}"\"',
},
"rebuild_ann_index": '${REBUILD_ANN_INDEX}'
}
}'
暗号化を管理する
RAG Engine は、保存データの暗号化方法を管理するための堅牢なオプションを提供します。デフォルトでは、RagManagedDb 内のすべてのユーザーデータが Google-owned and Google-managed encryption keyを使用して暗号化されます。これはデフォルトの設定です。このデフォルト設定により、特定の構成を必要とせずにデータの安全性を確認できます。
暗号化に使用される鍵をより詳細に制御する必要がある場合は、RAG Engine で顧客管理の暗号鍵（CMEK）がサポートされています。CMEK を使用すると、Cloud Key Management Service（KMS）内で管理されている暗号鍵を使用して、RAG コーパスデータを保護できます。
RAG コーパスの CMEK の制限事項については、Gemini Enterprise Agent Platform の RAG Engine の CMEK の制限事項をご覧ください。
KMS 鍵を設定して権限を付与する
CMEK で暗号化された RAG コーパスを作成する前に、Google Cloud KMS で暗号鍵を設定し、この鍵を使用するために必要な権限を RAG Engine サービス アカウントに付与する必要があります。
前提条件
次の設定手順を行うには、KMS 鍵と RAG コーパスを作成する Google Cloud プロジェクトで、ユーザー アカウントに適切な Identity and Access Management（IAM）権限があることを確認します。通常は、Cloud KMS 管理者のロール（roles/cloudkms.admin）などのロールが必要です。
API を有効にする
Cloud Key Management Service API を有効にするには、次の操作を行います。
- Google Cloud コンソールに移動します。
- 鍵を管理するプロジェクトを選択し、RAG コーパスを作成します。
- 検索バーに「キー管理」と入力し、[キー管理] サービスを選択します。
- API が有効になっていない場合は、[有効にする] をクリックします。API が完全にプロビジョニングされるまで数分かかることがあります。
KMS キーリングと鍵を作成する
キーリングを作成する手順は次のとおりです。
[キー管理] セクションで、[キーリングを作成] をクリックします。
次の情報を入力します。
- [キーリング名]: キーリングの一意の名前（rag-engine-cmek-keys など）を入力します。
- [ロケーション タイプ]: [リージョン] を選択します。Cloud Key Management Service のキーリングは、CMEK で RAG コーパスを暗号化するときに使用する RAG Engine エンドポイントと同じリージョンに存在する必要があります。
- [ロケーション]: 選択したリージョン（
us-central1など）を選択します。このリージョンは、RAG Engine リソースが存在するリージョンと一致していることが理想的です。
[作成] をクリックします。
キーリング内に鍵を作成する手順は次のとおりです。
キーリングを作成すると、プロンプトが表示されるか、[鍵を作成] に移動できます。
次の情報を入力します。
- 鍵名: 鍵の一意の名前（
my-rag-corpus-keyなど）を入力します。 - 保護レベル: 保護レベル（ソフトウェアまたは HSM）を選択します。ハードウェア格納型キーが必要な場合は、[HSM] を選択します。
- 目的: [対称暗号化 / 復号] を選択します。これは CMEK に必要です。
- 鍵マテリアルのソース: [生成された鍵] を選択します。
- ローテーション期間: 省略可。使用をおすすめします。90 日ごとなど、組織のセキュリティ ポリシーに従って鍵のローテーション スケジュールを構成します。
- 鍵名: 鍵の一意の名前（
[作成] をクリックします。
鍵のリソース名をコピーする手順は次のとおりです。
鍵が作成されたら、その詳細ページに移動します。
リソース名を見つけます。形式は
projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1です。リソース名をコピーし、
/cryptoKeyVersions/VERSION_NUMBER部分を削除します。正しい形式のリソース名はprojects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAMEです。
RAG Engine サービス エージェントに権限を付与する
RAG Engine が KMS 鍵を使用してデータを暗号化および復号するには、そのサービス エージェントに特定の鍵に対する適切な権限が必要です。
RAG Engine サービス エージェントを特定する手順は次のとおりです。
プロジェクトの Google Cloud コンソールで、[IAM と管理] > [IAM] ページに移動します。
[Identity and Access Management] ページで、[Google 提供のロール付与を含める] チェックボックスをオンにします。
プリンシパル リストのフィルタまたは検索バーで、RAG Engine サービス エージェントを検索します。パターン
service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.comに従います。YOUR_PROJECT_NUMBER は、使用する Google Cloud プロジェクト番号に置き換えます。
RAG Engine サービス エージェントがまだ存在していない場合は、次の操作を行ってサービス エージェントの作成をトリガーします。
Cloud Shell またはコマンドラインで次のコマンドを実行します。
gcloud beta services identity create --service=aiplatform.googleapis.com \ --projects=PROJECT_IDまたは、REST API 呼び出しを送信します。
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8" -d "" "https://serviceusage.googleapis.com/v1beta1/projects/PROJECT_ID/services/aiplatform.googleapis.com:generateServiceIdentity"RAG Engine サービス エージェントが作成されたことを確認します。
KMS 鍵に対する権限を付与する手順は次のとおりです。
Google Cloud コンソールの [鍵管理サービス] に戻ります。
作成した鍵を含むキーリングを選択します。
作成した特定の鍵を選択します。
鍵の詳細ページで、[権限] タブに移動します。
[プリンシパルを追加] をクリックします。
[新しいプリンシパル] フィールドに、RAG Engine サービス エージェントのメールアドレスを入力します。
[ロールを選択] プルダウンで、Cloud KMS CryptoKey の暗号化 / 復号ロール（
roles/cloudkms.cryptoKeyEncrypterDecrypter）を選択します。このロールにより、サービス エージェントに暗号化と復号のオペレーションで鍵を使用するために必要な権限が付与されます。[保存] をクリックします。
顧客管理の暗号化を使用して RAG コーパスを作成する
このコードサンプルは、顧客管理の暗号鍵（CMEK）で暗号化された RAG コーパスを作成する方法を示しています。
次のコードサンプルの変数を置き換えます。
Python
import vertexai
from google.cloud import aiplatform
from vertexai import rag
from google.cloud.aiplatform_v1.types.encryption_spec import EncryptionSpec
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME
vertexai.init(project=PROJECT_ID)
rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, encryption_spec=EncryptionSpec(kms_key_name=KMS_KEY_NAME))
REST
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
"display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
"encryption_spec" : {
"kms_key_name" : '\""${KMS_KEY_NAME}"\"'
}
}'
割り当て
Gemini Enterprise Agent Platform の RAG Engine などの Gemini Enterprise Agent Platform サービスで CMEK を使用する場合、プロジェクトごと、リージョンごとに使用できる一意の Cloud KMS 鍵の数に割り当てがあります。この割り当ては、指標 aiplatform.googleapis.com/in_use_customer_managed_encryption_keys によって追跡されます。
新しい一意の KMS 鍵を使用して、プロジェクトとリージョン内に RAG コーパスなどのリソースを作成するたびに、KMS 鍵がこの割り当ての 1 単位を消費します。この割り当て単位は、その特定の鍵を使用しているリソースが削除されても解放されません。
現在の上限を超える一意の鍵が必要な場合は、選択したリージョンの aiplatform.googleapis.com/in_use_customer_managed_encryption_keys の割り当ての増加をリクエストする必要があります。
割り当ての増加をリクエストする方法については、 Google Cloud コンソールで割り当てを表示して編集するをご覧ください。
次のステップ
- RagManagedDb の詳細については、RagManagedDb についてをご覧ください。
- Google ドライブまたは Cloud Storage からファイルとフォルダをインポートするには、RAG ファイルのインポートの例をご覧ください。
- RAG ファイルを一覧表示するには、RAG ファイルのリストの例をご覧ください。