این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ساخت و استقرار عامل‌های هوش مصنوعی با Gemma 4 و سرور BigQuery MCP در Cloud Run

۱. مقدمه

نمای کلی

آنچه یاد خواهید گرفت

نحوه استقرار مدل Gemma 4 روی پردازنده گرافیکی Cloud Run RTX 6000 Pro با vLLM
نحوه ایجاد یک عامل هوش مصنوعی با استفاده از کیت توسعه عامل (ADK) و استفاده از Gemma 4 با آن.
نحوه دسترسی به داده‌های ساختاریافته در BigQuery با استفاده از سرور BigQuery MCP به عوامل هوش مصنوعی.

Gemma 4 خانواده‌ای از مدل‌های وزن باز تحت لیسانس آپاچی ۲ از Google DeepMind است. این مدل‌ها چندوجهی، چندزبانه، دارای استدلال و معماری کارآمد هستند.

Cloud Run یک محیط بدون سرور برای کانتینرها با پشتیبانی از پردازنده‌های گرافیکی (GPU) است.

کیت توسعه عامل (ADK) یک چارچوب توسعه عامل متن‌باز است که به شما امکان می‌دهد عامل‌های هوش مصنوعی قابل اعتمادی را در مقیاس سازمانی بسازید، اشکال‌زدایی کنید و مستقر کنید.

بیگ‌کوئری (BigQuery) یک انبار داده سازمانی کاملاً مدیریت‌شده و بدون سرور است که به شما امکان می‌دهد مجموعه داده‌های عظیم را ذخیره، پرس‌وجو و تجزیه و تحلیل کنید.

پروتکل زمینه مدل (MCP) نحوه اتصال مدل‌های زبانی بزرگ (LLM) و برنامه‌های کاربردی یا عامل‌های هوش مصنوعی به منابع داده خارجی را استاندارد می‌کند. سرورهای MCP به شما امکان می‌دهند از ابزارها، منابع و اعلان‌های آنها برای انجام اقدامات و دریافت داده‌های به‌روز شده از سرویس backend آنها استفاده کنید. سرور MCP BigQuery به عامل‌های هوش مصنوعی شما روشی مستقیم و ایمن برای تجزیه و تحلیل داده‌ها در BigQuery می‌دهد. این سرور MCP کاملاً مدیریت‌شده، سربار مدیریتی را حذف می‌کند و شما را قادر می‌سازد تا بر توسعه عامل‌های هوشمند تمرکز کنید.

۲. تنظیمات و الزامات

از تنظیم پروژه پیش‌فرض و منطقه Cloud Run شروع کنید:

<YOUR_PROJECT_ID> را با شناسه پروژه گوگل کلود خود جایگزین کنید. می‌توانید با کلیک روی نام پروژه در بالای کنسول و مشاهده شناسه پروژه مرتبط با نام پروژه، آن را پیدا کنید.

PROJECT_ID=<YOUR_PROJECT_ID>

# set the project
gcloud config set project $PROJECT_ID

<YOUR_CLOUD_RUN_REGION> را با یکی از مناطق ابری زیر جایگزین کنید:

us-central1
asia-southeast1

# set Cloud Run region
REGION=<YOUR_CLOUD_RUN_REGION>

منطقه را تنظیم کنید:

gcloud config set run/region $REGION && echo $REGION > lab2rgn.txt

در اینجا متغیرهای محیطی که در سراسر این آزمایشگاه کد استفاده خواهند شد، آورده شده است. می‌توانید این موارد را در یک فایل محیطی ذخیره کرده و آن را "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"

API های مورد نیاز برای این Codelab را فعال کنید. تغییرات API ممکن است 2-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

۳. ایجاد حساب کاربری سرویس

اگر هنگام ایجاد سرویس یا کار 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"

۴. راه‌اندازی فضای ذخیره‌سازی ابری

یک مخزن ذخیره‌سازی ابری برای ذخیره وزن‌های مدل ایجاد کنید. این کار به شما امکان می‌دهد هر بار که Cloud Run یک نمونه سرویس را شروع می‌کند، از Direct VPC Egress برای دانلود سریع‌تر وزن‌های مدل استفاده کنید.

