Diese Seite wurde von der Cloud Translation API übersetzt.

Agentenbasierte KI-Anwendung mit dem Agent Development Kit (ADK) und einem selbst gehosteten LLM in GKE bereitstellen

In dieser Anleitung wird gezeigt, wie Sie containerisierte agentenbasierte KI-/ML-Anwendungen mit Google Kubernetes Engine (GKE) bereitstellen und verwalten. Durch die Kombination des Google Agent Development Kit (ADK) mit einem selbst gehosteten Large Language Model (LLM) wie Llama 3.1, das von vLLM bereitgestellt wird, können Sie KI-Agenten effizient und in großem Umfang operationalisieren und gleichzeitig die volle Kontrolle über den Modell-Stack behalten. In dieser Anleitung wird der gesamte Prozess durchlaufen, um einen Python-basierten Agenten von der Entwicklung bis zur Produktionsbereitstellung in einem GKE Autopilot-Cluster mit GPU-Beschleunigung zu bringen.

Diese Anleitung richtet sich an ML-Entwickler, Entwickler und Cloud-Architekten, die daran interessiert sind, Kubernetes-Container-Orchestrierungsfunktionen zum Bereitstellen von agentischen KI-/ML-Anwendungen zu nutzen. Weitere Informationen zu gängigen Rollen und Beispielaufgaben, auf die wir in Google Cloud-Inhalten verweisen, finden Sie unter Häufig verwendete GKE Enterprise-Nutzerrollen und -Aufgaben.

Machen Sie sich vorher mit folgenden Punkten vertraut:

Hintergrund

In diesem Abschnitt werden die in dieser Anleitung verwendeten Schlüsseltechnologien beschrieben.

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, erfordert aber nicht, dass Sie ein bestimmtes Modell oder eine bestimmte Bereitstellung verwenden. Es ist für die Kompatibilität mit anderen Frameworks konzipiert. Das ADK wurde entwickelt, um die Entwicklung von Agenten an die Softwareentwicklung anzunähern und Entwicklern die Erstellung, Bereitstellung und Orchestrierung von Agentenarchitekturen zu erleichtern, die von einfachen Aufgaben bis hin zu komplexen Workflows reichen.

Weitere Informationen finden Sie in der ADK-Dokumentation.

Verwalteter Kubernetes-Dienst von GKE

Google Cloud bietet eine Reihe von Diensten, darunter GKE, der sich gut für die Bereitstellung und Verwaltung von KI-/ML-Arbeitslasten eignet. GKE ist ein verwalteter Kubernetes-Dienst, der die Bereitstellung, Skalierung und Verwaltung von Containeranwendungen vereinfacht. GKE bietet die erforderliche Infrastruktur, einschließlich skalierbarer Ressourcen, verteiltes Computing und effiziente Netzwerke, 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.

vLLM

vLLM ist ein hoch optimiertes Open-Source-LLM-Bereitstellungs-Framework, das den Bereitstellungsdurchsatz auf GPUs über Funktionen wie die Folgenden beschleunigen kann:

Optimierte Transformer-Implementierung mit PagedAttention.
Kontinuierliche Batchverarbeitung zur Verbesserung des allgemeinen Bereitstellungsdurchsatzes.
Tensor-Parallelität und verteilte Bereitstellung auf mehreren GPUs.

Weitere Informationen finden Sie in der vLLM-Dokumentation.

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 eine Sitzung in einem Google Cloud Konsolenbereich gestartet.
Legen Sie die Standardumgebungsvariablen fest:
```
gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_REGION=REGION
export PROJECT_ID=PROJECT_ID
```
Ersetzen Sie die folgenden Werte:
- PROJECT_ID: Ihre Google Cloud Projekt-ID.
- REGION: die Google Cloud Region (z. B. us-east4), in der Ihr GKE-Cluster, Artifact Registry und andere regionale Ressourcen bereitgestellt werden. Geben Sie eine Region an, die L4-GPUs und G2-Maschinentypinstanzen unterstützt. Informationen zur regionalen Verfügbarkeit finden Sie in der Compute Engine-Dokumentation unter GPU-Regionen und -Zonen.

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-vllm

