Diese Seite wurde von der Cloud Translation API übersetzt.

Agentenbasierten KI-Agenten mit dem Agent Development Kit (ADK) und Vertex AI in GKE bereitstellen

In diesem Leitfaden wird gezeigt, wie Sie containerisierte agentische KI-/ML-Anwendungen mit Google Kubernetes Engine (GKE) bereitstellen und verwalten. Durch die Kombination des Google Agent Development Kit (ADK) mit Vertex AI als LLM-Anbieter (Large Language Model) können Sie KI-Agenten effizient und in großem Umfang operationalisieren. In diesem Leitfaden wird der gesamte Prozess von der Entwicklung bis zur Produktionsbereitstellung eines auf FastAPI basierenden Agents, der auf Gemini 2.0 Flash basiert, in GKE beschrieben.

Dieser Leitfaden richtet sich an ML-Entwickler, Entwickler und Cloud-Architekten, die daran interessiert sind, Kubernetes-Container-Orchestrierungsfunktionen für die Bereitstellung von agentenbasierten KI-/ML-Anwendungen zu nutzen. Weitere Informationen zu gängigen Rollen und Beispielaufgaben in Google Cloud Inhalten finden Sie unter Häufig verwendete GKE-Nutzerrollen und -Aufgaben.

Machen Sie sich vorher mit folgenden Punkten vertraut:

Hintergrund

In diesem Leitfaden werden mehrere Google-Technologien kombiniert, um eine skalierbare Plattform für agentenbasierte KI zu schaffen. GKE bietet die Containerorchestrierung für den Agent, der mit dem ADK erstellt wird. Wenn Sie die Vertex AI API für die LLM-Inferenz verwenden, ist für den GKE-Cluster keine spezielle GPU-Hardware erforderlich, da die Inferenz von der verwalteten Infrastruktur von Google übernommen wird.

Google Agent Development Kit (ADK)

Das Agent Development Kit (ADK) ist ein flexibles und modulares Framework zum Entwickeln und Bereitstellen von KI-Agenten. Das ADK ist zwar für Gemini und das Google-Ökosystem optimiert, aber modellunabhängig, unabhängig von der Bereitstellung und für die Kompatibilität mit anderen Frameworks konzipiert.

Weitere Informationen finden Sie in der ADK-Dokumentation.

Verwalteter Kubernetes-Dienst von GKE

GKE ist ein verwalteter Kubernetes-Dienst zum Bereitstellen, Skalieren und Verwalten von Containeranwendungen. GKE bietet die erforderliche Infrastruktur, einschließlich skalierbarer Ressourcen, verteiltem Computing und effizienter Vernetzung, um die Rechenanforderungen von LLMs zu bewältigen.

Weitere Informationen zu wichtigen Kubernetes-Konzepten finden Sie unter Kubernetes lernen. Weitere Informationen zu GKE und dazu, wie Sie damit Kubernetes skalieren, automatisieren und verwalten können, finden Sie in der GKE-Übersicht.

Vertex AI

Vertex AI ist die einheitliche ML-Plattform von Google Cloud, mit der Entwickler KI-/ML-Modelle erstellen, bereitstellen und skalieren können. Für agentische KI-Anwendungen in GKE bietet Vertex AI wichtige Tools und Dienste, darunter Zugriff auf LLMs wie Gemini 2.0 Flash, verwaltete Infrastruktur für Training und Inferenz sowie MLOps-Funktionen für ein effizientes Lebenszyklusmanagement.

Wenn Sie LLMs über die Vertex AI API nutzen, erfolgt die Modellinferenz auf der verwalteten Infrastruktur von Google. Dadurch ist in Ihrem GKE-Cluster kein bestimmtes GPU- oder TPU-Kontingent erforderlich.

Weitere Informationen zu Vertex AI für agentenbasierte KI-Anwendungen finden Sie in der Dokumentation zu Vertex AI.

Gemini 2.0 Flash

Gemini 2.0 Flash bietet Funktionen der nächsten Generation und verbesserte Möglichkeiten für agentenbasierte Arbeitslasten, darunter höhere Geschwindigkeit, integrierte Tool-Nutzung, multimodale Generierung und ein Kontextfenster von 1 Million Tokens. Gemini 2.0 Flash ist eine Weiterentwicklung des vorherigen Flash-Modells und bietet eine höhere Qualität bei ähnlicher Geschwindigkeit.

