تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إنشاء ونشر وكلاء مستندين إلى الذكاء الاصطناعي باستخدام Gemma 4 وخادم BigQuery MCP في Cloud Run

1- مقدمة

نظرة عامة

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

كيفية نشر نموذج Gemma 4 على وحدة معالجة الرسومات RTX 6000 Pro في Cloud Run باستخدام vLLM
كيفية إنشاء وكيل ذكاء اصطناعي باستخدام حزمة Agent Development Kit ‏ (ADK) واستخدام Gemma 4 معه
كيفية منح وكلاء الذكاء الاصطناعي إذن الوصول إلى البيانات المنظَّمة في BigQuery باستخدام خادم BigQuery MCP.

‫Gemma 4 هي مجموعة من النماذج المفتوحة التي تستخدم أوزانًا مرخّصة بموجب ترخيص Apache 2 من Google DeepMind. تتسم هذه النماذج بأنّها متعددة الوسائط ومتعددة اللغات وتوفّر إمكانات الاستدلال وبنية فعّالة.

‫Cloud Run هي بيئة بدون خادم للحاويات تتوافق مع وحدات معالجة الرسومات.

‫Agent Development Kit ‏ (ADK) هو إطار عمل مفتوح المصدر لتطوير الوكلاء يتيح لك إنشاء وكلاء ذكاء اصطناعي موثوق بهم وتصحيح أخطائهم ونشرهم على مستوى المؤسسة.

‫BigQuery هو مستودع مُدار بالكامل لبيانات المؤسسات بدون خادم يتيح لك تخزين مجموعات البيانات الضخمة والاستعلام عنها وتحليلها.

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

2. الإعداد والمتطلبات

ابدأ بضبط المشروع التلقائي ومنطقة Cloud Run التلقائية:

# set the project
gcloud config set project YOUR_PROJECT_ID

استبدِل YOUR_PROJECT_ID برقم تعريف مشروعك على Google Cloud.

# set Cloud Run region
REGION="CLOUD-RUN-REGION"; gcloud config set run/region $REGION && echo $REGION > lab2rgn.txt

استبدِل CLOUD-RUN-REGION بإحدى مناطق السحابة الإلكترونية التالية:

us-central1
asia-southeast1

في ما يلي متغيّرات البيئة التي سيتم استخدامها خلال هذا الدرس التطبيقي حول الترميز. يمكنك حفظها في ملف بيئة واستخدام الأمر `source` لتشغيلها. احرص على ضبط قيمة رقم تعريف مشروعك بشكل صحيح، ويمكنك أيضًا ضبط المنطقة.

# Model name on HuggingFace Hub
export MODEL_NAME="google/gemma-4-31B-it"

# Cloud Run Service name
export SERVICE_NAME="gemma4-rtx-vllm-codelab"

# Cloud Project and Region for Cloud Run
export GOOGLE_CLOUD_PROJECT=$(gcloud config get project -q)
export GOOGLE_CLOUD_REGION=$(cat lab2rgn.txt 2> /dev/null || gcloud config get run/region -q)

# Service account for Cloud Run service
export SERVICE_ACCOUNT="vllm-service-sa"
export SERVICE_ACCOUNT_EMAIL="${SERVICE_ACCOUNT}@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com"

# GCS Bucket for the model cache.
export MODEL_CACHE_BUCKET="${GOOGLE_CLOUD_PROJECT}-${GOOGLE_CLOUD_REGION}-hf-model-cache"
# Model cache location in GSC bucket
export GCS_MODEL_LOCATION="gs://${MODEL_CACHE_BUCKET}/model-cache/${MODEL_NAME}"
# Uncomment next line if loading gemma-4-31B-it directly from the public cache bucket
# export GCS_MODEL_LOCATION="gs://vertex-model-garden-public-us/gemma4/gemma-4-31B-it"

# VPC Network for Direct VPC Egress
export VPC_NETWORK="vllm-${GOOGLE_CLOUD_REGION}-net"
export VPC_SUBNET="vllm-${GOOGLE_CLOUD_REGION}-subnet"
export SUBNET_RANGE="10.8.0.0/26"

فعِّل واجهات برمجة التطبيقات اللازمة لهذا الدرس التطبيقي حول الترميز. قد يستغرق تطبيق تغييرات واجهة برمجة التطبيقات من دقيقتَين إلى 3 دقائق.

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    iam.googleapis.com \
    compute.googleapis.com \
    vpcaccess.googleapis.com \
    storage.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. إنشاء حساب خدمة

