拡張機能を作成して実行する

このドキュメントでは、Vertex AI 拡張サービスの主な機能について説明します。

Google が提供する拡張機能をインポートして実行する方法については、以下をご覧ください。

拡張機能の作成とインポート

このドキュメントでは、拡張機能をサポートできる API サービスがすでに実行されていることを前提としています。拡張機能を作成するには、API 仕様ファイルで外部 API のインターフェースを定義する必要があります。この仕様ファイルを Cloud Storage バケットにアップロードするか、文字列に変換する必要があります。次に、拡張機能のマニフェストを定義し、仕様ファイルを含めて、拡張機能サービスに登録リクエストを送信します。

API 仕様ファイルを作成する

拡張機能は、拡張機能の API エンドポイントを定義および記述するファイルを使用することで誰でも作成できます。API エンドポイントは公開または非公開にでき、任意のクラウドまたはオンプレミスにホストできます。

API 仕様ファイルには、API サービスのインターフェースを記述します。OpenAPI 3.0 と互換性のある YAML 形式の API 仕様ファイルを指定する必要があります。この仕様ファイルで、以下を定義する必要があります。

  • サーバー オブジェクト。このオブジェクトで API サーバー URL を定義する必要があります。Vertex AI 拡張サービスは複数のサーバーをサポートしていません。

    servers:
  - url: API_SERVICE_URL

  • パス オブジェクト。このオブジェクトには、API サービスによって提供されるさまざまなオペレーションと、各オペレーションに対応する入力パラメータを記述する必要があります。各オペレーションには、一意の識別子とレスポンスが必要です。

    paths:
  ...
    get:
      operationId: API_SERVICE_OPERATION_ID
      ...
      parameters:
        - name: API_SERVICE_INPUT_VAR
          ...
      responses:
      ...

  • コンポーネント オブジェクト。このオブジェクトは省略可能です。コンポーネント オブジェクトを使用すると、再利用可能なオブジェクトを定義できます。たとえば、コンポーネント オブジェクトを使用して、パス オブジェクトで定義されているオブジェクト スキーマの定義を指定できます。コンポーネント オブジェクトを使用して、API サービスの出力パラメータを記述することもできます。

    components:
  schemas:
    Result:
      ...
      properties:
        API_SERVICE_OUTPUT_VAR:
        ...

OpenAPI の詳細については、OpenAPI 仕様をご覧ください。

次の例は、リクエストされた言語で「hello」と表示する API サービスの API 仕様ファイルです。

  openapi: "3.0.0"
  info:
    version: 1.0.0
    title: Hello Extension
    description: Learn to build Vertex AI extensions
  servers:
    - url: [API_SERVICE_URL]
  paths:
    /hello:
      get:
        operationId: say_hello
        description: Say hello in prompted language.
        parameters:
          - name: apiServicePrompt
            in: query
            description: Language
            required: true
            schema:
              type: string
        responses:
          '200':
            description: Successful operation.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Result"
  components:
    schemas:
      Result:
        description: Hello in the requested language.
        properties:
          apiServiceOutput:
            type: string

仕様ファイルをアップロードする

仕様ファイルを Cloud Storage バケットにアップロードするか、文字列に変換します。

仕様ファイルを Cloud Storage バケットにアップロードする場合は、Vertex AI Extension Service Agent サービス アカウント（service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com）にストレージ オブジェクト閲覧者のロールを付与します。プロジェクト内のバケットを一覧表示する方法については、バケットの一覧表示をご覧ください。オブジェクトを Cloud Storage バケットにコピーする方法については、オブジェクトのコピー、名前の変更、移動をご覧ください。

拡張機能のインポート リクエストを定義する

API 仕様ファイルを作成したら、JSON ファイルで拡張機能のインポート リクエストを定義できます。拡張機能のインポート リクエストには、API 仕様ファイル（apiSpec）と認証構成（authConfig）への参照を含める必要があります。拡張機能を大規模言語モデル（LLM）に接続して拡張機能の動作を確認するには、オプションの toolUseExamples パラメータを追加します。拡張機能のみを実行する場合は、toolUseExamples パラメータを指定しないでください。

