Vertex AI RAG Engine でデータ取り込みを使用する

このページでは、サポートされているデータソース(Cloud Storage、Google ドライブ、Slack、Jira、SharePoint など)を使用してデータ取り込みを行う方法と、Vertex AI RAG Engine でそのデータを使用する方法について説明します。Import RagFiles API は、これらのデータソースにデータコネクタを提供します。

RAG でサポートされるデータソース

サポートされているデータソースは次のとおりです。

  • ローカル ファイルをアップロードする: upload_file(最大 25 MB)を使用した単一ファイルのアップロード。これは同期呼び出しです。
  • Cloud Storage: Cloud Storage からファイルをインポートします。
  • Google ドライブ: Google ドライブからディレクトリをインポートします。

    サービス アカウントには、ファイルをインポートするための適切な権限が付与されている必要があります。それ以外の場合は、ファイルはインポートされず、エラー メッセージも表示されません。ファイルサイズの上限の詳細については、サポートされているドキュメント タイプをご覧ください。

    認証し、権限を付与するには、次の手順を行います。

    1. Google Cloud プロジェクトの IAM ページに移動します。
    2. [Google 提供のロール付与を含む] を選択します。
    3. Vertex AI RAG データサービス エージェントのサービス アカウントを検索します。
    4. ドライブのフォルダで [共有] をクリックし、サービス アカウントと共有します。
    5. サービス アカウントに Google ドライブのフォルダまたはファイルに対する Viewer 権限を付与します。Google ドライブのリソース ID は、ウェブ URL で確認できます。
  • Slack: データコネクタを使用して Slack からファイルをインポートします。

  • Jira: データコネクタを使用して Jira からファイルをインポートします。

詳細については、RAG API リファレンスをご覧ください。

データ重複排除

同じファイルが変更なしで複数回インポートされた場合、ファイルはすでに存在するためスキップされます。したがって、response.skipped_rag_files_count は、インポート プロセス中にスキップされたファイルの数を示します。

ファイルは、次の条件が満たされるとスキップされます。

  • ファイルがインポートされました。
  • ファイルが変更されていない。
  • ファイルのチャンク構成が変更されていない。

インポートの失敗について

インポートの失敗を理解するために、このセクションでは、インポート リクエストのレスポンスとデータシンク(インポートするデータの宛先)のメタデータについて説明します。

レスポンス メタデータ

response.metadata(SDK 内のレスポンス オブジェクト)を使用して、インポート結果、リクエスト時間、レスポンス時間を表示できます。

インポート結果シンク

SDK では、import_result_sink は有効な文字列値に設定できるオプションの関数パラメータです。

import_result_sink が指定されている場合、成功したファイルと失敗したファイルの結果がシンクに書き込まれます。すべての結果をシンクに書き込むと、一部のファイルのインポートに失敗する理由と、インポートされなかったファイルを簡単に把握できます。

import_result_sink は Cloud Storage パスまたは BigQuery テーブルである必要があります。

  • import_result_sink が Cloud Storage パスの場合は、gs://my-bucket/my/object.ndjson の形式を使用し、オブジェクトが存在しないようにする必要があります。インポート ジョブが完了すると、Cloud Storage オブジェクトの各行に JSON オブジェクトが含まれます。このオブジェクトには、オペレーション ID、作成タイムスタンプ、ファイル名、ステータス、ファイル ID が含まれます。

  • import_result_sink が BigQuery テーブルの場合は、bq://my-project.my-dataset.my-table の形式を使用する必要があります。テーブルが存在している必要はありません。テーブルが存在しない場合は、作成されます。テーブルが存在する場合、スキーマが検証されます。BigQuery インポート結果シンクが初めて指定される場合は、存在しないテーブルを指定します。それ以外の場合は、既存のテーブルを再利用できます。

Cloud Storage または Google ドライブからファイルをインポートする

Cloud Storage または Google ドライブからファイル コーパスにファイルをインポートするには、次の操作を行います。

  1. RAG コーパスを作成するの手順に沿ってコーパスを作成します。

  2. Cloud Storage または Google ドライブからファイルをインポートするには、テンプレートを使用します。

    システムは、ファイルのパス、ファイル名、version_id を自動的にチェックします。version_id は、ファイルの内容を使用して計算されるファイル ハッシュです。これにより、ファイルのインデックスが再作成されるのを防ぐことができます。

    同じファイル名とパスのファイルのコンテンツが更新されると、そのファイルのインデックスが再作成されます。

