Leistungsstarke, zustandsorientierte, E2E-KI-Agent-Apps in Java mit ADK, AlloyDB und Gemini erstellen

Leistungsstarke, zustandsorientierte, E2E-KI-Agent-Apps in Java mit ADK, AlloyDB und Gemini erstellen

Informationen zu diesem Codelab

Zuletzt aktualisiert: Mai 28, 2025

Verfasst von Author: Abirami Sukumaran

1. Übersicht

In verschiedenen Branchen ist die kontextbezogene Suche eine wichtige Funktion, die im Mittelpunkt ihrer Anwendungen steht. Die Retrieval-Augmented Generation ist mit ihren KI-gestützten Abrufmechanismen seit einiger Zeit ein wichtiger Treiber dieser wichtigen technologischen Entwicklung. Generative Modelle mit ihren großen Kontextfenstern und ihrer beeindruckenden Ausgabequalität verändern die KI. RAG bietet eine systematische Möglichkeit, KI-Anwendungen und -Agenten Kontext zu geben, indem sie auf strukturierten Datenbanken oder Informationen aus verschiedenen Medien basieren. Diese Kontextdaten sind entscheidend für die Klarheit der Wahrheit und die Genauigkeit der Ausgabe. Aber wie genau sind diese Ergebnisse? Hängt Ihr Unternehmen weitgehend von der Genauigkeit dieser kontextbezogenen Übereinstimmungen und der Relevanz ab? Dann ist dieses Projekt genau das Richtige für Sie.

Stellen Sie sich vor, wir könnten die Vorteile generativer Modelle nutzen und interaktive Agenten entwickeln, die in der Lage sind, autonome Entscheidungen auf der Grundlage solcher kontextkritischen Informationen zu treffen und auf Fakten zu basieren. Genau das werden wir heute tun. Wir erstellen eine End-to-End-KI-Agent-App mit dem Agent Development Kit, das auf erweiterter RAG in AlloyDB basiert, für eine Patentanalyseanwendung.

Der Patent Analysis Agent hilft Nutzern, kontextbezogen relevante Patente für ihren Suchbegriff zu finden. Auf Anfrage liefert er eine klare und prägnante Erklärung und bei Bedarf zusätzliche Details zu einem ausgewählten Patent. Möchten Sie sehen, wie das geht? Los gehts!

Ziel

Das Ziel ist einfach. Nutzer sollen anhand einer Textbeschreibung nach Patenten suchen und dann eine detaillierte Erklärung zu einem bestimmten Patent aus den Suchergebnissen erhalten. All dies soll mit einem KI-Agenten erfolgen, der mit Java ADK, AlloyDB, Vector Search (mit erweiterten Indexen), Gemini und der gesamten Anwendung erstellt wurde, die serverlos auf Cloud Run bereitgestellt wird.

Aufgaben

In diesem Lab lernen Sie Folgendes:

1. AlloyDB-Instanz erstellen und Daten aus dem öffentlichen Patent-Dataset laden
2. Erweiterte Vektorsuche in AlloyDB mit den Bewertungsfunktionen „ScaNN“ und „Recall“ implementieren
3. Agent mit dem Java ADK erstellen
4. Die serverseitige Datenbanklogik in Java-serverlosen Cloud Functions implementieren
5. Agent in Cloud Run bereitstellen und testen

Das folgende Diagramm stellt den Datenfluss und die Schritte bei der Implementierung dar.

High level diagram representing the flow of the Patent Search Agent with AlloyDB & ADK

Voraussetzungen

• Ein Browser, z. B. Chrome oder Firefox
• Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.

2. Hinweis

Projekt erstellen

1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.
3. Sie verwenden Cloud Shell, eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird. Klicken Sie oben in der Google Cloud Console auf „Cloud Shell aktivieren“.

4. Nachdem Sie eine Verbindung zu Cloud Shell hergestellt haben, prüfen Sie mit dem folgenden Befehl, ob Sie bereits authentifiziert sind und das Projekt auf Ihre Projekt-ID festgelegt ist:

gcloud auth list

5. Führen Sie in Cloud Shell den folgenden Befehl aus, um zu prüfen, ob der gcloud-Befehl Ihr Projekt kennt.

gcloud config list project

6. Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:

gcloud config set project <YOUR_PROJECT_ID>

7. Aktivieren Sie die erforderlichen APIs. Sie können einen gcloud-Befehl im Cloud Shell-Terminal verwenden:

gcloud services enable alloydb.googleapis.com compute.googleapis.com cloudresourcemanager.googleapis.com servicenetworking.googleapis.com run.googleapis.com cloudbuild.googleapis.com cloudfunctions.googleapis.com aiplatform.googleapis.com

Alternativ können Sie in der Console nach den einzelnen Produkten suchen oder diesen Link verwenden.

Weitere Informationen zu gcloud-Befehlen und deren Verwendung finden Sie in der Dokumentation.

3. Datenbank einrichten

In diesem Lab verwenden wir AlloyDB als Datenbank für die Patentdaten. Alle Ressourcen wie Datenbanken und Protokolle werden in Clustern gespeichert. Jeder Cluster hat eine primäre Instanz, die einen Zugriffspunkt auf die Daten bietet. Die tatsächlichen Daten werden in Tabellen gespeichert.

