Menggunakan vLLM di GKE untuk menjalankan inferensi dengan Llama 4

Tutorial ini menunjukkan cara men-deploy dan menyajikan Llama 4 Scout (17Bx16E), sebuah model bahasa besar (LLM) 17B, dan menyajikannya menggunakan framework vLLM. Anda men-deploy model ini pada satu instance virtual machine (VM) A4 di Google Kubernetes Engine (GKE).

Tutorial ini ditujukan untuk engineer machine learning (ML), administrator dan operator platform, serta spesialis data dan AI yang tertarik menggunakan kemampuan orkestrasi container Kubernetes untuk menangani beban kerja inferensi.

Tujuan

Akses Llama 4 menggunakan Hugging Face.
Siapkan lingkungan Anda.
Buat cluster GKE dalam mode Autopilot.
Buat secret Kubernetes untuk kredensial Hugging Face.
Deploy container vLLM ke cluster GKE Anda.
Berinteraksi dengan Llama 4 menggunakan curl.
Jalankan pembersihan.

Biaya

Tutorial ini menggunakan komponen Google Cloud yang dapat ditagih, termasuk:

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan Kalkulator Harga.

Sebelum memulai

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Buat Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.
Pilih project Google Cloud yang Anda buat:
```
gcloud config set project PROJECT_ID
```
Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan API yang diperlukan:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

gcloud services enable container.googleapis.com

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Buat Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.
Pilih project Google Cloud yang Anda buat:
```
gcloud config set project PROJECT_ID
```
Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan API yang diperlukan:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

gcloud services enable container.googleapis.com

Memberikan peran ke akun pengguna Anda. Jalankan perintah berikut satu kali untuk setiap peran IAM berikut: roles/container.admin
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
```
Ganti kode berikut:
- PROJECT_ID: Project ID Anda.
- USER_IDENTIFIER: ID untuk akun pengguna Anda. Misalnya, myemail@example.com.
- ROLE: Peran IAM yang Anda berikan ke akun pengguna Anda.
Login atau buat akun Hugging Face.

Mengakses Llama 4 menggunakan Hugging Face

Untuk menggunakan Hugging Face guna mengakses Llama 4, lakukan hal berikut:

Tandatangani perjanjian izin untuk menggunakan Llama 4.
Buat token akses read Hugging Face.
Salin dan simpan nilai token akses read. Anda akan menggunakannya nanti dalam tutorial ini.

Menyiapkan lingkungan Anda

Untuk menyiapkan lingkungan Anda, tetapkan variabel berikut:

gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export RESERVATION_URL=RESERVATION_URL
export REGION=REGION
export CLUSTER_NAME=CLUSTER_NAME
export HUGGING_FACE_TOKEN=HUGGING_FACE_TOKEN
export NETWORK=NETWORK_NAME
export SUBNETWORK=SUBNETWORK_NAME

Ganti kode berikut:

PROJECT_ID: ID Google Cloud project tempat Anda ingin membuat cluster GKE.
RESERVATION_URL: URL reservasi yang ingin Anda gunakan untuk membuat cluster GKE. Berdasarkan project tempat pemesanan berada, tentukan salah satu nilai berikut:
- Reservasi ada di project Anda: RESERVATION_NAME
- Pemesanan ada di project lain, dan project Anda dapat menggunakan pemesanan: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
REGION: region tempat Anda ingin membuat cluster GKE. Anda hanya dapat membuat cluster di region tempat reservasi Anda berada.
CLUSTER_NAME: nama cluster GKE yang akan dibuat.
HUGGING_FACE_TOKEN: token akses Hugging Face yang Anda buat di bagian sebelumnya.
NETWORK_NAME: jaringan yang digunakan cluster GKE. Tentukan salah satu nilai berikut:
- Jika Anda membuat jaringan kustom, tentukan nama jaringan Anda.
- Jika tidak, tentukan default.
SUBNETWORK_NAME: subnetwork yang digunakan cluster GKE. Tentukan salah satu nilai berikut:
- Jika Anda membuat subnetwork kustom, tentukan nama subnetwork Anda. Anda hanya dapat menentukan subnetwork yang ada di region yang sama dengan reservasi.
- Jika tidak, tentukan default.

Membuat dan mengonfigurasi resource Google Cloud

Ikuti petunjuk di bagian ini untuk membuat resource yang diperlukan.

Membuat cluster GKE dalam mode Autopilot

Untuk membuat cluster GKE dalam mode Autopilot, jalankan perintah berikut:

gcloud container clusters create-auto $CLUSTER_NAME \
    --project=$PROJECT_ID \
    --region=$REGION \
    --release-channel=rapid \
    --network=$NETWORK \
    --subnetwork=$SUBNETWORK

Pembuatan cluster GKE mungkin memerlukan waktu beberapa saat untuk diselesaikan. Untuk memverifikasi bahwa Google Cloud telah selesai membuat cluster Anda, buka Kubernetes clusters di konsol Google Cloud .

Buat secret Kubernetes untuk menyimpan kredensial Hugging Face Anda

Untuk membuat secret Kubernetes guna menyimpan kredensial Hugging Face, lakukan hal berikut:

Konfigurasi kubectl untuk berkomunikasi dengan cluster GKE Anda:

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

Buat secret Kubernetes yang berisi token read access Hugging Face yang Anda buat pada langkah sebelumnya:

kubectl create secret generic hf-secret \
    --from-literal=hf_api_token=${HUGGING_FACE_TOKEN} \
    --dry-run=client -o yaml | kubectl apply -f -

Men-deploy container vLLM ke cluster GKE Anda

Untuk men-deploy container vLLM guna menayangkan model Llama-4-Scout-17B-16E-Instruct, lakukan langkah-langkah berikut:

Buat file vllm-l4-17b.yaml dengan deployment vLLM pilihan Anda:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-llama4-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: llama4-server
  template:
    metadata:
      labels:
        app: llama4-server
        ai.gke.io/model: llama-4-scout-17b
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250722_0916_RC01
        resources:
          requests:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "240Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "240Gi"
            nvidia.com/gpu: "8"
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=$(MODEL_ID)
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=4096
        - --max-num-seqs=4
        env:
        - 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
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 1800
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 1800
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: RESERVATION_URL
        cloud.google.com/reservation-affinity: "specific"
        cloud.google.com/gke-gpu-driver-version: latest
---
apiVersion: v1
kind: Service
metadata:
  name: llm-service
spec:
  selector:
    app: llama4-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-llama4-monitoring
spec:
  selector:
    matchLabels:
      app: llama4-server
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

Terapkan file vllm-l4-17b.yaml ke cluster GKE Anda:
```
  kubectl apply -f vllm-l4-17b.yaml
