Menjalankan agen dengan model Gemma 4 di Cloud Run

Panduan ini menjelaskan cara men-deploy model terbuka Gemma 4 di Cloud Run menggunakan container bawaan dengan library inferensi vLLM, dan memberikan panduan tentang cara menggunakan layanan Cloud Run yang di-deploy dengan agen AI yang dibuat menggunakan Agent Development Kit.

Gemma 4 adalah rangkaian model bobot terbuka Google yang paling efisien, yang memberikan kemampuan penalaran dan agen yang kuat.

Konteks panjang, multimodalitas, penalaran, dan pemanggilan alat memungkinkan Gemma 4 menangani logika kompleks, perencanaan multilangkah, coding, dan alur kerja agentic.

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Siapkan lingkungan pengembangan Cloud Run di project Google Cloud Anda.
2. Instal dan lakukan inisialisasi gcloud CLI.
3. Pastikan Anda memiliki peran IAM berikut yang diberikan ke akun Anda:
   • Cloud Run Admin (roles/run.admin)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Pelajari cara memberikan peran

Konsol

1. Di konsol Google Cloud , buka halaman IAM.

   Buka IAM
2. Pilih project.
3. Klik Grant access.

4. Di kolom New principals, masukkan ID pengguna Anda. Ini biasanya adalah alamat email yang digunakan untuk men-deploy layanan Cloud Run.

5. Di daftar Select a role, pilih peran.
6. Untuk memberikan peran tambahan, klik Add another role, lalu tambahkan tiap peran tambahan.
7. Klik Simpan.

gcloud

Untuk memberikan peran IAM yang diperlukan ke akun Anda di project Anda:

        gcloud projects add-iam-policy-binding PROJECT_ID \
            --member=PRINCIPAL \
            --role=ROLE
        

Ganti:

• PROJECT_NUMBER dengan nomor project Google Cloud Anda.
• PROJECT_ID dengan project ID Google Cloud Anda.
• PRINCIPAL dengan akun yang Anda tambahkan binding-nya. Biasanya, ini adalah alamat email yang digunakan untuk men-deploy layanan Cloud Run.
• ROLE dengan peran yang Anda tambahkan ke akun deployer.
4. Secara default, project baru otomatis diberi kuota 3.000 milliGPU saat deployment awal. Jika Anda memerlukan kuota tambahan, minta kuota Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region di bagian Cloud Run Admin API di halaman Quotas and system limits.
5. Tinjau halaman harga Cloud Run. Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Men-deploy model Gemma 4 dengan container vLLM

Gemma 4 menawarkan kemampuan agentic tingkat lanjut, termasuk penalaran, panggilan fungsi, pembuatan kode, dan output terstruktur.

Agent Development Kit (ADK) membantu Anda membangun agen AI yang berfungsi penuh dengan Gemma 4.

Gunakan vLLM untuk menyajikan Gemma sebagai endpoint API OpenAI. vLLM menyediakan penyajian yang cepat dan efisien untuk model generatif dalam skala besar, yang menampilkan throughput penyajian yang canggih, pengelolaan memori yang efisien dengan PagedAttention, pengelompokan berkelanjutan untuk permintaan yang masuk, dukungan kuantisasi, dan kernel CUDA yang dioptimalkan.

Catatan: Gemma 4 26B dan 31B memerlukan konfigurasi Cloud Run dan vLLM yang lebih canggih dengan Egress VPC Langsung dan Run:ai Model Streamer.

Untuk men-deploy model Gemma di Cloud Run, gunakan perintah gcloud CLI berikut dengan setelan yang direkomendasikan:

CONTAINER_ARGS=(
    "serve"
    "MODEL_NAME"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config=auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser=gemma4"
    "--reasoning-parser=gemma4"
    "--dtype=bfloat16"
    "--max-num-seqs=64"
    "--gpu-memory-utilization=0.95"
    "--tensor-parallel-size=1"
    "--port=8080"
    "--host=0.0.0.0"
)
gcloud beta run deploy SERVICE_NAME \
    --image "us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project PROJECT \
    --region REGION \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu 20 \
    --memory 80Gi \
    --gpu 1 \
    --gpu-type nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances 3 \
    --concurrency 64 \
    --timeout 600 \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=1,timeoutSeconds=240,periodSeconds=240 \
    --command "vllm" \
    --args=$(IFS=','; echo "${CONTAINER_ARGS[*]}")

Ganti:

