التمرين العملي 3: من النموذج الأولي إلى الإنتاج - نشر وكيل ADK على Cloud Run باستخدام وحدة معالجة الرسومات

1. مقدمة

نظرة عامة

في هذا الدرس التطبيقي، ستنشر وكيل "حزمة تطوير الوكلاء" (ADK) الجاهز للاستخدام في مرحلة الإنتاج مع خلفية Gemma متوافقة مع وحدات معالجة الرسومات. ينصب التركيز على أنماط النشر المهمة: إعداد خدمات Cloud Run المتوافقة مع وحدات معالجة الرسومات، ودمج الخلفيات النموذجية مع وكلاء ADK، ومراقبة سلوك التوسيع التلقائي للنطاق في ظل الحمل.

الإجراءات التي ستنفذّها

في هذا التمرين العملي، ستركز على الجوانب المهمة المتعلقة بنشر الإصدارات في بيئة الإنتاج:

  1. نشر Gemma على Cloud Run باستخدام وحدة معالجة الرسومات: إعداد خلفية نموذج Gemma عالي الأداء
  2. دمج نشر Gemma مع وكيل ADK: ربط الوكيل بالنموذج المتسارع باستخدام وحدة معالجة الرسومات
  3. الاختبار باستخدام واجهة ADK على الويب: التحقّق من أنّ الوكيل الحواري يعمل بشكل صحيح
  4. إجراء اختبار التحميل: راقِب كيف يتم توسيع نطاق مثيلات Cloud Run تلقائيًا عند التحميل

ويتم التركيز على أنماط نشر الإنتاج بدلاً من التطوير المكثّف للوكيل.

أهداف الدورة التعليمية

  • نشر نماذج Gemma المتوافقة مع وحدات معالجة الرسومات (GPU) على Cloud Run لاستخدامها في الإنتاج
  • دمج عمليات نشر النماذج الخارجية مع برامج ADK
  • ضبط عمليات نشر وكلاء الذكاء الاصطناعي الجاهزة للاستخدام واختبارها
  • فهم سلوك توسيع النطاق التلقائي في Cloud Run عند زيادة الحمل
  • مراقبة كيفية تنسيق مثيلات Cloud Run المتعددة أثناء ارتفاع عدد الزيارات
  • تطبيق اختبار التحميل للتحقّق من الأداء والتوسيع التلقائي

2. إعداد المشروع

  1. إذا لم يكن لديك حساب على Google، عليك إنشاء حساب على Google.
    • استخدام حساب شخصي بدلاً من حساب عمل أو حساب تديره مؤسسة تعليمية قد تتضمّن حسابات العمل والحسابات التي تديرها المؤسسة التعليمية قيودًا تمنعك من تفعيل واجهات برمجة التطبيقات اللازمة لهذا الدرس التطبيقي.
  2. سجِّل الدخول إلى Google Cloud Console.
  3. فعِّل الفوترة في Cloud Console.
    • يجب أن تكلّف إكمال هذا المختبر أقل من دولار أمريكي واحد من موارد السحابة الإلكترونية.
    • يمكنك اتّباع الخطوات في نهاية هذا المختبر لحذف الموارد وتجنُّب تحمّل المزيد من الرسوم.
    • يمكن للمستخدمين الجدد الاستفادة من الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.
  4. أنشئ مشروعًا جديدًا أو اختَر إعادة استخدام مشروع حالي.

3- فتح Cloud Shell Editor

  1. انقر على هذا الرابط للانتقال مباشرةً إلى محرّر Cloud Shell
  2. إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على منح الإذن للمتابعة. انقر لتفويض Cloud Shell
  3. إذا لم تظهر النافذة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
    • انقر على عرض.
    • انقر على Terminalفتح نافذة طرفية جديدة في "محرِّر Cloud Shell"
  4. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
    • التنسيق:
      gcloud config set project [PROJECT_ID]
    • مثال:
      gcloud config set project lab-project-id-example
    • إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، اتّبِع الخطوات التالية:
      • يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      ضبط رقم تعريف المشروع في نافذة Cloud Shell Editor
  5. من المفترض أن تظهر لك هذه الرسالة:
    Updated property [core/project].
    إذا ظهرت لك WARNING وطُلب منك Do you want to continue (Y/n)?، من المحتمل أنّك أدخلت رقم تعريف المشروع بشكل غير صحيح. اضغط على n، ثم على Enter، وحاوِل تنفيذ الأمر gcloud config set project مرة أخرى.

