建立及執行額外資訊

本文說明 Vertex AI 擴充功能服務的主要功能：

如要瞭解如何匯入及執行 Google 提供的擴充功能，請參閱下列文章：

建立及匯入額外資訊

本文假設您已擁有可支援擴充功能的執行中 API 服務。如要建立擴充功能，您必須在 API 規格檔案中定義其與外部 API 的介面。您必須將此規格檔案上傳至 Cloud Storage 值區，或將其轉換為字串。接著，您必須定義擴充功能資訊清單、納入規格檔案，並向擴充功能服務傳送註冊要求。

建立 API 規格檔案

任何人都可以透過定義及描述擴充功能 API 端點的檔案，建立擴充功能。API 端點可以是公開或私人，並託管在任何雲端或內部部署環境中。

API 規格檔案會說明 API 服務的介面。您必須提供以 YAML 格式編寫的 API 規格檔案，且必須與 OpenAPI 3.0 相容。此規格檔案必須定義下列項目：

  • 伺服器物件。這個物件必須定義 API 伺服器網址。Vertex AI 擴充功能服務不支援多個伺服器。

    servers:
  - url: API_SERVICE_URL

  • paths 物件。這個物件必須描述 API 服務提供的各種作業，以及與每項作業相對應的輸入參數。每個作業都必須具備不重複的 ID 和回應。

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

  • components 物件。這個物件為選用項目。您可以使用元件物件定義可重複使用的物件。舉例來說，您可以使用元件物件，為在路徑物件中定義的物件結構定義提供定義。您也可以使用 components 物件來描述 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 物件檢視者 角色。如要瞭解如何列出專案中的值區，請參閱「列出值區」。如要瞭解如何將物件複製至 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 提供摘要文字。

以下是 toolUseExamples 的範例，適用於以所要求語言說出「hello」的 API 服務：

"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，以便儲存及存取機密資料。Vertex AI Extensions 平台不會直接儲存機密資料。您有責任管理 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 密鑰版本資源。這個參數的格式如下：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，以便儲存及存取機密資料。Vertex AI Extensions 平台不會直接儲存機密資料。您必須自行管理 SecretManager 資源的生命週期。

請按照下列方式指定 authConfig：

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}
  • CREDENTIAL_SECRET：儲存 base64 編碼憑證的 SecretManager 密鑰版本資源。這個參數的格式如下：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」頁面

  2. 選取「Service Accounts」分頁標籤。

  3. 按一下服務帳戶。authConfig 中的 SERVICE_ACCOUNT_NAME 值必須與服務帳戶的名稱相符。

  4. 按一下「Permissions」(權限) 分頁標籤。

  5. 點選「授予存取權」。

  6. 在「新增主體」部分的「新增主體」欄位中輸入 service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com。這個主體對應至 Vertex AI Extension Service Agent 服務帳戶。

  7. 在「Assign roles」專區中，找出並選取 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) 權杖。Vertex AI 會將符記的目標對象設為 API_SERVICE_URL，如 API 規格檔案中所定義。

請執行下列步驟，讓 Vertex AI Extension Service Agent 從 SERVICE_ACCOUNT_NAME 取得存取權權杖。

  1. 前往身分與存取權管理頁面。

    前往「IAM」頁面

  2. 選取「Service Accounts」分頁標籤。

  3. 按一下服務帳戶。authConfig 中的 SERVICE_ACCOUNT_NAME 值必須與服務帳戶的名稱相符。

  4. 按一下「Permissions」(權限) 分頁標籤。

  5. 點選「授予存取權」。

  6. 在「新增主體」部分的「新增主體」欄位中輸入 service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com。這個主體對應至 Vertex AI Extension Service Agent 服務帳戶。

  7. 在「Assign roles」專區中，找出並選取 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"

後續步驟