部署 GKE 推論閘道

本頁說明如何部署 GKE Inference Gateway。

本頁面適用於負責管理 GKE 基礎架構的網路專家，以及管理 AI 工作負載的平台管理員。

閱讀本頁面之前，請先熟悉下列概念：

GKE Inference Gateway 可強化 Google Kubernetes Engine (GKE) Gateway，在 GKE 上提供最佳的生成式 AI 應用程式和工作負載服務。可有效管理及擴充 AI 工作負載、達成工作負載專屬的效能目標 (例如延遲)，並提升資源用量、可觀測性和 AI 安全性。

事前準備

開始之前，請確認您已完成下列工作：

  • 啟用 Google Kubernetes Engine API。
    • 啟用 Google Kubernetes Engine API
  • 如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update，取得最新版本。

  • 視需要啟用 Compute Engine API、Network Services API 和 Model Armor API。

    前往「啟用 API 存取權」，然後按照操作說明進行。

  • 請確認您在專案中擁有下列角色：roles/container.admin、roles/iam.serviceAccountAdmin。

  • 確認專案有足夠的 H100 GPU 配額。詳情請參閱「規劃 GPU 配額」和「分配配額」。

  • 如果沒有 Hugging Face 帳戶，請先建立一個。您需要這個帳戶才能存取本教學課程的模型資源。

  • 要求存取 Llama 3.1 模型，並產生存取權杖。如要存取這個模型，必須先在 Hugging Face 提出要求並獲得核准，否則部署作業會失敗。

    • 簽署授權同意聲明協議：您必須簽署同意聲明協議，才能使用 Llama 3.1 模型。前往 Hugging Face 上的模型頁面，驗證帳戶並接受條款。
    • 產生存取權杖：如要存取模型，您需要 Hugging Face 權杖。在 Hugging Face 帳戶中，依序前往「Your Profile」>「Settings」>「Access Tokens」，建立至少具備讀取權限的新權杖，然後複製到剪貼簿。

GKE Gateway 控制器需求

  • GKE 1.32.3 以上版本。
  • Google Cloud CLI 407.0.0 以上版本。
  • 閘道 API 僅支援虛擬私有雲原生叢集。
  • 您必須啟用僅限 Proxy 的子網路。
  • 叢集必須啟用 HttpLoadBalancing 外掛程式。
  • 如果您使用 Istio，請務必將 Istio 升級至下列其中一個版本：
    • 1.15.2 以上版本
    • 1.14.5 以上版本
    • 1.13.9 以上版本
  • 如果您使用共用虛擬私有雲，則必須在主機專案中，將 Compute Network User 角色指派給服務專案的 GKE 服務帳戶。

規定與限制

請注意下列限制：

  • 不支援多叢集閘道。
  • GKE Inference Gateway 僅支援 gke-l7-regional-external-managed 和 gke-l7-rilb GatewayClass 資源。
  • 不支援跨區域內部應用程式負載平衡器。

相容性矩陣

下表列出 Gateway API 推論擴充功能自訂資源定義 (CRD) 的相容性和支援矩陣。其中詳細說明 GKE 支援的 CRD 版本，以及開放原始碼 (OSS) Gateway API 推論擴充功能專案，包括特定版本需求和安裝注意事項。

CRD 名稱 CRD API 版本 GKE Managed Support OSS (Gateway API 推論擴充功能) 支援
V1 InferencePool inference.networking.k8s.io/v1 支援 GKE 1.32.3 以上版本，且 CRD 預設會安裝在 GKE 1.34.0-gke.1626000 以上版本 從 Gateway API 推論擴充功能 v1.0.0 開始支援
Alpha InferencePool (建議使用者從 v1 InferencePool 開始，因為 Alpha InferencePool 版本已淘汰) inference.networking.x-k8s.io/v1alpha2 支援 GKE 1.32.3 以上版本。不過，GKE 預設不會安裝 CRD。使用者必須從 Gateway API Inference Extension 手動安裝 CRD。 從 Gateway API Inference Extension v0.2.0 開始支援
Alpha InferenceObjective inference.networking.x-k8s.io/v1alpha2 GKE 不會管理 InferenceObjective 從 Gateway API 推論擴充功能 v1.0.0 開始支援
Alpha 版 InferenceModel (建議使用者從 InferenceObjective 開始，因為 InferenceModel 已遭淘汰) inference.networking.x-k8s.io/v1alpha2 GKE 不會管理 InferenceModel 從 Gateway API Inference Extension v0.2.0 開始支援。

