設定擴充功能來呼叫 Google 服務

有了 Service Extensions，支援的應用程式負載平衡器就能透過呼叫 Google 服務來設定擴充功能。本頁面說明如何設定這類擴充功能。

如需總覽說明，請參閱「與 Google 服務整合」。

設定流量擴充功能，呼叫 Model Armor 服務

您可以設定流量擴充功能來呼叫 Model Armor，對應用程式負載平衡器 (包括 GKE Inference Gateway) 的生成式 AI 推論流量，統一強制執行安全性政策。

流量擴展功能會將相關擴展服務歸入一或多個鏈結。您可以在同一個擴充功能鏈中設定外掛程式和附註。每個擴充功能鏈結都會使用一般運算語言 (CEL) 比對條件，選取要處理的流量。負載平衡器會依序評估要求是否符合每個鏈結的相符條件。如果要求符合鏈結定義的條件，鏈結中的所有擴充功能都會對要求採取行動。只有一個鏈結符合特定要求。

鏈結中的每個擴充功能都可以有自己的支援事件集。擴充功能對要求和回應內容所做的修改，會顯示在鏈結中的其餘擴充功能。如果擴充功能已設定為支援回應事件，回應路徑上的擴充功能順序會反轉。

流量擴充功能會附加至使用 Inference Gateway 建立的負載平衡器轉送規則。設定資源後，系統會將相符要求傳送至 Model Armor 服務。

事前準備

  1. 找出合適的專案，您必須具有專案擁有者或編輯者角色，或是下列 Compute Engine IAM 角色：

  2. 啟用必要的 API。

    控制台

    1. 前往 Google Cloud 控制台的「Enable access to APIs」(啟用 API 存取權) 頁面。

      前往「啟用 API 存取權」

    2. 按照操作說明啟用必要 API，包括 Compute Engine API、Model Armor API 和 Network Services API。

    gcloud

    使用 gcloud services enable 指令：

    gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com

  3. 建立必要的 Model Armor 範本。

  4. 部署 Inference Gateway，設定 Google Kubernetes Engine 基礎架構。傳送推論要求進行測試。

    受幾項限制約束，我們支援下列 OpenAI API 端點：Assistants、Chat Completions、Completions (舊版)、Messages 和 Threads。

設定 OpenAI API 端點時的限制

