এই পৃষ্ঠাটি Cloud Translation API অনুবাদ করেছে।

ক্লাউড রানে জেমা ৪ এবং বিগকোয়েরি এমসিপি সার্ভার ব্যবহার করে এআই এজেন্ট তৈরি ও স্থাপন করুন

১. ভূমিকা

সংক্ষিপ্ত বিবরণ

আপনি যা শিখবেন

vLLM ব্যবহার করে Cloud Run RTX 6000 Pro GPU-তে কীভাবে একটি Gemma 4 মডেল ডেপ্লয় করবেন
এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে কীভাবে একটি এআই এজেন্ট তৈরি করবেন এবং এর সাথে জেমা ৪ ব্যবহার করবেন।
BigQuery MCP সার্ভার ব্যবহার করে কীভাবে AI এজেন্টদের BigQuery-এর স্ট্রাকচার্ড ডেটাতে অ্যাক্সেস দেওয়া যায়।

জেমা ৪ হলো গুগল ডিপমাইন্ডের অ্যাপাচি ২-লাইসেন্সপ্রাপ্ত ওপেন ওয়েট মডেলের একটি পরিবার। এই মডেলগুলো মাল্টিমোডাল, বহুভাষিক, রিজনিং সুবিধাযুক্ত এবং একটি দক্ষ আর্কিটেকচারের অধিকারী।

ক্লাউড রান হলো জিপিইউ সমর্থিত কন্টেইনারের জন্য একটি সার্ভারবিহীন পরিবেশ।

এজেন্ট ডেভেলপমেন্ট কিট (ADK) হলো একটি ওপেন-সোর্স এজেন্ট ডেভেলপমেন্ট ফ্রেমওয়ার্ক যা আপনাকে এন্টারপ্রাইজ স্কেলে নির্ভরযোগ্য এআই এজেন্ট তৈরি, ডিবাগ এবং স্থাপন করতে দেয়।

BigQuery হলো একটি সম্পূর্ণভাবে পরিচালিত, সার্ভারবিহীন এন্টারপ্রাইজ ডেটা ওয়্যারহাউস যা আপনাকে বিশাল ডেটাসেট সংরক্ষণ, কোয়েরি এবং বিশ্লেষণ করতে দেয়।

মডেল কনটেক্সট প্রোটোকল (MCP) বৃহৎ ল্যাঙ্গুয়েজ মডেল (LLM) এবং এআই অ্যাপ্লিকেশন বা এজেন্টরা কীভাবে বাহ্যিক ডেটা উৎসের সাথে সংযোগ স্থাপন করে, তার একটি মান নির্ধারণ করে। MCP সার্ভার আপনাকে তাদের টুলস, রিসোর্স এবং প্রম্পট ব্যবহার করে বিভিন্ন পদক্ষেপ নিতে এবং তাদের ব্যাকএন্ড পরিষেবা থেকে হালনাগাদ ডেটা পেতে সাহায্য করে। BigQuery MCP সার্ভার আপনার এআই এজেন্টদের BigQuery-তে ডেটা বিশ্লেষণ করার জন্য একটি সরাসরি ও নিরাপদ উপায় প্রদান করে। এই সম্পূর্ণভাবে পরিচালিত MCP সার্ভারটি ব্যবস্থাপনার বাড়তি চাপ দূর করে, যার ফলে আপনি ইন্টেলিজেন্ট এজেন্ট তৈরির দিকে মনোযোগ দিতে পারেন।

দ্রষ্টব্য: এই কোডল্যাবটিতে জেমা ৪ ৩১বি ইন্সট্রাকশন-টিউনড মডেল ব্যবহার করা হয়েছে। কন্টেইনার চালু হওয়ার সময় ক্লাউড স্টোরেজ থেকে মডেল লোড হওয়ার সময় কমানোর জন্য কীভাবে রান:এআই মডেল স্ট্রিমার এবং ডাইরেক্ট ভিপিসি ইগ্রেস ব্যবহার করতে হয়, তা এই কোডল্যাবে দেখানো হয়েছে। আরও তথ্যের জন্য, জিপিইউ বেস্ট প্র্যাকটিসেস গাইড দেখুন।

২. সেটআপ এবং প্রয়োজনীয়তা

ডিফল্ট প্রজেক্ট এবং ক্লাউড রান রিজিয়ন সেট করা থেকে শুরু করুন:

<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

এই কোডল্যাব জুড়ে যে এনভায়রনমেন্ট ভেরিয়েবলগুলো ব্যবহার করা হবে, সেগুলো এখানে দেওয়া হলো। আপনি এগুলো একটি এনভায়রনমেন্ট ফাইলে সেভ করে "সোর্স" করতে পারেন। আপনার প্রজেক্ট আইডি এবং ঐচ্ছিকভাবে অঞ্চলের মান সঠিকভাবে সেট করতে ভুলবেন না।