Erstellen Sie einen AlloyDB-Cluster, eine Instanz und eine Tabelle, in die der Patentdatensatz geladen wird.

Cluster und Instanz erstellen

1. Rufen Sie in der Cloud Console die Seite „AlloyDB“ auf. Die meisten Seiten in der Cloud Console lassen sich ganz einfach über die Suchleiste der Console finden.
2. Wählen Sie auf dieser Seite CLUSTER ERSTELLEN aus:

3. Daraufhin wird ein Bildschirm wie der unten gezeigte angezeigt. Erstellen Sie einen Cluster und eine Instanz mit den folgenden Werten. Achten Sie darauf, dass die Werte übereinstimmen, falls Sie den Anwendungscode aus dem Repository klonen:

• Cluster-ID: "vector-cluster"
• password: "alloydb"
• PostgreSQL 15 / neueste empfohlene Version
• Region: "us-central1"
• Netzwerk: „default“

4. Wenn Sie das Standardnetzwerk auswählen, wird ein Bildschirm wie der unten angezeigt.

Wählen Sie VERKNÜPFUNG EINSTELLEN aus.

5. Wählen Sie dort Automatisch zugewiesenen IP-Bereich verwenden aus und klicken Sie auf „Weiter“. Nachdem Sie sich die Informationen angesehen haben, wählen Sie „VERKNÜPFUNG ERSTELLEN“ aus.
6. Sobald Ihr Netzwerk eingerichtet ist, können Sie mit dem Erstellen des Clusters fortfahren. Klicken Sie auf CLUSTER ERSTEHEN, um die Einrichtung des Clusters abzuschließen (siehe unten):

Ändern Sie die Instanz-ID (die Sie bei der Konfiguration des Clusters / der Instanz finden) in

vector-instance. Wenn Sie sie nicht ändern können, denken Sie daran, in allen nachfolgenden Verweisen Ihre Instanz-ID zu verwenden.

Die Clustererstellung dauert etwa 10 Minuten. Wenn der Vorgang erfolgreich war, sollte ein Bildschirm mit einer Übersicht über den gerade erstellten Cluster angezeigt werden.

4. Datenaufnahme

Jetzt fügen Sie eine Tabelle mit den Daten zum Geschäft hinzu. Rufen Sie AlloyDB auf, wählen Sie den primären Cluster und dann AlloyDB Studio aus:

Möglicherweise müssen Sie warten, bis die Instanz erstellt wurde. Melden Sie sich dann mit den Anmeldedaten an, die Sie beim Erstellen des Clusters erstellt haben. Verwenden Sie die folgenden Daten für die Authentifizierung bei PostgreSQL:

• Nutzername: „postgres“
• Datenbank: „postgres“
• Passwort: „alloydb“

Nachdem Sie sich erfolgreich in AlloyDB Studio authentifiziert haben, werden SQL-Befehle in den Editor eingegeben. Über das Pluszeichen rechts neben dem letzten Fenster können Sie weitere Editorfenster hinzufügen.

Sie geben Befehle für AlloyDB in Editorfenstern ein und verwenden nach Bedarf die Optionen „Ausführen“, „Formatieren“ und „Löschen“.

Erweiterungen aktivieren

Für die Erstellung dieser App verwenden wir die Erweiterungen pgvector und google_ml_integration. Mit der pgvector-Erweiterung können Sie Vektoreinbettungen speichern und darin suchen. Die Erweiterung google_ml_integration bietet Funktionen, mit denen Sie auf Vertex AI-Vorhersageendpunkte zugreifen und Vorhersagen in SQL abrufen können. Aktivieren Sie diese Erweiterungen, indem Sie die folgenden DDLs ausführen:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

Wenn Sie die in Ihrer Datenbank aktivierten Erweiterungen prüfen möchten, führen Sie diesen SQL-Befehl aus:

select extname, extversion from pg_extension;

Tabelle erstellen

Sie können eine Tabelle mit der folgenden DDL-Anweisung in AlloyDB Studio erstellen:

CREATE TABLE patents_data ( id VARCHAR(25), type VARCHAR(25), number VARCHAR(20), country VARCHAR(2), date VARCHAR(20), abstract VARCHAR(300000), title VARCHAR(100000), kind VARCHAR(5), num_claims BIGINT, filename VARCHAR(100), withdrawn BIGINT, abstract_embeddings vector(768)) ;

In der Spalte „abstract_embeddings“ können die Vektorwerte des Textes gespeichert werden.

Berechtigung gewähren

Führen Sie die folgende Anweisung aus, um die Ausführung der Funktion „embedding“ zu gewähren:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Dem AlloyDB-Dienstkonto die Rolle „Vertex AI User“ gewähren

Gewähren Sie in der Google Cloud IAM-Konsole dem AlloyDB-Dienstkonto (in diesem Beispiel: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) Zugriff auf die Rolle „Vertex AI-Nutzer“. PROJECT_NUMBER enthält Ihre Projektnummer.

Alternativ können Sie den folgenden Befehl über das Cloud Shell-Terminal ausführen:

PROJECT_ID=$(gcloud config get-value project)


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

Patentdaten in die Datenbank laden