4. تفعيل واجهات برمجة التطبيقات وضبط المنطقة التلقائية

قبل أن نتمكّن من نشر خدمات Cloud Run التي تتوافق مع وحدات معالجة الرسومات، علينا تفعيل واجهات Google Cloud APIs المطلوبة وضبط إعدادات مشروعك.

  1. في الوحدة الطرفية، فعِّل واجهات برمجة التطبيقات:
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

إذا طُلب منك منح الإذن، انقر على منح الإذن للمتابعة. انقر لتفويض Cloud Shell

قد يستغرق تنفيذ هذا الأمر بضع دقائق، ولكن من المفترض أن يعرض في النهاية رسالة نجاح مشابهة لما يلي:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
  1. اضبط منطقة Cloud Run التلقائية.
gcloud config set run/region europe-west1

5- إعداد مشروع Python

لنبدأ بإعداد الرمز الأولي الذي يحتوي على البنية الأساسية لكلّ من خدمات الخلفية في Gemma وخدمات وكيل ADK.

  1. استنسِخ مستودع حزمة البدء:
    cd ~
git clone https://github.com/amitkmaraj/accelerate-ai-lab3-starter.git
cd accelerate-ai-lab3-starter
  2. فحص بنية المشروع:
    ls -R
    من المفترض أن تظهر لك بنية البداية التالية:
    accelerate-ai-lab3-starter/
├── README.md                    # Project overview
├── ollama-backend/              # Ollama backend (separate deployment)
│   └── Dockerfile               # Backend container (🚧 to implement)
└── adk-agent/                   # ADK agent (separate deployment)
    ├── pyproject.toml           # Python dependencies (✅ completed)
    ├── server.py                # FastAPI server (🚧 to implement)
    ├── Dockerfile               # Container config (🚧 to implement)
    ├── load_test.py             # Load testing (🚧 to implement)
    └── production_agent/        # Agent implementation
        ├── __init__.py         # Package init (✅ completed)
        └── agent.py            # Agent logic (🚧 to implement)

6. نظرة عامة على الهندسة المعمارية

قبل التنفيذ، دعنا نتعرّف على بنية الخدمتين:

التمرين العملي 3: بنية الخدمتين

إحصاءات أساسية: أثناء اختبار التحميل، ستلاحظ أنّ الخدمتَين تتوسّعان بشكل مستقل، إذ يتوسّع الخلفية المستندة إلى وحدة معالجة الرسومات (الخدمة التي تشكّل عنق الزجاجة) إلى 1-3 مثيلات لحِمل الاستنتاج، بينما يبقى وكيل ADK على مثيل واحد لمعالجة الطلبات.

7. نشر Gemma Backend إلى Cloud Run باستخدام وحدة معالجة الرسومات

Lab 3 Gemma Service

تتمثّل الخطوة الأولى المهمة في نشر نموذج Gemma متوافق مع وحدة معالجة الرسومات، والذي سيعمل كعقل لوكيل ADK. قد يكون من المفضّل استخدام نموذج لغوي كبير (LLM) منفصل ومستخدَم في البُنى التي تحتاج إلى نموذج منفصل تم ضبطه بدقة أو تتطلّب توسيع نطاق معزول.

  1. انتقِل إلى دليل الخلفية في Ollama:
    cd ollama-backend
  2. افتح ملف Dockerfile الخاص بـ Ollama ونفِّذه:
    cloudshell edit Dockerfile
    استبدِل تعليق TODO بما يلي:
    FROM ollama/ollama:latest