為 GKE 基礎架構設定 OpenAI API 端點時，請注意以下清除提示和回應的限制：

  • 任何 API 都不支援串流 API 回應。Model Armor 會清理非串流回覆，並忽略串流回覆。

  • 系統只支援下列提示和回覆的清除作業，其他作業則會遭到忽略，並在未清除的情況下繼續執行：

    • Assistants API：Create、Delete、List、Modify 和 Retrieve
    • Chat Completions API：Create、Delete、Get Chat Completion、Get Chat Message、List 和 Update
    • Completions (legacy) API：Create
    • Messages API：Create、Delete、List、Modify 和 Retrieve
    • 回覆 API：Create、Delete 和 Get
    • Threads API：Create、Delete、Modify 和 Retrieve

  • 對於在回應中傳回多個選項的 API 呼叫 (例如 POST https://api.openai.com/v1/chat/completions)，系統只會清除選項清單中的第一個項目。

設定流量擴充功能

  1. 在設定擴充功能之前，請先將推論要求傳送至負載平衡器，並指定負載平衡器公開的 IP 位址，藉此檢查行為：

    curl -v http://${IP}/v1/chat/completions
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'

    要求會產生 HTTP 200 OK 狀態碼，但敏感資料已傳送至 LLM。

  2. 如要讓 Model Armor 封鎖含有私密資料的提示詞，請設定流量擴充功能。

    控制台

    1. 前往 Google Cloud 控制台的「Service Extensions」頁面。

      前往 Service Extensions

    2. 按一下「建立擴充功能」。精靈會開啟，引導您完成一些初始步驟。

    3. 選取「負載平衡」產品。然後按一下「繼續」。系統會顯示支援的應用程式負載平衡器清單。

    4. 選取負載平衡器類型。

    5. 將區域指定為 us-central1。按一下「Continue」(繼續)。

    6. 在「擴充功能類型」中選取「流量擴充功能」，然後按一下「繼續」。

    7. 如要開啟「建立擴充功能」表單，請按一下「繼續」。在「建立擴充功能」表單中，請注意先前的選取項目無法編輯。

    8. 在「Basics」(基本) 部分，執行下列操作：

      1. 為擴充功能指定不重複的名稱。

        名稱開頭必須為小寫英文字母，後方最多可接 62 個小寫字母、數字或連字號，但結尾不得為連字號。

      2. 選用：輸入擴充功能的簡短說明，最多 1,024 個字元。

    9. 選用：在「標籤」部分中，按一下「新增標籤」。接著，在顯示的資料列中執行下列操作：

      • 在「Key」中輸入金鑰名稱。
      • 在「值」中輸入索引鍵的值。

      如要新增更多鍵/值組合，請按一下「新增標籤」。最多可新增 64 個鍵/值組合。

      如要進一步瞭解標籤，請參閱「建立及更新專案標籤」。

    10. 在「Forwarding rules」(轉送規則)，選取要與擴充功能建立關聯的一或多個轉送規則。選擇在部署 Inference Gateway 時產生的轉送規則。如果轉送規則已與其他擴充功能建立關聯，就無法選取，且會顯示為無法使用。

    11. 如要為「擴充功能」新增擴充功能，以便在要求相符時執行，請按照下列步驟操作：

      • 如要比對執行擴充功能鏈的請求，請在「比對條件」Match condition中指定一般運算語言 (CEL) 運算式，例如 request.path == "/v1/chat/completions"。

        如要進一步瞭解 CEL 運算式，請按一下「取得語法說明」，或參閱 CEL 比對器語言參考資料。

      • 新增一或多個擴充功能，以執行相符要求。

        針對每個擴充功能，在「擴充功能」下方執行下列操作，然後按一下「完成」：

      • 在「Programmability type」(可程式化類型) 部分，選取「Google services」(Google 服務)，然後選取 Model Armor 服務端點，例如 modelarmor.us-central1.rep.googleapis.com。

      • 「逾時」：指定介於 10 到 1000 毫秒之間的值，超過這個時間後，串流中的訊息就會逾時。請注意，Model Armor 的延遲時間約為 250 毫秒。

      • 在「事件」部分，選取所有 HTTP 事件類型。

      • 在「Forward headers」(轉送標頭) 部分，按一下「Add header」(新增標頭)，然後新增要轉送至擴充功能的 HTTP 標頭 (來自用戶端或後端)。如果未指定標頭，系統會傳送所有標頭。

      • 選用：如果擴充功能逾時或失敗，但您希望繼續處理要求或回覆，請選取「啟用」，啟用「失敗時開放」。鏈結中的後續擴充功能也會執行。

        根據預設，系統不會選取「Fail open」(失敗時開放) 選項。在本例中，發生錯誤時，要求或回應處理作業會停止。如果回應標頭尚未傳送至下游用戶端，系統會傳回一般 HTTP 500 狀態碼給用戶端。如果已傳送回應標頭，系統會重設用戶端的 HTTP 串流。

        如果安全或完整性是首要考量，建議將「Fail open」預設選項保持為未選取狀態。啟用「Fail open」(特別是非重要作業) 有助於優先考量可用性。

      • 在「中繼資料」部分，點選「新增中繼資料」，指定用於篩選特定模型提示詞和回覆的 Model Armor 範本。

        在「Key」(鍵) 中指定 model_armor_settings。針對「值」，請以 JSON 字串指定範本，例如：

        [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]

        更改下列內容：

        • MODEL_NAME：模型的名稱，已透過 InferenceModel 資源設定，例如 meta-llama/Llama-3.1-8B-Instruct
        • TEMPLATE_PROJECT_ID：Model Armor 範本的專案 ID
        • LOCATION：Model Armor 範本的位置，例如 us-central1。
        • RESPONSE_TEMPLATE：模型要使用的回應範本
        • PROMPT_TEMPLATE：模型要使用的提示範本

        此外，您也可以指定預設範本，在要求與模型不完全相符時使用。如要設定預設範本，請將 MODEL_NAME 指定為 default。

        如要避免篩選提示或回覆流量，請建立並加入空白的篩選範本。

        metadata 的總大小不得超過 1 KiB。 中繼資料中的鍵總數不得超過 20 個。 每個鍵的長度不得超過 64 個半形字元。每個值的長度不得超過 1,024 個字元。所有值都必須是字串。

        要求遭到封鎖時，Model Armor 會傳回標準 403 Forbidden 狀態碼。您可以在 Model Armor 範本的安全政策中定義自訂回應設定 (包括自訂狀態碼和訊息)，藉此覆寫狀態。詳情請參閱「TemplateMetadata」。

      如要指定多個擴充功能或擴充功能鏈，而非單一擴充功能，請按一下表單結尾的「切換至進階模式」按鈕，然後指定所需擴充功能和鏈。擴充功能會按照列出的順序執行。

      為每個擴充功能和擴充功能鏈結指定不重複的名稱。名稱必須符合 RFC-1034 規定，只能使用小寫英文字母、數字和連字號，且長度不得超過 63 個字元。此外，第一個字元必須是英文字母，最後一個字元必須是英文字母或數字。

    12. 按一下「建立擴充功能」。

    gcloud

    1. 在 YAML 檔案中定義附註，並將其與部署 Inference Gateway 時產生的轉送規則建立關聯。使用提供的樣本值。

      cat >traffic_callout_service.yaml <<EOF
    name: traffic-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1-model-armor"
      matchCondition:
        celExpression: 'request.path == "/v1/chat/completions"'
      extensions:
      - name: extension-chain-1-model-armor
        service: modelarmor.us-central1.rep.googleapis.com
        failOpen: true
        supportedEvents:
        - REQUEST_HEADERS
        - REQUEST_BODY
        - REQUEST_TRAILERS
        - RESPONSE_HEADERS
        - RESPONSE_BODY
        - RESPONSE_TRAILERS
        timeout: 1s
        metadata:
          model_armor_settings: '[
            {
              "model": "MODEL_NAME",
              "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
              "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
            }
          ]'