拡張機能のインポート リクエストの形式は次のとおりです。

{
  "displayName":  "DISPLAY_NAME_HUMAN",
  "description": "DESCRIPTION_HUMAN",
  "manifest": {
    "name": "EXTENSION_NAME_LLM",
    "description": "DESCRIPTION_LLM",
    "apiSpec": { ... },
    "authConfig": { ... },
  }
  "toolUseExamples": [ ... ],
}
  • DISPLAY_NAME_HUMAN: ユーザーに表示される拡張機能の名前。
  • DESCRIPTION_HUMAN: ユーザーに表示される拡張機能の説明。
  • EXTENSION_NAME_LLM: LLM が推論に使用する拡張機能の名前。
  • DESCRIPTION_LLM: LLM が推論に使用する拡張機能の説明。意味があり、参考になる説明を入力する必要があります。

API 仕様ファイルへの参照

拡張機能のインポート リクエストには、API 仕様ファイルへの参照を含める必要があります。仕様ファイルは、次の 2 つの方法で指定できます。

  • openApiGcsUri を使用して、YAML ファイルの Cloud Storage URI を渡す。

    "apiSpec": {
  "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml"
},
    • BUCKET_NAME: 仕様ファイルを格納する Cloud Storage バケットの名前。
    • SPECIFICATION_FILE_NAME: API 仕様ファイルの名前。

  • openApiYaml を使用して、YAML ファイルに文字列として渡す。

認証構成

拡張機能は、一般公開（すべてのユーザーが使用可能）にすることも、限定公開（1 つ以上の組織内の承認済みユーザーのみが使用可能）にすることもできます。

拡張機能のインポート リクエストには、認証構成を含める必要があります。認証方法は、次の中から選択できます。

  • NO_AUTH: 認証なし
  • API_KEY_AUTH: API キー認証
  • HTTP_BASIC_AUTH: HTTP 基本認証
  • OAUTH: OAuth 認証
  • OIDC_AUTH: OIDC 認証

認証構成の詳細については、認証構成を指定するをご覧ください。

拡張機能の仕組みを示す例

最良の結果を得るには、拡張機能のインポート リクエストに、拡張機能の動作を示すサンプルを含める必要があります。この例では、toolUseExamples パラメータを使用します。

次のコードは、単一の入力パラメータと単一の出力パラメータを持つ単一の例の toolUseExamples の形式を示しています。この例では、リクエスト パラメータとレスポンス パラメータの両方が string 型です。

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "API_SERVICE_OPERATION_ID",
      },
      "displayName": "EXAMPLE_DISPLAY_NAME",
      "query": "EXAMPLE_QUERY",
      "requestParams": {
        "fields": [
          {
            "key": "API_SERVICE_INPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_INPUT",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "API_SERVICE_OUTPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_OUTPUT",
            },
          }
        ],
      },
      "responseSummary": "EXAMPLE_SUMMARY"
    }
],
  • query: この拡張機能を利用できるクエリの例。EXAMPLE_QUERY を使用してクエリテキストを指定します。
  • extensionOperation: query に回答するのに適した拡張オペレーション。API_SERVICE_OPERATION_ID を使用して、API 仕様ファイルで定義されている拡張機能オペレーションの ID を指定します。
  • displayName: 例の表示名。簡単な説明を入力するには EXAMPLE_DISPLAY_NAME を使用します。
  • requestParams: extensionOperation に必要なリクエスト パラメータとその値の例（Key-Value 形式）。API_SERVICE_INPUT_VAR を使用して、API 仕様ファイルで定義された、API_SERVICE_OPERATION_ID に対応する入力パラメータを指定します。EXAMPLE_INPUT を使用して、EXAMPLE_QUERY に対応する入力値の例を指定します。
  • responseParams: extensionOperation のレスポンス パラメータと Key-Value 形式の例の値。API_SERVICE_OUTPUT_VAR を使用して、API 仕様ファイルで定義された、API サービスに対応する出力パラメータを指定します。EXAMPLE_OUTPUT を使用して、EXAMPLE_INPUT に対応する出力値の例を指定します。
  • responseSummary: query に応じてアプリが提供する可能性のある概要の例。EXAMPLE_SUMMARY を使用して概要テキストを指定します。