# Listen on all interfaces, port 8080
ENV OLLAMA_HOST 0.0.0.0:8080

# Store model weight files in /models
ENV OLLAMA_MODELS /models

# Reduce logging verbosity
ENV OLLAMA_DEBUG false

# Never unload model weights from the GPU
ENV OLLAMA_KEEP_ALIVE -1

# Store the model weights in the container image
ENV MODEL gemma3:270m
RUN ollama serve & sleep 5 && ollama pull $MODEL

# Start Ollama
ENTRYPOINT ["ollama", "serve"]
    🔧 وظيفة هذا الإجراء:
    • يستخدم صورة Ollama الرسمية كأساس
    • يضبط OLLAMA_HOST على قبول الاتصالات من أي عنوان IP
    • تعرض المنفذ 8080
  3. يمكنك نشر الخلفية البرمجية لنموذج Gemma مع إتاحة استخدام وحدة معالجة الرسومات (GPU) باتّباع الخطوات التالية:
gcloud run deploy ollama-gemma3-270m-gpu \
  --source . \
  --region europe-west1 \
  --concurrency 4 \
  --cpu 8 \
  --set-env-vars OLLAMA_NUM_PARALLEL=4 \
  --gpu 1 \
  --gpu-type nvidia-l4 \
  --max-instances 3 \
  --memory 16Gi \
  --allow-unauthenticated \
  --no-cpu-throttling \
  --no-gpu-zonal-redundancy \
  --timeout 600 \
  --labels dev-tutorial=codelab-agent-gpu

إذا تلقّيت الرسالة "يتطلّب النشر من المصدر مستودع Artifact Registry Docker لتخزين الحاويات التي تم إنشاؤها. رسالة "سيتم إنشاء مستودع باسم [cloud-run-source-deploy] في المنطقة [europe-west1]"، تابِع.

⚙️ شرح الإعدادات الرئيسية:

  • وحدة معالجة الرسومات: تم اختيار NVIDIA L4 بسبب نسبة السعر إلى الأداء الممتازة لأحمال عمل الاستدلال. توفّر وحدة معالجة الرسومات L4 ذاكرة بسعة 24 غيغابايت وعمليات محسَّنة على موترات، ما يجعلها مثالية لنماذج تضم 270 مليون مَعلمة، مثل Gemma.
  • الذاكرة: ذاكرة نظام بسعة 16 غيغابايت للتعامل مع تحميل النماذج وعمليات CUDA وإدارة الذاكرة في Ollama
  • وحدة المعالجة المركزية (CPU): 8 نوى للتعامل الأمثل مع مهام الإدخال والإخراج والمعالجة المسبقة
  • التزامن: 4 طلبات لكل آلة افتراضية لتحقيق التوازن بين معدل النقل واستخدام ذاكرة وحدة معالجة الرسومات
  • المهلة: 600 ثانية لاستيعاب عملية تحميل النموذج الأولي وبدء تشغيل الحاوية

💰 مراعاة التكلفة: تكون تكلفة الآلات الافتراضية التي تستخدم وحدات معالجة الرسومات أعلى بكثير من تكلفة الآلات الافتراضية التي تستخدم وحدات المعالجة المركزية فقط (من 2 إلى 4 دولارات أمريكية في الساعة مقابل 0.10 دولار أمريكي في الساعة). يساعد إعداد --max-instances 1 في التحكّم في التكاليف من خلال منع توسيع نطاق مثيلات وحدة معالجة الرسومات غير الضرورية.

  1. انتظِر إلى أن يكتمل النشر، ثم سجِّل عنوان URL للخدمة:
    export OLLAMA_URL=$(gcloud run services describe ollama-gemma3-270m-gpu \
    --region=europe-west1 \
    --format='value(status.url)')

echo "🎉 Gemma backend deployed at: $OLLAMA_URL"

8. تنفيذ عملية دمج "وكيل ADK"