EOF

      更改下列內容：

      • TEMPLATE_PROJECT_ID：Model Armor 範本的專案 ID
      • LB_PROJECT_ID：負載平衡器轉送規則的專案 ID

      • FORWARDING_RULE：要與擴充功能建立關聯的一或多個轉送規則。選擇在部署 Inference Gateway 時產生的轉送規則。

        如果轉送規則已與其他擴充功能建立關聯，就無法選取，且會顯示為無法使用。

      • MODEL_NAME：模型的名稱，已透過 InferenceModel 資源設定，例如 meta-llama/Llama-3.1-8B-Instruct

      • LOCATION：Model Armor 範本的位置，例如 us-central1。

      • RESPONSE_TEMPLATE：模型要使用的回應範本

      • PROMPT_TEMPLATE：模型要使用的提示範本

      在 metadata 欄位中，指定要使用的 Model Armor 設定和範本，以便在篩選特定模型對應的提示詞和回覆時使用。

      此外，您也可以指定預設範本，在要求與模型不完全相符時使用。如要設定預設範本，請將 MODEL_NAME 指定為 default。

      如要避免篩選提示或回覆流量，請建立並加入空白的篩選範本。

      metadata 的總大小不得超過 1 KiB。 中繼資料中的鍵總數不得超過 16 個。 每個鍵的長度不得超過 64 個半形字元。每個值的長度不得超過 1,024 個字元。所有值都必須是字串。

      要求遭到封鎖時，Model Armor 會傳回標準 403 Forbidden 狀態碼。您可以在 Model Armor 範本的安全政策中定義自訂回應設定 (包括自訂狀態碼和訊息)，藉此覆寫狀態。詳情請參閱「TemplateMetadata」。

    2. 匯入流量擴充功能。使用 gcloud service-extensions lb-traffic-extensions import 指令和下列範例值。

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
    --source=traffic_callout_service.yaml \
    --location=us-central1

    kubectl

    1. 如果您使用的 GKE 版本早於 v1.32.2-gke.1182001，請安裝流量擴充功能 CRD：

      kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml

    2. 在 YAML 檔案中定義擴充功能。這項自訂資源會將 Inference Gateway 連結至 Model Armor 服務。使用提供的樣本值。

      cat >traffic_callout_service.yaml <<EOF
