Extensions API

拡張機能は、大規模言語モデル（LLM）が外部データへのアクセスや計算の実行などのオペレーションを実行するためのツールです。リアルタイム データを処理し、現実世界のアクションを実行できます。

Vertex AI には、拡張機能の登録、管理、実行を行う Extension API が用意されています。また、コード インタープリタ拡張機能や Vertex AI Search 拡張機能など、Extension API のビルド済み拡張機能も用意されています。

制限事項

Extension API は us-central1 リージョンでのみ使用できます。

構文の例

拡張機能リソースを作成するための構文。

curl

curl -X POST \

-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/extensions:import \
-d '{
  "displayName": "...",
  "description": "...",
  "manifest": {
    ...
    "apiSpec": {
      ...
    },
    "authConfig": {
      ...
    }
    ...
  }
}'

Python

from vertexai.preview import extensions

extensions.Extension.create(
  manifest: Union[JsonDict, ExtensionManifest],
  display_name: Optional[str] = None,
  description: Optional[str] = None,
  runtime_config: Optional[Union[JsonDict, RuntimeConfig]] = None
)

パラメータ リスト

リクエストの本文

パラメータ

displayName

省略可: string

API と UI からユーザーに表示される拡張機能の表示名。UTF-8 文字列で、最大 128 文字です。

description

省略可: string

API と UI からユーザーに表示される拡張機能の説明。UTF-8 文字列で、最大 1 MB です。

manifest

JsonDict|ExtensionManifest

拡張機能のマニフェスト。

runtimeConfig

省略可: JsonDict|RuntimeConfig

拡張機能のランタイム動作を制御するランタイム構成。

コード インタープリタ拡張機能の場合、形式は次のとおりです。

  "runtimeConfig": {
    "codeInterpreterRuntimeConfig": {
        "fileInputGcsBucket": string,
        "fileOutputGcsBucket": string
    }
  }

Vertex AI Search 拡張機能の場合、形式は次のとおりです。

  "runtimeConfig": {
    "vertexAiSearchRuntimeConfig": {
      "servingConfigName": string,
    }
  }

manifest

拡張機能のマニフェスト。

パラメータ

name

string

LLM が推論に使用する拡張機能の名前。UTF-8 文字列で、最大 128 文字です。

description

string

拡張機能の使用方法の自然言語による説明。説明は、LLM が推論を行う際に表示されます。UTF-8 文字列で、最大 1 MB です。

apiSpec

ApiSpec

推論のために LLM に提示される API 仕様。意味があり、参考になる説明を入力する必要があります。apiSpec には、OpenAPI yaml ファイルが保存されている Cloud Storage URI への参照が含まれます。

  "apiSpec": {
    "openApiGcsUri": string
  }

authConfig

JsonDict|AuthConfig

この拡張機能でサポートされている認証のタイプ。

拡張機能のインポート リクエストには、認証構成を含める必要があります。

"authConfig": {
  "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH",
  "googleServiceAccountConfig": {
    "serviceAccount": string
  },
}

apiSpec

推論のために LLM に提示される API 仕様。

パラメータ

openApiGcsUri

string

拡張機能 API を記述する OpenAPI YAML ファイルの Cloud Storage URI（gs://vertex-extension-public/code_interpreter.yaml など）

authConfig

この拡張機能でサポートされている認証のタイプ。

パラメータ

authType

string

認証方法です。サポートされる値: GOOGLE_SERVICE_ACCOUNT_AUTH。

googleServiceAccountConfig

コード インタープリタ拡張機能と Vertex AI Search 拡張機能は、Google サービス アカウント認証のみをサポートしています。この認証では、Vertex AI は Vertex AI Extension サービス エージェントを使用して API にアクセスします。

パラメータ

serviceAccount

省略可: string

拡張機能の実行に使用されるサービス アカウント。サービス アカウントを指定する場合は、指定したサービス アカウントの Vertex AI Extension サービス エージェントに iam.serviceAccounts.getAccessToken 権限を付与する必要があります。指定しない場合、Vertex AI Extension サービス エージェントを使用して拡張機能が実行されます。

runtimeConfig

runtimeConfig オブジェクトには、拡張機能の実行時に使用される追加の構成が含まれます。

コード インタープリタ拡張機能

パラメータ

fileInputGcsBucket

省略可: string

拡張機能へのファイル入力に使用する Cloud Storage バケット。Vertex Extension カスタムコード サービス エージェントに、このバケットに対する roles/storage.objectViewer 権限を付与する必要があります。指定しない場合、拡張機能はリクエスト本文のファイル コンテンツのみを受け取り、Cloud Storage ファイル入力を拒否します。

fileOutputGcsBucket

省略可: string