همراه با ویژگی 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}"

۵. بازیابی و ذخیره وزن‌های مدل

در مرحله بعد، مدل Gemma 4 را در فضای ذخیره‌سازی ابری خود دانلود کنید. وزن مدل‌ها ده‌ها گیگابایت است و دانلود آنها در ابتدا روی دستگاه محلی یا Cloud Shell شما ممکن است امکان‌پذیر نباشد. در عوض، از Cloud Build با فضای ذخیره‌سازی کافی برای نگهداری وزن‌های مدل استفاده کنید.

کپی کردن وزن‌های مدل از یک مخزن ذخیره‌سازی ابری مشترک

گوگل کلود میزبان یک سطل ذخیره‌سازی ابری با دسترسی عمومی و وزن‌های مدل 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

۶. پیکربندی شبکه برای خروجی مستقیم VPC

پیکربندی Direct VPC Egress نیاز به ایجاد یک شبکه و زیرشبکه با دسترسی خصوصی گوگل (Private Google Access) فعال دارد.

این به سرویس‌های Cloud Run اجازه می‌دهد تا به مجموعه‌ای از آدرس‌های IP خارجی که توسط APIها و سرویس‌های Google، از جمله 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"

۷. پیکربندی سیاست دسترسی به حساب سرویس

حساب کاربری سرویس Cloud Run برای دسترسی به وزن‌های مدل در Storage Bucket که ایجاد کرده‌اید، به مجوز نیاز دارد.

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

۸. مقداردهی اولیه متغیرهای پیکربندی

متغیرها را هم برای موتور استنتاج 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 باشد. برای استفاده بهینه با افزایش ناگهانی ترافیک، آن را کمی بالاتر (مثلاً ۲x) تنظیم کنید.
فشار بر حافظه : MAX_MODEL_LEN و MAX_NUM_SEQS هر دو حافظه GPU را برای حافظه پنهان KV مصرف می‌کنند. اگر با خطاهای کمبود حافظه (OOM) با طول متن زیاد مواجه شدید، کاهش MAX_NUM_SEQS را در نظر بگیرید.
تأخیر : همزمانی بالاتر ( MAX_NUM_SEQS ) کل توان عملیاتی را افزایش می‌دهد اما می‌تواند تأخیر درخواست‌های منفرد را نیز افزایش دهد.
مقیاس‌بندی : CLOUD_RUN_MAX_INSTANCES به شما امکان می‌دهد تا به صورت افقی مقیاس‌بندی کنید. اگر تأخیر تک نمونه‌ای شما قابل قبول است اما به ظرفیت کلی بیشتری نیاز دارید، این مقدار را افزایش دهید.

۹. استقرار در Cloud Run

آماده‌سازی خط فرمان کانتینر vLLM

vLLM برای اجرای سریع و کارآمد مدل‌های بزرگ به پارامترهای زیادی نیاز دارد. این پارامترها به عنوان آرگومان به کانتینر مستقر در 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}" \
    --labels dev-tutorial=codelab-cloud-run-adk-bq-mcp \
    --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}"

استقرار این کار چند دقیقه طول می‌کشد. پس از اتمام، شما یک محیط مبتنی بر GPU خواهید داشت که Gemma 4 را با استفاده از زیرساخت بدون سرور و با قابلیت مقیاس‌پذیری خودکار از جمله مقیاس‌پذیری تا صفر (بدون ترافیک، بدون هزینه) ارائه می‌دهد.

۱۰. سرویس را آزمایش کنید

پس از استقرار، می‌توانید با استفاده از API سازگار با vLLM OpenAI با مدل Gemma 4 خود تعامل داشته باشید.

دریافت آدرس اینترنتی سرویس

آدرس اینترنتی سرویس 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'

۱۱. با استفاده از کیت توسعه عامل، یک عامل داده ایجاد کنید

نوشتن کد عامل

از ترمینال Cloud Shell یا ترمینال محلی خود، یک دایرکتوری ریشه برای برنامه agentic خود ایجاد کنید:

mkdir data_agent