apiVersion: networking.gke.io/v1
kind: GCPTrafficExtension
metadata:
  name: traffic-ext
spec:
  targetRefs:
  - group: "gateway.networking.k8s.io"
    kind: Gateway
    name: inference-gateway
  extensionChains:
  - name: "chain1-model-armor"
    matchCondition:
      celExpressions:
      - celMatcher: 'request.path == "/v1/chat/completions"'
      extensions:
      - name: extension-chain-1-model-armor
        googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com
        failOpen: true
        supportedEvents:
        - RequestHeaders
        - RequestBody
        - RequestTrailers
        - ResponseHeaders
        - ResponseBody
        - ResponseTrailers
        timeout: 1s
        metadata:
          model_armor_settings: '[
            {
              "model": "MODEL_NAME",
              "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
              "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
            }
          ]'
EOF

      更改下列內容：

      • MODEL_NAME：模型的名稱，已透過 InferenceModel 資源設定，例如 meta-llama/Llama-3.1-8B-Instruct
      • TEMPLATE_PROJECT_ID：Model Armor 範本的專案 ID
      • LOCATION：Model Armor 範本的位置，例如 us-central1。
      • RESPONSE_TEMPLATE：模型要使用的回應範本
      • PROMPT_TEMPLATE：模型要使用的提示範本

      在 metadata 欄位中，指定要使用的 Model Armor 設定和範本，以便在篩選特定模型對應的提示詞和回覆時使用。

      此外，您也可以指定預設範本，在要求與模型不完全相符時使用。如要設定預設範本，請將 MODEL_NAME 指定為 default。

      如要避免篩選提示或回覆流量，請建立並加入空白的篩選範本。

      metadata 的總大小不得超過 1 KiB。 中繼資料中的鍵總數不得超過 16 個。 每個鍵的長度不得超過 64 個半形字元。每個值的長度不得超過 1,024 個字元。所有值都必須是字串。

      要求遭到封鎖時，Model Armor 會傳回標準 403 Forbidden 狀態碼。您可以在 Model Armor 範本的安全政策中定義自訂回應設定 (包括自訂狀態碼和訊息)，藉此覆寫狀態。詳情請參閱「TemplateMetadata」。

    3. 將 traffic_callout_service.yaml 檔案中定義的設定套用至 GKE 叢集。這個指令會建立 GCPTrafficExtension 資源，將 Inference Gateway 連結至 Model Armor 服務。

      kubectl apply -f traffic_callout_service.yaml

  3. 將必要角色授予 Service Extensions 服務帳戶。使用 gcloud projects add-iam-policy-binding 指令：

    gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

    更改下列內容：

    • TEMPLATE_PROJECT_ID：Model Armor 範本的專案 ID
    • LB_PROJECT_NUMBER：負載平衡器的專案編號

    這些值會列在專案Google Cloud 控制台的「Project info」(專案資訊) 面板中。

  4. 如要確認流量擴充功能是否正常運作，請執行相同的 curl 指令：

    curl -v http://${IP}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'
  ```

設定服務擴充功能後，如果要求含有私密資料，系統會產生 HTTP 403 Forbidden 狀態碼、記錄範本中設定的錯誤訊息，並關閉連線。

如果要求安全無虞，系統會產生 HTTP 200 OK 狀態碼，並將 LLM 回應傳回給使用者。

如要監控擴充功能的行為，請使用 Logs Explorer。 在查詢窗格中，視推論閘道設定而定，依適當的負載平衡器資源類型進行篩選。

應用程式負載平衡器記錄項目包含的資訊有助於偵錯 HTTP 或 HTTPS 流量。

如要更詳細地分析安全評估結果，請啟用 Model Armor 稽核記錄。

後續步驟