通过 vLLM 使用 GKE 上的 GPU 部署 Llama 模型

本教程介绍如何使用 Google Kubernetes Engine (GKE) 上的 GPU 和 vLLM 部署框架来部署和应用 Llama 模型 4 大语言模型 (LLM)。本教程为理解和探索在托管式 Kubernetes 环境中部署实际 LLM 以进行推理提供了基础。您会将运行 vLLM 的预构建容器部署到 GKE。您还将配置 GKE,以从 Hugging Face 加载 Llama。

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

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

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

背景

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

Llama

Llama 是由 Meta 提供的大语言模型,专为各种自然语言处理任务(包括文本生成、翻译和问答)而设计。GKE 提供所需的基础设施,以支持这种规模的模型的分布式训练和服务需求。如需了解详情,请参阅 Llama 文档

GPU

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

vLLM

vLLM 是一个经过高度优化的开源 LLM 服务框架,可提高 GPU 上的服务吞吐量,具有如下功能:

  • 具有 PagedAttention 且经过优化的 Transformer(转换器)实现
  • 连续批处理,可提高整体服务吞吐量
  • 多个 GPU 上的张量并行处理和分布式服务

如需了解详情,请参阅 vLLM 文档

获取对模型的访问权限

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

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

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

准备环境

在本教程中,您将使用 Cloud Shell 来管理Google Cloud上托管的资源。Cloud Shell 中预安装了本教程所需的软件,包括 kubectlgcloud CLI

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

  1. 在 Google Cloud 控制台中,点击 Google Cloud 控制台中的 Cloud Shell 激活图标 激活 Cloud Shell 以启动 Cloud Shell 会话。此操作会在 Google Cloud 控制台的底部窗格中启动会话。

  2. 设置默认环境变量:

    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 上部署 Llama 4 模型。我们建议您使用 Autopilot 集群获得全托管式 Kubernetes 体验。如需选择最适合您的工作负载的 GKE 操作模式,请参阅选择 GKE 操作模式

Autopilot

在 Cloud Shell 中,运行以下命令:

gcloud container clusters create-auto CLUSTER_NAME \
    --project=PROJECT_ID \
    --location=CONTROL_PLANE_LOCATION \
    --release-channel=rapid

替换以下值:

  • PROJECT_ID:您的 Google Cloud项目 ID
  • CONTROL_PLANE_LOCATION:集群控制平面的 Compute Engine 区域。提供支持要使用的加速器类型的区域,例如适用于 L4 GPU 的 us-central1
  • CLUSTER_NAME:您的集群的名称。

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

Standard

  1. 在 Cloud Shell 中,运行以下命令以创建 Standard 集群:

    gcloud container clusters create CLUSTER_NAME \
        --project=PROJECT_ID \
        --location=CONTROL_PLANE_LOCATION \
        --workload-pool=PROJECT_ID.svc.id.goog \
        --release-channel=rapid \
        --num-nodes=1
    

    替换以下值:

    • PROJECT_ID:您的 Google Cloud项目 ID
    • CONTROL_PLANE_LOCATION:集群控制平面的 Compute Engine 区域。提供支持要使用的加速器类型的区域,例如适用于 H100 GPU 的 us-central1
    • CLUSTER_NAME:您的集群的名称。

    集群创建可能需要几分钟的时间。

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

    gcloud container node-pools create gpupool \
        --accelerator type=nvidia-h100-80gb,count=1,gpu-driver-version=latest \
        --project=PROJECT_ID \
        --location=REGION \
        --node-locations=REGION-a \
        --cluster=CLUSTER_NAME \
        --machine-type=a3-highgpu-8g \
        --disk-type=pd-ssd \
        --num-nodes=1 \
        --disk-size=256
    

    GKE 会创建单个节点池,其中包含 8 个 H100 80GB GPU。

为 Hugging Face 凭据创建 Kubernetes Secret

在 Cloud Shell 中,执行以下操作:

  1. 配置 kubectl,使其能够与您的集群通信:

    gcloud container clusters get-credentials CLUSTER_NAME \
        --location=REGION
    

    替换以下值:

    • REGION:支持要使用的加速器类型的区域,例如适用于 L4 GPU 的 us-central1
    • CLUSTER_NAME:您的集群的名称。
  2. 创建包含 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 令牌。