# 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"

এই কোডল্যাবের জন্য প্রয়োজনীয় এপিআইগুলো সক্রিয় করুন। এপিআই-এর পরিবর্তন কার্যকর হতে ২-৩ মিনিট সময় লাগতে পারে।

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

৩. পরিষেবা অ্যাকাউন্ট তৈরি করুন

ক্লাউড রান সার্ভিস বা জব তৈরি করার সময় আপনি যদি কোনো সার্ভিস অ্যাকাউন্ট নির্দিষ্ট না করেন, তাহলে ক্লাউড রান কম্পিউট ইঞ্জিনের ডিফল্ট সার্ভিস অ্যাকাউন্ট ব্যবহার করে। সার্ভিসটিকে অতিরিক্ত অনুমতিসহ চালানো এড়াতে ক্লাউড রান সার্ভিসের জন্য একটি পৃথক সার্ভিস অ্যাকাউন্ট ব্যবহার করার পরামর্শ দেওয়া হয়।

ক্লাউড রান পরিষেবার জন্য পরিষেবা অ্যাকাউন্ট তৈরি করুন

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

৪. ক্লাউড স্টোরেজ সেটআপ করুন

মডেল ওয়েটগুলো সংরক্ষণ করার জন্য একটি ক্লাউড স্টোরেজ বাকেট তৈরি করুন। এর ফলে, প্রতিবার ক্লাউড রান যখন কোনো সার্ভিস ইনস্ট্যান্স চালু করবে, তখন ডিরেক্ট ভিপিসি ইগ্রেস ব্যবহার করে আরও দ্রুত মডেল ওয়েটগুলো ডাউনলোড করা যাবে।

vLLM-এ থাকা Run:ai Model Streamer ফিচারের সাথে মিলিতভাবে এটি মডেল লোড হওয়ার সময় উল্লেখযোগ্যভাবে কমিয়ে দেয়।

একটি বালতি তৈরি করুন

নিশ্চিত করুন যে এটি ক্লাউড রান পরিষেবার সাথে একই স্থানে অবস্থিত একটি একক-অঞ্চলের বাকেট।

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

৫. মডেলের ওজন পুনরুদ্ধার এবং ক্যাশ করুন

এরপর, জেমা ৪ মডেলটি আপনার ক্লাউড স্টোরেজ বাকেটে ডাউনলোড করুন। মডেলের ওয়েটগুলো কয়েক ডজন গিগাবাইটের হয়, এবং প্রথমে সেগুলো আপনার লোকাল মেশিনে বা ক্লাউড শেলে ডাউনলোড করা সম্ভব নাও হতে পারে। এর পরিবর্তে, মডেলের ওয়েটগুলো রাখার জন্য পর্যাপ্ত স্টোরেজসহ ক্লাউড বিল্ড ব্যবহার করুন।

একটি শেয়ার করা ক্লাউড স্টোরেজ বাকেট থেকে মডেলের ওজন কপি করুন

গুগল ক্লাউড জেমা ৪ মডেলের ওয়েটসহ একটি সর্বজনীনভাবে প্রবেশযোগ্য ক্লাউড স্টোরেজ বাকেট হোস্ট করে।

আপনি যদি us- অঞ্চলের কোনো একটি ব্যবহার করেন, তাহলে মডেলের ওয়েট কপি করার পরিবর্তে, আপনি সহজেই GCS_MODEL_LOCATION পরিবর্তন করে পাবলিক ক্যাশ লোকেশন নির্দেশ করতে পারেন। উদাহরণস্বরূপ, gemma-4-31B-it মডেলের জন্য, export GCS_MODEL_LOCATION="gs://vertex-model-garden-public-us/gemma4/gemma-4-31B-it" সেট করুন (যদি আপনি .env বা env.sh মতো কোনো এনভায়রনমেন্ট ফাইল ব্যবহার করেন, তবে সেটি পরিবর্তন করতে ভুলবেন না)।

সেগুলোকে আপনার স্টোরেজ বাকেটে কপি করতে, এই কমান্ডটি চালান:

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

৬. সরাসরি ভিপিসি থেকে বহির্গমনের জন্য নেটওয়ার্কিং কনফিগার করুন

ডাইরেক্ট ভিপিসি ইগ্রেস কনফিগারেশনের জন্য প্রাইভেট গুগল অ্যাক্সেস সক্রিয় করে একটি নেটওয়ার্ক ও সাবনেট তৈরি করতে হয়।

এর ফলে ক্লাউড রান পরিষেবাগুলি গুগল এপিআই এবং ক্লাউড স্টোরেজ সহ অন্যান্য পরিষেবাগুলিতে ব্যবহৃত বাহ্যিক আইপি ঠিকানাগুলির সাথে সংযোগ স্থাপন করতে পারে।