Als Dataset verwenden wir die öffentlichen Datasets von Google Patents in BigQuery. Wir verwenden AlloyDB Studio, um unsere Abfragen auszuführen. Die Daten werden in diese Datei insert_scripts.sql kopiert und wir führen sie aus, um die Patentdaten zu laden.

1. Öffnen Sie in der Google Cloud Console die Seite AlloyDB.
2. Wählen Sie den neu erstellten Cluster aus und klicken Sie auf die Instanz.
3. Klicken Sie im AlloyDB-Navigationsmenü auf AlloyDB Studio. Melden Sie sich mit Ihren Anmeldedaten an.
4. Öffnen Sie einen neuen Tab, indem Sie rechts auf das Symbol Neuer Tab klicken.
5. Kopieren Sie die insert-Abfrage aus dem oben genannten insert_scripts.sql-Script in den Editor. Sie können 10 bis 50 INSERT-Anweisungen kopieren, um eine kurze Demo dieses Anwendungsfalls zu erhalten.
6. Klicken Sie auf Ausführen. Die Ergebnisse der Abfrage werden in der Tabelle Ergebnisse angezeigt.

5. Einbettungen für Patentdaten erstellen

Testen wir zuerst die Einbettungsfunktion. Führen Sie dazu die folgende Beispielabfrage aus:

SELECT embedding('text-embedding-005', 'AlloyDB is a managed, cloud-hosted SQL database service.');

Dadurch sollte der Einbettungsvektor für den Beispieltext in der Abfrage zurückgegeben werden. Er sieht aus wie ein Array von Gleitkommazahlen. Sie sieht so aus:

Vektorfeld „abstract_embeddings“ aktualisieren

Führen Sie die folgende DML-Anweisung aus, um die Patentabstrakte in der Tabelle mit den entsprechenden Einbettungen zu aktualisieren:

UPDATE patents_data set abstract_embeddings = embedding( 'text-embedding-005', abstract);

6. Vektorsuche ausführen

Nachdem Tabelle, Daten und Einbettungen bereit sind, führen wir die Echtzeit-Vektorsuche für den Suchtext des Nutzers durch. Sie können dies mit der folgenden Abfrage testen:

SELECT id || ' - ' || title as title FROM patents_data ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

In dieser Abfrage:

1. Der Nutzer hat nach „Sentimentanalyse“ gesucht.
2. Wir wandeln ihn in der Methode „embedding()“ mit dem Modell „text-embedding-005“ in Einbettungen um.
3. „<=>“ steht für die Verwendung der KOSINUS-ÄHNLICHKEIT-Distanzmethode.
4. Wir konvertieren das Ergebnis der Einbettungsmethode in den Vektortyp, damit es mit den in der Datenbank gespeicherten Vektoren kompatibel ist.
5. Mit LIMIT 10 werden die zehn Übereinstimmungen ausgewählt, die dem Suchtext am nächsten kommen.

AlloyDB hebt die Vektorsuche mit RAG auf ein neues Level:

Es gibt eine ganze Reihe von Neuerungen. Zwei der auf Entwickler ausgerichteten Programme sind:

1. Inline-Filterung
2. Recall-Bewerter

Inline-Filterung

Bisher mussten Entwickler die Vector Search-Abfrage ausführen und sich um die Filterung und das Abrufen kümmern. Der AlloyDB-Abfrageoptimierer trifft Entscheidungen dazu, wie eine Abfrage mit Filtern ausgeführt wird. Das Inline-Filtern ist eine neue Abfrageoptimierungstechnik, mit der der AlloyDB-Abfrageoptimierer sowohl die Metadatenfilterbedingungen als auch die Vektorsuche gleichzeitig auswerten kann. Dabei werden sowohl Vektorindexe als auch Indexe für die Metadatenspalten verwendet. Dadurch konnte die Abrufleistung gesteigert werden, sodass Entwickler die Vorteile von AlloyDB direkt nutzen können.

Inline-Filter eignen sich am besten für Fälle mit mittlerer Selektivität. Wenn AlloyDB den Vektorindex durchsucht, werden nur Entfernungen für Vektoren berechnet, die den Metadatenfilterbedingungen entsprechen (Ihre funktionalen Filter in einer Abfrage, die normalerweise in der WHERE-Klausel verarbeitet werden). Dadurch wird die Leistung dieser Abfragen erheblich verbessert und die Vorteile von Post-Filtern oder Pre-Filtern ergänzt.

1. pgvector-Erweiterung installieren oder aktualisieren

CREATE EXTENSION IF NOT EXISTS vector WITH VERSION '0.8.0.google-3';

Wenn die pgvector-Erweiterung bereits installiert ist, führen Sie ein Upgrade auf Version 0.8.0.google-3 oder höher aus, um die Funktionen der Abrufbewertung zu nutzen.

ALTER EXTENSION vector UPDATE TO '0.8.0.google-3';

Dieser Schritt muss nur ausgeführt werden, wenn Ihre Vektorerweiterung <0.8.0.google-3 ist.

Wichtiger Hinweis:Wenn die Zeilenanzahl weniger als 100 beträgt, müssen Sie den ScaNN-Index nicht erstellen, da er bei weniger Zeilen nicht verwendet wird. Überspringen Sie in diesem Fall die folgenden Schritte.

2. Wenn Sie ScaNN-Indexe erstellen möchten, installieren Sie die Erweiterung „alloydb_scann“.

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