لننشئ الآن وكيل ADK بسيطًا يتصل بخادم Gemma الخلفي الذي تم نشره.

  1. انتقِل إلى دليل وكيل ADK:
    cd ../adk-agent
  2. افتح إعدادات الوكيل ونفِّذها:
    cloudshell edit production_agent/agent.py
    استبدِل كل تعليقات TODO بهذا التنفيذ البسيط:
    import os
from pathlib import Path

from dotenv import load_dotenv
from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
import google.auth

# Load environment variables
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)

# Configure Google Cloud
try:
    _, project_id = google.auth.default()
    os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
except Exception:
    pass

os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "europe-west1")

# Configure model connection
gemma_model_name = os.getenv("GEMMA_MODEL_NAME", "gemma3:270m")

# Production Gemma Agent - GPU-accelerated conversational assistant
gemma_agent = Agent(
   model=LiteLlm(model=f"ollama_chat/{gemma_model_name}"),
   name="gemma_agent",
   description="A production-ready conversational assistant powered by GPU-accelerated Gemma.",
   instruction="""You are 'Gem', a friendly, knowledgeable, and enthusiastic zoo tour guide.
   Your main goal is to make a zoo visit more fun and educational for guests by answering their questions.

   You can provide general information and interesting facts about different animal species, such as:
   - Their natural habitats and diet. 🌲🍓
   - Typical lifespan and behaviors.
   - Conservation status and unique characteristics.

   IMPORTANT: You do NOT have access to any tools. This means you cannot look up real-time, specific information about THIS zoo. You cannot provide:
   - The names or ages of specific animals currently at the zoo.
   - The exact location or enclosure for an animal.
   - The daily schedule for feedings or shows.

   Always answer based on your general knowledge about the animal kingdom. Keep your tone cheerful, engaging, and welcoming for visitors of all ages. 🦁✨""",
   tools=[],  # Gemma focuses on conversational capabilities
)

# Set as root agent
root_agent = gemma_agent
    🔧 وظيفة هذا الإجراء:
    • يتصل بخادم Gemma الخلفي الذي تم نشره من خلال LiteLlm
    • إنشاء برنامج وكيل محادثة بسيط
    • ضبط عملية الدمج مع Google Cloud
  3. افتح خادم FastAPI ونفِّذه:
    cloudshell edit server.py
    استبدال كل تعليقات TODO بما يلي:
    import os
from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app

# Load environment variables
load_dotenv()

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
app_args = {"agents_dir": AGENT_DIR, "web": True}

# Create FastAPI app with ADK integration
app: FastAPI = get_fast_api_app(**app_args)

# Update app metadata
app.title = "Production ADK Agent - Lab 3"
app.description = "Gemma agent with GPU-accelerated backend"
app.version = "1.0.0"

@app.get("/health")
def health_check():
    return {"status": "healthy", "service": "production-adk-agent"}

@app.get("/")
def root():
    return {
        "service": "Production ADK Agent - Lab 3",
        "description": "GPU-accelerated Gemma agent",
        "docs": "/docs",
        "health": "/health"
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8080, log_level="info")
    🔧 وظيفة هذا الإجراء:
    • إنشاء خادم FastAPI مع دمج ADK
    • تفعيل واجهة الويب للاختبار
    • توفير نقاط نهاية للتحقّق من الصحة
  4. افتح Dockerfile ونفِّذه:
    cloudshell edit Dockerfile
    استبدال كل تعليقات TODO بما يلي:
    FROM python:3.13-slim

# Copy uv from the official image
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Install system dependencies
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Copy all files
COPY . .

# Install Python dependencies
RUN uv sync

# Expose port
EXPOSE 8080

# Run the application
CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]
    شرح خيارات التكنولوجيا:
    • uv: أداة عصرية لإدارة حِزم Python أسرع من pip بمقدار 10 إلى 100 مرة يستخدم ذاكرة تخزين مؤقت عالمية وعمليات تنزيل متوازية، ما يقلّل بشكل كبير من أوقات إنشاء الحاويات
    • Python 3.13-slim: أحدث إصدار من Python مع الحد الأدنى من تبعيات النظام، ما يقلّل من حجم الحاوية ومساحة الهجوم
    • إنشاء متعدد المراحل: يضمن نسخ uv من صورته الرسمية الحصول على أحدث ثنائي محسّن

