הפעלת סוכנים עם מודלים של Gemma 4 ב-Cloud Run

במדריך הזה מוסבר איך לפרוס מודלים פתוחים של Gemma 4 ב-Cloud Run באמצעות קונטיינר מוכן מראש עם ספריית ההסקה vLLM. בנוסף, מוסבר איך להשתמש בשירות Cloud Run שנפרס עם סוכני AI שנבנו באמצעות הערכה לפיתוח סוכנים.

‫Gemma 4 היא משפחת המודלים הכי יעילה של Google עם פרמטרים שזמינים לכולם, והיא מספקת יכולות חזקות של הסקת מסקנות וסוכנים.

היכולות של Gemma 4 – הקשר ארוך, ריבוי מודאליות, הסקת מסקנות ושימוש בכלים – מאפשרות לו להתמודד עם לוגיקה מורכבת, תכנון רב-שלבי, כתיבת קוד ותהליכי עבודה מבוססי-סוכן.

לפני שמתחילים

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

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. הגדרת סביבת הפיתוח של Cloud Run בפרויקט Google Cloud .
2. מתקינים ומפעילים את ה-CLI של gcloud.
3. מוודאים שהתפקידים הבאים ב-IAM הוקצו לחשבון שלכם:
   • אדמין ב-Cloud Run (roles/run.admin)
   • אדמין IAM בפרויקט (roles/resourcemanager.projectIamAdmin)
   • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

איך נותנים את התפקידים

המסוף

1. נכנסים לדף IAM במסוף Google Cloud .

   כניסה לדף IAM
2. בוחרים את הפרויקט.
3. לוחצים על Grant access.

4. בשדה New principals, מזינים את מזהה המשתמש. בדרך כלל זו כתובת האימייל שמשמשת לפריסת שירות Cloud Run.

5. בוחרים תפקיד מהרשימה Select a role.
6. כדי לתת עוד תפקידים, לוחצים על Add another role ומוסיפים את כולם.
7. לוחצים על Save.

gcloud

כדי להקצות לחשבון שלכם את תפקידי ה-IAM הנדרשים בפרויקט:

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

מחליפים את:

• ‫PROJECT_NUMBER עם מספר הפרויקט ב- Google Cloud .
• PROJECT_ID במזהה הפרויקט ב- Google Cloud .
• ‫PRINCIPAL עם החשבון שאליו אתם מוסיפים את הקישור. בדרך כלל זו כתובת האימייל שמשמשת לפריסת שירות Cloud Run.
• ‫ROLE עם התפקיד שאתם מוסיפים לחשבון של כלי הפריסה.
4. אם צריך, מבקשים Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region מכסה בקטע Cloud Run Admin API בדף Quotas and system limits.
5. אפשר לעיין בדף המחירון של Cloud Run. כדי ליצור הערכת עלויות בהתאם לשימוש החזוי, אתם יכולים להשתמש במחשבון התמחור.

פריסת מודל Gemma 4 באמצעות קונטיינר vLLM

‫Gemma 4 מציע יכולות מתקדמות של סוכנים, כולל הסקת מסקנות, בקשות להפעלת פונקציות, יצירת קוד ופלט מובנה.

הערכה לפיתוח סוכנים (ADK) עוזרת לכם ליצור סוכני AI עם פונקציונליות מלאה באמצעות Gemma 4.

אפשר להשתמש ב-vLLM כדי להפעיל את Gemma כנקודת קצה של OpenAI API. ‏vLLM מספקת הפעלה מהירה ויעילה של מודלים גנרטיביים בהיקף נרחב, עם תפוקת הפעלה מתקדמת, ניהול זיכרון יעיל באמצעות PagedAttention, אצווה רציפה של בקשות נכנסות, תמיכה בקוונטיזציה וליבות CUDA שעברו אופטימיזציה.

הערה: כדי להשתמש ב-Gemma 4 26B וב-31B, צריך לבצע הגדרה מתקדמת יותר של Cloud Run ו-vLLM עם Direct VPC Egress ו-Run:ai Model Streamer.