3. Führen Sie zuerst die Vektorsuchabfrage ohne Index und ohne aktivierten Inline-Filter aus:

SELECT id || ' - ' || title as title FROM patents_data 
WHERE num_claims >= 15 
ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

Das Ergebnis sollte in etwa so aussehen:

4. Führen Sie „Erläutern und analysieren“ darauf aus (ohne Index und ohne Inline-Filterung):

Die Ausführungszeit beträgt 2,4 ms.

5. Erstellen wir einen regulären Index für das Feld „num_claims“, damit wir danach filtern können:

CREATE INDEX idx_patents_data_num_claims ON patents_data (num_claims);

6. Erstellen wir den ScaNN-Index für unsere Patentrecherche-Anwendung. Führen Sie in AlloyDB Studio Folgendes aus:

CREATE INDEX patent_index ON patents_data 
USING scann (abstract_embeddings cosine)
WITH (num_leaves=32);

Wichtiger Hinweis : (num_leaves=32) gilt für den gesamten Datensatz mit mehr als 1.000 Zeilen. Wenn die Zeilenanzahl weniger als 100 beträgt, müssen Sie keinen Index erstellen, da er bei weniger Zeilen nicht angewendet wird.

7. Aktivieren Sie die Inline-Filterung für den ScaNN-Index:

SET scann.enable_inline_filtering = on

8. Führen Sie jetzt dieselbe Abfrage mit Filter und Vektorsuche aus:

SELECT id || ' - ' || title as title FROM patents_data 
WHERE num_claims >= 15 
ORDER BY abstract_embeddings <=> embedding('text-embedding-005', 'Sentiment Analysis')::vector LIMIT 10;

Wie Sie sehen, wird die Ausführungszeit für dieselbe Vektorsuche deutlich reduziert. Das war dank des ScaNN-Index mit Inline-Filterung in der Vektorsuche möglich.

Als Nächstes bewerten wir die Trefferquote für diese ScaNN-fähige Vektorsuche.

Recall-Bewerter

Die Trefferquote bei der Ähnlichkeitssuche ist der Prozentsatz der relevanten Instanzen, die bei einer Suche zurückgegeben wurden, d.h. die Anzahl der echten positiven Ergebnisse. Dies ist der am häufigsten verwendete Messwert für die Suchqualität. Eine Ursache für den Rückgang des Recalls ist der Unterschied zwischen der Suche nach dem ungefähren nächsten Nachbarn (Approximate Nearest Neighbor, ANN) und der Suche nach dem k-ten (genauen) nächsten Nachbarn (k-Nearest Neighbor, KNN). Vektorindizes wie ScaNN von AlloyDB implementieren ANN-Algorithmen, mit denen sich die Vektorsuche in großen Datenmengen beschleunigen lässt, allerdings mit einem kleinen Einbußen beim Recall. Mit AlloyDB können Sie diesen Trade-off jetzt direkt in der Datenbank für einzelne Abfragen messen und dafür sorgen, dass er im Zeitverlauf stabil bleibt. Sie können die Abfrage- und Indexparameter anhand dieser Informationen aktualisieren, um bessere Ergebnisse und eine bessere Leistung zu erzielen.

Mit der Funktion evaluate_query_recall können Sie die Trefferquote für eine Vektorabfrage in einem Vektorindex für eine bestimmte Konfiguration ermitteln. Mit dieser Funktion können Sie Ihre Parameter so anpassen, dass Sie die gewünschten Ergebnisse für die Aufzählung von Ergebnissen für die Vektorabfrage erzielen. Der Recall ist der Messwert für die Suchqualität und wird als Prozentsatz der zurückgegebenen Ergebnisse definiert, die den Abfragevektoren objektiv am nächsten sind. Die Funktion evaluate_query_recall ist standardmäßig aktiviert.

Wichtiger Hinweis:

Wenn Sie bei den folgenden Schritten eine Fehlermeldung zur fehlenden Berechtigung für den HNSW-Index erhalten, überspringen Sie diesen gesamten Abschnitt zur Erinnerungsbewertung. Das kann an Zugriffsbeschränkungen liegen, da die Funktion zum Zeitpunkt der Dokumentation dieses Codelabs gerade erst veröffentlicht wurde.

1. Setzen Sie das Flag „Index-Scan aktivieren“ für den ScaNN-Index und den HNSW-Index:

SET scann.enable_indexscan = on
SET hnsw.enable_index_scan = on

2. Führen Sie in AlloyDB Studio die folgende Abfrage aus:

SELECT
  *
FROM
  evaluate_query_recall($$
  SELECT
    id || ' - ' || title AS title,
    abstract
  FROM
    patents_data
    where num_claims >= 15
  ORDER BY
    abstract_embeddings <=> embedding('text-embedding-005',
      'sentiment analysis')::vector
  LIMIT 25 $$,
    '{"scann.num_leaves_to_search":1, "scann.pre_reordering_num_neighbors":10}',
    ARRAY['scann']);

Die Funktion „evaluate_query_recall“ nimmt die Abfrage als Parameter entgegen und gibt die Trefferquote zurück. Ich verwende dieselbe Abfrage, die ich zur Leistungsprüfung verwendet habe, als Eingabeabfrage für die Funktion. Ich habe SCaNN als Indexmethode hinzugefügt. Weitere Parameteroptionen finden Sie in der Dokumentation.

