Extensions API

擴充功能是大型語言模型 (LLM) 的工具，可存取外部資料、執行運算及其他作業。處理即時資料並執行現實世界的動作。

Vertex AI 提供 Extension API，可註冊、管理及執行擴充功能。Vertex AI 也提供一組來自 Extension API 的預建擴充功能，包括程式碼解譯器擴充功能和 Vertex AI Search 擴充功能。

限制

擴充功能 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 使用者顯示的擴充功能顯示名稱。這應是長度最多 128 個字元的 UTF-8 字串。

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

大型語言模型用於推理的擴充功能名稱。這應是長度最多 128 個字元的 UTF-8 字串。

description

string

擴充功能用途的自然語言說明。這段說明會顯示給 LLM，協助其執行推理。這應是大小不超過 1 MB 的 UTF-8 字串。

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 擴充功能服務代理存取 API。

參數

serviceAccount

自由參加：string

擴充功能執行作業使用的服務帳戶。如果指定服務帳戶，請將 iam.serviceAccounts.getAccessToken 權限授予指定服務帳戶的 Vertex AI Extension 服務代理。如未指定，系統會使用 Vertex AI Extension 服務代理執行擴充功能。

runtimeConfig

runtimeConfig 物件包含執行擴充功能時使用的其他設定。

程式碼解譯器擴充功能

參數

fileInputGcsBucket

自由參加：string

擴充功能輸入檔案的 Cloud Storage bucket。請將這個值區的 roles/storage.objectViewer 權限授予 Vertex 擴充功能自訂程式碼服務代理。如未指定，擴充功能只會接受要求主體的檔案內容，並拒絕 Cloud Storage 檔案輸入。

fileOutputGcsBucket

自由參加：string

擴充功能輸出檔案的 Cloud Storage bucket。請將這個值區的 roles/storage.objectUser 權限授予 Vertex 擴充功能自訂程式碼服務代理。如果未指定，檔案內容會輸出至回應主體。

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 向使用者顯示的擴充功能顯示名稱。這應是長度最多 128 個字元的 UTF-8 字串。
  • DESCRIPTION：向使用者顯示的擴充功能說明 (透過 API 和 UI)。這應為 UTF-8 字串，大小上限為 1 MB。
  • MANIFEST_NAME：大型語言模型用於推理的擴充功能名稱。這應為 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 方法和網址：

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

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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：。
  • LOCATION：處理要求的區域。
  • DISPLAY_NAME：API 和 UI 向使用者顯示的擴充功能顯示名稱。這應是長度最多 128 個字元的 UTF-8 字串。
  • DESCRIPTION：向使用者顯示的擴充功能說明 (透過 API 和 UI)。這應為 UTF-8 字串，大小上限為 1 MB。
  • MANIFEST_NAME：大型語言模型用於推理的擴充功能名稱。這應為 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 方法和網址：

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：。
  • LOCATION：處理要求的區域。
  • EXTENSION_ID：擴充功能的 ID。
  • OPERATION_ID：要在這個擴充功能中執行的作業所選 ID。
  • QUERY：以鍵/值格式執行作業的要求參數，{"query": "What is Vertex AI?"}.

HTTP 方法和網址：

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

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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：。
  • LOCATION：處理要求的區域。
  • EXTENSION_ID：擴充功能的 ID。

HTTP 方法和網址：

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

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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：。
  • LOCATION：處理要求的區域。
  • EXTENSION_ID：擴充功能的 ID。

HTTP 方法和網址：

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

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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：。
  • LOCATION：處理要求的區域。
  • EXTENSION_ID：擴充功能的 ID。
  • UPDATE_MASK：要更新的參數。可接受的值為 displayName、description 或 toolUseExamples。

HTTP 方法和網址：

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：。
  • LOCATION：處理要求的區域。
  • EXTENSION_ID：擴充功能的 ID。

HTTP 方法和網址：

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

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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.

後續步驟