Informacje o tym ćwiczeniu (w Codelabs)
1. Omówienie
MCP Toolbox for Databases to serwer Google typu open source, 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ż obsługuje ono 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 programowanie: integruj narzędzia z agentem w ramach mniej niż 10 wierszy kodu, używaj ponownie narzędzi przez wiele agentów lub platform oraz łatwiej wdrażaj nowe wersje narzędzi.
Większa wydajność: sprawdzone metody dotyczące m.in. łączenia połączeń i uwierzytelniania.
Większe bezpieczeństwo: zintegrowane uwierzytelnianie, które zapewnia bezpieczniejszy dostęp do danych.
Pełna dostrzegalność: gotowe do użycia wskaźniki i śledzenie z wbudowaną obsługą OpenTelemetry.
Toolbox znajduje się między systemem sterowania 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 modułu utworzysz aplikację korzystającą z narzędzia do wykonywania prostego zapytania do bazy danych (AlloyDB), które można wywołać z Twojego agenta lub aplikacji generatywnej AI. Czynności, które musisz wykonać
- Instalowanie Narzędzi MCP dla baz danych
- Konfigurowanie narzędzia (zaprojektowanego do wykonywania zadania w AlloyDB) na serwerze Zestawu narzędzi
- Wdrażanie zestawu narzędzi MCP dla baz danych w Cloud Run
- Testowanie narzędzia za pomocą wdrożonego punktu końcowego Cloud Run
- Kompilowanie funkcji w Cloud Run do wywoływania Zestawu narzędzi
Wymagania
2. Zanim zaczniesz
Utwórz projekt
- W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt Google Cloud.
- Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.
- Użyjesz Cloud Shell – środowiska wiersza poleceń działającego w Google Cloud. Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud.
- Po nawiązaniu połączenia z Cloud Shell sprawdź za pomocą tego polecenia, czy jesteś już uwierzytelniony i czy projekt jest ustawiony na prawidłowy identyfikator projektu:
gcloud auth list
- Aby sprawdzić, czy polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:
gcloud config list project
- Jeśli projekt nie jest ustawiony, użyj tego polecenia:
gcloud config set project <YOUR_PROJECT_ID>
- Włącz wymagane interfejsy API, uruchamiając po kolei te polecenia w terminalu Cloud Shell:
Dostępne jest też jedno polecenie do uruchomienia poniżej, ale jeśli używasz konta próbnego, podczas próby ich zbiorczego włączenia mogą wystąpić problemy z limitem. Dlatego każde z poleceń jest w oddzielnym wierszu.
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 skorzystanie z konsoli poprzez wyszukanie poszczególnych usług lub skorzystanie z tego linku.
Jeśli pominiesz któryś interfejs API, zawsze możesz go włączyć w trakcie implementacji.
Więcej informacji o poleceniach i użyciu gcloud znajdziesz w dokumentacji.
3. Konfiguracja bazy danych
W tym module wykorzystamy AlloyDB jako bazę danych do przechowywania danych handlu detalicznego. Wykorzystuje klastry do przechowywania wszystkich zasobów, takich jak bazy danych i logi. Każdy klaster ma instancję główną, która zapewnia punkt dostępu do danych. Tabele zawierają rzeczywiste dane.
Utwórzmy klaster, instancję i tabelę AlloyDB, w których zostanie wczytany zbiór danych e-commerce.
Tworzenie klastra i instancji
- Poruszaj się po stronie AlloyDB w konsoli Cloud.
Łatwym sposobem na znalezienie większości stron w konsoli Cloud jest wyszukanie ich za pomocą paska wyszukiwania w konsoli.
- Wybierz na tej stronie opcję UTWÓRZ KLASTER:
- Zobaczysz ekran podobny do tego poniżej. Utwórz klaster i instancję o następujących wartościach (pamiętaj, aby się upewnić, że wartości są takie same, jeśli kopiujesz kod aplikacji z repozytorium):
- identyfikator klastra: „
vector-cluster” - hasło: „
alloydb” - Zgodność z PostgreSQL 15
- Region: „
us-central1” - Sieć: „
default”
- Po wybraniu sieci domyślnej zobaczysz ekran podobny do pokazanego poniżej. Kliknij SKONFIGURUJ POŁĄCZENIE.
- Następnie wybierz „Użyj automatycznie przydzielonego zakresu adresów IP” i kliknij Dalej. Po zapoznaniu się z informacjami kliknij UTWÓRZ POŁĄCZENIE.
- Po skonfigurowaniu sieci możesz kontynuować tworzenie klastra. Kliknij UTWÓRZ KLASTER, aby zakończyć konfigurowanie klastra w następujący sposób:
Pamiętaj, aby zmienić identyfikator instancji na „
vector-instance"
Pamiętaj, że utworzenie klastra zajmie około 10 minut. Gdy operacja się uda, powinien wyświetlić się ekran z omówieniem utworzonego przed chwilą klastra.
4. Pozyskiwanie danych
Teraz dodaj tabelę z danymi o sklepie. Przejdź do AlloyDB, wybierz klaster podstawowy, a następnie AlloyDB Studio:
Poczekaj na zakończenie tworzenia instancji. Gdy proces się zakończy, zaloguj się w AlloyDB przy użyciu danych logowania utworzonych podczas tworzenia klastra. Użyj tych danych do uwierzytelniania w PostgreSQL:
- Nazwa użytkownika: „
postgres” - Baza danych : "
postgres" - Hasło: „
alloydb”
Po uwierzytelnieniu w AlloyDB Studio można wpisywać polecenia SQL w edytorze. Możesz dodać wiele okien Edytora, klikając znak plusa po prawej stronie ostatniego okna.
W oknach edytora możesz wpisywać polecenia dla AlloyDB za pomocą opcji Uruchom, Formatuj i Wyczyść, jeśli to konieczne.
Włącz rozszerzenia
Do utworzenia tej aplikacji użyjemy rozszerzeń pgvector i google_ml_integration. Rozszerzenie pgvector umożliwia przechowywanie i wyszukiwanie wektorów dystrybucyjnych wektorów. Rozszerzenie google_ml_integration udostępnia funkcje umożliwiające dostęp do punktów końcowych prognozowania Vertex AI w celu otrzymywania prognoz w języku SQL. Włącz te rozszerzenia, uruchamiając następujące DDL:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Jeśli chcesz sprawdzić rozszerzenia, które zostały włączone w bazie danych, uruchom to polecenie SQL:
select extname, extversion from pg_extension;
Tworzenie tabeli
Utwórz tabelę przy użyciu 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 powyższych poleceń tabela powinna być dostępna w bazie danych.
Pozyskiwanie danych
W tym module w tym pliku SQL znajdują się dane testowe około 72 rekordów. Zawiera on pola id, name, description, quantity, price, image_url. Pozostałe pola zostaną wypełnione w dalszej części modułu.
Skopiuj stamtąd wiersze lub instrukcje wstawiania, a następnie wklej je w pustej karcie edytora i kliknij URUCHOM.
Aby zobaczyć zawartość tabeli, rozwiń sekcję Eksplorator, aż pojawi się tabela o nazwie odzież. Wybierz trójkąt (⋮), aby wyświetlić opcję Zapytanie do tabeli. Instrukcja SELECT zostanie otwarta w nowej karcie edytora.
Przyznaj uprawnienia
Uruchom poniższą instrukcję, aby przyznać użytkownikowi postgres uprawnienia do wykonania funkcji embedding:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Przyznaj rolę użytkownika Vertex AI kontu usługi AlloyDB
Przejdź do terminala 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 dystrybucyjnych dla kontekstu
Komputery mogą znacznie łatwiej przetwarzać liczby niż tekst. System wektorów dystrybucyjnych konwertuje tekst na szereg liczb zmiennoprzecinkowych nazywanych wektorami wektorowymi. Takie reprezentacje powinny reprezentować tekst bez względu na jego treść, używany język itp.
Lokalizacja nadmorska może na przykład nosić nazwę „nad wodą”, „nabrzeże”, „przejść z pokoju do oceanu”, „sur la mer”, „на Берегу океана” itp. Wszystkie te hasła wyglądają inaczej, ale ich znaczenie semantyczne lub w terminologii uczenia maszynowego powinny być bardzo blisko siebie.
Gdy dane i kontekst są już gotowe, uruchomimy kod SQL, aby dodać wektory dystrybucyjne opisu produktu do tabeli w polu embedding. Masz do wyboru wiele różnych modeli umieszczania. Używamy adresu text-embedding-005 z Vertex AI. Pamiętaj, aby używać tego samego modelu umieszczania w całym projekcie.
Uwaga: jeśli korzystasz ze starego projektu Google Cloud, konieczne może być dalsze korzystanie ze starszych wersji modelu umieszczania tekstu, takiego jak textembedding-gecko.
Wróć do karty AlloyDB Studio i wpisz ten kod DML:
UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);
Zajrzyj ponownie do tabeli toys, aby zobaczyć niektóre wektory dystrybucyjne. Pamiętaj, aby ponownie uruchomić instrukcję SELECT, aby zobaczyć zmiany.
SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;
Powinno to spowodować zwrócenie wektora dystrybucyjnego, który wygląda jak tablica pływaków dla opisu zabawki, jak pokazano poniżej:
Uwaga: w przypadku nowo utworzonych projektów Google Cloud na poziomie bezpłatnym mogą wystąpić problemy z limitami liczby żądań umieszczania na sekundę dla modeli umieszczania. Zalecamy użycie zapytania filtra dla identyfikatora, a następnie selektywne wybieranie 1–5 rekordów itd. podczas generowania wektora dystrybucyjnego.
6. Przeprowadź wyszukiwanie wektorowe
Tabela, dane i wektory dystrybucyjne są już gotowe, przejdźmy więc do wyszukiwania wektorowego w czasie rzeczywistym dla tekstu wyszukiwanego przez użytkownika.
Załóżmy, że użytkownik pyta:
„I want a white plush teddy bear toy with a floral pattern”.
Możesz je znaleźć, uruchamiając zapytanie poniżej:
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 szczegółowo:
W tym zapytaniu
- Tekst wyszukiwany przez użytkownika to: „
I want a white plush teddy bear toy with a floral pattern.” - Przekształcamy je w wektory dystrybucyjne w metodzie
embedding()przy użyciu modelu:text-embedding-005. Ten krok powinien wyglądać znajomo po ostatnim kroku, w którym zastosowaliśmy funkcję umieszczania do wszystkich elementów w tabeli. - „
<=>” oznacza zastosowanie metody COSINE PODOBNE. Wszystkie wskaźniki podobieństwa dostępne w dokumentacji komponentu pgvector. - Konwertujemy wynik metody umieszczania na typ wektorowy, aby zapewnić zgodność z wektorami przechowywanymi w bazie danych.
- LIMIT 5 oznacza, że dla wyszukiwanego tekstu chcemy wyodrębnić 5 najbliższych sąsiadów.
Wynik będzie wyglądał tak:
Jak widać w wynikach, dopasowania są bardzo zbliżone do wyszukiwanego tekstu. Spróbuj zmienić tekst, aby sprawdzić, jak zmienią się wyniki.
7. Przygotowywanie AlloyDB do interakcji z zestawem narzędzi
Przygotowując się do skonfigurowania Zestawu narzędzi, włączmy połączenia przez publiczny adres IP w naszej instancji AlloyDB, aby nowe narzędzie mogło uzyskać dostęp do bazy danych.
- Otwórz instancję AlloyDB, kliknij EDYTUJ i przejdź na stronę edytowania instancji głównej.
- W sekcji Połączenia przez publiczny adres IP zaznacz pole wyboru Włącz publiczny adres IP i wpisz adres IP swojej maszyny Cloud Shell.
- Aby uzyskać adres IP maszyny Cloud Shell, otwórz terminal Cloud Shell i wpisz parametr ifconfig. Na podstawie wyniku zidentyfikuj adres eth0 inet, a ostatnie 2 cyfry zastąp wartością 0,0, podając wartość maski o rozmiarze „/16”. Przykładowy kod wygląda tak: „XX.XX.0.0/16”, gdzie XX to liczby.
- Wklej ten adres IP w polu tekstowym „Sieci” autoryzowanej sieci zewnętrznej na stronie edycji instancji.
- Gdy skończysz, kliknij AKTUALIZUJ INSTANCJĘ.
Potrwa to kilka minut.
8. Zestaw narzędzi MCP do instalacji baz danych
- Możesz utworzyć folder projektu, w którym będą przechowywane szczegóły narzędzia. W tym przypadku pracujemy nad danymi dotyczącymi sklepów z zabawkami, więc utworzymy folder o nazwie „toystore” i przejdź do niego. Przejdź do terminalu Cloud Shell i sprawdź, czy Twój projekt jest wybrany i wyświetlony w oknie terminala. Uruchom to polecenie w terminalu Cloud Shell:
mkdir toystore
cd toystore
- Uruchom to polecenie, aby pobrać i zainstalować zestaw narzędzi w nowym folderze:
# 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
- Przełącz na edytor Cloud Shell. Rozwiń nowo utworzony folder „toystore” i utwórz nowy plik o nazwie Tools.yaml. Skopiuj poniższą treść. Zastąp identyfikator YOUR_PROJECT_ID i sprawdź, czy wszystkie pozostałe 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 informacje najbliższe wyszukiwanemu przez użytkownika (opis zabawki niestandardowej) i zwracamy jego cenę. Możesz też go zmodyfikować, aby poznać średnią cenę 5 najbliższych 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 już gotowa.
Więcej informacji na temat konfigurowania pliku Tools.yaml znajdziesz w tej dokumentacji.
- Przełącz się na terminal Cloud Shell i wpisz to polecenie, aby uruchomić serwer zestawu narzędzi z konfiguracją narzędzi:
./toolbox --tools_file "tools.yaml"
- Teraz, gdy otworzysz serwer w trybie podglądu w przeglądarce, będzie można zobaczyć, jak serwer z Zestawu narzędzi działa w przypadku nowego narzędzia o nazwie
get-toy-price..
9. Wdrażanie Zestawu narzędzi MCP dla baz danych w Cloud Run
Wdróżmy je w Cloud Run, aby można było zacząć z niego korzystać.
- Wykonuj po kolei instrukcje podane na tej stronie, aż dojdziesz do polecenia
gcloud run deploy toolbox, które znajduje się w 3 punkcie w sekcji „Wdróż w Cloud Run”. Musisz wybrać pierwszą opcję, a nie drugą, która ma zastosowanie w przypadku korzystania z metody sieci VPC. - Po wdrożeniu otrzymasz wdrożony punkt końcowy Cloud Run swojego serwera narzędzi. Przetestuj ją za pomocą polecenia CURL.
Wskazówki:
Uważnie postępuj zgodnie z instrukcjami na stronie, aby nie przegapić niczego ważnego.
Możesz teraz korzystać z nowo wdrożonego narzędzia w swojej aplikacji.
10. Łączenie aplikacji z Zestawem narzędzi MCP dla baz danych
W tej części utworzymy małą aplikację, która przetestuje Twoje narzędzie pod kątem interakcji z nią i pobierania odpowiedzi.
- Przejdź do Google Colab i otwórz nowy notatnik.
- Uruchom w notatniku te polecenia
!pip install toolbox-core
from toolbox_core import ToolboxClient
# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")
# If there are multiple tools
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")
# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})
# Print result
print(result)
- Powinien pojawić się następujący wynik:
To narzędzie jest bezpośrednio wywoływane w aplikacji w języku Python, która korzysta z zestawu narzędzi toolbox-langchain.
- Jeśli chcesz użyć tego narzędzia i powiązać je z agentem w aplikacji zintegrowanej z LangGraph, możesz to łatwo zrobić za pomocą pakietu narzędzi
langgraph. - Zapoznaj się z fragmentami kodu na ten temat.
11. Do chmury!
Umieśćmy ten fragment kodu Pythona w funkcji w Cloud Run Functions, aby była bezserwerowa.
- Skopiuj źródło z folderu repozytorium kodu, aby przesłać je do Cloud Functions.
- Otwórz konsolę Cloud Run Functions i kliknij UTWÓRZ FUNKCJĘ.
- Nie uwierzytelniaj aplikacji w wersji demonstracyjnej i na następnej stronie wybierz środowisko wykonawcze Pythona 3.11.
- Skopiuj pliki
main.pyirequirements.txtz repozytorium źródłowego udostępnionego w kroku 1 i wklej je w odpowiednich plikach. - Zastąp adres URL serwera w pliku main.py adresem URL swojego serwera.
- Wdróż funkcję i uzyskasz punkt końcowy REST dla narzędzia do prognozowania cen, do którego będzie można uzyskać dostęp w aplikacji internetowej toystore.
- Punkt końcowy powinien wyglądać tak:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- Możesz przetestować je bezpośrednio w konsoli Cloud Functions. Aby to zrobić, otwórz kartę TESTOWANIE i wpisz te dane jako dane wejściowe żądania:
{
"search": "White plush toy"
}
- Kliknij PRZETESTUJ FUNKCJĘ lub uruchom wybraną funkcję w terminalu Cloud Shell. Wynik powinien pojawić się po prawej stronie pod tytułem „Wyniki”:
12. Gratulacje
Gratulacje! Udało Ci się utworzyć wydajne i prawdziwie modułowe narzędzie, które może współdziałać z bazami danych, platformami i platformami administrowania generatywną AI, aby ułatwić tworzenie aplikacji agentowej.