创建和运行扩展程序

本文档介绍了 Vertex AI 扩展程序服务的关键功能：

如需了解如何导入和运行 Google 提供的扩展程序，请参阅以下内容：

创建和导入扩展程序

本文档假定您已有一个可以支持扩展程序的运行中的 API 服务。如需创建扩展程序，您必须在 API 规范文件中定义该扩展程序与相应外部 API 的接口。您必须将此规范文件上传到 Cloud Storage 存储桶，或者将其转换为字符串。之后，您必须定义扩展程序清单、添加规范文件，并向扩展程序服务发送注册请求。

创建 API 规范文件

任何人都可以使用定义和描述扩展程序的 API 端点的文件来创建扩展程序。API 端点可以是公共端点，也可以是专用端点，并且可以托管在任何云端或本地。

API 规范文件描述了 API 服务的接口。您必须提供与 OpenAPI 3.0 兼容的 YAML 格式的 API 规范文件。此规范文件必须定义以下内容：

  • 服务器对象。此对象必须定义 API 服务器网址。Vertex AI 扩展程序服务不支持多个服务器。

    servers:
  - url: API_SERVICE_URL

  • 路径对象。此对象必须描述 API 服务提供的各种操作以及与每个操作对应的输入参数。每个操作都必须具有唯一标识符和响应。

    paths:
  ...
    get:
      operationId: API_SERVICE_OPERATION_ID
      ...
      parameters:
        - name: API_SERVICE_INPUT_VAR
          ...
      responses:
      ...

  • 组件对象。此对象是可选对象。您可以使用组件对象来定义可重复使用的对象。例如，您可以使用组件对象来提供路径对象中定义的对象架构的定义。您还可以使用组件对象来描述 API 服务的输出参数。

    components:
  schemas:
    Result:
      ...
      properties:
        API_SERVICE_OUTPUT_VAR:
        ...

如需详细了解 OpenAPI，请参阅 OpenAPI 规范。

以下示例是一个 API 服务的 API 规范文件，该文件用请求的语言说“hello”：

  openapi: "3.0.0"
  info:
    version: 1.0.0
    title: Hello Extension
    description: Learn to build Vertex AI extensions
  servers:
    - url: [API_SERVICE_URL]
  paths:
    /hello:
      get:
        operationId: say_hello
        description: Say hello in prompted language.
        parameters:
          - name: apiServicePrompt
            in: query
            description: Language
            required: true
            schema:
              type: string
        responses:
          '200':
            description: Successful operation.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Result"
  components:
    schemas:
      Result:
        description: Hello in the requested language.
        properties:
          apiServiceOutput:
            type: string

上传规范文件

您可以将规范文件上传到 Cloud Storage 存储桶，或者将其转换为字符串。

如果您将规范文件上传到 Cloud Storage 存储桶，请为 Vertex AI Extension Service Agent 服务账号 (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com) 授予 Storage Object Viewer 角色。如需了解如何列出项目中的存储桶，请参阅列出存储桶。如需了解如何将对象复制到 Cloud Storage 存储桶，请参阅复制、重命名和移动对象。

定义扩展程序导入请求

创建 API 规范文件后，您可以在 JSON 文件中定义扩展程序导入请求。扩展程序导入请求必须包含对 API 规范文件 (apiSpec) 和身份验证配置 (authConfig) 的引用。如需将扩展程序连接到大语言模型 (LLM) 以查看扩展程序的工作原理，请添加可选的 toolUseExamples 参数。如果您只想运行扩展程序，请勿添加 toolUseExamples 参数。

扩展程序导入请求采用以下格式：

{
  "displayName":  "DISPLAY_NAME_HUMAN",
  "description": "DESCRIPTION_HUMAN",
  "manifest": {
    "name": "EXTENSION_NAME_LLM",
    "description": "DESCRIPTION_LLM",
    "apiSpec": { ... },
    "authConfig": { ... },
  }
  "toolUseExamples": [ ... ],
}
  • DISPLAY_NAME_HUMAN：向用户显示的扩展程序名称。
  • DESCRIPTION_HUMAN：向用户显示的扩展程序的说明。
  • EXTENSION_NAME_LLM：LLM 用于推理的扩展程序名称。
  • DESCRIPTION_LLM：LLM 用于推理的扩展程序的说明。您应提供有意义的、有帮助的说明。

引用 API 规范文件