以下は、リクエストされた言語で「hello」と返す API サービスの toolUseExamples の例です。

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "say_hello",
      },
      "displayName": "Say hello in the requested language",
      "query": "Say hello in French",
      "requestParams": {
        "fields": [
          {
            "key": "apiServicePrompt",
            "value": {
              "string_value": "French",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "apiServiceOutput",
            "value": {
              "string_value": "bonjour",
            },
          }
        ],
      },
      "responseSummary": "Bonjour"
    }
],

認証構成を指定する

拡張機能のインポート リクエストを定義するときに、認証構成を指定する必要があります。

拡張機能で認証が不要な場合は、authType 変数を NO_AUTH に設定します。

"authConfig": {
  "authType": "NO_AUTH"
}

拡張機能に認証が必要な場合は、authType 変数で認証タイプを設定して認証構成を指定する必要があります。認証方法は、次の中から選択できます。

API キー認証

API キー認証をサポートするため、Vertex AI は SecretManager と統合してシークレットの保存とアクセスを行います。Vertex AI Extensions プラットフォームは、シークレット データを直接保存しません。SecretManager リソースのライフサイクルはお客様が管理する責任があります。

authConfig は次のように指定します。

"authConfig": {
  "authType": "API_KEY_AUTH",
  "apiKeyConfig": {
    "name": "API_KEY_CONFIG_NAME",
    "apiKeySecret": "API_KEY_SECRET",
    "httpElementLocation": "HTTP_ELEMENT_LOCATION",
  },
}
  • API_KEY_CONFIG_NAME: API キーの名前。たとえば、API リクエスト https://example.com/act?api_key=<API KEY> では、API_KEY_CONFIG_NAME は api_key に対応します。
  • API_KEY_SECRET: キーを保存する SecretManager シークレット バージョン リソース。このパラメータの形式は projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION です。

  • HTTP_ELEMENT_LOCATION: HTTP リクエスト内の API キーの場所。指定できる値は次のとおりです。

    • HTTP_IN_QUERY
    • HTTP_IN_HEADER
    • HTTP_IN_PATH
    • HTTP_IN_BODY
    • HTTP_IN_COOKIE

    詳細については、パラメータの記述をご覧ください。

HTTP 基本認証

HTTP 基本認証をサポートするために、Vertex AI は SecretManager と統合してシークレットの保存とアクセスを行います。Vertex AI Extensions プラットフォームは、シークレット データを直接保存しません。SecretManager リソースのライフサイクルはユーザー自身で管理する必要があります。

authConfig は次のように指定します。

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}
  • CREDENTIAL_SECRET: base64 エンコードされた認証情報を保存する SecretManager シークレット バージョンのリソース。このパラメータの形式は projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION です。

OAuth 認証

Vertex AI は、アクセス トークンとサービス アカウントの 2 つの OAuth 認証方法をサポートしています。

アクセス トークン

authConfig は次のように指定します。

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {}
}

拡張機能をインポートする際は、oauthConfig フィールドを空白のままにします。登録済みの拡張機能を実行する場合は、実行リクエストの oauthConfig フィールドにアクセス トークンを指定する必要があります。詳しくは、拡張機能を実行するをご覧ください。

サービス アカウント

authConfig は次のように指定します。

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: Vertex AI はこのサービス アカウントを使用してアクセス トークンを生成します。

