Agent Search 拡張機能

このドキュメントでは、 Google Cloud コンソールと Vertex AI API から、Google 提供の Agent Search 拡張機能を登録して使用する方法について説明します。この拡張機能を使用すると、ウェブサイト コーパスと非構造化データにアクセスして検索し、次のような自然言語の質問に対する回答を得ることができます。

  • 「昨年の第 1 四半期から今年の第 1 四半期にかけて、競合の脅威はどのように変化しましたか?」
  • 「会社のどの部分が最も急速に成長していますか。どのくらい速く成長していますか?」

エージェント検索拡張機能は、エージェント検索を使用してデータストアから有意な結果を取得します。エージェント検索拡張機能は、OpenAPI 仕様の vertex_ai_search.yaml ファイルで定義されています。

エージェント検索拡張機能を使用するには、指定した検索スコープでグローバル リージョンにデータストアを作成する必要があります。最適な検索結果を得るには、ウェブサイト データに対して高度なインデックス登録を有効にし、非構造化データに対して Enterprise エディションを有効にします。詳しくは、高度な機能についてをご覧ください。

openapi: "3.0.0"
info:
  title: Vertex AI Search
  version: v1alpha
  description: >
    Performs search on user ingested data including website and unstructured data type.

    This extension is used when user wants to search or retrieve meaningful results from their ingested data in the Vertex AI Search service.

    Supported AuthTypes:
    - GOOGLE_SERVICE_ACCOUNT_AUTH: (only supports using Vertex AI Extension Service Agent).
paths:
  /search:
    get:
      operationId: search
      description: Retrieves the results from user's query by searching in the data store.
      parameters:
      - name: query
        in: query
        schema:
          type: string
        description: User natural language instructions for search.
        required: true
      responses:
        default:
          description: Search execution result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"

components:
  schemas:
    SearchResult:
      description: Top results from search response.
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                description: Retrieved document title.
              display_link:
                type: string
                description: Retrieved document link to display.
              link:
                type: string
                description: Retrieved document link.
              extractive_segments:
                type: array
                description: Extractive segments from the retrieved file.
                items:
                  type: string
              extractive_answers:
                type: array
                description: Extractive answers from the retrieved file. These are generated from the extractive segments.
                items:
                  type: string

    

エンドツーエンドのチュートリアルで Google 拡張機能について学習するには、以下の Jupyter ノートブックをご覧ください。

  • Vertex AI Extensions を使用したビジネス アナリストのワークフロー: Code Interpreter 拡張機能と Agent Search 拡張機能を使用して、ビジネス関係者向けの住宅投資機会リサーチ レポートを作成します。
    Colab | GitHub | Vertex AI Workbench
  • Vertex AI Extensions を使用したゲームレビュー分析ワークフロー: Code Interpreter 拡張機能を使用して、Steam のゲームレビューを分析します。Agent Search 拡張機能を使用して、ウェブサイトのゲームのレビューを要約します。Code Interpreter 拡張機能を使用して、生成されたすべてのアセットを含むレポートを作成します。
    Colab | GitHub | Vertex AI Workbench

始める前に

  1. Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

エージェント検索拡張機能の登録と実行

以降のセクションでは、 Google Cloud コンソールと Vertex AI API を使用して Agent Search 拡張機能を登録する方法について説明します。拡張機能を登録した後は、Vertex AI API を使用して実行できます。

コンソール

拡張機能を登録する

Google Cloud コンソールを使用して Agent Search 拡張機能を登録する手順は次のとおりです。

  1. Google Cloud コンソールで、Vertex AI [拡張機能] ページに移動します。

    Vertex AI の拡張機能に移動

  2. [拡張機能を作成] をクリックします。

  3. [新しい拡張機能の作成] ダイアログで、以下のフィールドに入力します。

    • 拡張機能名: 拡張機能の名前を入力します(例: vertex_search_extension)。
    • 説明:(省略可)拡張機能の説明を入力します(例: Vertex AI 検索拡張機能)。
    • 拡張機能の種類: Vertex AI search を選択します。
  4. 表示された [OpenAPI 仕様ファイル] セクションで、次のフィールドが正しく設定されていることを確認します。

    • API 名: vertex_ai_search
    • API の説明: Performs search on user ingested data including website and unstructured data type...
    • ソース: Cloud Storage
    • OpenAPI 仕様: vertex-extension-public/vertex_ai_search.yaml
    • 認証: Google service account.
  5. [ランタイム構成] セクションで、サービス構成の名前を指定します。サービス構成名は vertexAiSearchRuntimeConfig に指定します。次のようにフォーマットします。 projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG

    • COLLECTION_NAME を default_collection に設定します。
    • ENGINE は、検索アプリの作成時に取得したアプリケーション ID に設定します。詳しくは、ウェブサイト データ用の検索アプリを作成するをご覧ください。
    • SERVING_CONFIG を default_search に設定します。
  6. [拡張機能を作成] をクリックします。

REST

拡張機能を登録する

Vertex AI API extensions.import リクエストを送信して、エージェント検索拡張機能を登録します。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • REGION: Compute Engine のリージョン。
  • DISPLAY_NAME: ユーザーに表示される拡張機能の名前(例: my_search_extension)。
  • DESCRIPTION: (省略可)ユーザーに表示される拡張機能の説明(例: 検索拡張機能)。
  • SERVICE_ACCOUNT: (省略可)サンプルのリクエスト本文にあるように、Vertex AI Search 拡張機能は GOOGLE_SERVICE_ACCOUNT_AUTH を使用します。サービス アカウントを指定しない場合、拡張機能はデフォルトの Vertex AI Extension サービス エージェント サービス アカウントを使用します。別のサービス アカウントを指定する場合は、指定したサービス アカウントの Vertex AI Extension Service エージェント サービス アカウントに iam.serviceAccounts.getAccessToken 権限を付与します。
  • SERVING_CONFIG_NAME: サービング構成の名前は、vertexAiSearchRuntimeConfig で指定します。次のようにフォーマットします。 projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG
    • PROJECT_ID: 実際の Google Cloud プロジェクト ID
    • COLLECTION_NAME を default_collection に設定します。
    • ENGINE: 検索アプリの作成時に受け取ったアプリケーション ID。詳しくは、ウェブサイト データ用の検索アプリを作成するをご覧ください。
    • SERVING_CONFIG を default_search に設定します。

HTTP メソッドと URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import

リクエストの本文(JSON):

{
  "displayName":"DISPLAY_NAME",
  "description":"DESCRIPTION",
  "manifest":{
    "name":"vertex_ai_search_tool",
    "description":"A Vertex AI Search tool",
    "apiSpec":{
      "openApiGcsUri":"gs://vertex-extension-public/vertex_ai_search.yaml"
    },
    "authConfig":{
      "authType":"GOOGLE_SERVICE_ACCOUNT_AUTH",
      "googleServiceAccountConfig":{
        "serviceAccount":"SERVICE_ACCOUNT"
      }
    }
  }
  "runtimeConfig": {
     "vertexAiSearchRuntimeConfig": {
        "servingConfigName": "SERVING_CONFIG_NAME",
     }
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import" | Select-Object -Expand Content

拡張機能を実行する

Vertex AI API に execute オペレーションを送信して、データストアから有意な結果を取得できます。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • REGION: Compute Engine のリージョン。
  • EXTENSION_ID: Google Cloud コンソールの [拡張機能の詳細] に表示される Vertex AI Search 拡張機能の ID。

HTTP メソッドと URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute

リクエストの本文(JSON):

{
  "operation_id":"search",
  "operation_params":{
    "query":"Housing affordability since 2010",
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content