Technische Informationen zu Gemini 2.0 Flash, z. B. Leistungsbenchmarks, Informationen zu unseren Trainingsdatensätzen, Bemühungen um Nachhaltigkeit, beabsichtigte Nutzung und Einschränkungen sowie unser Ansatz in Bezug auf Ethik und Sicherheit, finden Sie in der Modellkarte für Gemini 2.0 Flash.

Umgebung vorbereiten

In dieser Anleitung wird Cloud Shell verwendet, um Ressourcen zu verwalten, die auf Google Cloudgehostet werden. Die Software, die Sie für diese Anleitung benötigen, ist in Cloud Shell vorinstalliert, einschließlich kubectl, terraform und Google Cloud CLI.

So richten Sie Ihre Umgebung mit Cloud Shell ein:

Starten Sie in der Google Cloud Console eine Cloud Shell-Sitzung und klicken Sie auf Cloud Shell aktivieren (). Dadurch wird im unteren Bereich der Google Cloud Console eine Sitzung gestartet.

Legen Sie die Standardumgebungsvariablen fest:

gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_LOCATION=REGION
export PROJECT_ID=PROJECT_ID
export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
export WORKLOAD_POOL=$PROJECT_ID.svc.id.goog
export PROJECT_NUMBER=$(gcloud projects describe --format json $PROJECT_ID | jq -r ".projectNumber")

Ersetzen Sie die folgenden Werte:

PROJECT_ID: Ihre Google Cloud Projekt-ID.
REGION: die Google Cloud Region (z. B. us-central1), in der Ihr GKE-Cluster, Artifact Registry und andere regionale Ressourcen bereitgestellt werden.

Beispielprojekt klonen

Klonen Sie in Ihrem Cloud Shell-Terminal das Beispielcode-Repository des Tutorials:
```
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
```

Gehen Sie zum Anleitungsverzeichnis:

cd kubernetes-engine-samples/ai-ml/adk-vertex

Google Cloud -Ressourcen erstellen und konfigurieren

Um Ihren Agent in GKE bereitzustellen, stellen Sie die erforderlichenGoogle Cloud -Ressourcen bereit. Sie können den Agenten entweder über die gcloud CLI für die direkte Ausführung über die Befehlszeile oder über Terraform für Infrastructure as Code bereitstellen.

gcloud

In diesem Abschnitt finden Sie gcloud CLI-Befehle zum Einrichten Ihres GKE-Cluster, von Artifact Registry und der Identitätsföderation von Arbeitslasten für GKE für die nahtlose Integration in Vertex AI. Achten Sie darauf, dass die Umgebungsvariablen wie unter Umgebung vorbereiten beschrieben festgelegt wurden.

GKE-Cluster erstellen: Sie können Ihre containerisierte agentenbasierte Anwendung in einem GKE-Cluster im Autopilot- oder Standardmodus bereitstellen. Verwenden Sie einen Autopilot-Cluster für eine vollständig verwaltete Kubernetes-Umgebung. Informationen zum Auswählen des GKE-Betriebsmodus, der für Ihre Arbeitslasten am besten geeignet ist, finden Sie unter GKE-Betriebsmodus auswählen.
Autopilot
Führen Sie in Cloud Shell den folgenden Befehl aus:
```
gcloud container clusters create-auto CLUSTER_NAME \
        --location=$GOOGLE_CLOUD_LOCATION \
        --project=$PROJECT_ID
```
Ersetzen Sie CLUSTER_NAME durch den Namen Ihres GKE Autopilot-Clusters.
Standard
Führen Sie in Cloud Shell den folgenden Befehl aus:
```
gcloud container clusters create CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_LOCATION \
    --project=$PROJECT_ID \
    --release-channel=stable \
    --num-nodes=1 \
    --machine-type=e2-medium \
    --workload-pool=$PROJECT_ID.svc.id.goog
```
Ersetzen Sie CLUSTER_NAME durch den Namen Ihres Standardclusters.
Artifact Registry-Repository für Ihren Docker-Container erstellen: Erstellen Sie ein Artifact Registry-Repository, um das Docker-Container-Image Ihres Agenten sicher zu speichern und zu verwalten. Diese private Registry sorgt dafür, dass Ihre Anwendung für die Bereitstellung in GKE verfügbar ist, und lässt sich in Cloud Build einbinden.
```
gcloud artifacts repositories create adk-repo \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_LOCATION \
    --project=$PROJECT_ID
```
Repository-URL abrufen: Führen Sie diesen Befehl aus, um den vollständigen Pfad zu Ihrem Repository zu prüfen. Sie verwenden dieses Pfadformat, um Ihr Docker-Image im nächsten Schritt zu taggen.
```
gcloud artifacts repositories describe adk-repo \
    --location $GOOGLE_CLOUD_LOCATION \
    --project=$PROJECT_ID
```

