Extensions API

扩展程序是供大语言模型 (LLM) 访问外部数据、运行计算以及执行其他操作的工具。它们可以处理实时数据并执行实际操作。

Vertex AI 提供了扩展程序 API，可用于注册、管理和执行扩展程序。Vertex AI 还通过扩展程序 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 和界面向用户显示的扩展程序的显示名称。该名称应该是一个不超过 128 个字符的 UTF-8 字符串。

description

可选：string。

通过 API 和界面向用户显示的扩展程序的说明。该说明应该是一个不超过 1MB 的 UTF-8 字符串。

manifest

JsonDict|ExtensionManifest

扩展程序清单。

runtimeConfig

可选：JsonDict|RuntimeConfig。

用于控制扩展程序运行时行为的运行时配置。

对于代码解释器扩展程序，格式如下：

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

对于 Vertex AI Search 扩展程序，格式如下：

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

manifest

扩展程序清单。

参数

name

string

LLM 用于推理的扩展程序名称。该名称应该是一个不超过 128 个字符的 UTF-8 字符串。

description

string

扩展程序用法的自然语言说明。系统会向 LLM 显示该说明，以帮助其执行推理。该说明应该是一个不超过 1MB 的 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 Extension Service Agent 访问 API。

参数

serviceAccount

可选：string。

运行扩展程序执行作业使用的服务账号。如果指定了服务账号，则应向指定服务账号的 Vertex AI Extension Service Agent 授予 iam.serviceAccounts.getAccessToken 权限。如果未指定，系统会使用 Vertex AI Extension Service Agent 执行扩展程序。

runtimeConfig

runtimeConfig 对象包含运行扩展程序时使用的其他配置。

代码解释器扩展程序

参数

fileInputGcsBucket

可选：string。

扩展程序的文件输入的 Cloud Storage 存储桶。应向 Vertex Extension Custom Code Service Agent 授予此存储桶的 roles/storage.objectViewer 权限。如果未指定，则扩展程序仅接受请求正文中的文件内容，并拒绝 Cloud Storage 文件输入。

fileOutputGcsBucket

可选：string。

扩展程序中的文件输出的 Cloud Storage 存储桶。应向 Vertex Extension Custom Code Service Agent 授予此存储桶的 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 和界面向用户显示的扩展程序的显示名称。该名称应该是一个不超过 128 个字符的 UTF-8 字符串。
  • DESCRIPTION：通过 API 和界面向用户显示的扩展程序的说明。该说明应该是一个不超过 1MB 的 UTF-8 字符串。
  • MANIFEST_NAME：LLM 用于推理的扩展程序名称。该名称应该是一个不超过 128 个字符的 UTF-8 字符串
  • MANIFEST_DESCRIPTION：向 LLM 显示的自然语言说明。它应描述扩展程序的用法，并且对于 LLM 执行推理至关重要。该说明应该是一个不超过 1MB 的 UTF-8 字符串。
  • 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

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。 如需了解详情，请参阅 Python API 参考文档。 

import vertexai
from vertexai.preview import extensions

# TODO (developer): update 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",
        },
    },
)

使用运行时配置导入

创建或注册扩展程序资源。

以下示例展示了如何通过指定 RuntimeConfig 来导入 Vertex AI Search 扩展程序。

REST

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID。
  • LOCATION：处理请求的区域。
  • DISPLAY_NAME：通过 API 和界面向用户显示的扩展程序的显示名称。该名称应该是一个不超过 128 个字符的 UTF-8 字符串。
  • DESCRIPTION：通过 API 和界面向用户显示的扩展程序的说明。该说明应该是一个不超过 1MB 的 UTF-8 字符串。
  • MANIFEST_NAME：LLM 用于推理的扩展程序名称。该名称应该是一个不超过 128 个字符的 UTF-8 字符串
  • MANIFEST_DESCRIPTION：向 LLM 显示的自然语言说明。它应描述扩展程序的用法，并且对于 LLM 执行推理至关重要。该说明应该是一个不超过 1MB 的 UTF-8 字符串。
  • 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：您的项目 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

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。 如需了解详情，请参阅 Python API 参考文档。 

import vertexai
from vertexai.preview import extensions

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

# TODO(developer): Update and un-comment below line
# extension_id = "EXTENSION_ID"
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)

列出扩展程序

列出项目中的扩展程序。

REST

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 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

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。 如需了解详情，请参阅 Python API 参考文档。 

import vertexai
from vertexai.preview import extensions

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

extensions = extensions.Extension.list()
print(extensions)

获取扩展程序

获取扩展程序的详细信息。

REST

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 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

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。 如需了解详情，请参阅 Python API 参考文档。 

import vertexai
from vertexai.preview import extensions

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

# TODO(developer): Update and un-comment below line
# extension_id = "EXTENSION_ID"
extension = extensions.Extension(extension_id)
print(extension)

更新扩展程序

更新扩展程序。

REST

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 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：您的项目 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

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。 如需了解详情，请参阅 Python API 参考文档。 

import vertexai
from vertexai.preview import extensions

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

# TODO(developer): Update and un-comment below line
# extension_id = "EXTENSION_ID"
extension = extensions.Extension(extension_id)
extension.delete()

后续步骤