部署 GKE 推理网关

本页面介绍如何部署 GKE 推理网关。

本页面适用于负责管理 GKE 基础设施的网络专家，以及管理 AI 工作负载的平台管理员。

在阅读本页面之前，请确保您熟悉以下内容：

GKE 推理网关在 Google Kubernetes Engine (GKE) 网关的基础上进行了增强，可优化 GKE 上生成式 AI 应用和工作负载提供的内容。它可高效管理和扩缩 AI 工作负载，实现工作负载特定的性能目标（例如延迟时间），并提高资源利用率、可观测性和 AI 安全性。

准备工作

在开始之前，请确保您已执行以下任务：

  • 启用 Google Kubernetes Engine API。
    • 启用 Google Kubernetes Engine API
  • 如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。 如果您之前安装了 gcloud CLI，请运行 gcloud components update 命令以获取最新版本。较早版本的 gcloud CLI 可能不支持运行本文档中的命令。

  • 根据需要启用 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 账号中，依次前往您的个人资料 > 设置 > 访问令牌，创建一个至少具有读取权限的新令牌，然后将其复制到剪贴板。

GKE Gateway Controller 要求

  • GKE 1.32.3 版或更高版本。
  • Google Cloud CLI 407.0.0 版或更高版本。
  • Gateway API 仅支持在 VPC 原生集群上使用。
  • 必须启用代理专用子网。
  • 集群必须启用 HttpLoadBalancing 插件。
  • 如果您使用的是 Istio，则必须将 Istio 升级到以下版本之一：
    • 1.15.2 或更高版本
    • 1.14.5 或更高版本
    • 1.13.9 或更高版本
  • 如果您使用的是共享 VPC，则需要在宿主项目中将 Compute Network User 角色分配给服务项目的 GKE 服务账号。

限制和局限

有以下限制和局限：

  • 不支持多集群网关。
  • GKE 推理网关仅支持 gke-l7-regional-external-managed 和 gke-l7-rilb GatewayClass 资源。
  • 不支持跨区域内部应用负载均衡器。

配置 GKE 推理网关

如需配置 GKE 推理网关，请参考以下示例。假设一个团队运行 vLLM 和 Llama3 模型，并在尝试使用如下两个不同的 LoRA 微调适配器的效果：“food-review”和“cad-fabricator”。

配置 GKE 推理网关的大概工作流如下：

  1. 准备环境：设置必要的基础设施和组件。
  2. 创建推理池：使用 InferencePool 自定义资源定义模型服务器池。
  3. 指定推理目标：使用 InferenceObjective 自定义资源指定推理目标
  4. 创建网关：使用 Gateway API 公开推理服务。
  5. 创建 HTTPRoute：定义 HTTP 流量路由到推理服务的方式。
  6. 发送推理请求：向已部署的模型发送请求。

准备环境

  1. 安装 Helm。

  2. 创建 GKE 集群：

    • 创建 1.32.3 版或更高版本的 GKE Autopilot 或 Standard 集群。如需查看一键式部署参考设置，请参阅cluster-toolkit gke-a3-highgpu示例。
    • 使用您偏好的计算机器家族和加速器配置节点。
    • 使用 GKE 推理快速入门，获取基于您选择的加速器、模型和性能需求的预配置且经过测试的部署清单。

  3. 在 GKE 集群中安装所需的自定义资源定义 (CRD)：

    • 对于 GKE 1.34.0-gke.1626000 版或更高版本，仅需安装 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

    • 对于 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/manifests.yaml

      如需了解详情，请参阅兼容性矩阵。

  4. 如果您使用的 GKE 版本低于 v1.32.2-gke.1182001，并且想要将 Model Armor 与 GKE 推理网关搭配使用，则必须安装流量和路由扩展 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

创建模型服务器和模型部署

本部分介绍如何部署模型服务器和模型。此示例使用提供 Llama3 模型的 vLLM 模型服务器。相应部署将被标记为 app:vllm-llama3-8b-instruct。此部署还使用了 Hugging Face 中的两个名为 food-review 和 cad-fabricator 的 LoRA 适配器。