扩展程序导入请求必须包含对 API 规范文件的引用。您可以通过以下两种方式提供规范文件：

  • 使用 openApiGcsUri 传入 YAML 文件的 Cloud Storage URI。

    "apiSpec": {
  "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml"
},
    • BUCKET_NAME：存储规范文件的 Cloud Storage 存储桶的名称。
    • SPECIFICATION_FILE_NAME：API 规范文件的名称。

  • 使用 openApiYaml 将 YAML 文件作为字符串传入。

身份验证配置

扩展程序可以是公开的（可供任何用户使用），也可以是专用的（仅可供一个或多个组织中已获授权的用户使用）。

扩展程序导入请求必须包含身份验证配置。您可以从以下身份验证方法中进行选择：

  • NO_AUTH：无身份验证
  • API_KEY_AUTH：API 密钥身份验证
  • HTTP_BASIC_AUTH：HTTP 基本身份验证
  • OAUTH：OAuth 身份验证
  • OIDC_AUTH：OIDC 身份验证

如需详细了解身份验证配置，请参阅指定身份验证配置。

演示扩展程序工作原理的示例

为获得最佳效果，扩展程序导入请求应包含展示扩展程序工作原理的示例。可使用 toolUseExamples 参数提供这些示例。

以下代码展示了单个示例的 toolUseExamples 格式，该示例包含一个输入参数和一个输出参数。在此示例中，请求和响应参数均为 string 类型。

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "API_SERVICE_OPERATION_ID",
      },
      "displayName": "EXAMPLE_DISPLAY_NAME",
      "query": "EXAMPLE_QUERY",
      "requestParams": {
        "fields": [
          {
            "key": "API_SERVICE_INPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_INPUT",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "API_SERVICE_OUTPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_OUTPUT",
            },
          }
        ],
      },
      "responseSummary": "EXAMPLE_SUMMARY"
    }
],
  • query：可以利用此扩展程序的查询示例。可使用 EXAMPLE_QUERY 提供查询文本。
  • extensionOperation：适合回应 query 的扩展程序操作。使用 API_SERVICE_OPERATION_ID 提供在 API 规范文件中定义的扩展程序操作的 ID。
  • displayName：示例的显示名称。使用 EXAMPLE_DISPLAY_NAME 提供简要说明。
  • requestParams：extensionOperation 和示例值所需的请求参数（采用键值对格式）。使用 API_SERVICE_INPUT_VAR 提供在 API 规范文件中定义并与 API_SERVICE_OPERATION_ID 对应的输入参数。使用 EXAMPLE_INPUT 提供与 EXAMPLE_QUERY 对应的输入值的示例。
  • responseParams：extensionOperation 和示例值的响应参数（采用键值对格式）。使用 API_SERVICE_OUTPUT_VAR 提供在 API 规范文件中定义并与 API 服务对应的输出参数。使用 EXAMPLE_OUTPUT 提供与 EXAMPLE_INPUT 对应的输出值的示例。
  • responseSummary：应用可能在响应 query 时提供的摘要示例。可使用 EXAMPLE_SUMMARY 提供摘要文本。

以下是使用请求的语言显示“hello”的 API 服务的 toolUseExamples 示例：

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "say_hello",
      },
      "displayName": "Say hello in the requested language",
      "query": "Say hello in French",
      "requestParams": {
        "fields": [
          {
            "key": "apiServicePrompt",
            "value": {
              "string_value": "French",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "apiServiceOutput",
            "value": {
              "string_value": "bonjour",
            },
          }
        ],
      },
      "responseSummary": "Bonjour"
    }
],

指定身份验证配置

您必须在定义扩展程序导入请求时指定身份验证配置。

如果您的扩展程序不需要身份验证，请将 authType 变量设置为 NO_AUTH：

"authConfig": {
  "authType": "NO_AUTH"
}

如果您的扩展程序需要身份验证，则必须在 authType 变量中设置身份验证类型，并提供身份验证配置。您可以从以下身份验证方法中进行选择：

API 密钥身份验证

为了支持 API 密钥身份验证，Vertex AI 与 SecretManager 集成以进行 Secret 存储和访问。Vertex AI Extensions 平台不直接存储 Secret 数据。您需要管理 SecretManager 资源的生命周期。

按如下所示指定 authConfig：

