Instalowanie i konfigurowanie Toolboxa do zastosowań generatywnej AI i agentów w AlloyDB

1. Omówienie

Gen AI Toolbox for Databases to serwer open source od Google, który ułatwia tworzenie narzędzi generatywnej AI do interakcji z bazami danych. Dzięki temu możesz tworzyć narzędzia łatwiej, szybciej i bezpieczniej, ponieważ biblioteka ta obsługuje złożone zadania, takie jak łączenie połączeń i uwierzytelnianie. Pomaga tworzyć narzędzia generatywnej AI, które umożliwiają agentom dostęp do danych w bazie danych. Zestaw narzędzi zawiera:

Uproszczone tworzenie: integracja narzędzi z agentem za pomocą mniej niż 10 wierszy kodu, ponowne wykorzystywanie narzędzi w różnych agentach lub ramach oraz łatwiejsze wdrażanie nowych wersji narzędzi.

Lepsza wydajność: sprawdzone metody, takie jak grupowanie połączeń, uwierzytelnianie i inne.

Zwiększone bezpieczeństwo: zintegrowana autoryzacja zapewniająca bezpieczniejszy dostęp do danych.

Kompleksowa obserwowalność: gotowe wskaźniki i śledzenie z wbudowanym wsparciem dla OpenTelemetry.

Toolbox znajduje się między systemem orkiestracji aplikacji a bazą danych. Zapewnia on płaszczyznę kontrolną, która służy do modyfikowania, rozpowszechniania i wywoływania narzędzi. Ułatwia zarządzanie narzędziami, ponieważ zapewnia scentralizowane miejsce do przechowywania i aktualizowania narzędzi. Umożliwia też udostępnianie narzędzi między pracownikami i aplikacją oraz aktualizowanie tych narzędzi bez konieczności ponownego wdrażania aplikacji.

Co utworzysz

W ramach tego laboratorium utworzysz aplikację, która używa narzędzia do wykonywania prostych zapytań do bazy danych (AlloyDB), które można wywołać z agenta lub aplikacji generatywnej AI. Aby to zrobić:

1. Instalowanie Toolbox
2. Skonfiguruj narzędzie (które ma wykonywać zadanie w AlloyDB) na serwerze Toolbox.
3. Wdrażanie Toolboxa w Cloud Run
4. przetestować narzędzie z wdrożonym punktem końcowym Cloud Run;
5. Utwórz funkcję Cloud Run, aby wywołać narzędzia

Wymagania

• przeglądarka, np. Chrome lub Firefox;
• projekt Google Cloud z włączonymi płatnościami (instrukcje w następnej sekcji),

2. Zanim zaczniesz

Utwórz projekt

1. W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt Google Cloud.
2. Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.
3. Użyjesz Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud. Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud.

4. Po połączeniu z Cloud Shell sprawdź, czy jesteś już uwierzytelniony i czy projekt ma prawidłowy identyfikator. Aby to zrobić, użyj tego polecenia:

gcloud auth list

5. Aby sprawdzić, czy polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:

gcloud config list project

6. Jeśli projekt nie jest ustawiony, użyj tego polecenia:

gcloud config set project <YOUR_PROJECT_ID>

7. Włącz wymagane interfejsy API, uruchamiając po kolei te polecenia w terminalu Cloud Shell:

Możesz też użyć pojedynczego polecenia, aby wykonać te czynności, ale jeśli korzystasz z konta próbnego, podczas zbiorczego włączania tych funkcji możesz napotkać problemy z kwotą. Dlatego polecenia są oddzielone po jednym na wiersz.

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

Alternatywą dla polecenia gcloud jest konsola, w której można wyszukać poszczególne usługi lub skorzystać z tego linku.

Jeśli pominiesz któryś interfejs API, możesz go włączyć w trakcie implementacji.

Więcej informacji o poleceniach i użytkowaniu gcloud znajdziesz w dokumentacji.

3. Konfiguracja bazy danych

W tym module użyjemy bazy danych AlloyDB do przechowywania danych o sprzedaży detalicznej. Do przechowywania wszystkich zasobów, takich jak bazy danych i logi, używa klastrów. Każdy klaster ma instancję główną, która stanowi punkt dostępu do danych. W tabelach będą się znajdować rzeczywiste dane.

Utwórz klaster, instancję i tabelę AlloyDB, do której zostanie załadowany zbiór danych e-commerce.

Tworzenie klastra i instancji

1. Otwórz stronę AlloyDB w konsoli Cloud.

Najłatwiej znaleźć większość stron w Cloud Console jest za pomocą paska wyszukiwania w konsoli.