您可以根据自己的模型服务器容器和模型、服务端口以及部署名称来调整此示例。您还可以在部署中配置 LoRA 适配器，或部署基础模型。以下步骤介绍如何创建必要的 Kubernetes 资源。

  1. 创建一个 Kubernetes Secret 来存储您的 Hugging Face 令牌。此令牌用于访问基础模型和 LoRA 适配器：

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

    将 HF_TOKEN 替换为您的 Hugging Face 令牌。

  2. 部署模型服务器和模型。以下命令会应用一个清单，该清单定义了一个 Kubernetes Deployment，用于部署包含 Llama3 模型的 vLLM 模型服务器：

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

创建推理池

InferencePool Kubernetes 自定义资源定义了一组采用相同的基础大语言模型 (LLM) 和计算配置的 Pod。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 \
  --set inferenceExtension.monitoring.gke.enabled=true \
  --version v1.0.1 \
  oci://registry.k8s.io/gateway-api-inference-extension/charts/inferencepool

更改以下字段以与您的 Deployment 相符：

  • inferencePool.modelServers.matchLabels.app：用于选择模型服务器 Pod 的标签的键。

对于监控，Google Cloud Managed Service for Prometheus 的指标抓取功能默认处于启用状态。

  • 如需停用此功能，请向命令添加 --set inferenceExtension.monitoring.gke.enabled=false 标志。
  • 如果您在 GKE Autopilot 集群中使用默认监控，还必须添加 --set provider.gke.autopilot=true 标志。

Helm 安装程序会自动安装必要的超时政策、端点选择器以及所需的 Pod，以便实现可观测性。

这会创建一个 InferencePool 对象：其中 vllm-llama3-8b-instruct 引用 Pod 内的模型端点服务。它还会为创建的 InferencePool 创建一个名为 app:vllm-llama3-8b-instruct-epp 的端点选择器 Deployment。

指定推理目标

通过 InferenceObjective 自定义资源，您可以指定请求的优先级。

InferenceObjective 资源的 metadata.name 字段指定推理目标名称，Priority 字段指定其服务重要性，poolRef 字段指定模型所部署的 InferencePool。

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 InferencePool 上配置 food-review 推理目标，优先级为 10。第二个对象将 llama3-base-model 推理目标配置为以更高的优先级（即 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 inference-objectives.yaml

创建网关

网关资源是外部流量进入 Kubernetes 集群的入口点。它定义用于接受传入连接的监听器。

GKE 推理网关可与以下网关类搭配使用：

  • gke-l7-rilb：对于区域级内部应用负载均衡器。
  • gke-l7-regional-external-managed：对于区域级外部应用负载均衡器。

如需了解详情，请参阅网关类文档。

如需创建网关，请执行以下步骤：

  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 保护网关，请参阅 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 推理网关后，您便可以向已部署的模型发送推理请求。这样一来，您就可以根据输入提示和指定参数生成文本。

如需发送推理请求，请执行以下步骤：

  1. 设置以下环境变量： 

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

    替换以下内容：

    • GATEWAY_NAME：网关资源的名称。
    • PORT_NUMBER：您在网关中配置的端口号。

  2. 如需获取网关端点，请运行以下命令：

    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：回答中可生成的 token 数量上限。
    • TEMPERATURE：控制输出的随机性。使用值 0 可获得确定性输出，使用更高的值则可获得更具创造性的输出。

以下示例展示了如何向 GKE 推理网关发送示例请求：

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）。

兼容性列表

下表概述了 Gateway API 推理扩展自定义资源定义 (CRD) 的兼容性和支持矩阵。其中详细介绍了 GKE 支持的 CRD 版本（与开源 (OSS) Gateway API 推理扩展项目相比），包括具体的版本要求和安装说明。

CRD 名称 CRD API 版本 GKE Managed 支持 OSS（Gateway API 推理扩展程序）支持
V1 InferencePool inference.networking.k8s.io/v1 在 GKE 1.32.3 或更高版本中受支持，并且在 GKE 1.34.0-gke.1626000 或更高版本中默认安装了 CRD 从 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 推断扩展程序中的 CRD。 从 Gateway API 推理扩展程序 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 推理扩展程序 v0.2.0 开始支持。

后续步骤