• SERVICE_NAME dengan nama unik untuk layanan Cloud Run.
• PROJECT dengan Project ID Google Cloud Anda.

• REGION dengan region Google Cloud tempat GPU nvidia-rtx-pro-6000 didukung untuk Cloud Run, seperti us-central1. Untuk mengetahui daftar lengkap wilayah yang didukung untuk deployment yang mendukung GPU, lihat Konfigurasi GPU.

• MODEL_NAME dengan nama lengkap varian Gemma 4.

  • Gemma 4 2B: google/gemma-4-E2B-it
  • Gemma 4 4B: google/gemma-4-E4B-it

Setelan lainnya adalah sebagai berikut:

Opsi	Deskripsi
--concurrency	Jumlah maksimum permintaan yang dapat diproses secara bersamaan oleh instance tertentu, seperti 8. Lihat Menetapkan konkurensi untuk performa optimal guna mendapatkan rekomendasi tentang latensi permintaan yang optimal.
--cpu	Jumlah CPU yang dialokasikan untuk layanan Anda, seperti 20.
--set-env-vars	Variabel lingkungan yang ditetapkan untuk layanan Anda. Misalnya, HF_TOKEN="..."
--gpu	Nilai GPU untuk layanan Anda, seperti 1.
--gpu-type	Jenis GPU yang akan digunakan untuk layanan Anda, seperti nvidia-rtx-pro-6000.
--max-instances	Jumlah maksimum instance container untuk layanan Anda, seperti 1.
--memory	Jumlah memori yang dialokasikan untuk layanan Anda, seperti 80Gi.
--no-invoker-iam-check	Menonaktifkan pemeriksaan IAM invoker. Lihat Tutorial layanan Cloud Run yang aman untuk mendapatkan rekomendasi tentang cara mengamankan aplikasi Anda dengan lebih baik.
--no-cpu-throttling	Setelan ini menonaktifkan throttling CPU saat container tidak aktif melayani permintaan.
--timeout	Waktu yang diperlukan untuk menampilkan respons, misalnya 600 detik.
--startup-probe	Setelan yang dipisahkan koma untuk pemeriksaan startup dalam bentuk KEY=VALUE. Lihat Pemeriksaan Startup Cloud Run untuk mengetahui detailnya. Dengan ukuran model Gemma 4, jika Anda tidak menggunakan Traffic Keluar VPC Langsung, sebaiknya tetapkan waktu tunggu pemeriksaan startup minimal 240 detik.

Jika Anda perlu mengubah setelan default atau menambahkan setelan yang lebih disesuaikan ke layanan Cloud Run, lihat Mengonfigurasi layanan.

Setelah layanan yang di-deploy selesai, pesan berhasil akan ditampilkan beserta URL endpoint Cloud Run yang diakhiri dengan run.app.

Menguji layanan Gemma yang di-deploy dengan curl

Setelah men-deploy layanan Gemma, Anda dapat mengirim permintaan ke layanan tersebut. Namun, jika Anda mengirim permintaan secara langsung, Cloud Run akan merespons dengan HTTP 401 Unauthorized. Hal ini disengaja, karena API inferensi LLM dimaksudkan untuk dipanggil oleh layanan lain, seperti aplikasi front-end. Untuk mengetahui informasi selengkapnya tentang autentikasi antar layanan di Cloud Run, lihat Mengautentikasi antar layanan.

Untuk mengirim permintaan ke layanan Gemma, tambahkan header dengan token OIDC yang valid ke permintaan, misalnya menggunakan proxy developer Cloud Run:

1. Mulai proxy, dan saat diminta untuk menginstal komponen cloud-run-proxy, pilih Y:

   gcloud run services proxy SERVICE_NAME \
     --project PROJECT \
     --region REGION \
     --port=9090

2. Jalankan perintah berikut untuk mengirim permintaan di tab terminal terpisah, dengan membiarkan proxy tetap berjalan. Proxy berjalan di localhost:9090. Tentukan model Gemma yang sebelumnya Anda gunakan:

   curl http://localhost:9090/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MODEL_NAME",
       "messages": [{"role": "user", "content": "Why is the sky blue?"}],
       "chat_template_kwargs": {
            "enable_thinking": true
        },
        "skip_special_tokens": false
     }'

   Perintah ini akan memberikan output yang mirip dengan berikut ini:

   {
    "id": "chatcmpl-9cf1ab1450487047",
    "object": "chat.completion",
    "created": 1774904187,
    "model": "google/gemma-4-E2B-it",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "The short answer is a phenomenon called **Rayleigh scattering**...",
          "function_call": null,
          "tool_calls": [],
          "reasoning": "*   Question: \"Why is the sky blue?\"\n..."
        },
        "finish_reason": "stop",
        "stop_reason": 106
      }
    ],
    "usage": {
      "prompt_tokens": 21,
      "total_tokens": 877,
      "completion_tokens": 856
    }
   }
   

   Berhasil: Anda telah men-deploy layanan Cloud Run yang mendukung GPU dengan Gemma 4 dan mengirim permintaan inferensi ke layanan tersebut.

