通过 Hugging Face TGI 使用 GKE 中的 GPU 应用 Gemma 开放模型

Autopilot Standard

本教程介绍如何使用 Google Kubernetes Engine (GKE) 上的 GPU 和来自 Hugging Face 的文本生成推理 (TGI) 服务框架来部署和应用大语言模型 (LLM)。本教程为理解和探索在托管式 Kubernetes 环境中部署实际 LLM 以进行推理提供了基础。您会将运行 TGI 的预构建容器部署到 GKE。您还将配置 GKE，以便从 Hugging Face 加载 Gemma 2B、9B 和 27B 权重。

本教程适用于机器学习 (ML) 工程师、平台管理员和运维人员，以及希望使用 Kubernetes 容器编排功能在 H100、A100 和 L4 GPU 硬件上部署 LLM 的数据和 AI 专家。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE 用户角色和任务。

如果您需要统一的托管式 AI 平台来经济高效地快速构建和部署机器学习模型，我们建议您试用我们的 Vertex AI 部署解决方案。

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

背景

本部分介绍本指南中使用的关键技术。

Gemma

Gemma 是一组公开提供的轻量级生成式人工智能 (AI) 模型（根据开放许可发布）。这些 AI 模型可以在应用、硬件、移动设备或托管服务中运行。

在本指南中，我们介绍了以下模型：

适用于文本生成的 Gemma，您也可以针对特定任务对这些模型进行调优。
CodeGemma 是功能强大的轻量级模型集合，这些模型可以执行各种编码任务，例如填充中间代码完成、代码生成、自然语言理解、数学推理和指令遵循。

如需了解详情，请参阅 Gemma 文档。

GPU

利用 GPU，您可以加速在节点上运行的特定工作负载（例如机器学习和数据处理）。GKE 提供了一系列机器类型选项以用于节点配置，包括配备 NVIDIA H100、L4 和 A100 GPU 的机器类型。

文本生成推理 (TGI)

TGI 是 Hugging Face 的工具包，用于部署和应用 LLM。TGI 可为热门开源 LLM（包括 Gemma）实现高性能文本生成。TGI 包含以下功能：

具有 Flash Attention 和 PagedAttention 且经过优化的 Transformer（转换器）实现
连续批处理，可提高整体服务吞吐量
张量并行处理，用于在多个 GPU 上加快推理速度

如需了解详情，请参阅 TGI 文档。

目标

使用处于 Autopilot 模式的 GKE 集群准备环境。
将 TGI 部署到您的集群。
通过 curl 和网页聊天界面，使用 TGI 提供 Gemma 2 模型。

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required API.

Enable the API

Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin

Check for the roles

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

In the Google Cloud console, go to the IAM page.
前往 IAM
选择项目。
点击 授予访问权限。
在新的主账号字段中，输入您的用户标识符。这通常是 Google 账号的电子邮件地址。
在选择角色列表中，选择一个角色。
如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
点击 Save（保存）。

如果您还没有 Hugging Face 账号，请创建一个。
确保您的项目具有足够的 L4 GPU 配额。如需了解详情，请参阅 GPU 简介和分配配额。

获取对模型的访问权限

如需获取对 Gemma 模型的访问权限以便部署到 GKE，您必须先签署许可同意协议，然后生成 Huggging Face 访问令牌。

您必须签署同意协议才能使用 Gemma。请按照以下说明操作：

访问 Kaggle.com 上的模型同意页面。
使用您的 Hugging Face 账号验证同意情况。
接受模型条款。

生成一个访问令牌

如需通过 Hugging Face 访问模型，您需要 Hugging Face 令牌。

如果您还没有令牌，请按照以下步骤生成新令牌：

点击您的个人资料 > 设置 > 访问令牌。
选择新建令牌 (New Token)。
指定您选择的名称和一个至少为 Read 的角色。
选择生成令牌。
将生成的令牌复制到剪贴板。

准备环境

在本教程中，您将使用 Cloud Shell 来管理Google Cloud上托管的资源。Cloud Shell 预安装有本教程所需的软件，包括 kubectl 和 gcloud CLI。

如需使用 Cloud Shell 设置您的环境，请按照以下步骤操作：

在 Google Cloud 控制台中，点击 Google Cloud 控制台中的 激活 Cloud Shell 以启动 Cloud Shell 会话。此操作会在 Google Cloud 控制台的底部窗格中启动会话。
设置默认环境变量：
```
gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export REGION=REGION
export CLUSTER_NAME=CLUSTER_NAME
export HF_TOKEN=HF_TOKEN
```
替换以下值：
- PROJECT_ID：您的 Google Cloud项目 ID。
- REGION：支持要使用的加速器类型的区域，例如适用于 L4 GPU 的 us-central1。
- CLUSTER_NAME：您的集群的名称。
- HF_TOKEN：您之前生成的 Hugging Face 令牌。