2. Na tej stronie wybierz UTWÓRZ KLASTER:

3. Zobaczysz ekran podobny do tego poniżej. Utwórz klaster i instancję z tymi wartościami (upewnij się, że wartości są zgodne, jeśli klonujesz kod aplikacji z repozytorium):

• identyfikator klastra: „vector-cluster”;
• hasło: „alloydb”
• Zgodność z PostgreSQL 15
• Region: „us-central1”
• Networking: „default”

4. Po wybraniu sieci domyślnej zobaczysz ekran podobny do tego poniżej. Wybierz USTAW POŁĄCZENIE.
   
5. Następnie kliknij „Użyj automatycznie przydzielonego zakresu adresów IP” i Dalej. Po sprawdzeniu informacji wybierz UTWÓRZ POŁĄCZENIE.
6. Po skonfigurowaniu sieci możesz kontynuować tworzenie klastra. Kliknij UTWÓRZ KLASTR, aby dokończyć konfigurowanie klastra, jak pokazano poniżej:

Pamiętaj, aby zmienić identyfikator instancji na „

vector-instance"

Pamiętaj, że utworzenie klastra zajmie około 10 minut. Po zakończeniu procesu powinien wyświetlić się ekran z ogólnymi informacjami o kreatorzym utworzonym klastrze.

4. Pozyskiwanie danych

Teraz dodaj tabelę z danymi o sklepie. Przejdź do AlloyDB, wybierz klaster główny, a następnie AlloyDB Studio:

Możesz musieć poczekać, aż instancja zostanie utworzona. Gdy to zrobisz, zaloguj się w AlloyDB, używając danych logowania utworzonych podczas tworzenia klastra. Do uwierzytelniania w PostgreSQL użyj tych danych:

• Nazwa użytkownika: „postgres”
• Baza danych: „postgres”
• Hasło: „alloydb”

Po pomyślnym uwierzytelnieniu się w AlloyDB Studio możesz wpisywać polecenia SQL w edytorze. Możesz dodać większą liczbę okien Edytora, klikając plus po prawej stronie ostatniego okna.

Polecenia AlloyDB możesz wpisywać w oknach edytora, korzystając w razie potrzeby z opcji Uruchom, Formatuj i Wyczyść.

Włączanie rozszerzeń

Do tworzenia tej aplikacji użyjemy rozszerzeń pgvector i google_ml_integration. Rozszerzenie pgvector umożliwia przechowywanie wektorów dystrybucyjnych i wyszukiwanie ich. Rozszerzenie google_ml_integration udostępnia funkcje, których używasz do uzyskiwania dostępu do punktów końcowych prognozowania Vertex AI w celu uzyskiwania prognoz w SQL. Włącz te rozszerzenia, uruchamiając te DDL:

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

Jeśli chcesz sprawdzić rozszerzenia włączone w bazie danych, uruchom to polecenie SQL:

select extname, extversion from pg_extension;

Tworzenie tabeli

Utwórz tabelę za pomocą poniższej instrukcji DDL:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

Po wykonaniu tego polecenia powinna się ona wyświetlić w bazie danych.

Pozyskiwanie danych

W tym module mamy dane testowe w postaci około 72 rekordów w pliku SQL. Zawiera ona pola id, name, description, quantity, price, image_url. Pozostałe pola zostaną wypełnione później w ramach tego modułu.

Skopiuj z tego miejsca wiersze lub instrukcje insert, a potem wklej je na pustą kartę edytora i kliknij URUCHOM.

Aby zobaczyć zawartość tabeli, rozwiń sekcję Eksplorator, aż zobaczysz tabelę o nazwie Odzież. Kliknij 3 kropki (⋮), aby wyświetlić opcję Zapytanie o tabelę. W nowej karcie Edytor otworzy się instrukcja SELECT.

Przyznaj uprawnienia

Aby przyznać użytkownikowi postgres uprawnienia do wykonywania funkcji embedding, uruchom to polecenie:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Przypisz rolę Vertex AI USER do konta usługi AlloyDB

Otwórz terminal Cloud Shell i wpisz to polecenie:

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"

5. Tworzenie wektorów kontekstu

Komputery znacznie łatwiej przetwarzają liczby niż tekst. System umieszczania konwertuje tekst w szereg liczb zmiennoprzecinkowych, zwanych wektorami zanurzeniowymi, które powinny reprezentować tekst niezależnie od tego, jak jest sformułowany, w jakim języku jest itd.

