Cloud Run'da Gemma 4 ve BigQuery MCP sunucusu ile yapay zeka aracıları oluşturma ve dağıtma

1. Giriş

Not: Bu özellik, Hizmete Özel Şartlar'ın Genel Hizmet Şartları bölümündeki "GKST Öncesi Teklif Şartları"na tabidir. GKST öncesi özellikler "olduğu gibi" sunulur ve desteği sınırlı olabilir. Daha fazla bilgi için lansman aşamalarının açıklamalarını inceleyin.

Genel Bakış

Neler öğreneceksiniz?

• vLLM ile Cloud Run RTX 6000 Pro GPU'da Gemma 4 modelini dağıtma
• Agent Development Kit (ADK) kullanarak nasıl yapay zeka ajanı oluşturulacağı ve Gemma 4'ün bu ajanla nasıl kullanılacağı.
• BigQuery MCP sunucusunu kullanarak yapay zeka aracılarına BigQuery'deki yapılandırılmış verilere erişim izni verme

Gemma 4, Google DeepMind'ın Apache 2 lisanslı açık ağırlık modelleri ailesidir. Modeller çok formatlı, çok dilli, muhakeme yeteneğine sahip ve verimli bir mimari sunar.

Cloud Run, GPU desteği sunan container'lar için sunucusuz bir ortamdır.

Agent Development Kit (ADK), kurumsal ölçekte güvenilir yapay zeka ajanları oluşturmanıza, hatalarını ayıklamanıza ve dağıtmanıza olanak tanıyan açık kaynaklı bir ajan geliştirme çerçevesidir.

BigQuery, devasa veri kümelerini depolamanıza, sorgulamanıza ve analiz etmenize olanak tanıyan, tümüyle yönetilen ve sunucusuz bir kurumsal veri ambarıdır.