Dem Compute Engine-Standarddienstkonto die erforderlichen IAM-Rollen zuweisen: Standardmäßig hat das Compute Engine-Standarddienstkonto keine Berechtigungen zum Pushen von Images in Artifact Registry oder zum Aufrufen von Objekten in Cloud Storage oder von Logs. Weisen Sie die erforderlichen Rollen für diese Vorgänge zu.

ROLES_TO_ASSIGN=(
    "roles/artifactregistry.writer"
    "roles/storage.objectViewer"
    "roles/logging.viewer"
)

for ROLE in "${ROLES_TO_ASSIGN[@]}"; do
    gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
        --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
        --role="${ROLE}"
done

Agent-Container-Image erstellen und per Push übertragen: Führen Sie diesen Befehl aus, um Ihr Docker-Image zu erstellen und per Push in Ihre Artifact Registry zu übertragen. Achten Sie darauf, dass sich Ihr Dockerfile und Ihr Anwendungscode im Verzeichnis /app befinden.
```
export IMAGE_URL="${GOOGLE_CLOUD_LOCATION}-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest"

gcloud builds submit \
    --tag "$IMAGE_URL" \
    --project="$PROJECT_ID" \
    app
```

Prüfen, ob das Image übertragen wurde:

gcloud artifacts docker images list \
    $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$PROJECT_ID/adk-repo/adk-agent \
    --project=$PROJECT_ID

Terraform

In diesem Abschnitt wird beschrieben, wie Sie Ihre Google Cloud-Ressourcen mit Terraform bereitstellen. Das Beispiel-Repository, das Sie geklont haben, enthält die erforderlichen Terraform-Konfigurationsdateien.

Terraform initialisieren: Wechseln Sie in das Verzeichnis terraform und initialisieren Sie Terraform.
```
terraform init
```
Ausführungsplan prüfen: Dieser Befehl zeigt die Infrastrukturänderungen, die Terraform vornehmen wird.
```
terraform plan -var-file=default_env.tfvars
```
Konfiguration anwenden: Führen Sie den Terraform-Plan aus, um die Ressourcen in Ihrem Google Cloud -Projekt zu erstellen. Bestätigen Sie den Vorgang, wenn Sie dazu aufgefordert werden.yes
```
terraform apply -var-file=default_env.tfvars
```
Nachdem Sie diese Befehle ausgeführt haben, stellt Terraform Ihren GKE-Cluster und Ihr Artifact Registry-Repository bereit und konfiguriert die erforderlichen IAM-Rollen und Dienstkonten, einschließlich der Identitätsföderation von Arbeitslasten für GKE.

Weitere Informationen zur Verwendung von Terraform finden Sie unter Terraform-Unterstützung für GKE.

`kubectl` für die Kommunikation mit Ihrem Cluster konfigurieren

Wenn Sie kubectl noch nicht für die Kommunikation mit Ihrem Cluster konfiguriert haben, führen Sie den folgenden Befehl aus:

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=${GOOGLE_CLOUD_LOCATION}

Ersetzen Sie dabei CLUSTER_NAME durch den Namen Ihres GKE-Cluster.

Zugriff über die Identitätsföderation von Arbeitslasten für GKE konfigurieren

Wenn Sie Terraform verwenden, können Sie diesen Schritt überspringen. Bei diesem Vorgang wird ein Kubernetes-Dienstkonto (Kubernetes Service Account, KSA) mit einem IAM-Dienstkonto verknüpft, um Ihrem Agenten sicheren Zugriff auf Google Cloud -Dienste zu gewähren.

Dienstkonto für den Vertex AI-Zugriff erstellen:

gcloud iam service-accounts create vertex-sa \
    --project=$PROJECT_ID

Weisen Sie dem Dienstkonto die Rolle aiplatform.user zu. Dadurch kann das Dienstkonto mit Vertex AI interagieren.

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/aiplatform.user"