次の手順で、Vertex AI Extension Service Agent が SERVICE_ACCOUNT_NAME からアクセス トークンを取得できるようにします。

  1. [IAM] ページに移動します。

    [IAM] に移動

  2. [サービス アカウント] タブを選択します。

  3. サービス アカウントをクリックします。authConfig の SERVICE_ACCOUNT_NAME の値は、サービス アカウントの名前と一致する必要があります。

  4. [権限] タブをクリックします。

  5. [アクセス権を付与] をクリックします。

  6. [プリンシパルの追加] セクションの [新しいプリンシパル] フィールドに「service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com」と入力します。このプリンシパルは Vertex AI Extension Service Agent サービス アカウントに対応しています。

  7. [ロールを割り当てる] セクションで、Service Account Token Creator ロールを見つけて選択します。このロールには権限 iam.serviceAccounts.getAccessToken が含まれています。

  8. [保存] をクリックします。

OIDC 認証

Vertex AI は、ID トークンとサービス アカウントの 2 つの OIDC 認証方法をサポートしています。

ID トークン

authConfig は次のように指定します。

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {}
}

拡張機能をインポートする際は、oidcConfig フィールドを空白のままにします。登録済みの拡張機能を実行する場合は、実行リクエストの oidcConfig フィールドに ID トークンを指定する必要があります。詳しくは、拡張機能を実行するをご覧ください。

サービス アカウント

authConfig は次のように指定します。

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: Vertex AI は、このサービス アカウントを使用して OpenID Connect（OIDC）トークンを生成します。Vertex AI は、API 仕様ファイルで定義されているように、トークンのオーディエンスを API_SERVICE_URL に設定します。

次の手順で、Vertex AI Extension Service Agent が SERVICE_ACCOUNT_NAME からアクセス トークンを取得できるようにします。

  1. [IAM] ページに移動します。

    [IAM] に移動

  2. [サービス アカウント] タブを選択します。

  3. サービス アカウントをクリックします。authConfig の SERVICE_ACCOUNT_NAME の値は、サービス アカウントの名前と一致する必要があります。

  4. [権限] タブをクリックします。

  5. [アクセス権を付与] をクリックします。

  6. [プリンシパルの追加] セクションの [新しいプリンシパル] フィールドに「service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com」と入力します。このプリンシパルは Vertex AI Extension Service Agent サービス アカウントに対応しています。

  7. [ロールを割り当てる] セクションで、Service Account Token Creator ロールを見つけて選択します。このロールには権限 iam.serviceAccounts.getOpenIdToken が含まれています。

  8. [保存] をクリックします。

Vertex AI で拡張機能をインポートする

拡張機能のインポート リクエストを定義したら、Vertex AI で拡張機能をインポートできます。

  1. 次のシェル変数を設定します。

    ENDPOINT="LOCATION-aiplatform.googleapis.com"
URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
    • PROJECT_ID: プロジェクト。
    • LOCATION: 選択したリージョン。不明な場合は、us-central1 を選択します。

  2. 次の curl コマンドを実行して、インポート リクエストを送信します。

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @IMPORT_REQUEST.json "${URL}/extensions:import"

    レスポンスの形式は次のとおりです。

    {
  "name": "projects/[PROJECT_NUMBER]/locations/[LOCATION]/extensions/[EXTENSION_ID]/operations/[IMPORT_OPERATION_ID]",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata",
    "genericMetadata": {
      "createTime": "[CREATE_TIME]",
      "updateTime": "[UPDATE_TIME]"
    }
  }
}

  3. インポート リクエストの出力に基づいてシェル変数を設定します。

    EXTENSION_ID=EXTENSION_ID
IMPORT_OPERATION_ID=IMPORT_OPERATION_ID

  4. インポートのステータスを確認するには、次の curl コマンドを実行します。

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/operations/${IMPORT_OPERATION_ID}"

拡張機能を管理する

登録されているすべての拡張機能の一覧を取得するには、次の curl コマンドを実行します。

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions"

拡張機能を取得するには、次の curl コマンドを実行します。

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions/${EXTENSION_ID}"

