このページは Cloud Translation API によって翻訳されました。

RAG Engine で Pinecone を使用する

このページでは、RAG コーパスを Pinecone データベースに接続する方法について説明します。

このノートブック RAG Engine with Pinecone を使用して、このチュートリアルに沿って作業することもできます。

RAG Engine で Pinecone データベースインスタンスを使用して、インデックスを作成し、ベクトルベースの類似性検索を実行できます。類似性検索は、検索しているテキストに類似するテキストを見つける方法です。この場合、エンベディングモデルを使用する必要があります。エンベディングモデルは、比較対象のテキストごとにベクトルデータを生成します。類似性検索は、グラウンディングのためのセマンティックコンテキストを取得し、LLM から最も正確なコンテンツを返すために使用されます。

RAG Engine を使用すると、フルマネージドベクトルデータベースインスタンスを引き続き使用できます（プロビジョニングはお客様の責任で行っていただく必要があります）。RAG Engine は、ストレージ、インデックス管理、検索にベクトルデータベースを使用します。

RAG Engine で Pinecone を使用するかどうかを検討する

次の点を検討して、Pinecone データベースが RAG アプリケーションに最適かどうかを判断してください。

Pinecone データベースインスタンスのスケーリングを作成、構成、管理する必要があります。
RAG Engine は、インデックスのデフォルトの名前空間を使用します。この Namespace が他の方法で変更できないことを確認します。
Pinecone API キーを指定する必要があります。これにより、RAG Engine が Pinecone データベースとやり取りできるようになります。RAG Engine は、Pinecone API キーの保存と管理を行いません。代わりに、次のことを行います。
- キーを Google Cloud Secret Manager に保存します。
- プロジェクトのサービスアカウントにシークレットへのアクセス権を付与します。
- RAG Engine に、シークレットのリソース名へのアクセス権を付与します。
- RAG コーパスを操作すると、RAG Engine はサービスアカウントを使用してシークレットリソースにアクセスします。
RAG コーパスと Pinecone インデックスには 1 対 1 のマッピングがあります。この関連付けは、CreateRagCorpus API 呼び出しまたは UpdateRagCorpus API 呼び出しの一部として行われます。

Pinecone インデックスを作成する

Pinecone インデックスを作成するには、次の手順を実施する必要があります。

インデックスを RAG コーパスと互換性を持たせるようにインデックスで指定する必要があるインデックス構成については、Pinecone のクイックスタートガイドをご覧ください。
次の理由から、Pinecone インデックスのロケーションは、RAG Engine を使用する場所と同じか、または近い場所に配置する必要があります。
- レイテンシを低く維持したい。
- 適用される法律で定められたデータ所在地に関する要件を満たす必要がある。

Pinecone インデックスの作成時に、RAG Engine で使用するエンベディングディメンションを指定します。次の表に、ディメンションサイズとディメンションサイズの場所を示します。

モデル	ディメンションのサイズ
ファーストパーティの Gecko	768
ファインチューニングされたファーストパーティ Gecko	768
E5	OSS エンベディングモデルを使用するをご覧ください。

サポートされている次の距離指標のいずれかを選択します。
- cosine
- dotproduct
- euclidean
省略可: Pod ベースのインデックスを作成する場合は、pod.metadata_config.indexed フィールドに file_id を指定する必要があります。詳細については、選択的メタデータインデックス処理をご覧ください。

Pinecone API キーを作成する

RAG Engine は、認証と認可に API キーを使用して Pinecone インデックスに接続します。Pinecone プロジェクトで API キーベースの認証を構成するには、Pinecone の認証に関する公式ガイドに沿って操作する必要があります。

API キーを Secret Manager に保存する

API キーには、個人を特定できる機密情報（SPII）が保持されます。この情報には法的要件が適用されます。SPII データが漏洩または不正使用された場合、個人に重大なリスクや損害が及ぶ可能性があります。RAG Engine を使用する際の個人に対するリスクを最小限に抑えるため、API キーを保存して管理しないでください。また、暗号化されていない API キーを共有しないようにします。

