Vertex AI Search 拡張機能

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

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

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

Vertex AI Search 拡張機能を使用するには、指定した検索スコープでグローバルリージョンにデータストアを作成する必要があります。最適な検索結果を得るには、ウェブサイトデータに対して高度なインデックス登録を有効にし、非構造化データに対して 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 拡張機能と Vertex AI Search 拡張機能を使用して、ビジネス関係者向けの住宅投資機会調査レポートを作成します。
Colab | GitHub | Vertex AI Workbench
Vertex AI Extensions を使用したゲームレビュー分析ワークフロー: Code Interpreter 拡張機能を使用して、Steam のゲームレビューを分析します。Vertex AI Search 拡張機能を使用して、ウェブサイトのゲームのレビューを要約します。Code Interpreter 拡張機能を使用して、生成されたすべてのアセットを含むレポートを作成します。
Colab | GitHub | Vertex AI Workbench

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

Vertex AI Search 拡張機能の登録と実行

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

コンソール

拡張機能を登録する

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

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

Vertex AI の拡張機能に移動
[拡張機能を作成] をクリックします。
[新しい拡張機能の作成] ダイアログで、以下のフィールドに入力します。
- 拡張機能名: 拡張機能の名前を入力します（例: vertex_search_extension）。
- 説明:（省略可）拡張機能の説明を入力します（例: Vertex AI 検索拡張機能）。
- 拡張機能の種類: Vertex AI search を選択します。
表示された [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.
[ランタイム構成] セクションで、サービス構成の名前を指定します。サービス構成名は vertexAiSearchRuntimeConfig に指定します。次のようにフォーマットします。 projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG
- COLLECTION_NAME を default_collection に設定します。
- ENGINE は、検索アプリの作成時に取得したアプリ ID に設定します。詳しくは、ウェブサイトデータ用の検索アプリを作成するをご覧ください。
- SERVING_CONFIG を default_search に設定します。
[拡張機能を作成] をクリックします。

REST

拡張機能を登録する

Vertex AI API extensions.import リクエストを送信して、Vertex AI Search 拡張機能を登録します。

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

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 に設定します。
拡張機能が入力ファイルの読み取りに使用する Cloud Storage バケット。gs:// 接頭辞を含みます（例: gs://sample-bucket-name）。指定する場合は、このバケットの roles/storage.objectViewer ロールを Vertex Extension カスタムコードサービスエージェントに割り当てる必要があります。

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

{
  "displayName":"DISPLAY_NAME",
  "description":"DESCRIPTION",
  "manifest":{
    "name":"code_interpreter_tool",
    "description":"A Google Code Interpreter tool",
    "apiSpec":{
      "openApiGcsUri":"gs://vertex-extension-public/code_interpreter.yaml"
    },
    "authConfig":{
      "authType":"GOOGLE_SERVICE_ACCOUNT_AUTH",
      "googleServiceAccountConfig":{
        "serviceAccount":"SERVICE_ACCOUNT"
      }
    }
  }
  "runtimeConfig": {
     "vertexAiSearchRuntimeConfig": {
        "servingConfigName": "SERVING_CONFIG_NAME",
     }
  }
}

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

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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 コンソールの [Extension details] に表示される 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