Vertex AI には、拡張機能の登録、管理、実行を行う Extension API が用意されています。Vertex AI には、コード インタープリタ拡張機能や 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 )
パラメータ リスト
リクエストの本文
| パラメータ | |
|---|---|
|
省略可: API と UI からユーザーに表示される拡張機能の表示名。UTF-8 文字列で、最大 128 文字です。 |
|
省略可: API と UI からユーザーに表示される拡張機能の説明。UTF-8 文字列で、最大 1 MB です。 |
拡張機能のマニフェスト。 |
|
省略可: 拡張機能のランタイム動作を制御するランタイム構成。 コード インタープリタ拡張機能の場合、形式は次のとおりです。 "runtimeConfig": { "codeInterpreterRuntimeConfig": { "fileInputGcsBucket": string, "fileOutputGcsBucket": string } } Vertex AI Search 拡張機能の場合、形式は次のとおりです。 "runtimeConfig": { "vertexAiSearchRuntimeConfig": { "servingConfigName": string, } } |
|
manifest
拡張機能のマニフェスト。
| パラメータ | |
|---|---|
|
LLM が推論に使用する拡張機能の名前。UTF-8 文字列で、最大 128 文字です。 |
|
拡張機能の使用方法の自然言語による説明。説明は、LLM が推論を行う際に表示されます。これは、最大 1 MB の UTF-8 文字列にする必要があります。 |
推論のために LLM に提示される API 仕様。意味があり、参考になる説明を入力する必要があります。 "apiSpec": { "openApiGcsUri": string } |
|
この拡張機能でサポートされている認証のタイプ。 拡張機能のインポート リクエストには、認証構成を含める必要があります。 "authConfig": { "authType": "GOOGLE_SERVICE_ACCOUNT_AUTH", "googleServiceAccountConfig": { "serviceAccount": string }, } |
|
apiSpec
推論のために LLM に提示される API 仕様。
| パラメータ | |
|---|---|
|
拡張機能 API を記述する OpenAPI YAML ファイルの Cloud Storage URI（ |
authConfig
この拡張機能でサポートされている認証の種類。
| パラメータ | |
|---|---|
|
認証方法。使用できる値: |
googleServiceAccountConfig
コード インタープリタ拡張機能と Vertex AI Search 拡張機能は、Google サービス アカウント認証のみをサポートしています。この場合、Vertex AI は Vertex AI Extension サービス エージェントを使用して API にアクセスします。
| パラメータ | |
|---|---|
|
省略可: 拡張機能の実行が実行されるサービス アカウント。サービス アカウントを指定する場合は、指定したサービス アカウントの Vertex AI Extension Service エージェントに |
runtimeConfig
runtimeConfig オブジェクトには、拡張機能の実行時に使用される追加の構成が含まれています。
コード インタープリタ拡張機能
| パラメータ | |
|---|---|
|
省略可: 拡張機能に入力するファイルの Cloud Storage バケット。Vertex Extension カスタム コード サービス エージェントに、このバケットに対する |
|
省略可: 拡張機能から出力されるファイルの Cloud Storage バケット。Vertex Extension カスタム コード サービス エージェントに、このバケットに対する |
Vertex AI Search 拡張機能
| パラメータ | |
|---|---|
|
Vertex AI Search サービング構成名。拡張機能で使用する Vertex AI Search リソースを指定します。形式:
|
拡張機能を実行する
| パラメータ | |
|---|---|
|
この拡張機能で実行するオペレーションの選択した ID。 |
|
省略可: このオペレーションの実行に使用されるリクエスト パラメータ。JSON は、パラメータ名をキーとして、実際のパラメータ値を値として持つマップの形式にする必要があります。たとえば、 |
例
コード インタープリタ拡張機能をインポートする
拡張機能リソースを作成または登録します。
この例では、コード インタープリタ拡張機能をインポートする方法を示します。
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
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
ランタイム構成でインポートする
拡張機能リソースを作成または登録します。
この例では、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
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
拡張機能の一覧表示
プロジェクト内の拡張機能を一覧表示します。
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
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
延長を取得する
拡張機能の詳細を取得します。
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
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
拡張機能を更新する
拡張機能を更新する。
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
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。