設定 GKE Inference Gateway

如要設定 GKE Inference Gateway，請參考這個範例。團隊會執行 vLLM 和 Llama3 模型，並積極實驗兩種不同的 LoRA 微調轉接程式：「food-review」和「cad-fabricator」。

設定 GKE Inference Gateway 的大致工作流程如下：

  1. 準備環境：設定必要的基礎架構和元件。
  2. 建立推論集區：使用 InferencePool 自訂資源定義模型伺服器集區。
  3. 指定推論目標：使用 InferenceObjective 自訂資源指定推論目標
  4. 建立閘道：使用 Gateway API 公開推論服務。
  5. 建立 HTTPRoute：定義 HTTP 流量如何路由至推論服務。
  6. 傳送推論要求：向已部署的模型提出要求。

準備環境

  1. 安裝 Helm。

  2. 建立 GKE 叢集：

    • 建立 GKE Autopilot 或 Standard 叢集，版本為 1.32.3 以上。如需操作說明，請參閱建立 GKE 叢集。
    • 使用偏好的運算系列和加速器設定節點。
    • 根據您選取的加速器、模型和效能需求，使用 GKE Inference Quickstart 取得預先設定及測試的部署資訊清單。

  3. 在 GKE 叢集中安裝必要的自訂資源定義 (CRD)：

    • 如果是 1.34.0-gke.1626000 之前的 GKE 版本，請執行下列指令，同時安裝 v1 InferencePool 和 Alpha 版 InferenceObjective CRD：
    kubectl apply -f  https://github.com/kubernetes-sigs/gateway-api-inference-extension/releases/download/v1.0.0/experimental-manifests.yaml
    • 如果是 1.34.0-gke.1626000 以上版本的 GKE，請只安裝 Alpha 版 InferenceObjective CRD，方法是執行下列指令：
    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api-inference-extension/raw/v1.0.0/config/crd/bases/inference.networking.x-k8s.io_inferenceobjectives.yaml

  4. 如果您使用的 GKE 版本早於 v1.32.2-gke.1182001，且想搭配 GKE Inference Gateway 使用 Model Armor，請務必安裝流量和路由擴充功能 CRD：

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

  5. 如要設定授權來擷取指標，請建立 inference-gateway-sa-metrics-reader-secret 密鑰：

    kubectl apply -f - <<EOF
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: inference-gateway-metrics-reader
rules:
- nonResourceURLs:
  - /metrics
  verbs:
  - get
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: inference-gateway-sa-metrics-reader
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: inference-gateway-sa-metrics-reader-role-binding
  namespace: default
subjects:
- kind: ServiceAccount
  name: inference-gateway-sa-metrics-reader
  namespace: default
roleRef:
  kind: ClusterRole
  name: inference-gateway-metrics-reader
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: v1
kind: Secret
metadata:
  name: inference-gateway-sa-metrics-reader-secret
  namespace: default
  annotations:
    kubernetes.io/service-account.name: inference-gateway-sa-metrics-reader