Slack からファイルをインポートする

Slack からコーパスにファイルをインポートするには、次の操作を行います。

  1. コーパスを作成します。コーパスは、検索用にデータを構造化して最適化するインデックスです。RAG コーパスを作成するの手順に沿って操作します。
  2. Slack チャンネル ID から CHANNEL_ID を取得します。
  3. Vertex AI RAG Engine で使用するアプリを作成して設定します。
    1. Slack UI の [Add features and functionality] セクションで、[Permissions] をクリックします。
    2. 次の権限を追加します。
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. [Install to Workspace] をクリックして、Slack ワークスペースにアプリをインストールします。
  4. [Copy] をクリックして API トークンを取得します。このトークンにより、ID が認証され、API へのアクセス権が付与されます。
  5. Secret Manager に API トークンを追加します。
  6. 保存されているシークレットを表示するには、プロジェクトの Vertex AI RAG Engine サービス アカウントに Secret Manager のシークレット アクセサー ロールを付与します。

次の curl と Python のコードサンプルは、Slack リソースからファイルをインポートする方法を示しています。

curl

特定のチャンネルからメッセージを取得する場合は、CHANNEL_ID を変更します。

API_KEY_SECRET_VERSION=SLACK_API_KEY_SECRET_VERSION
CHANNEL_ID=SLACK_CHANNEL_ID
PROJECT_ID=us-central1

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/${ PROJECT_ID }/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "slack_source": {
      "channels": [
        {
          "apiKeyConfig": {
            "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
          },
          "channels": [
            {
              "channel_id": "'"${ CHANNEL_ID }"'"
            }
          ]
        }
      ]
    }
  }
}'

Python

特定の期間または特定のチャネルからメッセージを取得するには、次のいずれかのフィールドを変更します。

  • START_TIME
  • END_TIME
  • CHANNEL1 または CHANNEL2
    # Slack example
    start_time = protobuf.timestamp_pb2.Timestamp()
    start_time.GetCurrentTime()
    end_time = protobuf.timestamp_pb2.Timestamp()
    end_time.GetCurrentTime()
    source = rag.SlackChannelsSource(
        channels = [
            SlackChannel("CHANNEL1", "api_key1"),
            SlackChannel("CHANNEL2", "api_key2", START_TIME, END_TIME)
        ],
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/us-central1/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

Jira からファイルをインポートする

Jira からコーパスにファイルをインポートするには、次の操作を行います。

  1. コーパスを作成します。コーパスは、検索用にデータを構造化して最適化するインデックスです。RAG コーパスを作成するの手順に沿って操作します。
  2. API トークンを作成するには、Atlassian サイトにログインします。
  3. リクエストの SERVER_URI として {YOUR_ORG_ID}.atlassian.net を使用します。
  4. リクエストの EMAIL として Atlassian のメールアドレスを使用します。
  5. リクエストに projects または customQueries を指定します。カスタムクエリの詳細については、Jira Query Language(JQL)で高度な検索を使用するをご覧ください。

    projects をインポートすると、projects は対応するクエリに展開され、プロジェクト全体が取得されます。たとえば、MyProjectproject = MyProject に展開されます。

  6. [Copy] をクリックして API トークンを取得します。このトークンにより、ID が認証され、API へのアクセス権が付与されます。
  7. Secret Manager に API トークンを追加します。
  8. プロジェクトの Vertex AI RAG Engine サービス アカウントに Secret Manager のシークレット アクセサー ロールを付与します。

curl

EMAIL=JIRA_EMAIL
API_KEY_SECRET_VERSION=JIRA_API_KEY_SECRET_VERSION
SERVER_URI=JIRA_SERVER_URI
CUSTOM_QUERY=JIRA_CUSTOM_QUERY
PROJECT_ID=JIRA_PROJECT
REGION= "us-central1"

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/REGION>/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "jiraSource": {
      "jiraQueries": [{
        "projects": ["'"${ PROJECT_ID }"'"],
        "customQueries": ["'"${ CUSTOM_QUERY }"'"],
        "email": "'"${ EMAIL }"'",
        "serverUri": "'"${ SERVER_URI }"'",
        "apiKeyConfig": {
          "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
        }
      }]
    }
  }
}'