Google Cloud -Ressourcen erstellen und konfigurieren

Bevor Sie Ihren Agent bereitstellen können, müssen Sie zuerst die erforderlichen Google Cloud-Ressourcen bereitstellen. Sie können den GKE-Cluster und das Artifact Registry-Repository entweder mit der gcloud CLI oder mit Terraform erstellen.

gcloud

In diesem Abschnitt finden Sie gcloud-Befehlszeilenbefehle zum Einrichten Ihres GKE-Cluster und von Artifact Registry.

GKE-Cluster erstellen: Sie können Ihre containerisierte agentenbasierte Anwendung in einem GKE Autopilot- oder Standard-Cluster 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-Betriebsmodi.
Autopilot
Führen Sie in Cloud Shell den folgenden Befehl aus:
```
gcloud container clusters create-auto CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION
```
Ersetzen Sie dabei CLUSTER_NAME durch den Namen Ihres GKE-Clusters.

Mit Autopilot stellt GKE Knoten automatisch basierend auf den Ressourcenanforderungen Ihrer Arbeitslast bereit. Die für das LLM erforderliche GPU wird im deploy-llm.yaml-Manifest mit einem nodeSelector angefordert.

So fügen Sie eine nodeSelector-Anfrage für die nvidia-l4-GPU hinzu:
1. Öffnen Sie kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml in einem Editor.
2. Fügen Sie unter spec.template.spec Folgendes nodeSelector hinzu:
  nodeSelector: cloud.google.com/gke-accelerator: nvidia-l4
Standard
1. Erstellen Sie in Cloud Shell einen Standardcluster, indem Sie den folgenden Befehl ausführen:
  gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION
  Ersetzen Sie CLUSTER_NAME durch den Namen Ihres GKE-Cluster.
2. Erstellen Sie einen GPU-fähigen Knotenpool für Ihren Cluster, indem Sie den folgenden Befehl ausführen:
  gcloud container node-pools create gpu-node-pool \ --cluster=CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION \ --machine-type=g2-standard-8 \ --accelerator=type=nvidia-l4,count=1 \ --enable-gvnic
  In der Datei deploy-llm.yaml wird eine nvidia-l4-GPU angegeben, die in der G2-Maschinenserie verfügbar ist. Weitere Informationen zu diesem Maschinentyp finden Sie unter GPU-Maschinentypen in der Compute Engine-Dokumentation.
Artifact Registry-Repository erstellen: Erstellen Sie ein Artifact Registry-Repository, um das Docker-Container-Image Ihres Agenten sicher zu speichern und zu verwalten.
```
gcloud artifacts repositories create REPO_NAME \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_REGION
```
Ersetzen Sie REPO_NAME durch den Namen des Artifact Registry-Repositorys, das Sie verwenden möchten (z. B. adk-repo).
Repository-URL abrufen: Führen Sie diesen Befehl aus, um den vollständigen Pfad zu Ihrem Repository zu prüfen. Sie verwenden dieses Format, um Ihr Docker-Image zu taggen, wenn Sie das Agent-Image erstellen.
```
gcloud artifacts repositories describe REPO_NAME \
    --location $GOOGLE_CLOUD_REGION
```

Terraform

In diesem Abschnitt wird beschrieben, wie Sie die im Beispiel-Repository enthaltene Terraform-Konfiguration verwenden, um Ihre Google Cloud Ressourcen automatisch bereitzustellen.