拡張機能からのファイル出力に使用する Cloud Storage バケット。Vertex Extension カスタムコード サービス エージェントに、このバケットに対する roles/storage.objectUser 権限を付与する必要があります。指定しない場合、ファイルの内容はレスポンスの本文に出力されます。

Vertex AI Search 拡張機能

パラメータ

servingConfigName

string

Vertex AI Search サービング構成名。拡張機能で使用する Vertex AI Search リソースを指定します。形式:

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}

拡張機能を実行する

パラメータ

operation_id

string

この拡張機能で実行するように選択したオペレーションの ID。

operation_params

省略可: JsonDict|Struct

このオペレーションの実行に使用されるリクエスト パラメータ。JSON は、パラメータ名をキー、実際のパラメータ値を値として持つマップの形式にする必要があります。たとえば、query というパラメータを「What is Vertex AI?」という文字列に設定するには、{"query": "What is Vertex AI?"} を使用します。

例

コード インタープリタ拡張機能をインポートする

拡張機能リソースを作成または登録します。

この例は、コード インタープリタ拡張機能をインポートする方法を示しています。

REST

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

  • PROJECT_ID: 実際のプロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • DISPLAY_NAME: API と UI からユーザーに表示される拡張機能の表示名。UTF-8 文字列で、最大 128 文字です。
  • DESCRIPTION: API と UI からユーザーに表示される拡張機能の説明。UTF-8 文字列で、最大 1 MB です。
  • MANIFEST_NAME: LLM が推論に使用する拡張機能の名前。UTF-8 文字列で、最大 128 文字です。
  • MANIFEST_DESCRIPTION: LLM に提示される自然言語の説明。拡張機能の使用方法を説明するもので、LLM が推論を実行するために不可欠です。UTF-8 文字列で、最大 1 MB です。
  • GCS_URI: 拡張機能 API を記述する OpenAPI YAML ファイルの Cloud Storage URI。
  • AUTH_TYPE: 認証方法。サポートされる値: GOOGLE_SERVICE_ACCOUNT_AUTH。

HTTP メソッドと URL:

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

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

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "manifest": {
    "name": "NAME",
    "description": "MANIFEST_DESCRIPTION",
    "apiSpec": {
      "openApiGcsUri": "GCS_URI",
    },
    "authConfig": {
      "authType": "AUTH_TYPE",
      "googleServiceAccountConfig": {}
    }
  }
}

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

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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import" | Select-Object -Expand Content

Vertex AI SDK for Python

Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Vertex AI SDK for Python API のリファレンス ドキュメントをご覧ください。 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension.create(
    display_name="Code Interpreter",
    description="This extension generates and executes code in the specified language",
    manifest={
        "name": "code_interpreter_tool",
        "description": "Google Code Interpreter Extension",
        "api_spec": {
            "open_api_gcs_uri": "gs://vertex-extension-public/code_interpreter.yaml"
        },
        "auth_config": {
            "google_service_account_config": {},
            "auth_type": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        },
    },
)
print(extension.resource_name)
# Example response:
# projects/123456789012/locations/us-central1/extensions/12345678901234567

ランタイム構成でインポートする

拡張機能リソースを作成または登録します。

この例は、RuntimeConfig を指定して Vertex AI Search 拡張機能をインポートする方法を示しています。

REST

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

  • PROJECT_ID: 実際のプロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • DISPLAY_NAME: API と UI からユーザーに表示される拡張機能の表示名。UTF-8 文字列で、最大 128 文字です。
  • DESCRIPTION: API と UI からユーザーに表示される拡張機能の説明。UTF-8 文字列で、最大 1 MB です。
  • MANIFEST_NAME: LLM が推論に使用する拡張機能の名前。UTF-8 文字列で、最大 128 文字です。
  • MANIFEST_DESCRIPTION: LLM に提示される自然言語の説明。拡張機能の使用方法を説明するもので、LLM が推論を実行するために不可欠です。UTF-8 文字列で、最大 1 MB です。
  • GCS_URI: 拡張機能 API を記述する OpenAPI YAML ファイルの Cloud Storage URI。
  • AUTH_TYPE: 認証方法。サポートされる値: GOOGLE_SERVICE_ACCOUNT_AUTH。
  • SERVING_CONFIG_NAME: Vertex AI Search サービング構成名。拡張機能で使用する Vertex AI Search リソースを指定します。形式: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}