拡張機能の displayName、description、または toolUseExamples を更新できます。拡張機能を更新するときに toolUseExamples を指定すると、更新によってサンプルが置き換えられます。たとえば、a と b のサンプルがあり、c のサンプルで拡張機能を更新すると、更新された拡張機能には c のサンプルのみが含まれます。拡張機能の説明を更新するには、次の curl コマンドを実行します。

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

拡張機能を削除するには、次の curl コマンドを実行します。

curl \
 -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}

拡張機能を実行する

拡張機能を実行する方法は 2 つあります。

  • execute: このモードは API の実行のみに焦点を当てています。拡張機能は、指定された API オペレーションをトリガーし、追加の処理を行わずに未加工の結果を返します。

  • query: このモードは、インテリジェントなインタラクション用に設計されています。このモードには、次の複数のステップが含まれています。

    • モデルのリクエスト: クエリと拡張機能のスキーマが、それぞれプロンプトと FunctionDeclaration として Gemini に提供されます。
    • API の実行: ツールの使用が必要とモデルが判断すると、拡張機能はモデルに代わって API オペレーションを自動的に呼び出し、結果を取得します。
    • モデルの統合: API の結果がモデルにフィードされます。モデルは、これらの結果を処理し、コンテキストに合わせて最終的な回答を生成します。基本的に、query は単一ツール エージェントとして機能し、API を使用して目標を達成します。

このセクションでは、拡張機能を execute する方法について説明します。

拡張機能で OAuth 認証とアクセス トークンを使用している場合は、OAuth 認証とアクセス トークンを使用して拡張機能を実行するをご覧ください。

拡張機能で OIDC 認証と ID トークンを使用している場合は、OIDC 認証と ID トークンを使用して拡張機能を実行するをご覧ください。

そうでない場合は、次の手順で実行できます。

  1. 次の内容のファイルを execute-extension.json という名前で作成します。

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {
    "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE"
  }
}
    • API_SERVICE_OPERATION_ID: 実行する API サービス オペレーションの ID。API サービス オペレーションは、API 仕様ファイルで定義されています。
    • API_SERVICE_INPUT_VAR: API_SERVICE_OPERATION_ID に対応し、API 仕様ファイルで定義されている入力変数。
    • API_SERVICE_INPUT_VALUE: 拡張機能の入力値。

  2. 次の curl コマンドを実行します。

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

    レスポンスの形式は次のとおりです。

    {
  "output": {
    "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}"
  }
}
    • API_SERVICE_OUTPUT_VAR: API 仕様ファイルで定義された、API サービスに対応する出力パラメータ。
    • API_SERVICE_OUTPUT_VALUE: レスポンス オブジェクトのシリアル化である文字列値。API 仕様ファイルで JSON レスポンス スキーマを定義している場合は、この出力文字列を自分で解析して JSON に変換する必要があります。

OAuth 認証とアクセス トークンを使用して拡張機能を実行する

拡張機能で OAuth 認証とアクセス トークンを使用する場合は、次の手順で実行できます。

  1. 次の内容のファイルを execute-extension.json という名前で作成します。

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {...},
  "runtime_auth_config": {
    "authType": "OAUTH",
    "oauth_config": {"access_token": "'$(gcloud auth print-access-token)'"}
  }
}
    • API_SERVICE_OPERATION_ID: 実行する API サービス オペレーションの ID。API サービス オペレーションは、API 仕様ファイルで定義されています。

  2. 次の curl コマンドを実行します。

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

OIDC 認証と ID トークンを使用して拡張機能を実行する

拡張機能で OIDC 認証と ID トークンを使用する場合は、次の手順で実行できます。

  1. 次の内容のファイルを execute-extension.json という名前で作成します。

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {...},
  "runtime_auth_config": {
    "authType": "OIDC_AUTH",
    "oidc_config": {"id_token": "$(gcloud auth print-identity-token)"}
  }
}
    • API_SERVICE_OPERATION_ID: 実行する API サービス オペレーションの ID。API サービス オペレーションは、API 仕様ファイルで定義されています。

  2. 次の curl コマンドを実行します。

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

次のステップ