创建和运行扩展程序

本文档介绍了 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 提供简要说明。
  • requestParamsextensionOperation 和示例值所需的请求参数(采用键值对格式)。使用 API_SERVICE_INPUT_VAR 提供在 API 规范文件中定义并与 API_SERVICE_OPERATION_ID 对应的输入参数。使用 EXAMPLE_INPUT 提供与 EXAMPLE_QUERY 对应的输入值的示例。
  • responseParamsextensionOperation 和示例值的响应参数(采用键值对格式)。使用 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_NAMEapi_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 AgentSERVICE_ACCOUNT_NAME 获取访问令牌。

  1. 转到 IAM 页面。

    进入 IAM

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

  3. 点击您的服务账号。authConfigSERVICE_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 AgentSERVICE_ACCOUNT_NAME 获取访问令牌。

  1. 转到 IAM 页面。

    进入 IAM

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

  3. 点击您的服务账号。authConfigSERVICE_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}"

您可以更新扩展程序的 displayNamedescriptiontoolUseExamples。如果您在更新扩展程序时指定 toolUseExamples,则更新内容会替换示例。例如,如果您有 ab 示例,然后使用示例 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"
    

后续步骤