部署 vLLM

在本部分中,您将部署 vLLM 容器以应用您要使用的 Llama 4 模型:

  • Llama 4 Maverick 17B-128E
  • Llama 4 Scout 17B-16E

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

Llama 4 Maverick 17B-128e

如需部署 Llama 4 Maverick 17B-128E 模型,请按照以下说明操作:

  1. 创建以下 vllm-llama4-maverick-17b-128e.yaml 清单:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: llama-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: llama-server
      template:
        metadata:
          labels:
            app: llama-server
            ai.gke.io/model: Llama-4-Maverick-17B-128E
            ai.gke.io/inference-server: vllm
        spec:
          containers:
          - name: inference-server
            image: docker.io/vllm/vllm-openai:v0.10.0
            resources:
              requests:
                cpu: 157
                memory: 2067Gi
                ephemeral-storage: 850Gi
                nvidia.com/gpu : 8
              limits:
                cpu: 157
                memory: 2067Gi
                ephemeral-storage: 850Gi
                nvidia.com/gpu : 8
            command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
            args:
            - --host=0.0.0.0
            - --port=7080
            - --swap-space=16
            - --max-model-len=131072
            - --gpu-memory-utilization=0.95
            - --disable-log-stats
            - --dtype=auto
            - --kv-cache-dtype=auto
            - --max-num-seqs=64
            - --model=meta-llama/Llama-4-Maverick-17B-128E
            - --tensor-parallel-size=8
            env:
            - name: LD_LIBRARY_PATH
              value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
            - name: MODEL_ID
              value: 'meta-llama/Llama-4-Maverick-17B-128E'
            - 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-h200-141gb
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: llama-service
    spec:
      selector:
        app: llama-server
      type: ClusterIP
      ports:
      - protocol: TCP
        port: 8000
        targetPort: 7080
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: hf-secret
    type: Opaque
    stringData:
      hf_api_token: {{HF_TOKEN}}
  2. 应用清单:

    kubectl apply -f vllm-llama4-maverick-17b-128e.yaml
    

    在我们的示例中,我们使用 --max-model-len=131072 vLLM 选项将上下文窗口限制为 128 K。

Llama 4 Maverick 17B-128e-it

如需部署 Llama 4 Maverick 17B-128e 指令调优模型,请按照以下说明操作:

  1. 创建以下 vllm-llama4-maverick-17b-128e-instruct.yaml 清单:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: llama-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: llama-server
      template:
        metadata:
          labels:
            app: llama-server
            ai.gke.io/model: Llama-4-Maverick-17B-128E-Instruct
            ai.gke.io/inference-server: vllm
        spec:
          containers:
          - name: inference-server
            image: docker.io/vllm/vllm-openai:v0.10.0
            resources:
              requests:
                cpu: 157
                memory: 2067Gi
                ephemeral-storage: 850Gi
                nvidia.com/gpu : 8
              limits:
                cpu: 157
                memory: 2067Gi
                ephemeral-storage: 850Gi
                nvidia.com/gpu : 8
            command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
            args:
            - --host=0.0.0.0
            - --port=7080
            - --swap-space=16
            - --max-model-len=131072
            - --gpu-memory-utilization=0.95
            - --disable-log-stats
            - --dtype=auto
            - --kv-cache-dtype=auto
            - --max-num-seqs=64
            - --model=meta-llama/Llama-4-Maverick-17B-128E-Instruct
            - --tensor-parallel-size=8
            env:
            - name: LD_LIBRARY_PATH
              value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
            - name: MODEL_ID
              value: 'meta-llama/Llama-4-Maverick-17B-128E-Instruct'
            - 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-h200-141gb
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: llama-service
    spec:
      selector:
        app: llama-server
      type: ClusterIP
      ports:
      - protocol: TCP
        port: 8000
        targetPort: 7080
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: hf-secret
    type: Opaque
    stringData:
      hf_api_token: {{HF_TOKEN}}
  2. 应用清单:

    kubectl apply -f vllm-llama4-maverick-17b-128e-instruct.yaml
    

    在我们的示例中,我们使用 --max-model-len=131072 vLLM 选项将上下文窗口限制为 128 K。