একটি নেটওয়ার্ক তৈরি করুন

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"

৭. পরিষেবা অ্যাকাউন্ট অ্যাক্সেস নীতি কনফিগার করুন

আপনার তৈরি করা স্টোরেজ বাকেটে থাকা মডেল ওয়েটগুলো অ্যাক্সেস করার জন্য ক্লাউড রান সার্ভিস অ্যাকাউন্টের অনুমতি প্রয়োজন।

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 ইনফারেন্স ইঞ্জিন এবং ক্লাউড রান সার্ভিস উভয়ের জন্য ভেরিয়েবলগুলো নির্ধারণ করুন।

# 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 ক্যাশের জন্য GPU মেমোরি ব্যবহার করে। যদি বড় কনটেক্সট লেংথের কারণে আপনি আউট-অফ-মেমোরি (OOM) এররের সম্মুখীন হন, তবে MAX_NUM_SEQS কমানোর কথা বিবেচনা করুন।
লেটেন্সি : উচ্চতর কনকারেন্সি ( MAX_NUM_SEQS ) মোট থ্রুপুট বাড়ায়, কিন্তু এটি প্রতিটি অনুরোধের লেটেন্সি বাড়িয়ে দিতে পারে।
স্কেলিং : CLOUD_RUN_MAX_INSTANCES আপনাকে হরাইজন্টালি স্কেল করতে দেয়। যদি আপনার একক-ইনস্ট্যান্স ল্যাটেন্সি গ্রহণযোগ্য হয় কিন্তু আপনার আরও মোট ধারণক্ষমতা প্রয়োজন হয়, তাহলে এই মানটি বাড়িয়ে দিন।

৯. ক্লাউড রান-এ ডেপ্লয় করুন

vLLM কন্টেইনার কমান্ড লাইন প্রস্তুত করুন

বড় মডেল দ্রুত ও দক্ষতার সাথে চালানোর জন্য vLLM-এর প্রচুর প্যারামিটার প্রয়োজন হয়। এই প্যারামিটারগুলো ক্লাউড রান-এ ডেপ্লয় করা কন্টেইনারে আর্গুমেন্ট হিসেবে পাঠানো হবে।

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

ক্লাউড রান পরিষেবা স্থাপন করুন