כדי לפרוס מודלים של Gemma ב-Cloud Run, משתמשים בפקודה הבאה ב-CLI של gcloud עם ההגדרות המומלצות:

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[*]}")

מחליפים את:

• ‫SERVICE_NAME מחליפים בשם ייחודי לשירות Cloud Run.
• ‫PROJECT במזהה הפרויקט ב- Google Cloud .

• ‫REGION באזור Google Cloud שבו יש תמיכה ביחידות GPU ל-Cloud Run, כמו us-central1.nvidia-rtx-pro-6000 רשימה מלאה של האזורים הנתמכים לפריסות עם GPU מופיעה במאמר בנושא הגדרת GPU.

• ‫MODEL_NAME בשם המלא של וריאציה של Gemma 4.

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

ההגדרות האחרות הן:

אפשרות	תיאור
--concurrency	המספר המקסימלי של בקשות שאפשר לעבד בו-זמנית במופע נתון, כמו 8. להמלצות בנושא חביון אופטימלי של בקשות, ראו הגדרת מקביליות לביצועים אופטימליים.
--cpu	כמות המעבד שהוקצה לשירות, כמו 20.
--set-env-vars	משתני הסביבה שהוגדרו לשירות. לדוגמה, HF_TOKEN="...".
--gpu	ערך ה-GPU של השירות, למשל 1.
--gpu-type	סוג ה-GPU שבו רוצים להשתמש בשירות, כמו nvidia-rtx-pro-6000.
--max-instances	המספר המקסימלי של מופעי קונטיינר לשירות, כמו 1.
--memory	כמות הזיכרון שהוקצה לשירות, כמו 80Gi.
--no-invoker-iam-check	השבתת בדיקות IAM של מי שמפעיל את הפונקציה. המלצות לשיפור האבטחה של האפליקציה זמינות במדריך Secure Cloud Run services tutorial.
--no-cpu-throttling	ההגדרה הזו משביתה את ההגבלות על השימוש במעבד כשהקונטיינר לא משרת בקשות באופן פעיל.
--timeout	הזמן שבו צריך להחזיר תשובה, למשל 600 שניות.
--startup-probe	הגדרות מופרדות בפסיקים לבדיקת ההפעלה בפורמט KEY=VALUE. פרטים נוספים מופיעים במאמר בנושא בדיקת מוכנות להפעלה ב-Cloud Run. אם אתם לא משתמשים ב-Direct VPC Egress, מומלץ להגדיר את הזמן הקצוב לתפוגה של בדיקת ההפעלה ל-240 שניות לפחות, אם אתם משתמשים במודלים בגודל Gemma 4.

אם אתם צריכים לשנות את הגדרות ברירת המחדל או להוסיף הגדרות מותאמות אישית לשירות Cloud Run, תוכלו לעיין במאמר בנושא הגדרת שירותים.

אחרי שהשירות שנפרס יסתיים, תוצג הודעת הצלחה עם כתובת ה-URL של נקודת הקצה של Cloud Run שמסתיימת ב-run.app.

בדיקה של שירות Gemma שנפרס באמצעות curl

אחרי שפורסים את שירות Gemma, אפשר לשלוח אליו בקשות. עם זאת, אם שולחים בקשה ישירות, Cloud Run מגיב עם HTTP 401 Unauthorized. זה מכוון, כי ממשק API של הסקת מסקנות של LLM מיועד לשירותים אחרים, כמו אפליקציית קצה. מידע נוסף על אימות בין שירותים ב-Cloud Run זמין במאמר אימות בין שירותים.

כדי לשלוח בקשות לשירות Gemma, צריך להוסיף לבקשות כותרת עם אסימון OIDC תקין, למשל באמצעות שרת proxy למפתחים של Cloud Run:

1. מפעילים את שרת ה-Proxy, וכשמוצגת בקשה להתקין את הרכיב cloud-run-proxy בוחרים באפשרות Y:

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