Die Trefferquote für diese Vektorsuchabfrage, die wir verwendet haben:

Ich sehe, dass der RECALL 70 % beträgt. Jetzt kann ich diese Informationen verwenden, um die Indexparameter, Methoden und Abfrageparameter zu ändern und die Trefferquote für diese Vektorsuche zu verbessern.

Ich habe die Anzahl der Zeilen im Ergebnissatz auf 7 geändert (vorher 10) und sehe eine leicht verbesserte RECALL-Rate von 86%.

So kann ich in Echtzeit die Anzahl der Übereinstimmungen variieren, die meine Nutzer sehen, um die Relevanz der Übereinstimmungen entsprechend dem Suchkontext der Nutzer zu verbessern.

Alles klar. Es ist an der Zeit, die Datenbanklogik bereitzustellen und mit dem Agenten fortzufahren.

7. Datenbanklogik serverlos im Web nutzen

Sind Sie bereit, diese App im Web zu veröffentlichen? Gehen Sie dazu so vor:

1. Rufen Sie in der Google Cloud Console „Cloud Run-Funktionen“ auf, um eine neue Cloud Run-Funktion zu erstellen, oder verwenden Sie den Link https://console.cloud.google.com/functions/add.
2. Wählen Sie als Umgebung Cloud Run-Funktion aus. Geben Sie den Funktionsnamen „patent-search“ ein und wählen Sie als Region „us-central1“ aus. Wählen Sie für die Authentifizierung die Option Nicht authentifizierte Aufrufe zulassen aus und klicken Sie auf WEITER. Wählen Sie Java 17 als Laufzeit und den Inline-Editor für den Quellcode aus.
3. Standardmäßig wird der Einstiegspunkt auf gcfv2.HelloHttpFunction festgelegt. Ersetzen Sie den Platzhaltercode in HelloHttpFunction.java und pom.xml Ihrer Cloud Run-Funktion durch den Code aus PatentSearch.java bzw. pom.xml. Ändern Sie den Namen der Klassendatei in „PatentSearch.java“.
4. Ersetzen Sie den Platzhalter ************* und die AlloyDB-Anmeldedaten in der Java-Datei durch Ihre Werte. Die AlloyDB-Anmeldedaten sind dieselben, die wir zu Beginn dieses Codelabs verwendet haben. Wenn Sie andere Werte verwendet haben, ändern Sie diese bitte in der Java-Datei.
5. Klicken Sie auf Bereitstellen.

WICHTIG:

Nach der Bereitstellung erstellen wir den VPC-Connector, damit die Cloud-Funktion auf unsere AlloyDB-Datenbankinstanz zugreifen kann.

Sobald die Bereitstellung abgeschlossen ist, sollten Sie die Funktionen in der Google Cloud Run Functions-Konsole sehen können. Suchen Sie nach der neu erstellten Funktion (patent-search), klicken Sie darauf und dann auf „NEUE ÜBERARBEITUNGEN BEARBEITEN UND ERSTELLEN“ (kenntlich am Symbol „BEARBEITEN“ (Stift) oben in der Cloud Run Functions Console). Ändern Sie Folgendes:

1. Rufen Sie den Tab „Netzwerk“ auf:

2. Wählen Sie Mit einer VPC für ausgehenden Traffic verbinden und dann Connectors für serverlosen VPC-Zugriff verwenden aus.
3. Klicken Sie im Drop-down-Menü „Netzwerk“ auf die Option Neuen VPC-Connector hinzufügen, falls Sie den Standard-VPC-Connector noch nicht konfiguriert haben. Folgen Sie dann der Anleitung im Pop-up-Dialogfeld:

4. Geben Sie einen Namen für den VPC-Connector an und achten Sie darauf, dass die Region mit der Ihrer Instanz übereinstimmt. Lassen Sie den Wert für „Netzwerk“ als Standard bei und legen Sie „Subnetz“ als benutzerdefinierten IP-Bereich mit dem IP-Bereich 10.8.0.0 oder einem ähnlichen verfügbaren Bereich fest.
5. Maximieren Sie die Konfiguration „ANZEIGENSKALIBRIERUNGS-EINSTELLUNGEN“ und prüfen Sie, ob die folgenden Einstellungen festgelegt sind:

6. Klicken Sie auf ERSTELLEN. Dieser Connector sollte jetzt in den Einstellungen für ausgehenden Traffic aufgeführt sein.
7. Wählen Sie den neu erstellten Connector aus.
8. Legen Sie fest, dass der gesamte Traffic über diesen VPC-Connector weitergeleitet werden soll.
9. Klicken Sie auf WEITER und dann auf Bereitstellen.
10. Sobald die aktualisierte Cloud-Funktion bereitgestellt wurde, sollte der generierte Endpunkt angezeigt werden. Kopieren Sie diese Zeichenfolge und ersetzen Sie sie im folgenden Befehl:

PROJECT_ID=$(gcloud config get-value project)

curl -X POST <<YOUR_ENDPOINT>> \
  -H 'Content-Type: application/json' \
  -d '{"search":"Sentiment Analysis"}'

Geschafft! So einfach ist es, mit dem Einbettungsmodell eine erweiterte Suche nach Vektorähnlichkeiten in AlloyDB-Daten durchzuführen.