Na przykład lokalizacja nad morzem może być nazwana „on the water”, „beachfront”, „walk from your room to the ocean”, „sur la mer”, „на берегу океана” itp. Wszystkie te terminy wyglądają inaczej, ale ich znaczenie semantyczne lub, mówiąc językiem uczenia maszynowego, ich ukryte reprezentacje powinny być bardzo podobne.

Gdy dane i kontekst będą gotowe, uruchomimy zapytanie SQL, aby dodać do tabeli w polu embedding kody osadzania opisu produktu. Możesz używać różnych modeli wstawiania. Używamy text-embedding-005 z Vertex AI. Pamiętaj, aby używać tego samego modelu w całym projekcie.

Uwaga: jeśli używasz starego projektu Google Cloud, być może musisz nadal używać starszych wersji modelu wklejania tekstu, takich jak textembedding-gecko.

Wróć do karty AlloyDB Studio i wpisz ten kod DML:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

Aby zobaczyć niektóre wstępnie przetworzone dane, ponownie spójrz na tabelę toys. Aby zobaczyć zmiany, ponownie uruchom instrukcję SELECT.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

Powinien on zwrócić wektor zagęszczenia, który wygląda jak tablica liczb zmiennoprzecinkowych, dla opisu zabawki, jak pokazano poniżej:

Uwaga: nowo utworzone projekty Google Cloud w wersji bezpłatnej mogą mieć problemy z limitem liczby żądań na potrzeby umieszczania w treści w modelu umieszczania w treści na sekundę. Zalecamy użycie zapytania filtra dla identyfikatora, a potem wybranie 1–5 rekordów itd. podczas generowania kodu embed.

6. Wykonywanie wyszukiwania wektorowego

Teraz, gdy tabela, dane i wektory są gotowe, przeprowadźmy wyszukiwanie wektorów w czasie rzeczywistym dla tekstu wyszukiwanego przez użytkownika.

Załóżmy, że użytkownik zadaje pytanie:

„I want a white plush teddy bear toy with a floral pattern”.

Możesz znaleźć dopasowania, uruchamiając to zapytanie:

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

Przyjrzyjmy się temu zapytaniu bliżej:

W tym zapytaniu

1. Tekst wyszukiwania użytkownika: „I want a white plush teddy bear toy with a floral pattern.”.
2. Przekształcamy je w embeddingi w ramach metody embedding(), używając modelu text-embedding-005. Ten krok powinien być Ci już znany z ostatniego kroku, w którym zastosowaliśmy funkcję umieszczania we wszystkich elementach w tabeli.
3. „<=>” oznacza użycie metody odległości COSINY SIMILARITY. Wszystkie dostępne miary podobieństwa znajdziesz w dokumentacji pgvector.
4. Przekształcamy wynik metody osadzania w typ wektora, aby był zgodny z wektorami zapisanymi w bazie danych.
5. LIMIT 5 oznacza, że chcemy wyodrębnić 5 najbliższych sąsiadów dla tekstu wyszukiwania.

Wynik wygląda tak:

Jak widać w wynikach, dopasowania są bardzo zbliżone do tekstu wyszukiwania. Zmień tekst, aby zobaczyć, jak zmieniają się wyniki.

7. Przygotowanie AlloyDB do interakcji z Toolbox

W ramach przygotowań do konfiguracji Toolbox włączmy w naszej instancji AlloyDB połączenie z publicznym adresem IP, aby nowe narzędzie mogło uzyskać dostęp do bazy danych.

1. Otwórz instancję AlloyDB, kliknij EDYTUJ i przejdź na stronę Edytuj instancję główną.
2. Przejdź do sekcji Łączność z publicznym adresem IP, zaznacz pole wyboru Włącz publiczny adres IP i wpisz adres IP maszyny Cloud Shell.
3. Aby uzyskać adres IP maszyny Cloud Shell, otwórz terminal Cloud Shell i wpisz ifconfig. Na podstawie wyników określ adres internetowy eth0 i zastąp 2 ostatnie cyfry 0,0 rozmiarem maski „/16”. Na przykład „XX.XX.0.0/16”, gdzie XX to cyfry.
4. Wklej ten adres IP w polu tekstowym „Sieci” w sekcji Autoryzowane sieci zewnętrzne na stronie edycji instancji.

5. Gdy skończysz, kliknij AKTUALIZUJ INSTANCJĘ.

Ta operacja może potrwać kilka minut.

8. Instalacja zestawu narzędzi

1. Możesz utworzyć folder projektu, w którym będą przechowywane szczegóły narzędzia. W tym przypadku, ponieważ pracujemy nad danymi sklepu z zabawkami, utwórzmy folder o nazwie „toystore” i przejdź do niego. Przejdź do terminala Cloud Shell i upewnij się, że Twój projekt jest wybrany i wyświetlany w wierszu poleceń. Uruchom to polecenie w terminalu Cloud Shell:

mkdir toystore

cd toystore

2. Aby pobrać i zainstalować narzędzia w nowym folderze, uruchom to polecenie:

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

3. Przełącz na edytor Cloud Shell. Rozwiń nowo utworzony folder „toystore” i utwórz nowy plik o nazwie tools.yaml. Skopiuj treść poniżej. Zastąp identyfikator YOUR_PROJECT_ID i sprawdź, czy wszystkie inne szczegóły połączenia są prawidłowe.

sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

W tym narzędziu znajdujemy po prostu najbliższe dopasowanie do tekstu wyszukiwania użytkownika (niestandardowy opis zabawki) i zwracamy jego cenę. Możesz też zmodyfikować zapytanie, aby znaleźć średnią cenę 5 najbardziej pasujących zabawek:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

Definicja narzędzia jest gotowa.

Więcej informacji o konfigurowaniu pliku tools.yaml znajdziesz w tej dokumentacji.

4. Przełącz się na terminal Cloud Shell i wpisz to polecenie, aby uruchomić serwer narzędzia z konfiguracją narzędzi:

./toolbox --tools_file "tools.yaml"

5. Jeśli otworzysz serwer w trybie podglądu w chmurze, powinieneś zobaczyć działający serwer Toolbox z nowym narzędziem o nazwie get-toy-price..

9. Wdrożenie Toolboxa w Cloud Run

Wdrożycie je w Cloud Run, aby móc z niego korzystać.

1. Wykonuj kolejno instrukcje podane na tej stronie, aż dojdziesz do polecenia gcloud run deploy toolbox, które znajduje się w 3 punkcie sekcji „Wdróż w Cloud Run”. Wybierz pierwszą opcję, a nie drugą, która jest przeznaczona do korzystania z metody sieci VPC.
2. Po udanym wdrożeniu otrzymasz punkt końcowy serwera Toolbox wdrożony w Cloud Run. Przetestuj to za pomocą polecenia CURL.

Możesz teraz korzystać z nowo wdrożonego narzędzia w aplikacji agentycznej.

10. Łączenie aplikacji z Toolbox

W tej części zbudujemy małą aplikację, która pozwoli przetestować, czy Twoje narzędzie może się komunikować z aplikacją i otrzymywać od niej odpowiedzi.

1. Otwórz Google Colab i otwórz nowy notatnik.
2. Wykonaj te czynności w notatniku

pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

3. Powinieneś uzyskać taki wynik:

To narzędzie jest wywoływane w aplikacji Pythona, która korzysta z pakietu narzędzi toolbox-langchain..

4. Jeśli chcesz używać tego narzędzia i połączyć je z agentem w ramach zintegrowanej aplikacji LangGraph, możesz to łatwo zrobić za pomocą zestawu narzędzi langgraph.
5. W tym celu skorzystaj z fragmentów kodu.

11. Prześlij do chmury.

Umieścimy ten fragment kodu Pythona w funkcjach Cloud Run, aby uczynić go bezserwerowym.

1. Skopiuj kod źródłowy z folderu repozytorium kodu, aby przesłać go do Cloud Functions.
2. Otwórz konsolę Funkcje Cloud Run i kliknij UTWÓRZ FUNKCJĘ.
3. W przypadku aplikacji demonstracyjnej nie trzeba się uwierzytelniać. Na następnej stronie wybierz środowisko wykonawcze Python 3.11.
4. Skopiuj pliki main.py i requirements.txt z repozytorium źródłowego udostępnionego w kroku 1 i wklej je w odpowiednich plikach.
5. Po wdrożeniu funkcji masz punkt końcowy REST dla narzędzia do prognozowania cen, do którego można uzyskać dostęp w aplikacji internetowej toystore.
6. Punkt końcowy powinien wyglądać tak:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

2. Możesz go przetestować bezpośrednio w konsoli Cloud Functions. W tym celu otwórz kartę TESTOWANIE i wpisz jako dane wejściowe żądania:

{

               "`search`"`:` "`White plush toy`"

}

3. Kliknij TESTUJ FUNKCJĘ lub Uruchom w terminalu Cloud Shell, w zależności od tego, czego potrzebujesz. Po prawej stronie pod nagłówkiem „Wyjście” powinien pojawić się wynik:

12. Gratulacje

Gratulacje! Udało Ci się utworzyć solidne i właściwie modułowe narzędzie, które może współpracować z bazami danych, platformami i ramami sterowania generatywnej AI, aby ułatwić tworzenie aplikacji agentycznej.