Erstellen Sie ein KSA in Ihrem Cluster. Folgen Sie der Anleitung unter kubectl für die Kommunikation mit Ihrem Cluster konfigurieren, bevor Sie diesen Befehl ausführen.
```
kubectl create serviceaccount vertex-sa
```

Annotieren Sie das KSA, um es mit Ihrem Dienstkonto zu verknüpfen:

kubectl annotate serviceaccount vertex-sa \
    iam.gke.io/gcp-service-account=vertex-sa@$PROJECT_ID.iam.gserviceaccount.com

Gewähren Sie Ihrem Dienstkonto Berechtigungen, damit es als Workload Identity Federation for GKE-Nutzer für das KSA fungieren kann:

gcloud iam service-accounts add-iam-policy-binding vertex-sa@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:$PROJECT_ID.svc.id.goog[default/vertex-sa]"

Agent-Anwendung bereitstellen und konfigurieren

Nachdem Sie Ihre Google Cloud -Ressourcen eingerichtet haben, bereiten Sie Ihre Agent-Anwendung für die Bereitstellung vor und konfigurieren Sie die Laufzeit in GKE. Dazu müssen Sie den Code Ihres Agents definieren, ein Dockerfile erstellen, um ihn in einen Container zu packen, und ein Kubernetes-Manifest schreiben, um ihn in Ihrem Cluster bereitzustellen.

Struktur der Agent-Anwendung verstehen: Das Verzeichnis /app enthält die Kerndateien für Ihre Agent-Anwendung:
- main.py: Der Einstiegspunkt der FastAPI-Anwendung, die für die Bereitstellung der API des Agents verantwortlich ist.
- agent.py: Enthält die Logik des ADK-Agents, die definiert, wie er Vertex AI verwendet und Anfragen verarbeitet.
- __init__.py: Initialisiert das Python-Paket.
- requirements.txt: Listet alle Python-Abhängigkeiten für Ihren Agent auf.
- Dockerfile: Definiert, wie Ihre Anwendung in einem Docker-Image verpackt wird.

Manifest für die Agentbereitstellung erstellen: Erstellen Sie im Verzeichnis tutorials-and-examples/adk/vertex das folgende Manifest als Datei mit dem Namen agent-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: adk-agent-deployment
  labels:
    app: adk-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: adk-agent
  template:
    metadata:
      labels:
        app: adk-agent
    spec:
      serviceAccountName: vertex-sa
      containers:
      - name: adk-agent
        image: IMAGE_URL
        ports:
        - containerPort: 8000
        env:
        - name: GOOGLE_CLOUD_PROJECT_ID
          value: PROJECT_ID
        - name: GOOGLE_CLOUD_LOCATION
          value: REGION
        - name: GOOGLE_GENAI_USE_VERTEXAI
          value: "1"
        - name: PORT
          value: "8000"
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1"

Ersetzen Sie die folgenden Werte:

IMAGE_URL: Die vollständige URL des Docker-Images, das Sie in Artifact Registry hochgeladen haben (z. B. us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest). Sie können diesen Wert aus der Ausgabe des Befehls gcloud artifacts docker images list im vorherigen Abschnitt abrufen. Alternativ können Sie einen Befehl wie den folgenden ausführen: sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yaml.
PROJECT_ID: Projekt-ID in Google Cloud .
REGION: die Google Cloud Region, in der Ihr GKE-Cluster bereitgestellt wird.

Deployment-Manifest anwenden:
```
kubectl apply -f agent-deployment.yaml
```
Mit diesem Befehl werden die Bereitstellung und die zugehörigen Pods für Ihre Agent-Anwendung im GKE-Cluster erstellt.
Agent freigeben: Mit diesen Methoden können Sie Ihren Agent für den Zugriff freigeben.
- Wenn Sie von außerhalb des Clusters auf Ihren Agent zugreifen möchten, erstellen Sie einen Kubernetes-Dienst. Für eine Web-API ist ein Dienst vom Typ LoadBalancer üblich.
- Für die lokale Entwicklung und das Testen können Sie mit dem Befehl kubectl port-forward direkt auf Ihren Agent zugreifen.
LoadBalancer
1. Erstellen Sie das folgende Manifest als Datei mit dem Namen agent-service.yaml:
  apiVersion: v1 kind: Service metadata: name: adk-agent-service spec: selector: app: adk-agent type: LoadBalancer # Creates an external IP address for access ports: - protocol: TCP port: 80 targetPort: 8000 # Matches the containerPort exposed in the Deployment
