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

1- مقدمة

نظرة عامة

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

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

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

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

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

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

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

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

  1. إذا لم يكن لديك حساب حاليًا، عليك إنشاء حساب على 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)
    ├── elasticity_test.py       # Elasticity testing (🚧 to implement)
    └── production_agent/        # Agent implementation
        ├── __init__.py          # Package init (✅ completed)
        └── agent.py             # Agent logic (🚧 to implement)

6. نظرة عامة على البنية

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

التمرين العملي 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 7 \
  --cpu 8 \
  --set-env-vars OLLAMA_NUM_PARALLEL=4 \
  --gpu 1 \
  --gpu-type nvidia-l4 \
  --max-instances 1 \
  --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
  • وحدة المعالجة المركزية: 8 نوى للتعامل الأمثل مع مهام الإدخال والإخراج والمعالجة المسبقة
  • التزامن: 7 طلبات لكل آلة افتراضية لتحقيق التوازن بين معدل النقل واستخدام ذاكرة وحدة معالجة الرسومات
  • المهلة: 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")
api_base = os.getenv("OLLAMA_API_BASE", "localhost:10010")  # Location of Ollama server

# Production Gemma Agent - GPU-accelerated conversational assistant
production_agent = Agent(
   model=LiteLlm(model=f"ollama_chat/{gemma_model_name}", api_base=api_base),
   name="production_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 = production_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 50 \
   --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

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

  • التوسّع التلقائي: تم ضبطه على مثيل واحد (التعامل مع الطلبات البسيطة)
  • التزامن: 50 طلبًا لكل مثيل
  • الذاكرة: 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 (إذا كنت بحاجة إلى تغيير متغير env، استخدِم العلامة ‎–port بدلاً من ذلك) أو المتغيرات التي تبدأ بـ 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: اختبار المرونة

لفهم كيفية تعامل عملية نشر الإصدار العلني مع الزيارات الفعلية، سننفّذ اختبارًا للمرونة يختبر قدرة النظام على التكيّف مع عبء عمل أعلى "محاكى" في الإصدار العلني.

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

class ProductionAgentUser(HttpUser):
    """Elasticity 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": "elasticity_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."""
        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
  3. ‫Locust هي أداة مفتوحة المصدر لاختبار التحميل مستندة إلى Python ومصمَّمة لاختبار أداء تطبيقات الويب والأنظمة الأخرى واختبار تحميلها. وتتمثّل السمة الرئيسية لهذه الأداة في أنّ سيناريوهات الاختبار وسلوك المستخدم يتم تحديدها باستخدام رموز Python البرمجية العادية، ما يوفّر مرونة عالية وقدرة على التعبير مقارنةً بالأدوات التي تعتمد على واجهات المستخدم الرسومية أو اللغات الخاصة بالمجال. سنستخدم Locust لمحاكاة عدد زيارات المستخدمين لخدماتنا.شغِّل الاختبار.
    uv run locust -f elasticity_test.py \
   -H $AGENT_URL \
   --headless \
   -t 60s \
   -u 20 \
   -r 5
    جرِّب تغيير المَعلمات في الاختبار وراقِب الناتج.📊 مَعلمات اختبار المرونة:
    • المدة: 60 ثانية
    • المستخدمون: 20 مستخدمًا متزامنًا
    • معدّل إنشاء المستخدمين: 5 مستخدمين في الثانية
    • الهدف: تفعيل التوسيع التلقائي النطاق على كلتا الخدمتين

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

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

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

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

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

🤖 خدمة وكيل ADK:

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

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

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

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

  • تظلّ الخدمتان متسقتَين ولا يتم توسيعهما، لأنّنا ضبطنا الحد الأقصى لعدد المثيلات على 1
  • يمكن توسيع نطاق الخدمتين بشكل مستقل استنادًا إلى خصائص الحمل الفردية
  • تساعد وحدة معالجة الرسومات في الحفاظ على الأداء في ظل ظروف تحميل مختلفة

13. الخاتمة

تهانينا! لقد نجحت في نشر وكيل ADK جاهز للإنتاج مع خلفية Gemma مسرَّعة بواسطة وحدة معالجة الرسومات، وذلك أثناء اختبار عبء عمل محاكى للإنتاج.

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

  • ‫✅ نشر خلفية نموذج Gemma مسرَّعة بواسطة وحدة معالجة الرسومات على Cloud Run
  • ✅ إنشاء وكيل "حزمة تطوير الوكلاء" ونشره، وهو وكيل يتكامل مع الخلفية البرمجية لنموذج 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

📖 المراجع