SPII を保護するには、次の操作を行う必要があります。

API キーを Secret Manager に保存します。
RAG Engine サービスアカウントにシークレットへの権限を付与し、シークレットリソースレベルでアクセス制御を管理します。
1. プロジェクトの権限に移動します。
2. [Google 提供のロール付与を含める] オプションを有効にします。
3. サービスアカウントを見つけます。形式は次のとおりです。
  
  service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
4. サービスアカウントのプリンシパルを編集します。
5. Secret Manager Secret Accessor ロールをサービスアカウントに追加します。
RAG コーパスの作成または更新時に、シークレットリソース名を RAG Engine に渡し、シークレットリソース名を保存します。

Pinecone インデックスに API リクエストを送信すると、RAG Engine は各サービスアカウントを使用して、プロジェクトの Secret Manager のシークレットリソースに対応する API キーを読み取ります。

RAG Engine サービスアカウントをプロビジョニングする

プロジェクトで最初の RAG コーパスを作成すると、RAG Engine は専用のサービスアカウントを作成します。サービスアカウントは、プロジェクトの [Identity and Access Management] ページで確認できます。

サービスアカウントの形式は次のとおりです。

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

次に例を示します。

service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

RAG コーパスを準備する

Pinecone インデックスを RAG Engine で使用するには、作成時にインデックスを RAG コーパスに関連付ける必要があります。関連付けが完了すると、このバインディングは RAG コーパスの存続期間中は永続的になります。関連付けは、CreateRagCorpus API または UpdateRagCorpus API を使用して行えます。

関連付けが完了していると見なされるようにするには、RAG コーパスに次の 3 つのキーフィールドを設定する必要があります。

rag_vector_db_config.pinecone: このフィールドは、RAG コーパスに関連付けるベクトルデータベースの選択に役立ちます。このフィールドは、CreateRagCorpus API 呼び出し時に設定する必要があります。設定されていない場合、デフォルトのベクトルデータベースの選択肢 RagManagedDb が RAG コーパスに割り当てられます。
rag_vector_db_config.pinecone.index_name: RAG コーパスで使用される Pinecone インデックスの作成に使用される名前。名前は CreateRagCorpus 呼び出し時に設定することも、UpdateRagCorpus API 呼び出し時に指定することもできます。
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: Secret Manager に保存されているシークレットの完全なリソース名。ここには Pinecone API キーが含まれています。名前は CreateRagCorpus 呼び出し時に設定することも、UpdateRagCorpus API 呼び出し時に指定することもできます。このフィールドを指定しないと、RAG コーパスにデータをインポートできません。
このフィールドの形式は次のとおりです。
projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

RAG コーパスを作成する

権限が設定されている Pinecone インデックス名とシークレットリソース名にアクセスできる場合は、RAG コーパスを作成して Pinecone インデックスに関連付けることができます。これは、このサンプルコードで示されています。

RAG コーパスを初めて作成する場合、サービスアカウント情報は準備されていません。ただし、これらのフィールドは省略可能で、UpdateRagCorpus API を使用して RAG コーパスに関連付けることができます。

サービスアカウント情報を指定せずに RAG コーパスを作成する方法の例については、インデックス名または API キーなしで RAG コーパスを作成するをご覧ください。

Python

このサンプルを試す前に、Vertex AI クイックスタート: クライアントライブラリの使用にある Python の設定手順を完了してください。詳細については、Vertex AI Python API のリファレンスドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# pinecone_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.EmbeddingModelConfig(
    publisher_model="publishers/google/models/text-embedding-004"
)