HTTP メソッドと URL:

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

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

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "manifest": {
    "name": "NAME",
    "description": "MANIFEST_DESCRIPTION",
    "apiSpec": {
      "openApiGcsUri": "GCS_URI",
    },
    "authConfig": {
      "authType": "AUTH_TYPE",
      "googleServiceAccountConfig": {}
    },
    runtime_config={
      "vertex_ai_search_runtime_config": {
          "serving_config_name": 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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions:import" | Select-Object -Expand Content

Python

import vertexai
from vertexai.preview import extensions

vertexai.init(project=PROJECT_ID, location=LOCATION)

extension_vertex_ai_search = extensions.Extension.create(
    display_name = "vertex_ai_search",
    description = "This extension search from provided datastore",
    manifest = {
        "name": "vertex_ai_search",
        "description": "Google Vertex AI Search Extension",
        "api_spec": {
            "open_api_gcs_uri": "gs://vertex-extension-public/vertex_ai_search.yaml"
        },
        "auth_config": {
            "google_service_account_config": {},
            "auth_type": "GOOGLE_SERVICE_ACCOUNT_AUTH",
        },
    },
    runtime_config={
        "vertex_ai_search_runtime_config": {
            "serving_config_name": SERVING_CONFIG_NAME,
        }
    }
)

拡張機能を実行する

拡張機能を実行するには、拡張機能を直接呼び出し、リクエストで実行パラメータを指定します。

この例では、コード インタープリタ拡張機能 generate_and_execute を実行して、クエリ find the max value in the list: [1,2,3,4,-5] の回答を取得します。

REST

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

  • PROJECT_ID: 実際のプロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • EXTENSION_ID: 拡張機能の ID。
  • OPERATION_ID: この拡張機能で実行するように選択したオペレーションの ID。
  • QUERY: オペレーションを実行するための Key-Value 形式によるリクエスト パラメータ、{"query": "What is Vertex AI?"}.。

HTTP メソッドと URL:

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

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

{
  "operation_id": "OPERATION_ID",
  "operation_params": {
    "query": "QUERY",
  }
}

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

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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/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://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content

Vertex AI SDK for Python

Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Vertex AI SDK for Python API のリファレンス ドキュメントをご覧ください。 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "your-extension-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension(extension_id)

response = extension.execute(
    operation_id="generate_and_execute",
    operation_params={"query": "find the max value in the list: [1,2,3,4,-5]"},
)
print(response)
# Example response:
# {
#     "generated_code": "```python\n# Find the maximum value in the list\ndata = [1, 2,..", ..
#     "execution_result": "The maximum value in the list is: 4\n",
#     "execution_error": "",
#     "output_files": [],
# }

拡張機能を一覧表示する

プロジェクト内の拡張機能を一覧表示します。

REST

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

  • PROJECT_ID: 実際のプロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • EXTENSION_ID: 拡張機能の ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions

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

curl

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions"

PowerShell

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions" | Select-Object -Expand Content

Vertex AI SDK for Python

Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Vertex AI SDK for Python API のリファレンス ドキュメントをご覧ください。 

import vertexai
from vertexai.preview import extensions

# TODO (developer):Update project_id
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extensions_list = extensions.Extension.list()
print(extensions_list)
# Example response:
# [<vertexai.extensions._extensions.Extension object at 0x76e8ced37af0>
# resource name: projects/[PROJECT_ID]/locations/us-central1/extensions/1234567890123456]

拡張機能を取得する

拡張機能の詳細を取得します。

REST

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

  • PROJECT_ID: 実際のプロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • EXTENSION_ID: 拡張機能の ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID

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

curl

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID"

PowerShell

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID" | Select-Object -Expand Content

Vertex AI SDK for Python

Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Vertex AI SDK for Python API のリファレンス ドキュメントをご覧ください。 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "your-extension-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension(extension_id)
print(extension.resource_name)
# Example response:
# projects/[PROJECT_ID]/locations/us-central1/extensions/12345678901234567

拡張機能を更新する

拡張機能を更新します。

REST

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

  • PROJECT_ID: 実際のプロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • EXTENSION_ID: 拡張機能の ID。
  • UPDATE_MASK: 更新するパラメータ。指定できる値は displayName、description、toolUseExamples です。

HTTP メソッドと URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID?update_mask="UPDATE_MASK"

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

{
  "description": "UPDATE_MASK",
}

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

curl

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

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

PowerShell

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

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

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

拡張機能を削除する

拡張機能を削除します。

この例では、拡張機能 ID に関連付けられている拡張機能を削除します。

REST

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

  • PROJECT_ID: 実際のプロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • EXTENSION_ID: 拡張機能の ID。

HTTP メソッドと URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID

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

curl

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

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID"

PowerShell

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

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

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/extensions/EXTENSION_ID" | Select-Object -Expand Content

Vertex AI SDK for Python

Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Vertex AI SDK for Python API のリファレンス ドキュメントをご覧ください。 

import vertexai
from vertexai.preview import extensions

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# extension_id = "extension_id"
vertexai.init(project=PROJECT_ID, location="us-central1")

extension = extensions.Extension(extension_id)
extension.delete()
# Example response:
# ...
# Extension resource projects/[PROJECT_ID]/locations/us-central1/extensions/[extension_id] deleted.

次のステップ