9- ضبط البيئة ونشر الوكيل

سنعمل الآن على ضبط وكيل ADK للاتصال بخادم Gemma الخلفي الذي تم نشره ونشره كخدمة Cloud Run. يتضمّن ذلك إعداد متغيّرات البيئة ونشر الوكيل باستخدام الإعداد الصحيح.

  1. اضبط إعدادات البيئة على النحو التالي:
    cat << EOF > .env
GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
GOOGLE_CLOUD_LOCATION=europe-west1
GEMMA_MODEL_NAME=gemma3:270m
OLLAMA_API_BASE=$OLLAMA_URL
EOF

التعرّف على متغيرات البيئة في Cloud Run

متغيّرات البيئة هي أزواج من المفاتيح والقيم تعمل على ضبط تطبيقك في وقت التشغيل. وهي مفيدة بشكل خاص في ما يلي:

  • نقاط نهاية واجهة برمجة التطبيقات وعناوين URL للخدمات (مثل الخلفية في Ollama)
  • الإعدادات التي تتغير بين البيئات (التطوير، والتشغيل التجريبي، والإنتاج)
  • البيانات الحسّاسة التي لا يجب ترميزها بشكل ثابت

نشر وكيل ADK:

export PROJECT_ID=$(gcloud config get-value project)

gcloud run deploy production-adk-agent \
   --source . \
   --region europe-west1 \
   --allow-unauthenticated \
   --memory 4Gi \
   --cpu 2 \
   --max-instances 1 \
   --concurrency 10 \
   --timeout 300 \
   --set-env-vars GOOGLE_CLOUD_PROJECT=$PROJECT_ID \
   --set-env-vars GOOGLE_CLOUD_LOCATION=europe-west1 \
   --set-env-vars GEMMA_MODEL_NAME=gemma3:270m \
   --set-env-vars OLLAMA_API_BASE=$OLLAMA_URL \
   --labels dev-tutorial=codelab-agent-gpu

⚙️ الإعدادات الرئيسية:

  • التوسّع التلقائي: تم ضبطه على مثيل واحد (معالجة الطلبات البسيطة)
  • التزامن: 10 طلبات لكل مثيل
  • الذاكرة: 4 غيغابايت لوكيل ADK
  • البيئة: تتصل هذه السمة بخادم Gemma الخلفي.

🔒 ملاحظة بشأن الأمان: تستخدم هذه الميزة الاختبارية --allow-unauthenticated لتبسيط العملية. في مرحلة الإنتاج، نفِّذ المصادقة المناسبة باستخدام:

  • مصادقة خدمة إلى خدمة في Cloud Run باستخدام حسابات الخدمة
  • سياسات إدارة الهوية وإمكانية الوصول (IAM)
  • مفاتيح واجهة برمجة التطبيقات أو OAuth للوصول الخارجي
  • ننصحك باستخدام gcloud run services add-iam-policy-binding للتحكّم في إمكانية الوصول

الحصول على عنوان URL لخدمة الوكيل:

export AGENT_URL=$(gcloud run services describe production-adk-agent \
    --region=europe-west1 \
    --format='value(status.url)')

echo "🎉 ADK Agent deployed at: $AGENT_URL"

✅ أفضل الممارسات المتعلّقة بمتغيرات البيئة استنادًا إلى مستندات متغيرات البيئة في Cloud Run:

  1. تجنُّب المتغيرات المحجوزة: لا تضبط PORT (يضبط Cloud Run هذا المتغير تلقائيًا) أو المتغيرات التي تبدأ بـ X_GOOGLE_
  2. استخدام أسماء وصفية: أضِف بادئة إلى المتغيّرات لتجنُّب التعارضات (مثل ‫GEMMA_MODEL_NAME بدلاً من MODEL)
  3. تجاهل الفواصل: إذا كانت القيم تحتوي على فواصل، استخدِم محدّدًا مختلفًا: --set-env-vars "^@^KEY1=value1,value2@KEY2=..."
  4. التعديل مقابل الاستبدال: استخدِم --update-env-vars لإضافة/تغيير متغيرات معيّنة بدون التأثير في المتغيرات الأخرى