type: kubernetes.io/service-account-token
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: inference-gateway-sa-metrics-reader-secret-read
rules:
- resources:
  - secrets
  apiGroups: [""]
  verbs: ["get", "list", "watch"]
  resourceNames: ["inference-gateway-sa-metrics-reader-secret"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: gmp-system:collector:inference-gateway-sa-metrics-reader-secret-read
  namespace: default
roleRef:
  name: inference-gateway-sa-metrics-reader-secret-read
  kind: ClusterRole
  apiGroup: rbac.authorization.k8s.io
subjects:
- name: collector
  namespace: gmp-system
  kind: ServiceAccount
EOF

建立模型伺服器和模型部署作業

本節說明如何部署模型伺服器和模型。這個範例使用 vLLM 模型伺服器和 Llama3 模型。部署作業會標示為 app:vllm-llama3-8b-instruct。這項部署作業也會使用來自 Hugging Face 的兩個 LoRA 適應器，分別命名為 food-review 和 cad-fabricator。

您可以根據自己的模型伺服器容器和模型、服務通訊埠和部署名稱，調整這個範例。您也可以在部署中設定 LoRA 配接器，或部署基礎模型。下列步驟說明如何建立必要的 Kubernetes 資源。

  1. 建立 Kubernetes Secret 來儲存 Hugging Face 權杖。這個權杖用於存取基礎模型和 LoRA 適應器：

    kubectl create secret generic hf-token --from-literal=token=HF_TOKEN

    將 HF_TOKEN 替換為您的 Hugging Face 權杖。

  2. 部署模型伺服器和模型。下列指令會套用資訊清單，為具有 Llama3 模型的 vLLM 模型伺服器定義 Kubernetes Deployment：

    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api-inference-extension/release-1.0/config/manifests/vllm/gpu-deployment.yaml

建立推論集區

InferencePool Kubernetes 自訂資源會定義一組 Pod，這些 Pod 具有共同的基礎大型語言模型 (LLM) 和運算設定。selector 欄位會指定哪些 Pod 屬於這個集區。這個選取器中的標籤必須與套用至模型伺服器 Pod 的標籤完全一致。targetPort 欄位會定義模型伺服器在 Pod 中使用的通訊埠。extensionRef 欄位會參照擴充功能服務，為推論集區提供額外功能。InferencePool 可讓 GKE 推論閘道將流量轉送至模型伺服器 Pod。

建立 InferencePool 前，請確認 InferencePool 選取的 Pod 已在執行中。

如要使用 Helm 建立 InferencePool，請執行下列步驟：

helm install vllm-llama3-8b-instruct \
  --set inferencePool.modelServers.matchLabels.app=vllm-llama3-8b-instruct \
  --set provider.name=gke \
  --version v1.0.0 \
  oci://registry.k8s.io/gateway-api-inference-extension/charts/inferencepool

變更下列欄位，以符合您的部署作業：

  • inferencePool.modelServers.matchLabels.app：用於選取模型伺服器 Pod 的標籤鍵。

Helm 安裝作業會自動安裝必要的逾時政策、端點選擇器，以及可觀測性所需的 Pod。

這會建立 InferencePool 物件：vllm-llama3-8b-instruct 參照 Pod 內的模型端點服務。此外，系統也會為這個建立的 InferencePool 建立名為 app:vllm-llama3-8b-instruct-epp 的 Endpoint Picker 部署作業。

指定推論目標

InferenceObjective 自訂資源可讓您指定要求的優先順序。

InferenceObjective 資源的 metadata.name 欄位會指定推論目標的名稱，Priority 欄位會指定其服務重要性，而 poolRef 欄位則會指定模型服務的 InferencePool。

```yaml
apiVersion: inference.networking.k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: NAME
spec:
  priority: VALUE
  poolRef:
    name: INFERENCE_POOL_NAME
    group: "inference.networking.k8s.io"
```

更改下列內容：

  • NAME：推論目標的名稱。例如：food-review。
  • VALUE：推論目標的優先順序。這是整數，值越大代表要求越重要。例如 10。
  • INFERENCE_POOL_NAME：您在上一個步驟中建立的InferencePool名稱。例如：vllm-llama3-8b-instruct。

如要建立 InferenceObjective，請執行下列步驟：

  1. 將下列資訊清單儲存為 inference-objectives.yaml。這個資訊清單會建立兩個 InferenceObjective 資源。第一個會設定 vllm-llama3-8b-instruct 上的 food-review 推論目標，優先順序為 10。InferencePool第二個設定會將 llama3-base-model Inference Objective 的優先順序設為 20，因此會優先放送。

    apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: food-review
spec:
  priority: 10
  poolRef:
    name: vllm-llama3-8b-instruct
    group: "inference.networking.k8s.io"
---
apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: llama3-base-model
spec:
  priority: 20 # Higher priority
  poolRef:
    name: vllm-llama3-8b-instruct

  2. 將範例資訊清單套用至叢集：

    kubectl apply -f inferenceobjective.yaml

建立閘道

Gateway 資源是外部流量進入 Kubernetes 叢集的進入點。定義接受連入連線的接聽程式。

GKE Inference Gateway 適用於下列 Gateway 類別：

  • gke-l7-rilb：適用於區域性內部應用程式負載平衡器。
  • gke-l7-regional-external-managed：適用於區域性外部應用程式負載平衡器。

詳情請參閱 GatewayClass 說明文件。

如要建立閘道，請執行下列步驟：

  1. 將下列範例資訊清單儲存為 gateway.yaml：

    apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: GATEWAY_NAME
spec:
  gatewayClassName: GATEWAY_CLASS
  listeners:
    - protocol: HTTP
      port: 80
      name: http

    更改下列內容：

    • GATEWAY_NAME：閘道資源的專屬名稱。例如：inference-gateway。
    • GATEWAY_CLASS：要使用的閘道類別。 例如：gke-l7-regional-external-managed。

  2. 將資訊清單套用至叢集：

    kubectl apply -f gateway.yaml

注意：如要進一步瞭解如何設定 TLS，透過 HTTPS 保護 Gateway 安全，請參閱 GKE 說明文件中的 TLS 設定。

建立 HTTPRoute

HTTPRoute 資源定義 GKE 閘道如何將傳入的 HTTP 要求轉送至後端服務，例如 InferencePool。HTTPRoute 資源會指定相符規則 (例如標頭或路徑)，以及流量應轉送至的後端。

  1. 如要建立 HTTPRoute，請將下列範例資訊清單儲存為 httproute.yaml：

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: HTTPROUTE_NAME
spec:
  parentRefs:
  - name: GATEWAY_NAME
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: PATH_PREFIX
    backendRefs:
    - name: INFERENCE_POOL_NAME
      group: "inference.networking.k8s.io"
      kind: InferencePool

    更改下列內容：

    • HTTPROUTE_NAME：HTTPRoute 資源的專屬名稱。例如：my-route。
    • GATEWAY_NAME：您建立的 Gateway 資源名稱。例如：inference-gateway。
    • PATH_PREFIX：用於比對傳入要求的路徑前置字元。例如，/ 可比對所有項目。
    • INFERENCE_POOL_NAME：要將流量導向的InferencePool資源名稱。例如：vllm-llama3-8b-instruct。

  2. 將資訊清單套用至叢集：

    kubectl apply -f httproute.yaml

傳送推論要求

設定 GKE Inference Gateway 後，您可以將推論要求傳送至已部署的模型。您可以根據輸入的提示和指定的參數生成文字。

如要傳送推論要求，請執行下列步驟：

  1. 請設定下列環境變數：

    export GATEWAY_NAME=GATEWAY_NAME
export PORT_NUMBER=PORT_NUMBER # Use 80 for HTTP

    更改下列內容：

    • GATEWAY_NAME：Gateway 資源的名稱。
    • PORT_NUMBER：您在閘道中設定的通訊埠號碼。

  2. 如要取得 Gateway 端點，請執行下列指令：

    echo "Waiting for the Gateway IP address..."
IP=""
while [ -z "$IP" ]; do
  IP=$(kubectl get gateway/${GATEWAY_NAME} -o jsonpath='{.status.addresses[0].value}' 2>/dev/null)
  if [ -z "$IP" ]; then
    echo "Gateway IP not found, waiting 5 seconds..."
    sleep 5
  fi
done

echo "Gateway IP address is: $IP"
PORT=${PORT_NUMBER}

  3. 如要使用 curl 將要求傳送至 /v1/completions 端點，請執行下列指令：

    curl -i -X POST ${IP}:${PORT}/v1/completions \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $(gcloud auth application-default print-access-token)' \
-d '{
    "model": "MODEL_NAME",
    "prompt": "PROMPT_TEXT",
    "max_tokens": MAX_TOKENS,
    "temperature": "TEMPERATURE"
}'

    更改下列內容：

    • MODEL_NAME：要使用的模型或 LoRA 轉接器名稱。
    • PROMPT_TEXT：模型的輸入提示。
    • MAX_TOKENS：回覆中生成的權杖數量上限。
    • TEMPERATURE：控制輸出內容的隨機性。如要取得確定性輸出內容，請使用值 0；如要取得更多創意輸出內容，請使用較大的數字。

以下範例說明如何將範例要求傳送至 GKE Inference Gateway：

curl -i -X POST ${IP}:${PORT}/v1/completions -H 'Content-Type: application/json' -H 'Authorization: Bearer $(gcloud auth print-access-token)' -d '{
    "model": "food-review-1",
    "prompt": "What is the best pizza in the world?",
    "max_tokens": 2048,
    "temperature": "0"
}'

請注意下列行為：

  • 要求主體：要求主體可以包含其他參數，例如 stop 和 top_p。如需完整的選項清單，請參閱 OpenAI API 規格。
  • 錯誤處理：在用戶端程式碼中實作適當的錯誤處理機制，以處理回應中可能發生的錯誤。舉例來說，請檢查 curl 回應中的 HTTP 狀態碼。非 200 狀態碼通常表示發生錯誤。
  • 驗證和授權：針對正式版部署作業，請使用驗證和授權機制保護 API 端點。在要求中加入適當的標頭 (例如 Authorization)。

後續步驟