8. Agent mit dem Java ADK erstellen

Beginnen wir zuerst mit dem Java-Projekt im Editor.

1. Cloud Shell-Terminal aufrufen

https://shell.cloud.google.com/?fromcloudshell=true&show=ide%2Cterminal

2. Autorisieren, wenn Sie dazu aufgefordert werden
3. Klicken Sie oben in der Cloud Shell-Konsole auf das Editorsymbol, um zum Cloud Shell-Editor zu wechseln.

4. Erstellen Sie in der Cloud Shell-Editor-Konsole einen neuen Ordner und nennen Sie ihn „adk-agents“.

Klicken Sie im Stammverzeichnis Ihrer Cloud Shell auf „Neuen Ordner erstellen“, wie unten dargestellt:

Geben Sie ihm den Namen „adk-agents“:

5. Erstellen Sie die folgende Ordnerstruktur und die leeren Dateien mit den entsprechenden Dateinamen in der folgenden Struktur:

adk-agents/
 └—— pom.xml
 └—— src/ 
     └—— main/
         └—— java/
             └—— agents/
                 └—— App.java

6. Öffnen Sie das GitHub-Repository in einem separaten Tab und kopieren Sie den Quellcode für die Dateien „App.java“ und „pom.xml“.
7. Wenn Sie den Editor über das Symbol „In neuem Tab öffnen“ oben rechts in einem neuen Tab geöffnet haben, können Sie das Terminal unten auf der Seite öffnen. Sie können sowohl den Editor als auch das Terminal parallel öffnen, um frei arbeiten zu können.
8. Wechseln Sie nach dem Klonen zurück zur Cloud Shell-Editor-Konsole.
9. Da wir die Cloud Run-Funktion bereits erstellt haben, müssen Sie die Cloud Run-Funktionsdateien nicht aus dem Repository-Ordner kopieren.

Erste Schritte mit dem ADK Java SDK

Das ist ziemlich einfach. Achten Sie vor allem darauf, dass beim Klonen Folgendes berücksichtigt wird:

1. Abhängigkeiten hinzufügen:

Fügen Sie die Artefakte „google-adk“ und „google-adk-dev“ (für die Web-Benutzeroberfläche) in „pom.xml“ ein.

<!-- The ADK core dependency -->
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk</artifactId>
            <version>0.1.0</version>
        </dependency>
        <!-- The ADK dev web UI to debug your agent -->
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk-dev</artifactId>
            <version>0.1.0</version>
        </dependency>

Verweisen Sie auf die pom.xml aus dem Quellverzeichnis, da es andere Abhängigkeiten und Konfigurationen gibt, die für die Ausführung der Anwendung erforderlich sind.

2. Projekt konfigurieren:

Prüfen Sie, ob die Java-Version (17 oder höher empfohlen) und die Maven-Compiler-Einstellungen in Ihrer pom.xml-Datei korrekt konfiguriert sind. Sie können Ihr Projekt so konfigurieren, dass es der folgenden Struktur folgt:

adk-agents/
 └—— pom.xml
 └—— src/ 
     └—— main/
         └—— java/
             └—— agents/
                 └—— App.java

3. Agent und seine Tools definieren (App.java):

Hier kommt das ADK Java SDK ins Spiel. Wir definieren unseren Bot, seine Funktionen (Anweisungen) und die Tools, die er verwenden kann.

Hier finden Sie eine vereinfachte Version einiger Code-Snippets der Haupt-Kundenservicemitarbeiterklasse. Das vollständige Projekt finden Sie in diesem Repository.

// App.java (Simplified Snippets)
package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.InvocationContext;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
// ... other imports

public class App {

    static FunctionTool searchTool = FunctionTool.create(App.class, "getPatents");
    static FunctionTool explainTool = FunctionTool.create(App.class, "explainPatent");

    public static BaseAgent ROOT_AGENT = initAgent();

    public static BaseAgent initAgent() {
        return LlmAgent.builder()
            .name("patent-search-agent")
            .description("Patent Search agent")
            .model("gemini-2.0-flash-001") // Specify your desired Gemini model
            .instruction(
                """
                You are a helpful patent search assistant capable of 2 things:
                // ... complete instructions ...
                """)
            .tools(searchTool, explainTool)
            .outputKey("patents") // Key to store tool output in session state
            .build();
    }

    // --- Tool: Get Patents ---
    public static Map<String, String> getPatents(
        @Schema(name="searchText",description = "The search text for which the user wants to find matching patents")
        String searchText) {
        try {
            String patentsJson = vectorSearch(searchText); // Calls our Cloud Run Function
            return Map.of("status", "success", "report", patentsJson);
        } catch (Exception e) {
            // Log error
            return Map.of("status", "error", "report", "Error fetching patents.");
        }
    }