كيفية ضبط المتغيّرات في Cloud Run:

  • من ملف: gcloud run deploy SERVICE_NAME --env-vars-file .env --labels dev-tutorial codelab-adk (لتحميل متغيرات متعددة من ملف)
  • علامات متعدّدة: كرِّر --set-env-vars للقيم المعقّدة التي لا يمكن فصلها بفواصل

10. الاختبار باستخدام واجهة الويب الخاصة بـ "حزمة تطوير التطبيقات"

بعد نشر كلتا الخدمتين، حان الوقت للتأكّد من أنّ وكيل ADK يمكنه التواصل بنجاح مع الخلفية المزوّدة بتسريع وحدة معالجة الرسومات والردّ على طلبات المستخدمين.

  1. اختبِر نقطة نهاية التحقّق من الصحة:
    curl $AGENT_URL/health
    من المفترض أن يظهر لك ما يلي:
    { "status": "healthy", "service": "production-adk-agent" }
  2. تفاعَل مع وكيلك من خلال إدخال عنوان URL الخاص بـ production-adk-agent في علامة تبويب متصفّح جديدة. من المفترض أن تظهر لك واجهة الويب الخاصة بـ ADK.
  3. اختبِر الوكيل باستخدام هذه المحادثات النموذجية:
    • "ماذا تأكل حيوانات الباندا الحمراء عادةً في البرية؟"
    • "هل يمكنك أن تخبرني بمعلومة مثيرة للاهتمام عن النمور الثلجية؟"
    • "لماذا تتميّز الضفادع السامة بألوانها الزاهية؟"
    • "أين يمكنني العثور على صغير الكنغر الجديد في حديقة الحيوانات؟"
    👀 ما يجب مراقبته:
    • يردّ الوكيل باستخدام نموذج Gemma الذي تم نشره. يمكنك التأكّد من ذلك من خلال مراقبة سجلّات خدمة Gemma التي تم نشرها. سننفّذ ذلك في القسم التالي.
    • يتم إنشاء الردود بواسطة نظام الخلفية المسرَّع بواسطة وحدة معالجة الرسومات
    • تقدّم واجهة الويب تجربة محادثة سلسة

التمرين العملي 3: اختبار حزمة تطوير التطبيقات

11. تنفيذ اختبار التحميل وتشغيله

التمرين العملي 3: اختبار التحميل

لفهم كيفية تعامل عملية النشر في مرحلة الإنتاج مع الزيارات الفعلية، سننفّذ اختبار تحميل شاملًا يؤدي إلى تفعيل التوسيع التلقائي على مستوى كل من وكيل ADK وخدمات الخلفية لوحدة معالجة الرسومات.

  1. افتح نص اختبار التحميل البرمجي ونفِّذه:
    cloudshell edit load_test.py
    استبدِل تعليق TODO بما يلي:
    import random
import uuid
from locust import HttpUser, task, between