创建和配置 Google Cloud 资源

请按照以下说明创建所需的资源。

创建 GKE 集群和节点池

您可以在 GKE Autopilot 或 Standard 集群中的 GPU 上应用 Gemma。我们建议您使用 Autopilot 集群获得全托管式 Kubernetes 体验。如需选择最适合您的工作负载的 GKE 操作模式，请参阅选择 GKE 操作模式。

Autopilot

在 Cloud Shell 中，运行以下命令：

gcloud container clusters create-auto CLUSTER_NAME \
    --project=PROJECT_ID \
    --region=REGION \
    --release-channel=rapid

替换以下值：

PROJECT_ID：您的 Google Cloud项目 ID。
REGION：支持要使用的加速器类型的区域，例如适用于 L4 GPU 的 us-central1。
CLUSTER_NAME：您的集群的名称。

GKE 会根据所部署的工作负载的请求，创建具有所需 CPU 和 GPU 节点的 Autopilot 集群。

Standard

在 Cloud Shell 中，运行以下命令以创建 Standard 集群：
```
gcloud container clusters create CLUSTER_NAME \
    --project=PROJECT_ID \
    --region=REGION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --release-channel=rapid \
    --num-nodes=1
```
替换以下值：
- PROJECT_ID：您的 Google Cloud项目 ID。
- REGION：支持要使用的加速器类型的区域，例如适用于 L4 GPU 的 us-central1。
- CLUSTER_NAME：您的集群的名称。
集群创建可能需要几分钟的时间。

如需为集群创建具有适当磁盘大小的节点池，请运行以下命令：

Gemma 2 2B

gcloud container node-pools create gpupool \
    --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \
    --project=PROJECT_ID \
    --location=REGION \
    --node-locations=REGION-a \
    --cluster=CLUSTER_NAME \
    --machine-type=g2-standard-8 \
    --num-nodes=1

GKE 会创建一个节点池，其中每个节点有一个 L4 GPU。

Gemma 2 9B

gcloud container node-pools create gpupool \
    --accelerator type=nvidia-l4,count=2,gpu-driver-version=latest \
    --project=PROJECT_ID \
    --location=REGION \
    --node-locations=REGION-a \
    --cluster=CLUSTER_NAME \
    --machine-type=g2-standard-24 \
    --num-nodes=1

GKE 会创建一个节点池，其中每个节点有两个 L4 GPU。

Gemma 2 27B

gcloud container node-pools create gpupool \
    --accelerator type=nvidia-l4,count=4,gpu-driver-version=latest \
    --project=PROJECT_ID \
    --location=REGION \
    --node-locations=REGION-a \
    --cluster=CLUSTER_NAME \
    --machine-type=g2-standard-48 \
    --num-nodes=1 \
    --disk-size=180

GKE 会创建一个节点池，其中每个节点有四个 L4 GPU。

为 Hugging Face 凭据创建 Kubernetes Secret

在 Cloud Shell 中，执行以下操作：

