Menjalankan agen dengan model Gemma 4 di Cloud Run

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

Gemma 4 adalah lini model open source dengan bobot ringan paling efisien dari Google, yang memberikan kemampuan penalaran dan agentik yang kuat.

Konteks panjang, multimodalitas, penalaran, dan pemanggilan alat memungkinkan Gemma 4 menangani logika yang kompleks, perencanaan multi-langkah, 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.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Siapkan lingkungan pengembangan Cloud Run di Google Cloud project Anda.
Instal dan lakukan inisialisasi gcloud CLI.
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

Di konsol Google Cloud , buka halaman IAM.
Buka IAM
Pilih project.
Klik Grant access.
Di kolom New principals, masukkan ID pengguna Anda. Identitas ini biasanya berupa alamat email yang digunakan untuk men-deploy layanan Cloud Run.
Di daftar Select a role, pilih peran.
Untuk memberikan peran tambahan, klik Add another role, lalu tambahkan tiap peran tambahan.
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, alamat email ini adalah alamat yang digunakan untuk men-deploy layanan Cloud Run.
ROLE dengan peran yang Anda tambahkan ke akun deployer.

Jika perlu, 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.
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 agentik 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 OpenAI API. vLLM menyediakan penyajian yang cepat dan efisien untuk model generatif dalam skala besar, yang menampilkan throughput penyajian canggih, pengelolaan memori yang efisien dengan PagedAttention, batch berkelanjutan untuk permintaan yang masuk, dukungan kuantisasi, dan kernel CUDA yang dioptimalkan.

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 ID Project 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 region 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 serentak untuk performa optimal untuk 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`	Nonaktifkan pemeriksaan IAM pemanggil. Lihat Tutorial layanan Cloud Run yang aman untuk mengetahui rekomendasi tentang cara mengamankan aplikasi Anda dengan lebih baik.
`--no-cpu-throttling`	Setelan ini menonaktifkan pembatasan CPU saat penampung tidak aktif melayani permintaan.
`--timeout`	Waktu saat respons harus ditampilkan, seperti `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 Anda setidaknya 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 berakhir 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 ditujukan untuk dipanggil oleh layanan lain, seperti aplikasi frontend. 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:

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

Jalankan perintah berikut untuk mengirim permintaan di tab terminal terpisah, dengan 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:

{
 "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
 }
}

Menetapkan konkurensi untuk performa 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 bersamaan.
--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 penskalaan dan memulai instance baru.

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

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

Optimalkan pemanfaatan

Untuk pemanfaatan GPU yang optimal, tingkatkan --concurrency, dengan mempertahankannya dalam dua kali nilai --max-num-seqs. Meskipun menyebabkan permintaan mengantre 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 menggunakan Agent Development Kit, pastikan permintaan 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 mulai yang lebih cepat dengan Run:ai Model Streamer, gunakan codelab Menjalankan inferensi model Gemma 4 di Cloud Run dengan GPU RTX 6000 Pro menggunakan vLLM
Konfigurasi GPU
Praktik terbaik: Inferensi AI di Cloud Run dengan GPU
Menjalankan model Gemma 4 dengan berbagai framework runtime AI

Menjalankan agen dengan model Gemma 4 di Cloud Run Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Pelajari cara memberikan peran

Konsol

gcloud

Men-deploy model Gemma 4 dengan container vLLM

Menguji layanan Gemma yang di-deploy dengan curl

Menetapkan konkurensi untuk performa optimal

Optimalkan pemanfaatan

Membangun agen AI dengan Agent Development Kit menggunakan Gemma 4

Pembersihan

Langkah berikutnya

Menjalankan agen dengan model Gemma 4 di Cloud Run