ক্লাউড রান সার্ভিসটি ডেপ্লয় করতে নিম্নলিখিত কমান্ডটি চালান। জিপিইউ-এর ধরন ( 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 পরিবেশন করবে এবং এতে অটোস্কেলিং সুবিধা থাকবে, যার মধ্যে স্কেল টু জিরো (কোনো ট্র্যাফিক নেই, কোনো খরচ নেই) অন্তর্ভুক্ত।

১০. পরিষেবাটি পরীক্ষা করুন

একবার স্থাপন করা হলে, আপনি vLLM OpenAI-সামঞ্জস্যপূর্ণ API ব্যবহার করে আপনার Gemma 4 মডেলের সাথে যোগাযোগ করতে পারবেন।

পরিষেবার URL পান

আপনার ডেপ্লয় করা ক্লাউড রান সার্ভিসের URL-টি পুনরুদ্ধার করুন।

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'

১১. এজেন্ট ডেভেলপমেন্ট কিট ব্যবহার করে একটি ডেটা এজেন্ট তৈরি করুন।

এজেন্টের কোড লিখুন

ক্লাউড শেল টার্মিনাল অথবা আপনার লোকাল টার্মিনাল থেকে, আপনার agentic অ্যাপের জন্য রুট ডিরেক্টরি তৈরি করুন:

mkdir data_agent

Cloud Shell Editor বা অন্য কোনো টেক্সট এডিটর খুলুন এবং data_agent ডিরেক্টরিতে agent.py তৈরি করুন:

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 ফাইলে পাইথন নির্ভরতাগুলোর তালিকা দেওয়া আছে: এজেন্ট ডেভেলপমেন্ট কিট (Agent Development Kit)-এর জন্য google-adk , নন-জেমিনি মডেল ব্যবহারের জন্য ADK-এর সহায়ক LiteLLM লাইব্রেরির জন্য litellm , এবং মডেল কনটেক্সট প্রোটোকল (Model Context Protocol) ক্লায়েন্টের জন্য 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

স্থানীয় এজেন্টের সাথে যোগাযোগ করুন।

এজেন্ট ডেভেলপমেন্ট কিটের সাথে adk CLI টুল আসে – যা আপনার এজেন্ট পরীক্ষা করার জন্য একটি ইন্টারেক্টিভ টার্মিনাল ইন্টারফেস। এটি দ্রুত পরীক্ষা, স্ক্রিপ্টেড ইন্টারঅ্যাকশন এবং CI/CD পাইপলাইনের জন্য উপযোগী। এর অন্যতম একটি ফিচার হলো adk web – ADK ওয়েব ইন্টারফেস – যা আপনার এজেন্টগুলোকে ইন্টারেক্টিভভাবে ডেভেলপ এবং ডিবাগ করার একটি সহজ উপায়। ADK ওয়েব প্রোডাকশন ডেপ্লয়মেন্টে ব্যবহারের জন্য নয়, তবে এটি এজেন্ট পরীক্ষা করাকে অত্যন্ত সহজ করে তোলে।

এই কমান্ডটি 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/।

আপনি যদি গুগল ক্লাউড শেল ব্যবহার করেন , তাহলে ওয়েব প্রিভিউ-তে ক্লিক করুন। বোতাম।

ADK ওয়েব UI-তে, এজেন্টকে তার অ্যাক্সেস আছে এমন ডেটা সম্পর্কে জিজ্ঞাসা করুন:

What data do you have?

এজেন্ট কোডটি ক্লাউড রান-এ ডেপ্লয় করা জেমা ৪ মডেল ব্যবহার করবে। মডেলটি সিটিবাইক ডেটাসেটটি অন্বেষণ করার জন্য বিগকোয়েরি এমসিপি টুলস ব্যবহার করবে। এটি আপনাকে সিটিবাইক ডেটাসেটে উপলব্ধ টেবিল এবং ফিল্ডগুলির একটি সার্বিক ধারণা দেবে।

১২. এজেন্টটিকে ক্লাউড রান-এ স্থাপন করুন

এই কমান্ডটি 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 \
      -- \
      --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 ওয়েব ইন্টারফেস সহ এজেন্টটিকে ডেপ্লয় করেছে।

ওয়েব ব্রাউজারে এজেন্ট URL-টি খুলুন। adk deploy কমান্ডটি এটি রিটার্ন করে, এবং আপনি gcloud run services কমান্ডটি চালিয়েও URL-টি পুনরুদ্ধার করতে পারেন:

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.

এজেন্টকে BigQuery MCP সার্ভার ব্যবহার করে Citibike ডেটাসেট অন্বেষণ করতে হবে, কয়েকটি SQL কোয়েরি চালাতে হবে এবং ৩টি সিটিবাইক স্টেশনের একটি তালিকা ফেরত দিতে হবে।

১৩. অভিনন্দন!

কোডল্যাবটি সম্পন্ন করার জন্য অভিনন্দন!

আমরা ক্লাউড রান ডকুমেন্টেশন পর্যালোচনা করার পরামর্শ দিই।

আমরা যা আলোচনা করেছি

Cloud Run RTX 6000 Pro GPU-তে কীভাবে Gemma 4 মডেল স্থাপন করবেন
দ্রুত পরিষেবা চালুর জন্য ক্লাউড স্টোরেজের সাথে ডিরেক্ট ভিপিসি ইগ্রেস এবং ভিএলএলএম মডেল স্ট্রিমিং কীভাবে কনফিগার করবেন।
এজেন্ট ডেভেলপমেন্ট কিট ব্যবহার করে কীভাবে জেমা ৪ এলএলএম এবং বিগকোয়েরি এমসিপি সার্ভার দিয়ে একটি এআই এজেন্ট তৈরি ও ডেপ্লয় করা যায়।

১৪. পরিষ্কার করা

এই টিউটোরিয়ালে ব্যবহৃত রিসোর্সগুলোর জন্য আপনার গুগল ক্লাউড অ্যাকাউন্টে চার্জ হওয়া এড়াতে, আপনি প্রজেক্টটি অথবা স্বতন্ত্র রিসোর্সগুলো ডিলিট করে দিতে পারেন।

বিকল্প ১: রিসোর্স মুছে ফেলুন

ক্লাউড রান পরিষেবাগুলি মুছে ফেলুন

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

বিকল্প ২: প্রজেক্টটি মুছে ফেলুন

সম্পূর্ণ প্রজেক্টটি ডিলিট করতে, 'Manage Resources'- এ যান, ধাপ ২-এ তৈরি করা প্রজেক্টটি সিলেক্ট করুন এবং 'Delete' বেছে নিন। প্রজেক্টটি ডিলিট করলে, আপনাকে আপনার Cloud SDK-তে প্রজেক্ট পরিবর্তন করতে হবে। gcloud projects list ' কমান্ডটি চালিয়ে আপনি সমস্ত উপলব্ধ প্রজেক্টের তালিকা দেখতে পারেন। আপনি যদি কমান্ড লাইন ব্যবহার করতে চান, তাহলে এই কমান্ডটিও ব্যবহার করতে পারেন:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}