Llama 4 Maverick 17B-128e-it-fp8

如需部署 Llama 4 Maverick 17B-128e-Instruct-FP8 模型,请按照以下说明操作:

  1. 创建以下 vllm-llama4-maverick-17b-128e-instruct-fp8.yaml 清单:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: llama-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: llama-server
      template:
        metadata:
          labels:
            app: llama-server
            ai.gke.io/model: Llama-4-Maverick-17B-128E-Instruct-FP8
            ai.gke.io/inference-server: vllm
        spec:
          containers:
          - name: inference-server
            image: docker.io/vllm/vllm-openai:v0.10.0
            resources:
              requests:
                cpu: 146
                memory: 1311Gi
                ephemeral-storage: 600Gi
                nvidia.com/gpu : 8
              limits:
                cpu: 146
                memory: 1311Gi
                ephemeral-storage: 600Gi
                nvidia.com/gpu : 8
            command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
            args:
            - --host=0.0.0.0
            - --port=7080
            - --swap-space=16
            - --max-model-len=524288
            - --gpu-memory-utilization=0.90
            - --disable-log-stats
            - --model=meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8
            - --tensor-parallel-size=8
            env:
            - name: LD_LIBRARY_PATH
              value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
            - name: MODEL_ID
              value: 'meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8'
            - 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-h100-80gb
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: llama-service
    spec:
      selector:
        app: llama-server
      type: ClusterIP
      ports:
      - protocol: TCP
        port: 8000
        targetPort: 7080
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: hf-secret
    type: Opaque
    stringData:
      hf_api_token: {{HF_TOKEN}}
  2. 应用清单:

    kubectl apply -f vllm-llama4-maverick-17b-128e-instruct-fp8.yaml
    

    在我们的示例中,我们使用 --max-model-len=524288 vLLM 选项将上下文窗口限制为 512 K。

Llama 4 Scout 17B-16e

如需部署 Llama 4 Scout 17B-16E 模型,请按照以下说明操作:

  1. 创建以下 vllm-llama4-scout-17b-16e.yaml 清单:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: llama-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: llama-server
      template:
        metadata:
          labels:
            app: llama-server
            ai.gke.io/model: Llama-4-Scout-17B-16E
            ai.gke.io/inference-server: vllm
        spec:
          containers:
          - name: inference-server
            image: docker.io/vllm/vllm-openai:v0.10.0
            resources:
              requests:
                cpu: 146
                memory: 1311Gi
                ephemeral-storage: 600Gi
                nvidia.com/gpu : 8
              limits:
                cpu: 146
                memory: 1311Gi
                ephemeral-storage: 600Gi
                nvidia.com/gpu : 8
            command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
            args:
            - --host=0.0.0.0
            - --port=7080
            - --swap-space=16
            - --max-model-len=262144
            - --limit_mm_per_prompt
            - '{"image": 5}'
            - --disable-log-stats
            - --model=meta-llama/Llama-4-Scout-17B-16E
            - --tensor-parallel-size=8
            env:
            - name: LD_LIBRARY_PATH
              value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64        
            - name: MODEL_ID
              value: 'meta-llama/Llama-4-Scout-17B-16E'
            - 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-h100-80gb
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: llama-service
    spec:
      selector:
        app: llama-server
      type: ClusterIP
      ports:
      - protocol: TCP
        port: 8000
        targetPort: 7080
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: hf-secret
    type: Opaque
    stringData:
      hf_api_token: {{HF_TOKEN}}
  2. 应用清单:

    kubectl apply -f vllm-llama4-scout-17b-16e.yaml
    

    在我们的示例中,我们使用 --max-model-len=262144 vLLM 选项将上下文窗口限制为 256 K。

Llama 4 Scout 17B-16e-it