إذا لم تحدّد حساب خدمة عند إنشاء خدمة Cloud Run أو مهمتها، تستخدم Cloud Run حساب الخدمة التلقائي في Compute Engine. يُنصح باستخدام حساب خدمة منفصل لخدمة Cloud Run لتجنُّب تشغيل الخدمة بأذونات مفرطة.

إنشاء حساب خدمة لخدمة Cloud Run

gcloud iam service-accounts create ${SERVICE_ACCOUNT} \
  --project "${GOOGLE_CLOUD_PROJECT}" \
  --display-name "vLLM Service Account"

4. إعداد Cloud Storage

أنشئ حزمة Cloud Storage لتخزين أوزان النموذج. سيسمح ذلك باستخدام Direct VPC Egress لتنزيل أوزان النموذج بشكل أسرع في كل مرة تبدأ فيها Cloud Run مثيلاً للخدمة.

بالإضافة إلى ميزة Run:ai Model Streamer في vLLM، يقلّل ذلك بشكل كبير من وقت تحميل النموذج.

إنشاء حزمة

احرص على أن تكون حزمة ذات منطقة واحدة وموجودة في الموقع الجغرافي نفسه لخدمة Cloud Run.

gcloud storage buckets create "gs://${MODEL_CACHE_BUCKET}" \
    --uniform-bucket-level-access --public-access-prevention \
    --project "${GOOGLE_CLOUD_PROJECT}" --location "${GOOGLE_CLOUD_REGION}"

5. استرداد أوزان النموذج وتخزينها مؤقتًا

بعد ذلك، نزِّل نموذج Gemma 4 إلى حزمة Cloud Storage. تزن أوزان النماذج عشرات الجيجابايت، وقد يكون تنزيلها إلى جهازك المحلي أو Cloud Shell أولاً غير ممكن. بدلاً من ذلك، استخدِم Cloud Build مع مساحة تخزين كافية لحفظ أوزان النموذج.

نسخ أوزان النموذج من حزمة Cloud Storage مشترَكة

تستضيف Google Cloud حزمة Cloud Storage متاحة للجميع تحتوي على أوزان نموذج Gemma 4.

لنسخها إلى حزمة التخزين، شغِّل الأمر:

gcloud builds submit --project="${GOOGLE_CLOUD_PROJECT}" --region="${GOOGLE_CLOUD_REGION}" --no-source \
    --substitutions="_MODEL_NAME=${MODEL_NAME},_GCS_MODEL_LOCATION=${GCS_MODEL_LOCATION}" \
    --config=/dev/stdin <<'EOF'
steps:
- name: 'gcr.io/google.com/cloudsdktool/google-cloud-cli:slim'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
    if [[ "$_GCS_MODEL_LOCATION" == *"vertex-model-garden-public-us"* ]]; then
      echo "Using the public cache bucket."
      exit 0
    fi
    gcloud config set storage/parallel_composite_upload_enabled True
    gcloud config set storage/parallel_composite_upload_threshold 150M
    gcloud config set storage/sliced_object_download_threshold 150M
    MODEL_NAME="$_MODEL_NAME"
    SHORT_NAME="$${MODEL_NAME#*/}"
    gcloud storage cp -r -D "gs://vertex-model-garden-public-us/gemma4/$${SHORT_NAME}" "$_GCS_MODEL_LOCATION"
EOF

6. ضبط إعدادات الشبكات لـ Direct VPC Egress

يتطلب ضبط Direct VPC Egress إنشاء شبكة وشبكة فرعية مع تفعيل "الوصول الخاص إلى Google".

يسمح ذلك لخدمات Cloud Run بالاتصال بمجموعة عناوين IP الخارجية التي تستخدمها Google APIs وخدماتها، بما في ذلك Cloud Storage.

إنشاء شبكة

gcloud compute networks create "$VPC_NETWORK" \
        --subnet-mode=custom \
        --bgp-routing-mode=regional \
        --project "$GOOGLE_CLOUD_PROJECT"

إنشاء شبكة فرعية

gcloud compute networks subnets create "$VPC_SUBNET" \
        --network="$VPC_NETWORK" \
        --region="$GOOGLE_CLOUD_REGION" \
        --range="$SUBNET_RANGE" \
        --enable-private-ip-google-access \
        --project "$GOOGLE_CLOUD_PROJECT"