Menetapkan konkurensi untuk performa yang optimal

Bagian ini memberikan konteks tentang setelan serentak yang direkomendasikan. Untuk latensi permintaan yang optimal, pastikan setelan --concurrency sama dengan argumen command line --max-num-seqs vLLM.

• --max-num-seqs menentukan jumlah urutan (permintaan) yang tersedia per setiap instance vLLM untuk menangani inferensi secara serentak.
• --concurrency menentukan jumlah permintaan yang dikirim Cloud Run ke instance vLLM secara bersamaan.

Jika --concurrency melebihi --max-num-seqs, Cloud Run dapat mengirim lebih banyak permintaan ke instance vLLM daripada slot permintaan yang tersedia. Hal ini menyebabkan antrean permintaan dalam vLLM, sehingga meningkatkan latensi permintaan untuk permintaan yang diantrekan. Hal ini juga menyebabkan penskalaan otomatis yang kurang responsif, karena permintaan yang diantrekan tidak memicu Cloud Run untuk melakukan penyebaran skala dan memulai instance baru.

Untuk sepenuhnya menghindari antrean permintaan pada instance vLLM, Anda harus menetapkan --concurrency agar cocok dengan --max-num-seqs.

Penting untuk diperhatikan bahwa meningkatkan --max-num-seqs juga membuat permintaan paralel memerlukan waktu lebih lama, dan memerlukan lebih banyak memori GPU untuk KV cache.

Optimalkan pemanfaatan

Untuk pemanfaatan GPU yang optimal, tingkatkan --concurrency, dengan menjaganya tetap dalam dua kali nilai --max-num-seqs. Meskipun hal ini menyebabkan antrean permintaan di vLLM, hal ini dapat membantu meningkatkan pemanfaatan: instance vLLM dapat segera memproses permintaan dari antreannya, dan antrean membantu menyerap lonjakan traffic.

Membangun agen AI dengan Agent Development Kit menggunakan Gemma 4

Setelah men-deploy layanan Cloud Run, Anda dapat menggunakan endpoint Cloud Run dengan Gemma 4 untuk membuat agen AI dengan Agent Development Kit.

Sebelum Anda menggunakan Agent Development Kit, pastikan permintaan yang masuk meneruskan token identitas yang sesuai. Untuk mempelajari lebih lanjut cara menggunakan autentikasi IAM dan Cloud Run, lihat Mengautentikasi antar-layanan.

Contoh berikut menunjukkan cara menggunakan Agent Development Kit di Python dengan autentikasi IAM:

import subprocess
from google.adk.models.lite_llm import LiteLlm
from google.adk.agents import Agent

# Get the identity token using gcloud
id_token = subprocess.run(
    ["gcloud", "auth", "print-identity-token"],
    capture_output=True, text=True
).stdout.strip()

gemma_model = LiteLlm(
    model=f'openai/MODEL_NAME',
    base_url='https://YOUR_CLOUD_RUN_SERVICE_URL/v1',
    extra_body={
        "chat_template_kwargs": {
            "enable_thinking": True
        },
        "skip_special_tokens": False
    },
    extra_headers={
        "Authorization": f"Bearer {id_token}",
    },
)

root_agent = Agent(
    model=gemma_model,
    name='assistant',
    instruction="You are a helpful assistant",
)

Pembersihan

Hapus resource Google Cloud berikut yang dibuat:

• Layanan Cloud Run

Langkah berikutnya

• Untuk model yang lebih besar dan waktu startup yang lebih cepat dengan Run:ai Model Streamer, gunakan codelab Menjalankan inferensi model Gemma 4 di Cloud Run dengan GPU RTX 6000 Pro dengan vLLM
• Mengonfigurasi GPU
• Praktik terbaik: Inferensi AI di Cloud Run dengan GPU
• Menjalankan model Gemma 4 dengan berbagai framework runtime AI