2. Wenden Sie das Manifest an:
  kubectl apply -f agent-service.yaml
  Es kann einige Minuten dauern, bis die externe IP-Adresse bereitgestellt wird.
3. Prüfen Sie, ob die IP-Adresse bereitgestellt wurde:
  kubectl get service adk-agent-service
  Suchen Sie in der Ausgabe nach dem Wert EXTERNAL-IP. Sobald der Wert verfügbar ist, können Sie mit dieser IP-Adresse mit Ihrem bereitgestellten Agent interagieren.
port-forward
Wenn Sie hauptsächlich port-forward verwenden, sollten Sie anstelle von LoadBalancer den Diensttyp ClusterIP verwenden, da der ClusterIP-Dienst intern ist und weniger Ressourcen verbraucht.
```
POD_NAME=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl port-forward $POD_NAME 8000:8000
```
Dieser Befehl blockiert Ihr Terminal, leitet aber den Traffic von localhost:8000 auf Ihrem Computer an den Agent weiter, der im GKE-Cluster ausgeführt wird.

Bereitgestellten Agent testen

Nachdem Ihre Agent-Anwendung bereitgestellt und verfügbar gemacht wurde, sollten Sie ihre Funktionalität testen.

In diesem Abschnitt wird beschrieben, wie Sie den Endpunkt Ihres Agents ermitteln und die API des Agents testen.

Endpunkt des Agents ermitteln: Ermitteln Sie den zugänglichen Endpunkt des Agents. Das hängt davon ab, wie Sie den Agent im vorherigen Abschnitt verfügbar gemacht haben:
LoadBalancer
1. Rufen Sie die externe IP-Adresse ab:
  kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
2. Speichern Sie die externe IP-Adresse zur einfacheren Verwendung in einer Umgebungsvariablen:
  export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
  Die Basis-URL Ihres Agents ist http://${AGENT_IP}.
port-forward
Achten Sie darauf, dass der Befehl kubectl port-forward in einem separaten Terminal ausgeführt wird. Die Basis-URL Ihres Agents ist http://localhost:8000.
API des Agents testen: Testen Sie die API des Agents, indem Sie eine curl-Anfrage an den /run-Endpunkt senden. Der Agent erwartet eine JSON-Nutzlast mit einem Nachrichtenfeld. Ersetzen Sie AGENT_BASE_URL durch http://${AGENT_IP} (für LoadBalancer) oder http://localhost:8000 (für Portweiterleitung).
1. Neue Sitzung erstellen. Dadurch wird der Kundenservicemitarbeiter auf eine neue Unterhaltung vorbereitet.
```
# The user ID and session ID are arbitrary.
# The appName must match the agent's Python package directory name (in this case, "capital-agent").
curl -X POST AGENT_BASE_URL/apps/capital-agent/users/user-123/sessions/session-123
```
  Mit dem folgenden Befehl können Sie verfügbare Apps auflisten:
```
curl -X GET AGENT_BASE_URL/list-apps
```
2. Senden Sie eine Anfrage an den Agenten. Verwenden Sie dazu die Sitzungsdetails aus dem vorherigen Schritt.
```
curl -X POST AGENT_BASE_URL/run \
-H "Content-Type: application/json" \
-d '{
  "appName": "capital-agent",
  "userId": "user-123",
  "sessionId": "session-123",
  "newMessage": {
    "role": "user",
    "parts": [{
      "text": "Hello, agent! What can you do for me?"
    }]
  }
}'
```
  Sie sollten eine JSON-Antwort von Ihrem Agent erhalten, die angibt, dass er Anfragen erfolgreich verarbeitet und über Vertex AI mit dem Gemini-Modell interagiert. Die Antwort enthält die vom Agent generierte Antwort auf Ihre Nachricht.
Auf die Web-UI des Agents zugreifen (falls zutreffend): Wenn Ihr Agent eine webbasierte Benutzeroberfläche enthält, können Sie darauf zugreifen, indem Sie in einem Webbrowser zu AGENT_BASE_URL navigieren. Das ADK enthält in der Regel eine einfache Web-UI für die Interaktion und das Debugging. Wenn Sie Ihren Agent beispielsweise über einen Load-Balancer bereitgestellt haben und dessen EXTERNAL-IP 34.123.45.67 ist, rufen Sie http://34.123.45.67 in Ihrem Browser auf.