```
Selama proses deployment, container harus mendownload model Llama-4-Scout-17B-16E-Instruct dari Hugging Face. Oleh karena itu, deployment penampung mungkin memerlukan waktu hingga 30 menit untuk diselesaikan.
Untuk melihat status penyelesaian, jalankan perintah berikut:
```
  kubectl wait \
          --for=condition=Available \
          --timeout=1800s deployment/vllm-llama4-deployment
```
Flag--timeout=1800s memungkinkan perintah memantau deployment hingga 30 menit.

Berinteraksi dengan Llama 4 menggunakan curl

Untuk memverifikasi model Llama 4 Scout yang Anda deploy, lakukan langkah-langkah berikut:

Menyiapkan penerusan port ke Llama 4 Scout:

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

Buka jendela terminal baru. Kemudian, Anda dapat melakukan percakapan dengan model menggunakan curl:

curl http://127.0.0.1:8000/v1/chat/completions \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "model": "meta-llama/Llama-4-Scout-17B-16E-Instruct",
       "messages": [
         {
           "role": "user",
           "content": "Describe a sailboat in one short sentence?"
         }
       ]
     }'

Output yang Anda lihat mirip dengan berikut ini:

{
      "id": "chatcmpl-ec0ad6310c494a889b17600881c06e3d",
      "object": "chat.completion",
      "created": 1754073279,
      "model": "meta-llama/Llama-4-Scout-17B-16E-Instruct",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "A sailboat is a type of watercraft that uses the wind for propulsion, typically featuring a hull, mast, and one or more sails.",
            "refusal": null,
            "annotations": null,
            "audio": null,
            "function_call": null,
            "tool_calls": [],
            "reasoning_content": null
          },
          "logprobs": null,
          "finish_reason": "stop",
          "stop_reason": null
        }
      ],
      "service_tier": null,
      "system_fingerprint": null,
      "usage": {
        "prompt_tokens": 19,
        "total_tokens": 49,
        "completion_tokens": 30,
        "prompt_tokens_details": null
      },
      "prompt_logprobs": null,
      "kv_transfer_params": null
    }

Mengamati performa model

Untuk mengamati performa model, Anda dapat menggunakan integrasi dasbor vLLM di Cloud Monitoring. Anda dapat menggunakan dasbor ini untuk melihat metrik performa penting seperti throughput token, latensi permintaan, dan tingkat error.

Untuk mengetahui informasi tentang cara menggunakan Google Cloud Managed Service for Prometheus untuk mengumpulkan metrik dari model Anda, lihat panduan kemampuan pengamatan vLLM dalam dokumentasi Cloud Monitoring.

Pembersihan

Agar tidak perlu membayar biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource tersebut, atau simpan project dan hapus setiap resource.

Menghapus project Anda

Perhatian: Menghapus project memiliki efek berikut:

Semua hal dalam project akan dihapus. Jika Anda menggunakan project yang ada untuk mengerjakan tugas di dokumen ini, saat Anda menghapusnya, pekerjaan lain dalam project tersebut juga akan dihapus.
Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin juga membuat project ID kustom yang masih ingin digunakan pada masa mendatang. Agar tidak kehilangan URL yang menggunakan project ID tersebut, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

Jika Anda berencana mempelajari beberapa arsitektur, tutorial atau panduan memulai, dengan menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

Menghapus Google Cloud project:

gcloud projects delete PROJECT_ID

Menghapus resource

Untuk menghapus deployment dan layanan dalam file vllm-l4-17b.yaml dan secret Kubernetes dari cluster GKE, jalankan perintah berikut:
```
kubectl delete -f vllm-l4-17b.yaml
kubectl delete secret hf-secret
```

Untuk menghapus cluster GKE, jalankan perintah berikut:

gcloud container clusters delete $CLUSTER_NAME \
        --region=$REGION

Langkah berikutnya

Pelajari cara mengelola cluster GKE yang dioptimalkan untuk AI