Zum Terraform-Verzeichnis wechseln: Das Verzeichnis \terraform enthält alle erforderlichen Konfigurationsdateien zum Erstellen des GKE-Cluster und anderer erforderlicher Ressourcen.
```
cd terraform
```
Terraform-Variablendatei erstellen: Kopieren Sie die bereitgestellte Beispielvariablendatei (example_vars.tfvars), um Ihre eigene vars.tfvars-Datei zu erstellen.
```
cp example_vars.tfvars vars.tfvars
```
Öffnen Sie die Datei vars.tfvars in einem Editor und ersetzen Sie die Platzhalterwerte durch Ihre spezifische Konfiguration. Sie müssen mindestens PROJECT_ID durch Ihre Google Cloud Projekt-ID und CLUSTER_NAME durch den Namen Ihres GKE-Cluster ersetzen.
Terraform initialisieren: Führen Sie diesen Befehl aus, um die erforderlichen Anbieter-Plug-ins für Google Cloudherunterzuladen.
```
terraform init
```
Ausführungsplan prüfen: Dieser Befehl zeigt die Infrastrukturänderungen, die Terraform vornehmen wird.
```
terraform plan -var-file=vars.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=vars.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 Workload Identity Federation for GKE.

Weitere Informationen zur Verwendung von Terraform finden Sie unter GKE-Ressourcen mit Terraform bereitstellen.

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

Führen Sie den folgenden Befehl aus, um kubectl für die Kommunikation mit Ihrem Cluster zu konfigurieren:

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

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

Agent-Image erstellen

Nachdem Sie die Infrastruktur mit der gcloud CLI oder Terraform erstellt haben, gehen Sie so vor, um Ihre Agent-Anwendung zu erstellen.

Erforderliche IAM-Rolle für Cloud Build zuweisen: Der Cloud Build-Dienst benötigt Berechtigungen, um das Container-Image des Agents per Push-Funktion in Artifact Registry zu übertragen. Weisen Sie dem Compute Engine-Standarddienstkonto, das von Cloud Build verwendet wird, die Rolle roles/artifactregistry.writer zu.
1. Erstellen Sie die E-Mail-Adresse für das Compute Engine-Standarddienstkonto:
```
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com
```
2. Weisen Sie dem Dienstkonto die Rolle roles/artifactregistry.writer zu.
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer
```
Agent-Container-Image erstellen und per Push übertragen: Erstellen Sie im Projektstammverzeichnis (adk/llama/vllm) Ihr Docker-Image und übertragen Sie es per Push in Ihre Artifact Registry, indem Sie die folgenden Befehle ausführen.
```
export IMAGE_URL="${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME/adk-agent:latest"
gcloud builds submit --tag $IMAGE_URL
```
Prüfen, ob das Image per Push übertragen wurde: Nachdem der Buildvorgang erfolgreich abgeschlossen wurde, prüfen Sie, ob das Container-Image Ihres Agents per Push an Artifact Registry übertragen wurde. Dazu listen Sie die Images in Ihrem Repository auf.
```
gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME
```
In der Ausgabe sollte das Image aufgeführt sein, das Sie gerade per Push übertragen und mit dem Tag latest versehen haben.

Modell bereitstellen

Nachdem Sie Ihren GKE-Cluster eingerichtet und das Agent-Image erstellt haben, müssen Sie das selbst gehostete Llama 3.1-Modell in Ihrem Cluster bereitstellen. Dazu stellen Sie einen vorkonfigurierten vLLM-Inferenzserver bereit, der das Modell von Hugging Face abruft und intern im Cluster bereitstellt.