如需部署 Llama 4 Scout 17B-16e Instruct 指令调优模型,请按照以下说明操作:

  1. 创建以下 vllm-llama4-scout-17b-16e-instruct.yaml 清单:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: llama-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: llama-server
      template:
        metadata:
          labels:
            app: llama-server
            ai.gke.io/model: Llama-4-Scout-17B-16E-Instruct
            ai.gke.io/inference-server: vllm
        spec:
          containers:
          - name: inference-server
            image: docker.io/vllm/vllm-openai:v0.10.0
            resources:
              requests:
                cpu: 146
                memory: 1311Gi
                ephemeral-storage: 600Gi
                nvidia.com/gpu : 8
              limits:
                cpu: 146
                memory: 1311Gi
                ephemeral-storage: 600Gi
                nvidia.com/gpu : 8
            command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
            args:
            - --host=0.0.0.0
            - --port=7080
            - --swap-space=16
            - --max-model-len=1310720
            - --limit_mm_per_prompt
            - '{"image": 5}'
            - --disable-log-stats
            - --model=meta-llama/Llama-4-Scout-17B-16E-Instruct
            - --tensor-parallel-size=8
            env:
            - name: LD_LIBRARY_PATH
              value: ${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64
            - name: MODEL_ID
              value: 'meta-llama/Llama-4-Scout-17B-16E-Instruct'
            - 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-h100-80gb
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: llama-service
    spec:
      selector:
        app: llama-server
      type: ClusterIP
      ports:
      - protocol: TCP
        port: 8000
        targetPort: 7080
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: hf-secret
    type: Opaque
    stringData:
      hf_api_token: {{HF_TOKEN}}
  2. 应用清单:

    kubectl apply -f vllm-llama4-scout-17b-16e-instruct.yaml
    

    在我们的示例中,我们使用 --max-model-len=1310720 vLLM 选项将上下文窗口限制为 1280 K。

等待部署成为可用状态:

kubectl wait --for=condition=Available --timeout=1800s deployment/llama-deployment

查看正在运行的部署的日志:

kubectl logs -f -l app=llama-server

部署资源会下载模型数据。此过程可能需要几分钟的时间。输出类似于以下内容:

INFO:     Started server process [145]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
...
INFO 04-07 13:36:29 [async_llm.py:228] Added request chatcmpl-4149ea4cf35e48559f9f819dcdbbb23e.
INFO:     127.0.0.1:44018 - "POST /v1/chat/completions HTTP/1.1" 200 OK

确保模型已完全下载,然后再继续下一部分。

应用模型

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

设置端口转发

如需设置到模型的端口转发,请运行以下命令:

kubectl port-forward service/llama-service 8080:8000

输出类似于以下内容:

Forwarding from 127.0.0.1:8080 -> 7080

使用 curl 与模型互动

本部分介绍如何执行基本冒烟测试以验证所部署的 Llama 指令调优模型。 对于其他模型,请将 meta-llama/Llama-4-Scout-17B-16E 替换为相应模型的名称。

此示例展示了如何使用纯文本输入测试 Llama 4 Scout 17B-16E 模型。

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

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-4-Scout-17B-16E",
    "messages": [{"role": "user", "content": "San Francisco is a"}],
    "max_tokens": 7,
    "temperature": 0
  }'

输出类似于以下内容:

"message":{"role":"assistant","reasoning_content":null,"content":"San Francisco is a city","tool_calls":[]}

问题排查

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

观察模型性能

如需查看模型的可观测性指标对应的信息中心,请按以下步骤操作:

  1. 在 Google Cloud 控制台中,前往已部署的模型页面。

    前往“已部署的模型”页面

  2. 如需查看特定部署的详细信息(包括其指标、日志和信息中心),请点击列表中的模型名称。

  3. 在模型详情页面中,点击可观测性标签页以查看以下信息中心。如果系统提示,请点击启用以对集群启用指标收集。

    • 基础设施使用情况信息中心会显示利用率指标。
    • DCGM 信息中心会显示 DCGM 指标。
    • 如果您使用的是 vLLM,则可以使用模型性能信息中心,该信息中心会显示 vLLM 模型性能的指标。

您还可以在 Cloud Monitoring 中的 vLLM 信息中心集成中查看指标。 这些指标会针对所有 vLLM 部署进行汇总,且没有预设过滤条件

如需使用 Cloud Monitoring 中的信息中心,您必须在 GKE 集群中启用 Google Cloud Managed Service for Prometheus,该服务会从 vLLM 收集指标。vLLM 默认以 Prometheus 格式公开指标;您无需安装其他导出工具。如需了解如何使用 Google Cloud Managed Service for Prometheus 从模型收集指标,请参阅 Cloud Monitoring 文档中的 vLLM 可观测性指南。