    // --- Tool: Explain Patent (Leveraging InvocationContext) ---
    public static Map<String, String> explainPatent(
        @Schema(name="patentId",description = "The patent id for which the user wants to get more explanation for, from the database") 
    String patentId, 
    @Schema(name="ctx",description = "The list of patent abstracts from the database from which the user can pick the one to get more explanation for") 
    InvocationContext ctx) { // Note the InvocationContext
        try {
            // Retrieve previous patent search results from session state
            String previousResults = (String) ctx.session().state().get("patents");
            if (previousResults != null && !previousResults.isEmpty()) {
// Logic to find the specific patent abstract from 'previousResults' by 'patentId'
                String[] patentEntries = previousResults.split("\n\n\n\n"); 
                for (String entry : patentEntries) {
                    if (entry.contains(patentId)) { // Simplified check
       // The agent will then use its instructions to summarize this 'report'
                        return Map.of("status", "success", "report", entry);
                    }
                }
            }
            return Map.of("status", "error", "report", "Patent ID not found in previous search.");
        } catch (Exception e) {
            // Log error
            return Map.of("status", "error", "report", "Error explaining patent.");
        }
    }

    public static void main(String[] args) throws Exception {
        InMemoryRunner runner = new InMemoryRunner(ROOT_AGENT);
        // ... (Session creation and main input loop - shown in your source)
    }
}

Hervorgehobene wichtige ADK-Java-Codekomponenten:

1. LlmAgent.builder(): Fluent API zum Konfigurieren Ihres Agents.
2. .instruction(...): Enthält den Hauptvorschlag und die Richtlinien für das LLM, einschließlich der Informationen dazu, wann welches Tool verwendet werden soll.
3. FunctionTool.create(App.class, "methodName"): Hiermit können Sie Ihre Java-Methoden ganz einfach als Tools registrieren, die der Kundenservicemitarbeiter aufrufen kann. Der String für den Methodennamen muss mit einer tatsächlichen öffentlichen statischen Methode übereinstimmen.
4. @Schema(description = ...): Hiermit werden Toolparameter annotiert, damit das LLM weiß, welche Eingaben von jedem Tool erwartet werden. Diese Beschreibung ist entscheidend für die korrekte Toolauswahl und Parameterausfüllung.
5. InvocationContext ctx:Wird automatisch an Toolmethoden übergeben und bietet unter anderem Zugriff auf den Sitzungsstatus (ctx.session().state()) und Nutzerinformationen.
6. .outputKey("patents"): Wenn ein Tool Daten zurückgibt, kann ADK diese automatisch im Sitzungsstatus unter diesem Schlüssel speichern. So kann „explainPatent“ auf die Ergebnisse von „getPatents“ zugreifen.
7. VECTOR_SEARCH_ENDPOINT::Diese Variable enthält die Hauptfunktionslogik für die kontextbezogenen Fragen und Antworten für den Nutzer im Anwendungsfall der Patentrecherche.
8. Zu tun: Sie müssen einen aktualisierten Wert für den bereitgestellten Endpunkt festlegen, sobald Sie den Schritt „Java-Cloud Run-Funktion“ aus dem vorherigen Abschnitt implementiert haben.
9. searchTool: Hier wird der Nutzer gebeten, kontextbezogene Patentübereinstimmungen aus der Patentdatenbank für den Suchtext des Nutzers zu finden.
10. explainTool: Der Nutzer wird nach einem bestimmten Patent gefragt, zu dem er mehr erfahren möchte. Anschließend fasst er den Patentabstrakt zusammen und kann anhand der Patentdetails weitere Fragen des Nutzers beantworten.

Wichtiger Hinweis: Ersetzen Sie die Variable VECTOR_SEARCH_ENDPOINT durch den bereitgestellten CRF-Endpunkt.

InvocationContext für zustandsorientierte Interaktionen nutzen

Eine der wichtigsten Funktionen für die Entwicklung nützlicher Chatbots ist die Verwaltung des Status über mehrere Gesprächsrunden hinweg. Der InvocationContext der ADK macht das ganz einfach.

In App.java:

1. Wenn initAgent() definiert ist, verwenden wir .outputKey("patents"). So wird ADK mitgeteilt, dass Daten, die ein Tool wie „getPatents“ in seinem Berichtsfeld zurückgibt, im Sitzungsstatus unter dem Schlüssel „patents“ gespeichert werden sollen.
2. In der Methode des Tools „explainPatent“ fügen wir den InvocationContext ctx ein:

public static Map<String, String> explainPatent(
    @Schema(description = "...") String patentId, InvocationContext ctx) {
    String previousResults = (String) ctx.session().state().get("patents");
    // ... use previousResults ...
}

So kann das Tool „explainPatent“ auf die Patentliste zugreifen, die in einer vorherigen Gesprächsrunde vom Tool „getPatents“ abgerufen wurde. Dadurch wird die Unterhaltung zustands- und kohärent.

9. Lokale Befehlszeilentests

Umgebungsvariablen definieren

Sie müssen zwei Umgebungsvariablen exportieren:

1. Einen Gemini-Schlüssel, den Sie in AI Studio abrufen können:

Rufen Sie dazu https://aistudio.google.com/apikey auf und rufen Sie den API-Schlüssel für Ihr aktives Google Cloud-Projekt ab, in dem Sie diese Anwendung implementieren. Speichern Sie den Schlüssel an einem beliebigen Ort:

1. Nachdem Sie den Schlüssel erhalten haben, öffnen Sie das Cloud Shell-Terminal und wechseln Sie mit dem folgenden Befehl zum neuen Verzeichnis „adk-agents“, das wir gerade erstellt haben:

cd adk-agents