Kubernetes-Secret für Hugging Face-Anmeldedaten erstellen: Damit der GKE-Cluster das Llama 3.1-Modell mit eingeschränktem Zugriff herunterladen kann, müssen Sie Ihr Hugging Face-Token als Kubernetes-Secret angeben. Das deploy-llm.yaml-Manifest ist für die Verwendung dieses Secrets zur Authentifizierung konfiguriert.
```
kubectl create secret generic hf-secret \
    --from-literal=hf-token-secret=HUGGING_FACE_TOKEN
```
Ersetzen Sie HUGGING_FACE_TOKEN durch Ihr Token.
Manifest ansehen: Wechseln Sie vom Stammverzeichnis Ihres Projekts (adk/llama/vllm) zum Verzeichnis /deploy-llm, das das Manifest für die Modellbereitstellung enthält.
```
cd deploy-llm
```
Manifest anwenden: Führen Sie den folgenden Befehl aus, um das Manifest deploy-llm.yaml auf Ihren Cluster anzuwenden.
```
kubectl apply -f deploy-llm.yaml
```
Mit dem Befehl werden drei Kubernetes-Ressourcen erstellt:
- Eine Bereitstellung, auf der der vLLM-Server ausgeführt wird, der für die Verwendung des Modells meta-llama/Llama-3.1-8B-Instruct konfiguriert ist.
- Ein Dienst mit dem Namen vllm-llama3-service, der den vLLM-Server über eine interne Cluster-IP-Adresse verfügbar macht, sodass der ADK-Agent mit ihm kommunizieren kann.
- Eine ConfigMap mit einer Jinja-Chatvorlage, die für das Llama 3.1-Modell erforderlich ist.
Modellbereitstellung prüfen: Der vLLM-Server ruft die Modelldateien von Hugging Face ab. Dieser Vorgang kann einige Minuten dauern. Sie können den Status des Pods überwachen, um sicherzustellen, dass er bereit ist.
1. Warten Sie, bis die Bereitstellung verfügbar ist.
```
kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment
```
2. Sehen Sie sich die Logs des ausgeführten Pods an, um zu bestätigen, dass der Server erfolgreich gestartet wurde.
```
export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $LLM_POD
```
  Die Bereitstellung ist abgeschlossen, wenn Sie eine Logausgabe wie die folgende sehen, die angibt, dass der LLM-Server gestartet wurde und die API-Routen verfügbar sind:
```
INFO 07-16 14:15:16 api_server.py:129] Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```
3. Senden Sie eine Anfrage direkt an den Modellserver, um zu bestätigen, dass das LLM bereit ist. Öffnen Sie dazu ein neues Cloud Shell-Terminal und führen Sie den folgenden Befehl aus, um vllm-llama3-service an Ihren lokalen Computer weiterzuleiten:
```
kubectl port-forward service/vllm-llama3-service 8000:8000
```
4. Senden Sie in einem anderen Terminal mit curl eine Beispielanfrage an den API-Endpunkt des Modells. Beispiel:
```
curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "prompt": "Hello!",
    "max_tokens": 10
  }'
```
  Wenn der Befehl eine erfolgreiche JSON-Antwort zurückgibt, ist Ihr LLM bereit. Sie können den Portweiterleitungsprozess jetzt beenden, indem Sie zum zugehörigen Terminalfenster zurückkehren und Ctrl+C drücken. Fahren Sie dann mit der Bereitstellung des Agents fort.

Agent-Anwendung bereitstellen

Im nächsten Schritt wird die ADK-basierte Agent-Anwendung bereitgestellt.

Zum Verzeichnis /deploy-agent wechseln: Wechseln Sie vom Stammverzeichnis Ihres Projekts (adk/llama/vllm) zum Verzeichnis /deploy-agent, das den Quellcode und das Bereitstellungsmanifest des Agents enthält.
```
cd ../deploy-agent
```
Manifest für die Agent-Bereitstellung aktualisieren:
1. Die deploy-agent.yaml-Beispielmanifestdatei enthält einen Platzhalter für Ihre Projekt-ID in der Container-Image-URL. Sie müssen den Platzhalter durch Ihre Google Cloud Projekt-ID ersetzen.
```
image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest
```
  Um diese Ersetzung vor Ort durchzuführen, können Sie den folgenden Befehl ausführen:
```
sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml
```
2. Achten Sie darauf, dass der Pfad readinessProbe auf / anstatt auf /dev-ui festgelegt ist. Um diese Ersetzung vor Ort durchzuführen, können Sie den folgenden Befehl ausführen:
```
sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml
```
Manifest anwenden: Führen Sie den folgenden Befehl aus, um das Manifest deploy-agent.yaml auf Ihren Cluster anzuwenden.
```
kubectl apply -f deploy-agent.yaml
```
Mit diesem Befehl werden zwei Kubernetes-Ressourcen erstellt:
- Ein Deployment mit dem Namen adk-agent, in dem Ihr benutzerdefiniertes Agent-Container-Image ausgeführt wird.
- Ein Dienst mit dem Namen adk-agent vom Typ „NodePort“, der die Agent-Anwendung verfügbar macht, damit sie für Tests aufgerufen werden kann.
Agent-Bereitstellung überprüfen: Prüfen Sie den Status des Pods, um sicherzustellen, dass er ordnungsgemäß ausgeführt wird.
1. Warten Sie, bis die Bereitstellung verfügbar ist:
```
kubectl wait --for=condition=available --timeout=300s deployment/adk-agent
```
2. So rufen Sie die Logs des laufenden Agent-Pods auf:
```
export AGENT_POD=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $AGENT_POD
```

Die Bereitstellung ist erfolgreich, wenn Sie eine Logausgabe sehen, die in etwa so aussieht und darauf hinweist, dass der Uvicorn-Server ausgeführt wird und bereit ist, Anfragen anzunehmen:

INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

Bereitgestellten Agent testen

Nachdem Sie sowohl den vLLM-Server als auch die Agent-Anwendung bereitgestellt haben, können Sie die End-to-End-Funktionalität testen, indem Sie mit der Web-UI des Agents interagieren.

Dienst des Agents an Ihren lokalen Computer weiterleiten: Der adk-agent-Dienst hat den Typ NodePort. Der direkteste Weg, um in Ihrer Cloud Shell-Umgebung darauf zuzugreifen, ist die Verwendung des Befehls kubectl port-forward. Erstellen Sie einen sicheren Tunnel zum Pod des Agents, indem Sie diesen Befehl ausführen.
```
kubectl port-forward $AGENT_POD 8001:8001
```
Auf die Web-UI des Agents zugreifen: Klicken Sie in Cloud Shell auf die Schaltfläche Webvorschau und wählen Sie Vorschau auf Port 8001 aus. Ein neuer Browsertab wird geöffnet, auf dem die Chatoberfläche des Agents angezeigt wird.
Mit dem Agent interagieren: Stellen Sie dem Agent eine Frage, die sein Tool get_weather aufruft. Beispiel:
```
What's the weather like in Tokyo?
```
Der Agent ruft zuerst das LLM auf, um die Intention zu verstehen und festzustellen, ob das Tool get_weather verwendet werden muss. Anschließend wird das Tool mit „Tokio“ als Parameter ausgeführt. Schließlich wird die Ausgabe des Tools verwendet, um eine Antwort zu generieren. Die Antwort sieht ungefähr so aus:
```
  The weather in Tokyo is 25°C and sunny.
```
(Optional) Tool-Aufruf in den Logs überprüfen: Sie können die Interaktion des Agents mit dem LLM und die Tool-Ausführung beobachten, indem Sie die Logs der entsprechenden Pods aufrufen.
1. Agent-Pod-Logs: Rufen Sie in einem neuen Terminal die Logs des adk-agent-Pods auf. Sie sehen den Tool-Aufruf und das Ergebnis.
```
kubectl logs -f $AGENT_POD
```
  In der Ausgabe wird angezeigt, dass das Tool aufgerufen und das Ergebnis verarbeitet wird.
2. LLM-Pod-Logs: Sehen Sie sich die Logs des vllm-llama3-deployment-Pods an, um die eingehende Anfrage vom Agent zu sehen.
```
kubectl logs -f $LLM_POD
```
  Die Logs enthalten den vollständigen Prompt, der vom Agent an das LLM gesendet wurde, einschließlich der Systemnachricht, Ihrer Anfrage und der Definition des Tools get_weather.

Wenn Sie die Tests abgeschlossen haben, können Sie den port-forward-Prozess beenden, indem Sie zum zugehörigen Terminalfenster zurückkehren und Ctrl+C drücken.