class ProductionAgentUser(HttpUser):
    """Load test user for the Production ADK Agent."""

    wait_time = between(1, 3)  # Faster requests to trigger scaling

    def on_start(self):
        """Set up user session when starting."""
        self.user_id = f"user_{uuid.uuid4()}"
        self.session_id = f"session_{uuid.uuid4()}"

        # Create session for the Gemma agent using proper ADK API format
        session_data = {"state": {"user_type": "load_test_user"}}

        self.client.post(
            f"/apps/production_agent/users/{self.user_id}/sessions/{self.session_id}",
            headers={"Content-Type": "application/json"},
            json=session_data,
        )

    @task(4)
    def test_conversations(self):
        """Test conversational capabilities - high frequency to trigger scaling."""
        topics = [
            "What do red pandas typically eat in the wild?",
            "Can you tell me an interesting fact about snow leopards?",
            "Why are poison dart frogs so brightly colored?",
            "Where can I find the new baby kangaroo in the zoo?",
            "What is the name of your oldest gorilla?",
            "What time is the penguin feeding today?"
        ]

        # Use proper ADK API format for sending messages
        message_data = {
            "app_name": "production_agent",
            "user_id": self.user_id,
            "session_id": self.session_id,
            "new_message": {
                "role": "user",
                "parts": [{
                    "text": random.choice(topics)
                }]
            }
        }

        self.client.post(
            "/run",
            headers={"Content-Type": "application/json"},
            json=message_data,
        )

    @task(1)
    def health_check(self):
        """Test the health endpoint."""
        self.client.get("/health")
    🔧 وظيفة هذا الإجراء:
    • إنشاء الجلسة: يتم استخدام تنسيق واجهة برمجة تطبيقات ADK المناسب مع POST إلى /apps/production_agent/users/{user_id}/sessions/{session_id}. بعد إنشاء session_id وuser_id، يمكن تقديم طلب إلى الوكيل.
    • تنسيق الرسالة: يتّبع مواصفات ADK مع app_name وuser_id وsession_id وعنصر new_message المنظَّم
    • نقطة نهاية المحادثة: تستخدم نقطة النهاية /run لجمع جميع الأحداث في وقت واحد (يُنصح بها لاختبار التحميل)
    • التحميل الواقعي: ينشئ تحميلًا حواريًا مع أوقات انتظار أقصر لتفعيل التوسيع التلقائي.
    📚 لمزيد من التفاصيل حول نقاط نهاية واجهة برمجة التطبيقات في "حزمة تطوير التطبيقات" وأنماط الاختبار، يُرجى الاطّلاع على دليل اختبار "حزمة تطوير التطبيقات".
  2. ثبِّت التبعيّات:
    uv sync
pip install locust
  3. ‫Locust هي أداة مفتوحة المصدر لاختبار التحميل مستندة إلى Python ومصمَّمة لاختبار أداء تطبيقات الويب والأنظمة الأخرى واختبار تحميلها. وتتمثّل السمة الرئيسية لهذه الأداة في أنّ سيناريوهات الاختبار وسلوك المستخدم يتم تحديدها باستخدام رموز Python البرمجية العادية، ما يوفّر مرونة عالية وقدرة على التعبير مقارنةً بالأدوات التي تعتمد على واجهات المستخدم الرسومية أو اللغات الخاصة بالمجال. سنستخدم Locust لمحاكاة عدد الزيارات إلى خدماتنا.شغِّل اختبار التحميل.
    # Run a load test to trigger autoscaling
locust -f load_test.py \
   -H $AGENT_URL \
   --headless \
   -t 50s \
   -u 3 \
   -r 1
    جرِّب تغيير المَعلمات في الاختبار ولاحِظ الناتج. ستلاحظ ارتفاعًا في عدد مرات ظهور ollama-gemma3-270m-gpu إلى 2 أو 3 مرات. 📊 مَعلمات اختبار التحميل:
    • المدة: 50 ثانية
    • المستخدمون: 3 مستخدمين متزامنين
    • معدّل ظهور المستخدمين: مستخدم واحد في الثانية
    • الهدف: تفعيل التوسيع التلقائي النطاق على كلتا الخدمتين

12. مراقبة سلوك AutoScaling

أثناء تنفيذ اختبار التحميل، ستتمكّن من ملاحظة ميزة "التوسيع التلقائي" في Cloud Run أثناء عملها. وهنا ستلاحظ المزايا المعمارية الرئيسية لفصل وكيل ADK عن الخلفية المستندة إلى وحدة معالجة الرسومات.