7. ضبط سياسة الوصول إلى حساب الخدمة

يحتاج حساب خدمة Cloud Run إلى أذونات للوصول إلى أوزان النموذج في حزمة التخزين التي أنشأتها.

gcloud storage buckets add-iam-policy-binding "gs://${MODEL_CACHE_BUCKET}" \
    --member "serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
    --role "roles/storage.admin" \
    --project "${GOOGLE_CLOUD_PROJECT}"

8. تهيئة متغيّرات الإعدادات

حدِّد المتغيّرات لكل من محرّك استنتاج vLLM وخدمة Cloud Run.

# vLLM variables
export MAX_MODEL_LEN="32767"    # 32767 to improve concurrency. Keep it empty to use model's maximim context length (256K)
export QUANTIZATION_TYPE="fp8"  # Model quantization for faster performance and lower memory usage.
export KV_CACHE_DTYPE="fp8"     # KV-cache quantization to save GPU memory.
export GPU_MEM_UTIL="0.95"      # Fraction of GPU memory to be used by the vLLM engine.
export TENSOR_PARALLEL_SIZE="1" # Partitioning model across GPUs (1 here as we have only 1 GPU).
export MAX_NUM_SEQS="16"         # Max concurrent requests vLLM processes in one batch.

# Cloud Run variables
export CLOUD_RUN_CPU_NUM=20
export CLOUD_RUN_MEMORY_GB=80
export CLOUD_RUN_MAX_INSTANCES=1
export CLOUD_RUN_CONCURRENCY=16

ملاحظة حول التحسين لتحقيق الأداء: يمثّل ضبط هذه المتغيّرات توازنًا بين سرعة نقل البيانات ووقت الاستجابة:

MAX_NUM_SEQS مقابل CLOUD_RUN_CONCURRENCY: يجب أن تكون قيمة CLOUD_RUN_CONCURRENCY أكبر من MAX_NUM_SEQS أو مساوية لها على الأقل. لتحقيق الاستخدام الأمثل مع الارتفاعات المفاجئة في عدد الزيارات، اضبطها على قيمة أعلى قليلاً (مثل ضعف القيمة).
ضغط الذاكرة: يستهلك كل من MAX_MODEL_LEN وMAX_NUM_SEQS ذاكرة وحدة معالجة الرسومات لذاكرة التخزين المؤقت KV. إذا واجهت أخطاء نفاد الذاكرة مع أطوال السياق الكبيرة، ننصحك بتقليل MAX_NUM_SEQS.
وقت الاستجابة: يؤدي التزامن الأعلى (MAX_NUM_SEQS) إلى زيادة سرعة معالجة البيانات الإجمالية، ولكن يمكن أن يزيد من وقت استجابة الطلب الفردي.
التحجيم: CLOUD_RUN_MAX_INSTANCES يتيح لك التحجيم الأفقي. إذا كان وقت استجابة المثيل الفردي مقبولاً ولكنك بحاجة إلى سعة إجمالية أكبر، يمكنك زيادة هذه القيمة.

9- النشر على Cloud Run

إعداد سطر الأوامر لحاوية vLLM

يتطلب vLLM الكثير من المَعلمات لتشغيل النماذج الكبيرة بسرعة وكفاءة. سيتم تمرير هذه المَعلمات كarguments إلى الحاوية التي تم نشرها على Cloud Run.

CONTAINER_ARGS=(
    "vllm"
    "serve"
    "${GCS_MODEL_LOCATION}"
    "--served-model-name" "${MODEL_NAME}"
    "--enable-log-requests"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config" "auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser" "gemma4"
    "--reasoning-parser" "gemma4"
    "--dtype" "bfloat16"
    "--quantization" "${QUANTIZATION_TYPE}"
    "--kv-cache-dtype" "${KV_CACHE_DTYPE}"
    "--max-num-seqs" "${MAX_NUM_SEQS}"
    "--gpu-memory-utilization" "${GPU_MEM_UTIL}"
    "--tensor-parallel-size" "${TENSOR_PARALLEL_SIZE}"
    "--load-format" "runai_streamer"
    "--port" "8080"
    "--host" "0.0.0.0"
)

if [[ "${MAX_MODEL_LEN}" != "" ]]; then
    CONTAINER_ARGS+=("--max-model-len" "${MAX_MODEL_LEN}")
fi

export CONTAINER_ARGS_STR="${CONTAINER_ARGS[*]}"

نشر خدمة Cloud Run