# Configure Vector DB
vector_db = rag.Pinecone(
    index_name=pinecone_index_name,
    api_key=pinecone_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    embedding_model_config=embedding_model_config,
    vector_db=vector_db,
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

REST

   # Set your project ID under which you want to create the corpus
   PROJECT_ID = "YOUR_PROJECT_ID"

   # Choose a display name for your corpus
   CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

   # Set your Pinecone index name
   PINECONE_INDEX_NAME=YOUR_INDEX_NAME

   # Set the full resource name of your secret. Follows the format
   # projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
   SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

   # Call CreateRagCorpus API with all the Vector DB information.
   # You can also add the embedding model choice or set other RAG corpus parameters on
   # this call per your choice.
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
         "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
         "rag_vector_db_config" : {
            "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
            "api_auth": {"api_key_config":
                  {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
            }
         }
      }'

   # To poll the status of your RAG corpus creation, get the operation_id returned in
   # response of your CreateRagCorpus call.
   OPERATION_ID="YOUR_OPERATION_ID"

   # Poll Operation status until done = true in the response.
   # The response to this call will contain the ID for your created RAG corpus
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

インデックス名または API キーなしで RAG コーパスを作成する

初めての RAG コーパスで、サービスアカウントの詳細にアクセスできない場合や、Pinecone インデックスのプロビジョニング手順を完了していない場合でも、RAG コーパスを作成できます。その後、RAG コーパスを空の Pinecone 構成に関連付けて、詳細を後で追加できます。

次の点を考慮する必要があります。

インデックス名と API キーシークレット名を指定しない場合、ファイルは RAG コーパスにインポートできません。
RAG コーパスのベクトルデータベースとして Pinecone を選択した場合、後で別のデータベースに切り替えることはできません。

このコードサンプルは、Pinecone インデックス名または API シークレット名を指定しなくても、Pinecone で RAG コーパスを作成する方法を示しています。不足している情報は後で UpdateRagCorpus API を使用して指定します。

Python

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone()

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST

# Set your project ID under which you want to create the corpus
PROJECT_ID = "YOUR_PROJECT_ID"

# Choose a display name for your corpus
CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

# Call CreateRagCorpus API with all the Vector DB information.
# You can also add the embedding model choice or set other RAG corpus parameters on
# this call per your choice.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "rag_vector_db_config" : {
         "pinecone": {}
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

RAG コーパスを更新する

UpdateRagCorpus API を使用すると、ベクトルデータベースの構成を更新できます。Pinecone インデックス名と API キーシークレットバージョンが設定されていない場合は、Pinecone API を使用してフィールドを更新できます。ベクトルデータベースの選択を更新することはできません。API キーのシークレットは省略可能です。ただし、API キーシークレットを指定しない場合でも、RAG コーパスにデータをインポートできます。

フィールド	可変性	必須または省略可
`rag_vector_db_config.vector_db`	選択した後は変更不可。	必須
`rag_vector_db_config.pinecone.index_name`	RAG コーパスにフィールドを設定すると変更不可になります。	必須
`rag_vector_db_config.api_auth.api_key_config.api_key_secret_version`	変更可。API キーを設定すると、そのキーを削除することはできません。	省略可

Python

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone(index_name=)

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST

# Set your project ID for the corpus that you want to create.
PROJECT_ID = "YOUR_PROJECT_ID"

# Set your Pinecone index name
PINECONE_INDEX_NAME=YOUR_INDEX_NAME

# Set the full resource name of your secret. Follows the format
# projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

# Call UpdateRagCorpus API with the Vector DB information.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "rag_vector_db_config" : {
         "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
         "api_auth": {"api_key_config":
               {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
         }
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

次のステップ

エンベディングモデルの選択の詳細については、RAG Engine でエンベディングモデルを使用するをご覧ください。
ファイルのインポートの詳細については、RAG ファイルをインポートするをご覧ください。

RAG Engine で Pinecone を使用する

RAG Engine で Pinecone を使用するかどうかを検討する

Pinecone インデックスを作成する

Pinecone API キーを作成する

API キーを Secret Manager に保存する

RAG Engine サービス アカウントをプロビジョニングする

RAG コーパスを準備する

RAG コーパスを作成する

Python

REST

インデックス名または API キーなしで RAG コーパスを作成する

Python

REST

RAG コーパスを更新する

Python

REST

次のステップ

RAG Engine サービスアカウントをプロビジョニングする