Python

    # Jira Example
    jira_query = rag.JiraQuery(
        email="xxx@yyy.com",
        jira_projects=["project1", "project2"],
        custom_queries=["query1", "query2"],
        api_key="api_key",
        server_uri="server.atlassian.net"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

SharePoint からファイルをインポートする

SharePoint サイトからコーパスにファイルをインポートするには、次の操作を行います。

  1. コーパスを作成します。コーパスは、検索用にデータを構造化して最適化するインデックスです。RAG コーパスを作成するの手順に沿って操作します。
  2. SharePoint サイトにアクセスする Azure アプリを作成します。
    1. 登録を作成するには、[App Registrations] に移動します。
      1. アプリケーションの名前を指定します。
      2. [Accounts in this organizational directory only] オプションを選択します。
      3. リダイレクト URI が空であることを確認します。
    2. [Overview] セクションで、アプリケーション(クライアント)ID に CLIENT_ID を使用し、ディレクトリ(テナント)ID に TENANT_ID を使用します。
    3. [Manage] セクションで、次の手順で API 権限を更新します。
      1. SharePoint の Sites.Read.All 権限を追加します。
      2. Microsoft Graph の Files.Read.All 権限と Browser SiteLists.Read.All 権限を追加します。
      3. 権限の変更を有効にするには、管理者の同意が必要です。
    4. [Manage] セクションで、次の操作を行います。
      1. 新しいクライアント シークレットで [Certificates and Secrets] を更新します。
      2. API_KEY_SECRET_VERSION を使用して、シークレット値を Secret Manager に追加します。
  3. プロジェクトの Vertex AI RAG Engine サービス アカウントに Secret Manager のシークレット アクセサー ロールを付与します。
  4. SHAREPOINT_SITE_NAME として {YOUR_ORG_ID}.sharepoint.com を使用します。
  5. リクエストで、SharePoint サイトのドライブ名またはドライブ ID を指定する必要があります。
  6. 省略可: ドライブのフォルダパスまたはフォルダ ID を指定できます。フォルダパスまたはフォルダ ID が指定されていない場合、ドライブ上のすべてのフォルダとファイルがインポートされます。

curl

CLIENT_ID=SHAREPOINT_CLIENT_ID
API_KEY_SECRET_VERSION=SHAREPOINT_API_KEY_SECRET_VERSION
TENANT_ID=SHAREPOINT_TENANT_ID
SITE_NAME=SHAREPOINT_SITE_NAME
FOLDER_PATH=SHAREPOINT_FOLDER_PATH
DRIVE_NAME=SHAREPOINT_DRIVE_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/REGION>/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "sharePointSources": {
      "sharePointSource": [{
        "clientId": "'"${ CLIENT_ID }"'",
        "apiKeyConfig": {
          "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
        },
        "tenantId": "'"${ TENANT_ID }"'",
        "sharepointSiteName": "'"${ SITE_NAME }"'",
        "sharepointFolderPath": "'"${ FOLDER_PATH }"'",
        "driveName": "'"${ DRIVE_NAME }"'"
      }]
    }
  }
}'

Python

    from vertexai.preview import rag
    from vertexai.preview.rag.utils import resources

    CLIENT_ID="SHAREPOINT_CLIENT_ID"
    API_KEY_SECRET_VERSION="SHAREPOINT_API_KEY_SECRET_VERSION"
    TENANT_ID="SHAREPOINT_TENANT_ID"
    SITE_NAME="SHAREPOINT_SITE_NAME"
    FOLDER_PATH="SHAREPOINT_FOLDER_PATH"
    DRIVE_NAME="SHAREPOINT_DRIVE_NAME"

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id=CLIENT_ID,
                client_secret=API_KEY_SECRET_VERSION,
                tenant_id=TENANT_ID,
                sharepoint_site_name=SITE_NAME,
                folder_path=FOLDER_PATH,
                drive_id=DRIVE_ID,
            )
        ]
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

次のステップ