شغِّل الأمر التالي لنشر خدمة Cloud Run. لاحظ نوع وحدة معالجة الرسومات (RTX 6000 Pro) والصورة الأساسية (pytorch-vllm-serve:gemma4) والحاجة إلى المصادقة لاستدعاء الخدمة (--no-allow-unauthenticated).

gcloud beta run deploy "${SERVICE_NAME}" \
    --image="us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --region "${GOOGLE_CLOUD_REGION}" \
    --service-account "${SERVICE_ACCOUNT_EMAIL}" \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu="${CLOUD_RUN_CPU_NUM}" \
    --memory="${CLOUD_RUN_MEMORY_GB}Gi" \
    --gpu=1 \
    --gpu-type=nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances ${CLOUD_RUN_MAX_INSTANCES} \
    --concurrency ${CLOUD_RUN_CONCURRENCY} \
    --network ${VPC_NETWORK} \
    --subnet ${VPC_SUBNET} \
    --vpc-egress all-traffic \
    --set-env-vars "MODEL_NAME=${MODEL_NAME}" \
    --set-env-vars "GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}" \
    --set-env-vars "GOOGLE_CLOUD_REGION=${GOOGLE_CLOUD_REGION}" \
    --port=8080 \
    --timeout=3600 \
    --cpu-boost \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=40,timeoutSeconds=10,periodSeconds=15 \
    --command "bash" \
    --args="^;^-c;${CONTAINER_ARGS_STR}"

سيستغرق التفعيل بضع دقائق. بعد اكتمال النشر، ستتوفّر لديك بيئة تستخدم وحدة معالجة الرسومات لعرض Gemma 4 باستخدام بنية تحتية بدون خادم مع التحجيم التلقائي، بما في ذلك التحجيم إلى صفر (بدون زيارات، بدون تكلفة).

10- اختبار الخدمة

بعد النشر، يمكنك التفاعل مع نموذج Gemma 4 باستخدام واجهة برمجة التطبيقات المتوافقة مع vLLM OpenAI.

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

استردِد عنوان URL لخدمة Cloud Run التي تم نشرها.

SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --project "${GOOGLE_CLOUD_PROJECT}" --region "${GOOGLE_CLOUD_REGION}" --format 'value(status.url)')
echo "Service URL: $SERVICE_URL"

تشغيل الاستنتاج

أرسِل طلبًا إلى النموذج باستخدام curl.

curl -s "$SERVICE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -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
}' | jq -r '.choices[0].message.content'

11- إنشاء وكيل بيانات باستخدام حزمة Agent Development Kit

كتابة رمز الوكيل

من Cloud Shell Terminal أو جهازك المحلي، أنشئ دليلًا رئيسيًا لتطبيقك المستند إلى الوكلاء:

mkdir data_agent

افتح Cloud Shell Editor أو محرِّر نصوص آخر، وأنشئ agent.py في الدليل data_agent:

data_agent/
    agent.py

agent.py

import os
import subprocess

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

import google.auth
from google.auth.transport.requests import Request
from google.oauth2 import id_token

# Fetch Application Default Credentials (ADC)
application_default_credentials, project_id = google.auth.default()
application_default_credentials.refresh(Request())

# Retrieve Google Cloud project to use.
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", project_id)
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set.")

if os.getenv("GOOGLE_GENAI_USE_ENTERPRISE", "").lower() not in ["true", "1"]:
    # Using Cloud Run for hosting LLM with LiteLLM wrapper
    api_base = os.getenv(
        "API_BASE",
        os.environ.get("OPENAI_API_BASE", "")
    ).rstrip("/")
    if not api_base:
        raise ValueError("API_BASE environment variable is not set")
    if not api_base.endswith("/v1"):
        api_base += "/v1"

    model_name = os.getenv("MODEL_NAME")
    if not model_name:
        raise ValueError("MODEL_NAME environment variable is not set")
    # Format required by LiteLLM for OpenAI-compatible APIs
    model_name=f"openai/{model_name}"

    # To access the model's Cloud Run service,
    # we need an identity token.
    try:
        model_service_token_string = id_token.fetch_id_token(Request(), api_base)
    except Exception as e:
        # Fallback with using gcloud CLI to get the identity token
        model_service_token_string = subprocess.check_output(
            f"gcloud auth print-identity-token -q",
            shell=True
        ).decode().strip()

    # Gemma 4 in vLLM requires additional parameters in the request body.
    extra_body={
        "chat_template_kwargs": {
            "enable_thinking": True
        },
        "skip_special_tokens": False
    }
    # Configure the model with LiteLLM and an OpenAI-compatible endpoint
    custom_model = LiteLlm(
      model=model_name,
      base_url=api_base,
      api_key=model_service_token_string,
      extra_body=extra_body
    )
    model = custom_model