2. Eine Variable, mit der angegeben wird, dass wir Vertex AI dieses Mal nicht verwenden.

export GOOGLE_GENAI_USE_VERTEXAI=FALSE
export GOOGLE_API_KEY=AIzaSyDF...

3. Ersten Agenten in der Befehlszeile ausführen

Verwenden Sie den folgenden Maven-Befehl in Ihrem Terminal, um diesen ersten Agenten zu starten:

mvn compile exec:java -DmainClass="agents.App"

Die interaktive Antwort des Kundenservicemitarbeiters wird in Ihrem Terminal angezeigt.

10. In Cloud Run bereitstellen

Das Bereitstellen Ihres ADK-Java-Agents in Cloud Run ähnelt dem Bereitstellen jeder anderen Java-Anwendung:

1. Dockerfile: Erstellen Sie ein Dockerfile, um Ihre Java-Anwendung zu verpacken.
2. Docker-Image erstellen und hochladen: Verwenden Sie Google Cloud Build und Artifact Registry.
3. Sie können den obigen Schritt ausführen und mit nur einem Befehl in Cloud Run bereitstellen:

gcloud run deploy --source . --set-env-vars GOOGLE_API_KEY=<<Your_Gemini_Key>>

Ähnlich stellen Sie Ihre Java-Cloud Run-Funktion (gcfv2.PatentSearch) bereit. Alternativ können Sie die Java-Cloud Run-Funktion für die Datenbanklogik direkt über die Cloud Run Functions-Konsole erstellen und bereitstellen.

11. Mit der Web-UI testen

Die ADK bietet eine praktische Web-UI für lokale Tests und Fehlerbehebungen Ihres Agents. Wenn Sie App.java lokal ausführen (z.B. mvn exec:java -Dexec.mainClass="agents.App", falls konfiguriert, oder nur die main-Methode ausführen), startet die ADK in der Regel einen lokalen Webserver.

Mit der ADK-Web-UI haben Sie folgende Möglichkeiten:

1. Senden Sie Nachrichten an Ihren Kundenservicemitarbeiter.
2. Sehen Sie sich die Ereignisse an (Nutzernachricht, Toolaufruf, Toolantwort, LLM-Antwort).
3. Prüfen Sie den Sitzungsstatus.
4. Logs und Traces ansehen

Das ist während der Entwicklung von unschätzbarem Wert, um zu verstehen, wie Ihr Agent Anfragen verarbeitet und seine Tools verwendet. Dabei wird davon ausgegangen, dass Ihre mainClass in pom.xml auf com.google.adk.web.AdkWebServer festgelegt ist und Ihr Agent dort registriert ist oder Sie einen lokalen Test-Runner ausführen, der dies freigibt.

Wenn Sie Ihre App.java mit dem InMemoryRunner und dem Scanner für die Konsoleneingabe ausführen, testen Sie die Agent-Kernlogik. Die Web-Benutzeroberfläche ist eine separate Komponente für eine visuellere Fehlerbehebung. Sie wird häufig verwendet, wenn ADK Ihren Agenten über HTTP bereitstellt.

Mit dem folgenden Maven-Befehl können Sie im Stammverzeichnis den lokalen SpringBoot-Server starten:

mvn compile exec:java -Dexec.args="--adk.agents.source-dir=src/main/java/ --logging.level.com.google.adk.dev=TRACE --logging.level.com.google.adk.demo.agents=TRACE"

Oft ist die Benutzeroberfläche unter der URL verfügbar, die der obige Befehl ausgibt. Wenn es in Cloud Run bereitgestellt wurde, sollten Sie über den Cloud Run-Bereitstellungslink darauf zugreifen können.

Das Ergebnis sollte in einer interaktiven Benutzeroberfläche angezeigt werden.

Im Video unten sehen Sie unseren eingesetzten Patentanwalt:

Demo eines qualitätskontrollierten Patent-Agenten mit AlloyDB-Inline-Suche und Abrufbewertung

12. Bereinigen

Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud-Konto die in diesem Beitrag verwendeten Ressourcen in Rechnung gestellt werden:

1. Rufen Sie in der Google Cloud Console https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog auf.
2. https://console.cloud.google.com/cloud-resource-manager?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog
3. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie auf Löschen.
4. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Beenden, um das Projekt zu löschen.

13. Glückwunsch

Glückwunsch! Sie haben Ihren Patent Analysis Agent in Java erfolgreich erstellt, indem Sie die Funktionen von ADK, https://cloud.google.com/alloydb/docs?utm_campaign=CDR_0x1d2a42f5_default_b419133749&utm_medium=external&utm_source=blog, Vertex AI und Vector Search kombiniert haben. Außerdem haben wir einen großen Schritt nach vorne gemacht, um kontextbezogene Ähnlichkeitssuchen so transformativ, effizient und wirklich sinnvoll zu gestalten.

Jetzt starten

ADK-Dokumentation: [Link zu den offiziellen ADK-Java-Dokumenten]

Quellcode des Patent Analysis Agents: [Link zu Ihrem (jetzt öffentlichen) GitHub-Repository]

Java-Beispiel-Agenten: [Link zum adk-samples-Repository]

ADK-Community beitreten: https://www.reddit.com/r/agentdevelopmentkit/

Viel Spaß beim Erstellen von Bots!