Model Bağlam Protokolü (MCP), büyük dil modellerinin (LLM'ler) ve yapay zeka uygulamalarının ya da ajanlarının harici veri kaynaklarına bağlanma şeklini standartlaştırır. MCP sunucuları, arka uç hizmetlerinden güncellenmiş veriler almak ve işlem yapmak için araçlarını, kaynaklarını ve istemlerini kullanmanıza olanak tanır. BigQuery MCP Server, yapay zeka aracılarınıza BigQuery'deki verileri analiz etmenin doğrudan ve güvenli bir yolunu sunar. Bu tamamen yönetilen MCP sunucusu, yönetim ek yükünü ortadan kaldırarak akıllı aracıları geliştirmeye odaklanmanızı sağlar.

Not: Bu codelab'de Gemma 4 31B Instruction-Tuned modeli kullanılmaktadır. Bu codelab'de, Run:ai Model Streamer ve doğrudan VPC çıkışının, modelin kapsayıcı başlatma sırasında Cloud Storage'dan yüklenmesi için gereken süreyi nasıl en aza indirdiği gösterilmektedir. Daha fazla bilgi için GPU en iyi uygulamalar rehberini inceleyin.

2. Kurulum ve Gereksinimler

Bu laboratuvarın tamamı komut satırında yürütülebilir. Ortamı başlatmak için CloudShell'i kullanabilirsiniz (konsolun sağ üst kısmındaki istem simgesini tıklayın).

Varsayılan projeyi ve Cloud Run bölgesini ayarlayarak başlayın:

# set the project
gcloud config set project YOUR_PROJECT_ID

YOUR_PROJECT_ID kısmını Google Cloud proje kimliğinizle değiştirin.

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

CLOUD-RUN-REGION değerini aşağıdaki Cloud bölgelerinden biriyle değiştirin:

• us-central1
• asia-southeast1

Bu codelab boyunca kullanılacak ortam değişkenleri aşağıda verilmiştir. Bunları bir ortam dosyasına kaydedip "kaynak" olarak kullanabilirsiniz. Proje kimliğinizin ve isteğe bağlı olarak bölgenin değerini doğru şekilde ayarladığınızdan emin olun.

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

Not: Bu snippet'i bir komut dosyası olarak kaydetmek ve Cloud Shell oturumu sıfırlandığında gelecekte yeniden kullanmak faydalıdır. env.sh olarak kaydedin ve sonraki adımları çalıştırırken ortam değişkenlerini ayarlamak için source env.sh komutunu çalıştırın. Sürüm kontrol sistemlerine env.sh işlem yapmayın.

Bu Codelab için gerekli API'leri etkinleştirin. API değişikliklerinin geçerlilik kazanması 2-3 dakika sürebilir.

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. Hizmet hesabı oluşturma

Cloud Run hizmeti veya işi oluşturulurken bir hizmet hesabı belirtmezseniz Cloud Run, varsayılan Compute Engine hizmet hesabını kullanır. Hizmeti aşırı izinlerle çalıştırmamak için Cloud Run hizmeti için ayrı bir hizmet hesabı kullanılması önerilir.

Cloud Run hizmeti için hizmet hesabı oluşturma

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

4. Cloud Storage'ı kurma

Model ağırlıklarını depolamak için bir Cloud Storage paketi oluşturun. Bu işlem, Cloud Run her hizmet örneğini başlattığında model ağırlıklarının daha hızlı indirilmesi için doğrudan VPC çıkışının kullanılmasına olanak tanır.

vLLM'deki Run:ai Model Streamer özelliğiyle birlikte kullanıldığında model yükleme süresini önemli ölçüde azaltır.

Paket oluşturma

Cloud Run hizmetiyle aynı konumda bulunan tek bölgeli bir paket olduğundan emin olun.

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

5. Model Ağırlıklarını Alma ve Önbelleğe Alma

Ardından, Gemma 4 modelini Cloud Storage paketinize indirin. Model ağırlıkları onlarca gigabayt olduğundan bunları önce yerel makinenize veya Cloud Shell'e indirmeniz mümkün olmayabilir. Bunun yerine, model ağırlıklarını tutacak kadar depolama alanına sahip Cloud Build'i kullanın.

Model ağırlıklarını paylaşılan bir Cloud Storage paketinden kopyalama

Google Cloud, Gemma 4 model ağırlıklarını içeren herkese açık bir Cloud Storage paketi barındırır.

us- bölgelerinden birini kullanıyorsanız model ağırlıklarını kopyalamak yerine GCS_MODEL_LOCATION değerini herkese açık önbellek konumunu gösterecek şekilde değiştirmeniz yeterlidir. Örneğin, gemma-4-31B-it modeli için export GCS_MODEL_LOCATION="gs://vertex-model-garden-public-us/gemma4/gemma-4-31B-it" değerini ayarlayın (.env veya env.sh gibi bir ortam dosyası kullanıyorsanız dosyayı değiştirmeyi unutmayın).

Bu dosyaları Storage paketinize kopyalamak için şu komutu çalıştırın:

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

Not: Bu işlem 10 ila 30 dakika arasında önemli bir süre alır.

6. Doğrudan VPC çıkışı için ağı yapılandırma

Doğrudan VPC çıkışı yapılandırması için Özel Google Erişimi'nin etkin olduğu bir ağ ve alt ağ oluşturulması gerekir.

Bu, Cloud Run hizmetlerinin Cloud Storage dahil olmak üzere Google API'leri ve hizmetleri tarafından kullanılan harici IP adresleri grubuna bağlanmasına olanak tanır.

Ağ oluşturma

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

Alt ağ oluşturma

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. Hizmet Hesabı Erişim Politikasını Yapılandırma

Cloud Run hizmet hesabının, oluşturduğunuz depolama paketindeki model ağırlıklarına erişme izni olması gerekir.

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. Yapılandırma Değişkenlerini Başlatma

Hem vLLM çıkarım motoru hem de Cloud Run hizmeti için değişkenleri tanımlayın.

# 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

Performans için ayarlama ile ilgili not: Bu değişkenleri ayarlarken işleme hızı ve gecikme arasında denge kurulur:

• MAX_NUM_SEQS - CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY, en az MAX_NUM_SEQS kadar büyük olmalıdır. Trafik artışlarında optimum kullanım için bu değeri biraz daha yüksek (ör. 2 kat) ayarlayın.
• Bellek Baskısı: MAX_MODEL_LEN ve MAX_NUM_SEQS, KV önbelleği için GPU belleğini kullanır. Büyük bağlam uzunluklarında bellek yetersiz (OOM) hatalarıyla karşılaşırsanız MAX_NUM_SEQS değerini düşürmeyi deneyin.
• Gecikme: Daha yüksek eşzamanlılık (MAX_NUM_SEQS), toplam işleme hızını artırır ancak tek tek isteklerin gecikmesini de artırabilir.
• Ölçeklendirme: CLOUD_RUN_MAX_INSTANCES yatay olarak ölçeklendirmenize olanak tanır. Tek örnek gecikmeniz kabul edilebilir düzeydeyse ancak daha fazla toplam kapasiteye ihtiyacınız varsa bu değeri artırın.

9. Cloud Run'a dağıt

vLLM kapsayıcı komut satırını hazırlama

vLLM, büyük modelleri hızlı ve verimli bir şekilde çalıştırmak için çok sayıda parametre gerektirir. Bu parametreler, Cloud Run'a dağıtılan container'a bağımsız değişken olarak iletilir.

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 hizmetini dağıtma

Cloud Run hizmetini dağıtmak için aşağıdaki komutu çalıştırın. GPU türünü (RTX 6000 Pro), temel görüntüyü (pytorch-vllm-serve:gemma4) ve hizmeti çağırmak için kimlik doğrulama yapılması gerektiğini (--no-allow-unauthenticated) unutmayın.

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

Bu işlemin dağıtılması birkaç dakika sürer. Bu işlem tamamlandığında, Gemma 4'ü sunan, GPU destekli bir ortamınız olur. Bu ortamda, sıfıra ölçeklendirme (trafik yoksa maliyet de yoktur) dahil olmak üzere otomatik ölçeklendirme özellikli sunucusuz bir altyapı kullanılır.

Not: Hizmet dağıtımı, GPU kullanılabilirliği veya kotasıyla ilgili olarak başarısız olursa hizmeti test etmeyi atlayın ve Agent Development Kit'i kullanarak veri aracısı oluşturma bölümüne geçin. Kullanılacak Gemma 4 hizmeti yoksa ajan, Gemini Enterprise Ajan Platformu'nda Gemini 3.5 Flash Lite'ı kullanabilir.

10. Hizmeti test etme

Dağıtım tamamlandıktan sonra vLLM OpenAI uyumlu API'yi kullanarak Gemma 4 modelinizle etkileşim kurabilirsiniz.

Hizmet URL'sini alma

Dağıtılan Cloud Run hizmetinizin URL'sini alın.

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"

Çıkarım Çalıştırma

curl kullanarak modele istem gönderin.

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'i kullanarak veri temsilcisi oluşturma

Ajanın kodunu yazma

Cloud Shell Terminal'den veya yerel terminalinizden, yapay zeka aracılı uygulamanız için bir kök dizin oluşturun:

mkdir data_agent

Cloud Shell Düzenleyici'yi veya başka bir metin düzenleyiciyi açın ve data_agent dizininde agent.py dosyasını oluşturun:

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'nın dağıtılması için __init__.py ve requirements.txt da gerekir:

• __init__.py, aracı için bir içe aktarma işlemine sahip olmalıdır.
• requirements.txt Python bağımlılıklarını listeleyin: google-adk Agent Development Kit için, litellm ADK'nın Gemini dışındaki modelleri kullanmak için yararlandığı LiteLLM kitaplığı için ve mcp Model Bağlam Protokolü istemcisi için.

Bu komutlar, __init__.py ve requirements.txt oluşturmanıza yardımcı olur:

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

Son klasör yapısı şu şekilde görünmelidir:

data_agent/
    __init__.py
    agent.py
    requirements.txt

Temsilciyi yerel olarak deneme

Agent Development Kit, adk CLI aracını içerir. Bu araç, ajanlarınızı test etmek için kullanılan etkileşimli bir terminal arayüzüdür. Bu, hızlı testler, komut dosyası oluşturulmuş etkileşimler ve CI/CD ardışık düzenleri için kullanışlıdır. Sunduğu özelliklerden biri de adk web - ADK Web Arayüzü'dür. Bu arayüz, aracılarınızı etkileşimli olarak geliştirip hatalarını ayıklamanın basit bir yoludur. ADK Web, üretim dağıtımlarında kullanılmak üzere tasarlanmamıştır ancak aracı denemeyi çok kolaylaştırır.

Not: Bu komutu çalıştırmadan önce geçerli dizininizde data_agent dizininin bulunduğundan emin olun (ls komutuyla).

Bu komut, 8080 numaralı bağlantı noktasında yerel bir web sunucusu başlatan adk web uygulamasını başlatır.

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 .

Hizmet başlatıldıktan sonra yerel ADK web sayfasını açın: http://localhost:8080/.

Google Cloud Shell'i kullanıyorsanız Web Önizlemesi düğmesini tıklayın.

ADK Web Kullanıcı Arayüzü'nde, aracının erişebildiği veriler hakkında soru sorun:

What data do you have?

Not: Daha önce dağıtılan Gemma 4 hizmeti Cloud Run tarafından sıfıra indirildiyse aracının ilk isteği birkaç dakika sürebilir. Modelin başlatılması ve yüklenmesi yaklaşık 3-4 dakika sürer.

Aracı kodu, Cloud Run'a dağıtılan Gemma 4 modelini kullanır. Model, citibike veri kümesini keşfetmek için BigQuery MCP araçlarını kullanacak. Citibike veri kümesindeki mevcut tablolar ve alanlar hakkında genel bir bakış sunar.

12. Aracıyı Cloud Run'a dağıtma

Önceki komutunuz hâlâ ADK Web Sunucusu'nu çalıştırıyorsa Ctrl + C tuşlarına basarak durdurun.

Bu komut, ADK KSA'yı kullanarak aracıyı Cloud Run'a dağıtır.

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

Temsilciyi deneme

Aracı dağıtımımız için --with_ui seçeneğini kullandık. Ajanı ADK Web Arayüzü ile dağıttı.

1. Temsilci URL'sini web tarayıcısında açın. adk deploy komutu döndürdü. Ayrıca gcloud run services komutunu çalıştırarak da URL'yi alabilirsiniz:

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

2. Aracıdan, mevcut Citibike verileri hakkında akıl yürütmesini isteyin:

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

Aracı, BigQuery MCP sunucusunu kullanarak Citibike veri kümesini keşfetmeli, birkaç SQL sorgusu çalıştırmalı ve 3 Citibike istasyonunun listesini döndürmelidir.

13. Tebrikler!

Codelab'i tamamladığınız için tebrik ederiz.

Cloud Run belgelerini incelemenizi öneririz.

İşlediğimiz konular

• Gemma 4 modelini Cloud Run RTX 6000 Pro GPU'ya dağıtma
• Daha hızlı hizmet başlatma için Cloud Storage ile doğrudan VPC çıkışı ve vLLM modeli akışını yapılandırma
• Gemma 4 LLM ve BigQuery MCP sunucusunu kullanan bir yapay zeka ajanı, Agent Development Kit ile nasıl oluşturulur ve dağıtılır?

14. Temizleme

Bu eğiticide kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız projeyi veya tek tek kaynakları silebilirsiniz.

1. seçenek: Kaynakları silme

Cloud Run hizmetlerini silme

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

Hizmet hesabını silme

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

Cloud Storage paketini silme

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

VPC ağını ve alt ağı silme

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. seçenek: Projeyi silme

Projenin tamamını silmek için Kaynakları Yönet'e gidin, 2. adımda oluşturduğunuz projeyi seçin ve Sil'i tıklayın. Projeyi silerseniz Cloud SDK'nızda projeleri değiştirmeniz gerekir. gcloud projects list komutunu çalıştırarak kullanılabilir tüm projelerin listesini görüntüleyebilirsiniz. Komut satırını kullanmaya devam etmek istiyorsanız şu komutu da kullanabilirsiniz:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}