ویرایشگر Cloud Shell یا ویرایشگر متن دیگری را باز کنید و agent.py در دایرکتوری data_agent ایجاد کنید:

data_agent/
    agent.py

عامل.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 باید یک import برای عامل داشته باشد.
requirements.txt وابستگی‌های پایتون را فهرست می‌کند: google-adk برای کیت توسعه عامل، 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 CLI - یک رابط ترمینال تعاملی برای آزمایش عامل‌های شما - ارائه می‌شود. این ابزار برای آزمایش سریع، تعاملات اسکریپت‌نویسی شده و خطوط لوله CI/CD مفید است. یکی از ویژگی‌هایی که ارائه می‌دهد adk web - رابط وب ADK - است که روشی ساده برای توسعه و اشکال‌زدایی تعاملی عامل‌های شما محسوب می‌شود. ADK Web برای استفاده در استقرارهای تولید در نظر گرفته نشده است، اما امتحان کردن عامل را بسیار ساده می‌کند.

این دستور adk web را اجرا می‌کند که یک وب سرور محلی را روی پورت ۸۰۸۰ راه‌اندازی می‌کند.

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 را باز کنید: http://localhost:8080/.

اگر از Google Cloud Shell استفاده می‌کنید ، روی پیش‌نمایش وب کلیک کنید. دکمه

در رابط کاربری وب ADK، از نماینده در مورد داده‌هایی که به آنها دسترسی دارد، سوال کنید:

What data do you have?

کد عامل از مدل Gemma 4 که در Cloud Run مستقر شده است، استفاده خواهد کرد. این مدل از ابزارهای BigQuery MCP برای کاوش در مجموعه داده‌های citibike استفاده خواهد کرد. این مدل، مروری بر جداول و فیلدهای موجود در مجموعه داده‌های Citibike به شما ارائه می‌دهد.

۱۲. عامل را در Cloud Run مستقر کنید

این دستور، عامل را با استفاده از ADK CLI در Cloud Run مستقر می‌کند.

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 \
      -- \
      --labels dev-tutorial=codelab-cloud-run-adk-bq-mcp \
      --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 مستقر می‌کند.

آدرس اینترنتی عامل را در مرورگر وب باز کنید. دستور adk deploy آن را برگرداند، و همچنین می‌توانید با اجرای دستور running gcloud run services آدرس اینترنتی را بازیابی کنید:

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

از نماینده بخواهید که در مورد داده‌های موجود سیتی‌بایک توضیح دهد:

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 اجرا کند و لیستی از ۳ ایستگاه citibike را برگرداند.

۱۳. تبریک می‌گویم!

تبریک می‌گویم که آزمایشگاه کد را تمام کردید!

توصیه می‌کنیم مستندات Cloud Run را بررسی کنید.

آنچه ما پوشش داده‌ایم

نحوه‌ی پیاده‌سازی مدل Gemma 4 روی پردازنده‌ی گرافیکی Cloud Run RTX 6000 Pro
نحوه پیکربندی Direct VPC Egress و پخش مدل vLLM با Cloud Storage برای راه‌اندازی سریع‌تر سرویس.
نحوه ایجاد و استقرار یک عامل هوش مصنوعی با کیت توسعه عامل که از Gemma 4 LLM و سرور BigQuery MCP استفاده می‌کند.

۱۴. تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب گوگل کلود خود برای منابع استفاده شده در این آموزش، می‌توانید پروژه یا منابع تکی را حذف کنید.

گزینه ۱: حذف منابع

سرویس‌های 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

سطل ذخیره‌سازی ابری را حذف کنید

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

گزینه ۲: حذف پروژه

برای حذف کل پروژه، به مدیریت منابع بروید، پروژه‌ای را که در مرحله ۲ ایجاد کرده‌اید انتخاب کنید و حذف را انتخاب کنید. اگر پروژه را حذف کنید، باید پروژه‌ها را در Cloud SDK خود تغییر دهید. می‌توانید با اجرای gcloud projects list لیست تمام پروژه‌های موجود را مشاهده کنید. اگر می‌خواهید از خط فرمان استفاده کنید، می‌توانید از این دستور نیز استفاده کنید:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}