"authConfig": {
  "authType": "API_KEY_AUTH",
  "apiKeyConfig": {
    "name": "API_KEY_CONFIG_NAME",
    "apiKeySecret": "API_KEY_SECRET",
    "httpElementLocation": "HTTP_ELEMENT_LOCATION",
  },
}
  • API_KEY_CONFIG_NAME：API 密钥的名称。例如，在 API 请求 https://example.com/act?api_key=<API KEY> 中，API_KEY_CONFIG_NAME 与 api_key 相对应。
  • API_KEY_SECRET：存储该密钥的 SecretManager Secret 版本资源。此参数的格式如下： projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION。

  • HTTP_ELEMENT_LOCATION：HTTP 请求中 API 密钥的位置。可能的值包括：

    • HTTP_IN_QUERY
    • HTTP_IN_HEADER
    • HTTP_IN_PATH
    • HTTP_IN_BODY
    • HTTP_IN_COOKIE

    如需了解详情，请参阅描述参数。

HTTP 基本身份验证

为了支持 HTTP 密钥身份验证，Vertex AI 与 SecretManager 集成以进行 Secret 存储和访问。Vertex AI Extensions 平台不直接存储 Secret 数据。您必须自行管理 SecretManager 资源的生命周期。

按如下所示指定 authConfig：

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}
  • CREDENTIAL_SECRET：存储 base64 编码的凭据的 SecretManager Secret 版本资源。此参数的格式如下： projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION。

OAuth 身份验证

Vertex AI 支持两种 OAuth 身份验证方法：访问令牌和服务账号。

访问令牌

按如下所示指定 authConfig：

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {}
}

导入扩展程序时，请将 oauthConfig 字段留空。如果您选择运行已注册的扩展程序，则必须在执行请求的 oauthConfig 字段中提供访问令牌。如需了解详情，请参阅运行扩展程序。

服务账号

按如下所示指定 authConfig：

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME：Vertex AI 将使用此服务账号来生成访问令牌。

执行以下步骤以允许 Vertex AI Extension Service Agent 从 SERVICE_ACCOUNT_NAME 获取访问令牌。

  1. 转到 IAM 页面。

    进入 IAM

  2. 选择服务账号标签页。

  3. 点击您的服务账号。authConfig 中 SERVICE_ACCOUNT_NAME 的值必须与您的服务账号的名称相对应。

  4. 点击权限标签页。

  5. 点击授予访问权限。

  6. 在添加主账号部分的新的主账号字段中，输入 service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com。此主账号与 Vertex AI Extension Service Agent 服务账号相对应。

  7. 在分配角色部分，找到并选择 Service Account Token Creator 角色。此角色可提供 iam.serviceAccounts.getAccessToken 权限。

  8. 点击保存按钮。

OIDC 身份验证

Vertex AI 支持两种 OIDC 身份验证方法：ID 令牌和服务账号。

ID 令牌

按如下所示指定 authConfig：

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {}
}

导入扩展程序时，请将 oidcConfig 字段留空。如果您选择运行已注册的扩展程序，则必须在执行请求的 oidcConfig 字段中提供 ID 令牌。如需了解详情，请参阅运行扩展程序。

服务账号

按如下所示指定 authConfig：

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME：Vertex AI 使用此服务账号生成 OpenID Connect (OIDC) 令牌。根据 API 规范文件中所定义，Vertex AI 将该令牌的受众群体设置为 API_SERVICE_URL。

执行以下步骤以允许 Vertex AI Extension Service Agent 从 SERVICE_ACCOUNT_NAME 获取访问令牌。

  1. 转到 IAM 页面。

    进入 IAM

  2. 选择服务账号标签页。

  3. 点击您的服务账号。authConfig 中 SERVICE_ACCOUNT_NAME 的值必须与您的服务账号的名称相对应。

  4. 点击权限标签页。

  5. 点击授予访问权限。

  6. 在添加主账号部分的新的主账号字段中，输入 service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com。此主账号与 Vertex AI Extension Service Agent 服务账号相对应。

  7. 在分配角色部分，找到并选择 Service Account Token Creator 角色。此角色可提供 iam.serviceAccounts.getOpenIdToken 权限。

  8. 点击保存按钮。

使用 Vertex AI 导入扩展程序

定义扩展程序导入请求后，您便可以使用 Vertex AI 导入扩展程序。

  1. 设置以下 shell 变量：

    ENDPOINT="LOCATION-aiplatform.googleapis.com"
URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
    • PROJECT_ID：您的项目。
    • LOCATION：您选择的区域。如果您不确定，请选择 us-central1。

  2. 运行以下 curl 命令以提交导入请求：

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @IMPORT_REQUEST.json "${URL}/extensions:import"

    响应的格式如下：

    {
  "name": "projects/[PROJECT_NUMBER]/locations/[LOCATION]/extensions/[EXTENSION_ID]/operations/[IMPORT_OPERATION_ID]",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata",
    "genericMetadata": {
      "createTime": "[CREATE_TIME]",
      "updateTime": "[UPDATE_TIME]"
    }
  }
}

  3. 根据导入请求的输出设置 Shell 变量：

    EXTENSION_ID=EXTENSION_ID
IMPORT_OPERATION_ID=IMPORT_OPERATION_ID

  4. 如需检查导入的状态，请运行以下 curl 命令：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/operations/${IMPORT_OPERATION_ID}"

管理扩展程序

如需列出所有已注册的扩展程序，请运行以下 curl 命令：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions"

如需获取扩展程序，请运行以下 curl 命令：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions/${EXTENSION_ID}"

您可以更新扩展程序的 displayName、description 或 toolUseExamples。如果您在更新扩展程序时指定 toolUseExamples，则更新内容会替换示例。例如，如果您有 a 和 b 示例，然后使用示例 c 更新扩展程序，则更新后的扩展程序仅包含示例 c。如需更新扩展程序说明，请运行以下 curl 命令：

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

如需删除扩展程序，请运行以下 curl 命令：

curl \
 -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}

运行扩展程序

您可以通过以下两种方式运行扩展程序：

  • execute：此模式仅专注于 API 执行。此扩展程序会触发指定的 API 操作并返回原始结果，无需进一步处理。

  • query：此模式专为智能互动而设计。它涉及多个步骤：

    • 模型请求：查询和扩展程序的架构分别作为提示和 FunctionDeclaration 提供给 Gemini。
    • API 执行：如果模型确定需要使用该工具，扩展程序会代表模型自动调用 API 操作并检索结果。
    • 模型集成：API 结果会馈送到模型，模型对其进行处理，以生成与上下文相关的最终响应。本质上，query 充当单工具代理，使用 API 来实现其目标。

本部分介绍了如何 execute 扩展程序。

如果扩展程序使用 OAuth 身份验证和访问令牌，请参阅使用 OAuth 身份验证和访问令牌运行扩展程序。

如果扩展程序使用 OIDC 身份验证和 ID 令牌，请参阅使用 OIDC 身份验证和 ID 令牌运行扩展程序。

否则，您可以按照以下步骤运行扩展程序：

  1. 创建名为 execute-extension.json 且包含以下内容的文件：

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {
    "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE"
  }
}
    • API_SERVICE_OPERATION_ID：您要运行的 API 服务操作的 ID。API 服务操作在 API 规范文件中定义。
    • API_SERVICE_INPUT_VAR：与 API_SERVICE_OPERATION_ID 对应的输入变量，并在 API 规范文件中定义。
    • API_SERVICE_INPUT_VALUE：扩展程序的输入值。

  2. 运行以下 curl 命令：

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

    响应的格式如下：

    {
  "output": {
    "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}"
  }
}
    • API_SERVICE_OUTPUT_VAR：在 API 规范文件中定义并与 API 服务对应的输出参数。
    • API_SERVICE_OUTPUT_VALUE：一个字符串值，它是响应对象的序列化。如果 API 规范文件定义了 JSON 响应架构，则必须自行将此输出字符串解析为 JSON。

使用 OAuth 身份验证和访问令牌运行扩展程序

如果扩展程序使用 OAuth 身份验证和访问令牌，则可以按照以下步骤运行扩展程序：

  1. 创建名为 execute-extension.json 且包含以下内容的文件：

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {...},
  "runtime_auth_config": {
    "authType": "OAUTH",
    "oauth_config": {"access_token": "'$(gcloud auth print-access-token)'"}
  }
}
    • API_SERVICE_OPERATION_ID：您要运行的 API 服务操作的 ID。API 服务操作在 API 规范文件中定义。

  2. 运行以下 curl 命令：

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

使用 OIDC 身份验证和 ID 令牌运行扩展程序

如果扩展程序使用 OIDC 身份验证和 ID 令牌，则可以按照以下步骤运行扩展程序：

  1. 创建名为 execute-extension.json 且包含以下内容的文件：

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {...},
  "runtime_auth_config": {
    "authType": "OIDC_AUTH",
    "oidc_config": {"id_token": "$(gcloud auth print-identity-token)"}
  }
}
    • API_SERVICE_OPERATION_ID：您要运行的 API 服务操作的 ID。API 服务操作在 API 规范文件中定义。

  2. 运行以下 curl 命令：

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

后续步骤