else:
    # Gemini API in Agent Platform fallback
    model = "gemini-3.5-flash-lite"

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers={
            "Authorization": f"Bearer {application_default_credentials.token}",
            "x-goog-user-project": project_id, # This is used for billing
        },
        tool_filter=[
            'get_dataset_info',
            'list_table_ids',
            'get_table_info',
            # Using readonly is a security measure to prevent accidental data modification.
            'execute_sql_readonly',
        ]
    )
)

# Configure the agent

system_instruction = f"""
You are a helpful assistant that can answer questions about data in BigQuery.
To answer the user's question, use data you have access to by using tools `list_table_ids` and `get_table_info`.
Your data is in `bigquery-public-data.new_york_citibike` dataset
   (Citi Bike trips and stations in the NYC area.
    It includes trip records starting from September 2013 and is updated daily.)

Plan of action:
0. ALWAYS start by analyzing dataset.
1. Analyze your data, investigate schema and dimensions by querying distrinct values of columns using `execute_sql_readonly`.
   Output information about tables, columns, their data types and sets of values (for dimensions).
   Note which columns can be joined or used in aggregations/filters, and what type conversion may be needed for joining or aggregating.
   DO NOT MAKE ASSUMPTIONS ABOUT DATA (structure, type, values, relationships) BASED ON YOUR PRIOR KNOWLEDGE. ALWAYS VERIFY YOUR ASSUMPTIONS.
2. Understand and interpret the user's question.
3. Formulate a plan to answer the user's question.
4. Write a SQL query to retrieve relevant data in necessary form.
   This is where you must pay extra attention to column types and dimensions' sets of values.
5. Retrieve data by generating BigQuery SQL and using `execute_sql_readonly`.
   Always use Dry Run to verify SQL correctness.
   Use `{project_id}` to run BigQuery queries (`project_id` parameter of `execute_sql_readonly`).

Do not use LaTeX in your responses. When giving a final answer, use Markdown.
"""

root_agent = LlmAgent(
    model=model,
    name="data_agent",
    instruction=system_instruction,
    description="A helpful assistant that can answer questions using NYC Citibike data.",
    tools=[bigquery_toolset]
)

تتطلب حزمة ADK أيضًا __init__.py وrequirements.txt للنشر:

يجب أن يحتوي __init__.py على عملية استيراد للوكيل.
يسرد requirements.txt التبعيات في Python: google-adk لحزمة Agent Development Kit، وlitellm لمكتبة LiteLLM التي تستخدمها حزمة ADK لاستخدام نماذج غير Gemini، وmcp لبرنامج بروتوكول سياق النموذج.

تساعدك هذه الأوامر في إنشاء __init__.py وrequirements.txt:

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nlitellm\nmcp==1.29.*" > data_agent/requirements.txt

يجب أن تبدو بنية المجلد النهائية على النحو التالي:

data_agent/
    __init__.py
    agent.py
    requirements.txt

تجربة الوكيل محليًا

تتضمّن حزمة Agent Development Kit أداة سطر الأوامر adk، وهي واجهة طرفية تفاعلية لاختبار الوكلاء. تفيد هذه الأداة في الاختبار السريع والتفاعلات المبرمَجة وخطوط أنابيب CI/CD. إحدى الميزات التي توفّرها هي adk web - واجهة ADK Web - وهي طريقة بسيطة لتطوير الوكلاء وتصحيح أخطائهم بشكل تفاعلي. لا يُقصد استخدام ADK Web في عمليات النشر في مرحلة الإنتاج، ولكنها تسهّل تجربة الوكيل.

يشغِّل هذا الأمر adk web الذي يبدأ خادم ويب محليًا على المنفذ 8080.

export API_BASE=$(gcloud run services describe $SERVICE_NAME \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)')

# If Gemma 4 deployment failed, use Gemini fallback
if [[ "${API_BASE}" == "" ]]; then
  export GOOGLE_GENAI_USE_ENTERPRISE=true
else
  export GOOGLE_GENAI_USE_ENTERPRISE=false
fi