2. מריצים את הפקודה הבאה כדי לשלוח בקשה בכרטיסיית מסוף נפרדת, ומשאירים את ה-proxy פועל. שרת ה-Proxy פועל ב-localhost:9090. מציינים את מודל Gemma שהשתמשתם בו בעבר:

   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
     }'

   הפלט של הפקודה אמור להיראות כך:

   ‫

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

   הצלחה: פרסת שירות Cloud Run עם GPU ועם Gemma 4, ושלחת אליו בקשת הסקה.

הגדרת מקביליות לביצועים אופטימליים

בקטע הזה מוסבר על הגדרות הבו-זמניות המומלצות. כדי להשיג חביון בקשות אופטימלי, צריך לוודא שההגדרה --concurrency שווה לארגומנט של שורת הפקודה --max-num-seqs של vLLM.

• --max-num-seqs קובע כמה רצפים (בקשות) זמינים לכל מופע vLLM כדי לטפל בהסקת מסקנות בו-זמנית.
• ‫--concurrency קובע כמה בקשות Cloud Run שולח למופע vLLM בו-זמנית.

אם --concurrency גדול מ---max-num-seqs, ‏ Cloud Run יכול לשלוח יותר בקשות למופע vLLM ממה שיש לו משבצות בקשה זמינות. כתוצאה מכך, הבקשות נכנסות לתור ב-vLLM, וזמן האחזור של הבקשות בתור מתארך. בנוסף, התאמה אוטומטית לעומס תהיה פחות רספונסיבית, כי הבקשות בתור לא יפעילו את Cloud Run להרחבת קנה המידה ולהפעלת מופעים חדשים.

כדי להימנע לחלוטין מהוספת בקשות לתור במופע vLLM, צריך להגדיר את --concurrency כך שיתאים ל---max-num-seqs.

חשוב לציין שהגדלת --max-num-seqs גם מאריכה את משך הזמן של בקשות מקבילות, ודורשת יותר זיכרון GPU למטמון KV.

אופטימיזציה של הניצול

כדי להשיג ניצול אופטימלי של ה-GPU, צריך להגדיל את --concurrency, אבל לשמור אותו בטווח של עד פי שניים מהערך של --max-num-seqs. למרות שהדבר מוביל להוספת בקשות לתור ב-vLLM, הוא יכול לעזור לשפר את הניצול: מופעי vLLM יכולים לעבד באופן מיידי בקשות מהתור שלהם, והתורים עוזרים לספוג עליות פתאומיות בתנועה.

יצירת סוכני AI באמצעות ערכה לפיתוח סוכנים (ADK) באמצעות Gemma 4

אחרי שפורסים את שירות Cloud Run, אפשר להשתמש בנקודת הקצה של Cloud Run עם Gemma 4 כדי ליצור סוכני AI באמצעות הערכה לפיתוח סוכנים.

לפני שמשתמשים בערכת פיתוח הנציגים, צריך לוודא שהבקשות הנכנסות מעבירות את אסימון הזהות המתאים. למידע נוסף על שימוש באימות IAM ו-Cloud Run, ראו אימות בין שירותים.

בדוגמה הבאה אפשר לראות איך משתמשים בערכה לפיתוח סוכנים ב-Python עם אימות 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",
)

הסרת המשאבים

מחיקת המשאבים הבאים שנוצרו: Google Cloud

• שירות Cloud Run

המאמרים הבאים

• למודלים גדולים יותר ולזמן הפעלה מהיר יותר עם Run:ai Model Streamer, אפשר להשתמש בשיעור Codelab Run inference of Gemma 4 model on Cloud Run with RTX 6000 Pro GPU with vLLM (הפעלת הסקה של מודל Gemma 4 ב-Cloud Run עם RTX 6000 Pro GPU באמצעות vLLM).
• הגדרת GPU
• שיטות מומלצות: הסקת מסקנות מ-AI ב-Cloud Run עם יחידות GPU
• הפעלת מודלים של Gemma 4 עם מסגרות זמן ריצה שונות של AI