أثناء اختبار التحميل، راقِب كيفية توسيع نطاق كلتا الخدمتَين في Cloud Run في وحدة التحكّم.

  1. في Cloud Console، انتقِل إلى:
    • ‫Cloud Run → production-adk-agent → المقاييس
    • Cloud Run → ollama-gemma3-270m-gpu → المقاييس

👀 ما يجب ملاحظته:

🤖 خدمة وكيل ADK:

  • يجب أن يظل ثابتًا عند مثيل واحد أثناء زيادة عدد الزيارات
  • ارتفاع معدّل استخدام وحدة المعالجة المركزية والذاكرة أثناء زيادة عدد الزيارات
  • التعامل مع إدارة الجلسات وتوجيه الطلبات بكفاءة

🎮 خدمة الخلفية في Gemma (عنق الزجاجة):

  • تتراوح سعة التوسّع بين مثيل واحد و3 مثيلات استنادًا إلى الطلب على الاستدلال
  • زيادة استخدام وحدة معالجة الرسومات بشكل كبير عند التحميل
  • تصبح هذه الخدمة عنق الزجاجة بسبب استنتاج النماذج المكثّف لوحدة معالجة الرسومات
  • تظل أوقات الاستدلال في النموذج ثابتة بسبب تسريع وحدة معالجة الرسومات

💡 إحصاءات أساسية:

  • تمثّل الخلفية لوحدة معالجة الرسومات عنق الزجاجة، ويتم توسيع نطاقها بشكل أكثر فعالية (من مثيل واحد إلى 3 مثيلات).
  • يظلّ وكيل ADK متسقًا
  • يمكن توسيع نطاق الخدمتين بشكل مستقل استنادًا إلى خصائص الحمل الفردية
  • تساعد ميزة "التوسيع التلقائي" في الحفاظ على الأداء في ظل ظروف الأحمال المتغيرة

13. الخاتمة

تهانينا! لقد نجحت في نشر وكيل ADK جاهز للإنتاج مع خلفية Gemma متوافقة مع وحدة معالجة الرسومات (GPU) ولاحظت سلوك التوسّع التلقائي.

✅ الإنجازات التي حققتها

  • ‫✅ نشر خلفية نموذج Gemma متسارعة باستخدام وحدة معالجة الرسومات على Cloud Run
  • ✅ إنشاء وكيل ADK ونشره يتكامل مع الخلفية البرمجية لنموذج Gemma
  • ✅ تم اختبار الوكيل باستخدام واجهة الويب الخاصة بـ ADK
  • ‫✅ تم رصد سلوك توسيع النطاق التلقائي في خدمتَين منسّقتَين على Cloud Run

💡 الإحصاءات الرئيسية من هذه الميزة الاختبارية

  1. 🎮 تسريع وحدة معالجة الرسومات: تعمل وحدة معالجة الرسومات NVIDIA L4 على تحسين أداء استنتاج النماذج بشكل كبير
  2. 🔗 تنسيق الخدمات: يمكن لخدمتَين من Cloud Run العمل معًا بسلاسة
  3. 📈 التوسّع المستقل: تتوسّع كل خدمة استنادًا إلى خصائص التحميل الفردية الخاصة بها
  4. 🚀 الجاهزية للإنتاج: تتعامل البنية الأساسية بفعالية مع أنماط الزيارات في العالم الحقيقي

🔄 الخطوات التالية

  • تجربة أنماط تحميل مختلفة ومراقبة سلوك التوسيع
  • جرِّب أحجامًا مختلفة من نماذج Gemma (عدِّل الذاكرة ووحدة معالجة الرسومات وفقًا لذلك)
  • تنفيذ عمليات المراقبة والتنبيه لعمليات النشر في بيئة الإنتاج
  • استكشاف عمليات النشر في مناطق متعدّدة لتحقيق التوفّر على مستوى العالم

‫🧹 تنظيف

لتجنُّب تحمّل رسوم، احذف الموارد عند الانتهاء من استخدامها:

gcloud run services delete production-adk-agent --region=europe-west1
gcloud run services delete ollama-gemma3-270m-gpu --region=europe-west1

📖 المراجع