配置 kubectl 以与您的集群通信：
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=REGION
```
替换以下值：
- REGION：支持要使用的加速器类型的区域，例如适用于 L4 GPU 的 us-central1。
- CLUSTER_NAME：您的集群的名称。

创建包含 Hugging Face 令牌的 Kubernetes Secret：

kubectl create secret generic hf-secret \
    --from-literal=hf_api_token=HF_TOKEN \
    --dry-run=client -o yaml | kubectl apply -f -

将 HF_TOKEN 替换为您之前生成的 Hugging Face 令牌。

部署 TGI

在本部分中，您将部署 TGI 容器以应用您要使用的 Gemma 模型。为了部署模型，本教程将使用 Kubernetes Deployment。Deployment 是一个 Kubernetes API 对象，可让您运行在集群节点中分布的多个 Pod 副本。

Gemma 2 2B-it

请按照以下说明部署 Gemma 2B 指令调优模型。

创建以下 tgi-2-2b-it.yaml 清单：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tgi-gemma-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-2-2b-it
        ai.gke.io/inference-server: text-generation-inference
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/huggingface-text-generation-inference-cu124.2-3.ubuntu2204.py311
        resources:
          requests:
            cpu: "2"
            memory: "10Gi"
            ephemeral-storage: "10Gi"
            nvidia.com/gpu: "1"
          limits:
            cpu: "2"
            memory: "10Gi"
            ephemeral-storage: "10Gi"
            nvidia.com/gpu: "1"
        env:
        - name: AIP_HTTP_PORT
          value: '8000'
        - name: NUM_SHARD
          value: '1'
        - name: MAX_INPUT_LENGTH
          value: '1562'
        - name: MAX_TOTAL_TOKENS
          value: '2048'
        - name: MAX_BATCH_PREFILL_TOKENS
          value: '2048'
        - name: CUDA_MEMORY_FRACTION
          value: '0.93'
        - name: MODEL_ID
          value: google/gemma-2-2b-it
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-l4
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
  - protocol: TCP
    port: 8000
    targetPort: 8000

应用清单：
```
kubectl apply -f tgi-2-2b-it.yaml
```

Gemma 2 9B-it

请按照以下说明部署 Gemma 9B 指令调优模型。

创建以下 tgi-2-9b-it.yaml 清单：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tgi-gemma-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-2-9b-it
        ai.gke.io/inference-server: text-generation-inference
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/huggingface-text-generation-inference-cu124.2-3.ubuntu2204.py311
        resources:
          requests:
            cpu: "4"
            memory: "30Gi"
            ephemeral-storage: "30Gi"
            nvidia.com/gpu: "2"
          limits:
            cpu: "4"
            memory: "30Gi"
            ephemeral-storage: "30Gi"
            nvidia.com/gpu: "2"
        env:
        - name: AIP_HTTP_PORT
          value: '8000'
        - name: NUM_SHARD
          value: '2'
        - name: MAX_INPUT_LENGTH
          value: '1562'
        - name: MAX_TOTAL_TOKENS
          value: '2048'
        - name: MAX_BATCH_PREFILL_TOKENS
          value: '2048'
        - name: CUDA_MEMORY_FRACTION
          value: '0.93'
        - name: MODEL_ID
          value: google/gemma-2-9b-it
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-l4
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
  - protocol: TCP
    port: 8000
    targetPort: 8000

应用清单：
```
kubectl apply -f tgi-2-9b-it.yaml
```

Gemma 2 27B-it

请按照以下说明部署 Gemma 2 27B 指令调优模型。

创建以下 tgi-2-27b-it.yaml 清单：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tgi-gemma-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-2-27b-it
        ai.gke.io/inference-server: text-generation-inference
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/huggingface-text-generation-inference-cu124.2-3.ubuntu2204.py311
        resources:
          requests:
            cpu: "10"
            memory: "80Gi"
            ephemeral-storage: "80Gi"
            nvidia.com/gpu: "4"
          limits:
            cpu: "10"
            memory: "80Gi"
            ephemeral-storage: "80Gi"
            nvidia.com/gpu: "4"
        env:
        - name: AIP_HTTP_PORT
          value: '8000'
        - name: NUM_SHARD
          value: '4'
        - name: MAX_INPUT_LENGTH
          value: '1562'
        - name: MAX_TOTAL_TOKENS
          value: '2048'
        - name: MAX_BATCH_PREFILL_TOKENS
          value: '2048'
        - name: CUDA_MEMORY_FRACTION
          value: '0.93'
        - name: MODEL_ID
          value: google/gemma-2-27b-it
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-l4
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
  - protocol: TCP
    port: 8000
    targetPort: 8000

应用清单：
```
kubectl apply -f tgi-2-27b-it.yaml
```

CodeGemma 7B-it

请按照以下说明部署 CodeGemma 7B 指令调优模型。

创建以下 tgi-codegemma-1.1-7b-it.yaml 清单：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tgi-gemma-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: codegemma-1.1-7b-it
        ai.gke.io/inference-server: text-generation-inference
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/huggingface-text-generation-inference-cu124.2-3.ubuntu2204.py311
        resources:
          requests:
            cpu: "2"
            memory: "25Gi"
            ephemeral-storage: "40Gi"
            nvidia.com/gpu: 2
          limits:
            cpu: "10"
            memory: "25Gi"
            ephemeral-storage: "40Gi"
            nvidia.com/gpu: 2
        args:
        - --model-id=$(MODEL_ID)
        - --num-shard=2
        env:
        - name: MODEL_ID
          value: google/codegemma-1.1-7b-it
        - name: PORT
          value: "8000"
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-l4
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000

应用清单：

kubectl apply -f tgi-codegemma-1.1-7b-it.yaml

应用模型

在本部分中，您将与模型互动。

设置端口转发

运行以下命令以设置到模型的端口转发：

kubectl port-forward service/llm-service 8000:8000

输出类似于以下内容：

Forwarding from 127.0.0.1:8000 -> 8000

使用 curl 与模型互动

本部分介绍如何执行基本的冒烟测试来验证所部署的预训练或指令调优模型。为简单起见，本部分介绍使用 Gemma 2 指令调优模型和 CodeGemma 模型的测试方法。

Gemma 2

在新的终端会话中，使用 curl 与模型聊天：

USER_PROMPT="I'm new to coding. If you could only recommend one programming language to start with, what would it be and why?"

curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "inputs": "<start_of_turn>user\n${USER_PROMPT}<end_of_turn>\n",
    "parameters": {
        "temperature": 0.90,
        "top_p": 0.95,
        "max_new_tokens": 128
    }
}
EOF

以下输出显示了模型响应的示例：

{"generated_text":"**Python**\n\n**Reasons why Python is a great choice for beginners:**\n\n* **Simple syntax:** Python uses clear and concise syntax, making it easy for beginners to pick up.\n* **Easy to learn:** Python's syntax is based on English, making it easier to learn than other languages.\n* **Large and supportive community:** Python has a massive and active community of developers who are constantly willing to help.\n* **Numerous libraries and tools:** Python comes with a vast collection of libraries and tools that make it easy to perform various tasks, such as data manipulation, web development, and machine learning.\n* **"}

CodeGemma

在新的终端会话中，使用 curl 与模型聊天：

USER_PROMPT="Generate a python code example of a adding two numbers from a function called addNumbers"

curl -s -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r .generated_text
{
    "inputs": "<start_of_turn>user\n${USER_PROMPT}<end_of_turn>\n",
    "parameters": {
        "temperature": 0.90,
        "top_p": 0.95,
        "max_new_tokens": 2000
    }
}
EOF

以下输出显示了模型响应的示例：

def addNumbers(num1, num2):
  sum = num1 + num2
  return sum

# Get the input from the user
num1 = float(input("Enter the first number: "))
num2 = float(input("Enter the second number: "))

# Call the addNumbers function
sum = addNumbers(num1, num2)

# Print the result
print("The sum of", num1, "and", num2, "is", sum)

（可选）通过 Gradio 聊天界面与模型互动

在本部分中，您将构建一个网页聊天应用，可让您与指令调优模型互动。为简单起见，本部分仅介绍使用 2B-it 模型的测试方法。

Gradio 是一个 Python 库，它具有一个可为聊天机器人创建界面的 ChatInterface 封装容器。

部署聊天界面

在 Cloud Shell 中，将以下清单保存为 gradio.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gradio
  labels:
    app: gradio
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gradio
  template:
    metadata:
      labels:
        app: gradio
    spec:
      containers:
      - name: gradio
        image: us-docker.pkg.dev/google-samples/containers/gke/gradio-app:v1.0.4
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"
        env:
        - name: CONTEXT_PATH
          value: "/generate"
        - name: HOST
          value: "http://llm-service:8000"
        - name: LLM_ENGINE
          value: "tgi"
        - name: MODEL_ID
          value: "gemma"
        - name: USER_PROMPT
          value: "<start_of_turn>user\nprompt<end_of_turn>\n"
        - name: SYSTEM_PROMPT
          value: "<start_of_turn>model\nprompt<end_of_turn>\n"
        ports:
        - containerPort: 7860
---
apiVersion: v1
kind: Service
metadata:
  name: gradio
spec:
  selector:
    app: gradio
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 7860
  type: ClusterIP

应用清单：
```
kubectl apply -f gradio.yaml
```

等待部署成为可用状态：

kubectl wait --for=condition=Available --timeout=300s deployment/gradio

使用聊天界面

在 Cloud Shell 中，运行以下命令：
```
kubectl port-forward service/gradio 8080:8080
```
这会创建从 Cloud Shell 到 Gradio 服务的端口转发。
点击 Cloud Shell 任务栏右上角的 网页预览按钮。点击在端口 8080 上预览。浏览器中会打开一个新的标签页。
使用 Gradio 聊天界面与 Gemma 互动。添加提示，然后点击提交。

问题排查

如果您收到 Empty reply from server 消息，则容器可能尚未完成模型数据下载。再次检查 Pod 的日志中是否包含 Connected 消息，该消息表明模型已准备好进行应用。
如果您看到 Connection refused，请验证您的端口转发已启用。

观察模型性能

如需观察模型性能，您可以使用 Cloud Monitoring 中的 TGI 信息中心集成。在此信息中心内，您可以查看各种关键性能指标，例如令牌吞吐量、请求延迟时间和错误率。

如需使用 TGI 信息中心，您必须在 GKE 集群中启用 Google Cloud Managed Service for Prometheus，该服务会从 TGI 收集指标。TGI 默认以 Prometheus 格式公开指标；您无需安装其他导出器。

然后，您可以使用 TGI 信息中心查看指标。如需了解如何使用 Google Cloud Managed Service for Prometheus 从模型收集指标，请参阅 Cloud Monitoring 文档中的 TGI 可观测性指南。

清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除已部署的资源

为避免因您在本指南中创建的资源导致您的 Google Cloud 账号产生费用，请运行以下命令：

gcloud container clusters delete CLUSTER_NAME \
    --region=REGION