Extensions API

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

Vertex AI 提供可以注册、管理和执行扩展程序的 Extension API。Vertex AI 还提供了 Extension API 中的一组预构建扩展程序,包括代码解释器扩展程序和 Vertex AI Search 扩展程序。

局限性

Extension API 仅在 us-central1 区域可用。

示例语法

用于创建扩展程序资源的语法。

curl

curl -X POST \

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

http://${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 和界面向用户显示的扩展程序的显示名称。这应该是 UTF-8 字符串,最多 128 个字符。

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 用于推理的扩展程序名称。这应该是 UTF-8 字符串,最多 128 个字符。

description

string

扩展程序使用情况的自然语言说明。系统会向 LLM 显示说明,以帮助其执行推理。该说明应为 UTF-8 字符串,大小不超过 1MB。

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 的参数设置为字符串“什么是 Vertex AI?”,您可以使用 {"query": "What is Vertex AI?"}

示例

导入代码解释器扩展程序

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

此示例展示了如何导入代码解释器扩展程序。

REST

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

  • PROJECT_ID:您的项目 ID
  • LOCATION:处理请求的区域。
  • DISPLAY_NAME:通过 API 和界面向用户显示的扩展程序的显示名称。这应该是 UTF-8 字符串,最多 128 个字符。
  • 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 http://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 \
"http://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 "http://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 lines
# project_id = "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 和界面向用户显示的扩展程序的显示名称。这应该是 UTF-8 字符串,最多 128 个字符。
  • 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 http://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 \
"http://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 "http://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 http://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 \
"http://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 "http://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 = "PROJECT_ID"
# extension_id = "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)

列出扩展程序

列出项目中的扩展程序。

REST

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

  • PROJECT_ID:您的项目 ID
  • LOCATION:处理请求的区域。
  • EXTENSION_ID:扩展程序的 ID。

HTTP 方法和网址:

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

如需发送请求,请选择以下方式之一:

curl

执行以下命令:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"http://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 "http://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 and un-comment below lines
# project_id = "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 http://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)" \
"http://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 "http://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 = "PROJECT_ID"
# extension_id = "EXTENSION_ID"

vertexai.init(project=project_id, location="us-central1")

extension = extensions.Extension(extension_id)
print(extension)

更新扩展程序

更新扩展程序。

REST

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

  • PROJECT_ID:您的项目 ID
  • LOCATION:处理请求的区域。
  • EXTENSION_ID:扩展程序的 ID。
  • UPDATE_MASK:要更新的参数。接受的值:displayNamedescriptiontoolUseExamples

HTTP 方法和网址:

PATCH http://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 \
"http://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 "http://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 http://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)" \
"http://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 "http://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 = "PROJECT_ID"
# extension_id = "EXTENSION_ID"

vertexai.init(project=project_id, location="us-central1")

extension = extensions.Extension(extension_id)
extension.delete()

后续步骤