本頁面由 Cloud Translation API 翻譯而成。

建立及執行額外資訊

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

如何建立及匯入擴充功能。
如何管理擴充功能。
如何執行擴充功能。

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

使用程式碼解譯器擴充功能生成及執行程式碼。
使用 Vertex AI Search 擴充功能存取及搜尋網站語料庫和非結構化資料，針對自然語言問題提供相關回覆。

建立及匯入擴充功能

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

建立 API 規格檔案

任何人都能透過定義及說明擴充功能 API 端點的檔案建立擴充功能。API 端點可以是公開或私人的，且可託管於任何雲端或地端。

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

伺服器物件。這個物件必須定義 API 伺服器網址。Vertex AI 擴充功能服務不支援多部伺服器。
```
servers:
  - url: API_SERVICE_URL
```

路徑物件。這個物件必須說明 API 服務提供的各種作業，以及與每個作業對應的輸入參數。每項作業都必須有不重複的 ID 和回應。

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

元件物件。這個物件為選用項目。您可以使用 components 物件定義可重複使用的物件。舉例來說，您可以使用 components 物件，提供 paths 物件中定義的物件結構定義。您也可以使用 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 bucket，或將其轉換為字串。

如果將規格檔案上傳至 Cloud Storage 值區，請將「Storage 物件檢視者」角色授予 Vertex AI Extension Service Agent 服務帳戶 (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com)。如要瞭解如何列出專案中的 bucket，請參閱列出 bucket。如要瞭解如何將物件複製到 Cloud Storage bucket，請參閱「複製、重新命名及移動物件」。

定義擴充功能匯入要求

建立 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 bucket 名稱。
- 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 提供摘要文字。

以下是 API 服務的 toolUseExamples 範例，該服務會以要求的語言說「hello」：

"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 變數中設定驗證類型，並提供驗證設定。您可以選擇下列驗證方式：

HTTP API 金鑰驗證
HTTP 基本驗證
OAuth 驗證
OIDC 驗證

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 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，用於儲存及存取密碼。Vertex AI Extensions 平台不會直接儲存密碼資料。您必須自行管理 SecretManager 資源的生命週期。

按照下列方式指定 authConfig：

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}

CREDENTIAL_SECRET：SecretManager 儲存 Base64 編碼憑證的密碼版本資源。這個參數的格式如下：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 取得存取權杖。

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

前往「IAM」頁面
選取「服務帳戶」分頁標籤。
按一下服務帳戶。authConfig 中的 SERVICE_ACCOUNT_NAME 值必須與服務帳戶名稱相符。
按一下「具有存取權的主體」分頁標籤。
點選「授予存取權」。
在「新增主體」部分的「新增主體」欄位中，輸入 service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com。這個主體對應於 Vertex AI Extension Service Agent 服務帳戶。
在「指派角色」專區中，找出並選取 Service Account Token Creator 角色。這個角色包含 iam.serviceAccounts.getAccessToken 權限。
按一下「儲存」按鈕。

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 取得存取權杖。

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

前往「IAM」頁面
選取「服務帳戶」分頁標籤。
按一下服務帳戶。authConfig 中的 SERVICE_ACCOUNT_NAME 值必須與服務帳戶名稱相符。
按一下「Permissions」(權限) 分頁標籤。
點選「授予存取權」。
在「新增主體」部分的「新增主體」欄位中，輸入 service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com。這個主體對應於 Vertex AI Extension Service Agent 服務帳戶。
在「指派角色」專區中，找出並選取 Service Account Token Creator 角色。這個角色包含 iam.serviceAccounts.getOpenIdToken 權限。
按一下「儲存」按鈕。

使用 Vertex AI 匯入擴充功能

定義擴充功能匯入要求後，即可使用 Vertex AI 匯入擴充功能。

設定下列殼層變數：
```
ENDPOINT="LOCATION-aiplatform.googleapis.com"
URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
```
- PROJECT_ID：您的專案。
- LOCATION：您選擇的區域。如果不確定，請選擇 us-central1。

執行下列 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"

IMPORT_REQUEST：JSON 檔案名稱，其中包含擴充功能匯入要求。

回應格式如下：

{
  "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]"
    }
  }
}

根據匯入要求輸出內容設定 Shell 變數：

EXTENSION_ID=EXTENSION_ID
IMPORT_OPERATION_ID=IMPORT_OPERATION_ID

如要查看匯入狀態，請執行下列 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 權杖執行擴充功能」。

否則，請按照下列步驟執行：

建立名為 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：擴充功能的輸入值。

執行下列 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 驗證和存取權杖，請按照下列步驟執行：

建立名為 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 規格檔案中定義。

執行下列 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 權杖，請按照下列步驟執行：

建立名為 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 規格檔案中定義。

執行下列 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"

後續步驟

建構及部署 LLM 自動調度管理架構。

建立及執行額外資訊 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建立及匯入擴充功能

建立 API 規格檔案

上傳規格檔案

定義擴充功能匯入要求

API 規格檔案的參照

驗證設定

示範擴充功能運作方式的範例

指定驗證設定

API 金鑰驗證

HTTP 基本驗證

OAuth 驗證

存取權杖

服務帳戶

OIDC 驗證

ID 權杖

服務帳戶

使用 Vertex AI 匯入擴充功能

管理擴充功能

執行擴充功能

使用 OAuth 驗證和存取權杖執行擴充功能

使用 OIDC 驗證和 ID 權杖執行擴充功能

後續步驟

建立及執行額外資訊