uv tool run --with litellm,"mcp==1.29.*" --from "google-adk[mcp]==2.4.*" adk web --allow_origins="*" --port 8080 .

بعد بدء الخدمة، افتح صفحة ADK Web المحلية: http://localhost:8080/.

إذا كنت تستخدم Google Cloud Shell، انقر على "معاينة الويب" .

في واجهة مستخدم ADK Web، اطلب من الوكيل بيانات يمكنه الوصول إليها:

What data do you have?

سيستخدم رمز الوكيل نموذج Gemma 4 الذي تم نشره على Cloud Run. سيستخدم النموذج أدوات BigQuery MCP لاستكشاف مجموعة بيانات citibike. سيقدّم لك نظرة عامة على الجداول والحقول المتاحة في مجموعة بيانات Citibike.

12- نشر الوكيل على Cloud Run

سينشر هذا الأمر الوكيل على Cloud Run باستخدام ADK CLI.

export API_BASE=$(gcloud run services describe $SERVICE_NAME \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)')

# If Gemma 4 deployment failed, use Gemini fallback
if [[ "${API_BASE}" == "" ]]; then
  export GOOGLE_GENAI_USE_ENTERPRISE=true
else
  export GOOGLE_GENAI_USE_ENTERPRISE=false
fi

uv tool run --from google-adk==2.4.0 \
  adk deploy cloud_run \
      --with_ui \
      --project $GOOGLE_CLOUD_PROJECT \
      --region $GOOGLE_CLOUD_REGION \
      --service_name gemma4-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=${GOOGLE_GENAI_USE_ENTERPRISE},MODEL_NAME="${MODEL_NAME}",API_BASE="${API_BASE}",GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT}"

تجربة الوكيل

استخدَمنا الخيار --with_ui لنشر الوكيل. وقد نشر الوكيل باستخدام واجهة ADK Web.

افتح عنوان URL للوكيل في متصفّح الويب. عرضه الأمر adk deploy، ويمكنك أيضًا استرداد عنوان URL عن طريق تشغيل الأمر gcloud run services:

gcloud run services describe gemma4-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'

اطلب من الوكيل الاستدلال على بيانات Citibike المتاحة:

We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

يجب أن يستكشف الوكيل مجموعة بيانات Citibike باستخدام خادم BigQuery MCP، ويشغِّل بعض طلبات SQL، ويعرض قائمة بـ 3 محطات citibike.

13- تهانينا!

تهانينا على إكمال الدرس التطبيقي حول الترميز.

ننصحك بمراجعة مستندات Cloud Run.

المواضيع التي تحدثنا عنها

كيفية نشر نموذج Gemma 4 على وحدة معالجة الرسومات RTX 6000 Pro في Cloud Run
كيفية ضبط Direct VPC Egress وvLLM model streaming مع Cloud Storage لبدء تشغيل الخدمة بشكل أسرع
كيفية إنشاء وكيل ذكاء اصطناعي ونشره باستخدام حزمة Agent Development Kit التي تستخدم نموذج Gemma 4 اللغوي الكبير وخادم BigQuery MCP

14- تَنظيم

لتجنُّب تحصيل رسوم من حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، يمكنك إما حذف المشروع أو حذف الموارد الفردية.

الخيار 1: حذف الموارد

حذف خدمات Cloud Run

gcloud run services delete gemma4-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet
gcloud run services delete $SERVICE_NAME \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

حذف حساب الخدمة

gcloud iam service-accounts delete \
      ${SERVICE_ACCOUNT_EMAIL} \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --quiet

حذف حزمة Cloud Storage

gcloud storage rm --recursive gs://$MODEL_CACHE_BUCKET

حذف شبكة VPC والشبكة الفرعية

gcloud compute networks subnets delete $VPC_SUBNET \
    --region "${GOOGLE_CLOUD_REGION}" \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --quiet

gcloud compute networks delete $VPC_NETWORK \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --quiet

الخيار 2: حذف المشروع

لحذف المشروع بأكمله، انتقِل إلى إدارة الموارد، واختَر المشروع الذي أنشأته في الخطوة 2، ثم انقر على "حذف". إذا حذفت المشروع، عليك تغيير المشاريع في Cloud SDK. يمكنك الاطّلاع على قائمة بجميع المشاريع المتاحة عن طريق تشغيل gcloud projects list. إذا كنت تريد استخدام سطر الأوامر، يمكنك أيضًا استخدام هذا الأمر:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}