Instalowanie i konfigurowanie zestawu narzędzi MCP dla baz danych na potrzeby generatywnej AI oraz aplikacji agentowych w AlloyDB

1. Przegląd

Zestaw narzędzi MCP dla baz danych to serwer open source od Google, który ułatwia tworzenie narzędzi opartych na generatywnej AI do interakcji z bazami danych. Umożliwia łatwiejsze, szybsze i bezpieczniejsze tworzenie narzędzi dzięki obsłudze złożonych procesów, takich jak pula połączeń, uwierzytelnianie i inne. Ułatwia tworzenie narzędzi opartych na generatywnej AI, które umożliwiają agentom dostęp do danych w bazie danych. Zestaw narzędzi zapewnia:

Uproszczone programowanie: integruj narzędzia z agentem za pomocą mniej niż 10 linii kodu, ponownie wykorzystuj narzędzia w przypadku wielu agentów lub platform i łatwiej wdrażaj nowe wersje narzędzi.

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

Większe bezpieczeństwo: zintegrowane uwierzytelnianie zapewniające bezpieczniejszy dostęp do danych.

Kompleksowa obserwowalność: gotowe wskaźniki i śledzenie z wbudowaną obsługą OpenTelemetry.

Toolbox znajduje się między platformą orkiestracji aplikacji a bazą danych, zapewniając platformę sterującą, która służy do modyfikowania, rozpowszechniania i wywoływania narzędzi. Upraszcza zarządzanie narzędziami, ponieważ zapewnia centralną lokalizację do przechowywania i aktualizowania narzędzi, umożliwiając udostępnianie ich agentom i aplikacjom oraz aktualizowanie ich bez konieczności ponownego wdrażania aplikacji.

Co utworzysz

W ramach tego laboratorium utworzysz aplikację, która korzysta z narzędzia do wykonywania prostego zapytania do bazy danych (AlloyDB), które można wywołać z poziomu agenta lub aplikacji generatywnej AI. W tym celu

  1. Instalowanie zestawu narzędzi MCP dla baz danych
  2. Skonfiguruj narzędzie (przeznaczone do wykonywania zadania w AlloyDB) na serwerze zestawu narzędzi.
  3. Wdrażanie narzędzi MCP dla baz danych w Cloud Run
  4. Testowanie narzędzia za pomocą wdrożonego punktu końcowego Cloud Run
  5. Utwórz funkcję Cloud Run, aby wywołać Toolbox

Wymagania

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

2. Zanim zaczniesz

Utwórz projekt

  1. W konsoli Google Cloud na stronie selektora projektów 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. Będziesz używać Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud. U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell.

Obraz przycisku aktywowania Cloud Shell

  1. Po połączeniu z Cloud Shell sprawdź, czy uwierzytelnianie zostało już przeprowadzone i czy projekt jest ustawiony na prawidłowy identyfikator projektu, używając tego polecenia:
gcloud auth list
  1. Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:
gcloud config list project
  1. Jeśli projekt nie jest ustawiony, użyj tego polecenia, aby go ustawić:
gcloud config set project <YOUR_PROJECT_ID>
  1. Włącz wymagane interfejsy API, uruchamiając w terminalu Cloud Shell te polecenia:

Istnieje też jedno polecenie, które umożliwia uruchomienie poniższych funkcji, ale jeśli korzystasz z konta próbnego, możesz napotkać problemy z limitami podczas próby włączenia tych funkcji zbiorczo. Dlatego polecenia są wyróżniane po jednym w 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 konsola, w której możesz wyszukać poszczególne produkty lub skorzystać z tego linku.

Jeśli pominiesz jakiś interfejs API, możesz go włączyć w trakcie wdrażania.

Informacje o poleceniach gcloud i ich użyciu znajdziesz w dokumentacji.

3. Konfiguracja bazy danych

W tym module użyjemy AlloyDB jako bazy danych do przechowywania danych o sprzedaży detalicznej. Używa klastrów 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 będą zawierać rzeczywiste dane.

Utwórzmy klaster, instancję i tabelę AlloyDB, do których zostanie wczytany zbiór danych e-commerce.

Tworzenie klastra i instancji

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

Najprostszym sposobem na znalezienie większości stron w Cloud Console jest wyszukanie ich za pomocą paska wyszukiwania w konsoli.

  1. Na tej stronie kliknij UTWÓRZ KLASTER:

f76ff480c8c889aa.png

  1. Wyświetli się 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”
  • Sieci: „default”

538dba58908162fb.png

  1. Po wybraniu sieci domyślnej zobaczysz ekran podobny do tego poniżej. Wybierz SKONFIGURUJ POŁĄCZENIE.
    7939bbb6802a91bf.png
  2. Następnie wybierz „Użyj automatycznie przydzielonego zakresu adresów IP” i kliknij Dalej. Po sprawdzeniu informacji kliknij UTWÓRZ POŁĄCZENIE. 768ff5210e79676f.png
  3. Po skonfigurowaniu sieci możesz kontynuować tworzenie klastra. Aby dokończyć konfigurowanie klastra, kliknij UTWÓRZ KLASTER, jak pokazano poniżej:

e06623e55195e16e.png

Pamiętaj, aby zmienić identyfikator instancji na „

vector-instance"

.

Pamiętaj, że utworzenie klastra zajmie około 10 minut. Po zakończeniu procesu wyświetli się ekran z omówieniem utworzonego klastra.

4. Pozyskiwanie danych

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

847e35f1bf8a8bd8.png

Może być konieczne poczekanie na zakończenie tworzenia instancji. Po zakończeniu 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 w AlloyDB Studio możesz wpisywać polecenia SQL w Edytorze. Możesz dodać wiele okien Edytora, klikając znak plusa po prawej stronie ostatniego okna.

91a86d9469d499c4.png

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

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. Rozszerzenie google_ml_integration udostępnia funkcje, których możesz używać 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ć, które rozszerzenia są 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 pomyślnym wykonaniu powyższego polecenia powinna być widoczna tabela w bazie danych.

Pozyskiwanie danych

W tym laboratorium użyjemy danych testowych zawierających około 72 rekordy w pliku SQL. Zawiera pola id, name, description, quantity, price, image_url. Pozostałe pola wypełnisz w dalszej części tego modułu.

Skopiuj stamtąd wiersze lub instrukcje wstawiania, a następnie wklej je na pustej karcie edytora i kliknij URUCHOM.

Aby wyświetlić zawartość tabeli, rozwiń sekcję Eksplorator, aż zobaczysz tabelę o nazwie apparels. Kliknij ikonę trzech kropek (⋮), aby wyświetlić opcję Zapytanie do tabeli. Instrukcja SELECT otworzy się w nowej karcie Edytora.

cfaa52b717f9aaed.png

Przyznaj uprawnienia

Uruchom poniższą instrukcję, aby przyznać użytkownikowi postgres uprawnienia do wykonywania funkcji embedding:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Przyznawanie roli Użytkownik Vertex AI kontu 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 dystrybucyjnych dla kontekstu

Komputery znacznie łatwiej przetwarzają liczby niż tekst. System wektorów dystrybucyjnych przekształca tekst w ciąg liczb zmiennoprzecinkowych, zwanych wektorami dystrybucyjnymi, które powinny reprezentować tekst niezależnie od tego, jak jest sformułowany, w jakim języku jest napisany itp.

Na przykład lokalizacja nadmorska może być określana jako „nad wodą”, „przy plaży”, „z pokoju na plażę”, „sur la mer”, „на берегу океана” itp. Te terminy wyglądają inaczej, ale ich znaczenie semantyczne, czyli w terminologii uczenia maszynowego ich osadzenia, powinno być bardzo zbliżone.

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

Uwaga: jeśli używasz starszego projektu Google Cloud, być może musisz nadal korzystać ze starszych wersji modelu do osadzania tekstu, takich jak textembedding-gecko.

Wróć na kartę AlloyDB Studio i wpisz ten język DML:

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

Jeszcze raz spójrz na toys tabelę, aby zobaczyć niektóre osadzenia. Aby zobaczyć zmiany, ponownie uruchom instrukcję SELECT.

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

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

7d32f7cd7204e1f3.png

Uwaga: nowo utworzone projekty Google Cloud w ramach poziomu bezpłatnego mogą mieć problemy z limitami liczby żądań wektorów dystrybucyjnych na sekundę do modeli wektorów dystrybucyjnych. Podczas generowania osadzania zalecamy użycie zapytania filtra dla identyfikatora, a następnie selektywne wybieranie 1–5 rekordów itd.

6. Wykonywanie wyszukiwania wektorowego

Tabela, dane i wektory dystrybucyjne są już gotowe. Przeprowadźmy teraz wyszukiwanie wektorowe w czasie rzeczywistym dla tekstu wyszukiwanego przez użytkownika.

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

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

Aby znaleźć pasujące elementy, uruchom 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 szczegółowo:

W tym zapytaniu

  1. Tekst wyszukiwania użytkownika to: „I want a white plush teddy bear toy with a floral pattern.”
  2. Przekształcamy go w wektory za pomocą metody embedding() i modelu text-embedding-005. Ten krok powinien być Ci znany z poprzedniego etapu, na którym zastosowaliśmy funkcję osadzania do wszystkich elementów w tabeli.
  3. „<=>” oznacza użycie metody odległości COSINE SIMILARITY. Wszystkie dostępne miary podobieństwa znajdziesz w dokumentacji pgvector.
  4. Wynik metody wektorów dystrybucyjnych przekształcamy w typ wektorowy, aby był zgodny z wektorami przechowywanymi w bazie danych.
  5. LIMIT 5 oznacza, że chcemy wyodrębnić 5 najbliższych sąsiadów dla tekstu wyszukiwania.

Wynik wygląda tak:

fa7f0fc3a4c68804.png

Jak widać w wynikach, dopasowania są dość zbliżone do tekstu wyszukiwania. Spróbuj zmienić tekst, aby zobaczyć, jak zmieniają się wyniki.

7. Przygotowywanie AlloyDB do interakcji z zestawem narzędzi

Zanim skonfigurujemy zestaw narzędzi, włączmy w instancji AlloyDB łączność z publicznym adresem IP, aby nowe narzędzie miało 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. W wyniku znajdź adres eth0 inet i zastąp 2 ostatnie cyfry wartością 0.0 z maską „/16”. Na przykład może to być „XX.XX.0.0/16”, gdzie XX to liczby.
  4. Wklej ten adres IP w polu tekstowym „Sieci” w sekcji Autoryzowane sieci zewnętrzne na stronie edycji instancji.

5f6e60e8dec2cea1.png

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

Może to potrwać kilka minut.

8. Instalacja zestawu narzędzi MCP dla baz danych

  1. Możesz utworzyć folder projektu, w którym będziesz przechowywać szczegóły narzędzia. W tym przypadku pracujemy nad danymi sklepu z zabawkami, więc utwórzmy folder o nazwie „toystore” i przejdźmy do niego. Otwórz terminal Cloud Shell i sprawdź, czy Twój projekt jest wybrany i widoczny w wierszu poleceń terminala. Uruchom to polecenie w terminalu Cloud Shell:
mkdir toystore

cd toystore
  1. Aby pobrać i zainstalować pakiet narzędzi 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
  1. Przełącz na edytor Cloud Shell. Rozwiń nowo utworzony folder „toystore” i utwórz w nim nowy plik o nazwie tools.yaml. Skopiuj poniższą treść. Zastąp ID_TWOJEGO_PROJEKTU 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 po prostu wyszukujemy najbliższe dopasowanie do tekstu wyszukiwania użytkownika (opisu zabawki na zamówienie) i zwracamy jego cenę. Możesz też zmodyfikować go tak, aby znaleźć średnią cenę 5 najbardziej podobnych 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.

  1. Przejdź do terminala Cloud Shell i wpisz to polecenie, aby uruchomić serwer zestawu narzędzi z konfiguracją narzędzi:
./toolbox --tools_file "tools.yaml"
  1. Jeśli teraz otworzysz serwer w trybie podglądu w chmurze, powinien być widoczny działający serwer Toolbox z nowym narzędziem o nazwie get-toy-price..

9. Wdrożenie narzędzi MCP dla baz danych w Cloud Run

Wdróżmy go w Cloud Run, aby można było go używać w praktyce.

  1. Postępuj zgodnie z instrukcjami na tej stronie, aż dojdziesz do polecenia gcloud run deploy toolbox, które znajduje się w punkcie 3 w sekcji „Wdróż w Cloud Run”. Potrzebujesz pierwszej opcji, a nie drugiej, która jest przeznaczona do korzystania z metody sieci VPC.
  2. Po pomyślnym wdrożeniu otrzymasz wdrożony punkt końcowy Cloud Run serwera Toolbox. Sprawdź to za pomocą polecenia CURL.

Wskazówki:

Postępuj zgodnie z instrukcjami na stronie i nie pomijaj żadnych kroków.

Możesz już używać nowo wdrożonego narzędzia w aplikacji opartej na agentach.

10. Łączenie aplikacji z MCP Toolbox for Databases

W tej części utworzymy małą aplikację, aby przetestować narzędzie pod kątem interakcji z potrzebami aplikacji i pobierania odpowiedzi.

  1. Otwórz Google Colab i utwórz nowy notatnik.
  2. Uruchom w notatniku to polecenie
!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)
  1. Wynik powinien wyglądać tak:

5074f209a86c4f15.png

Jest to narzędzie wywoływane bezpośrednio w aplikacji w języku Python, która korzysta z zestawu narzędzi toolbox-langchain..

  1. 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.
  2. W tym celu zapoznaj się z fragmentami kodu.

11. Przenieś go do chmury.

Umieśćmy ten fragment kodu w funkcjach Cloud Run, aby był bezserwerowy.

  1. Skopiuj źródło z folderu repozytorium kodu, aby przenieść je do Cloud Functions.
  2. Otwórz konsolę Cloud Run Functions i kliknij UTWÓRZ FUNKCJĘ.
  3. W przypadku aplikacji demonstracyjnej pozostaw ją bez uwierzytelniania, a 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 do odpowiednich plików.
  5. Zastąp adres URL serwera w pliku main.py swoim adresem URL serwera.
  6. Wdróż funkcję, aby uzyskać punkt końcowy REST dla narzędzia do prognozowania cen, do którego można uzyskać dostęp w aplikacji internetowej sklepu z zabawkami.
  7. Punkt końcowy powinien wyglądać tak:

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

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

{

           "search": "White plush toy"

}

  1. Kliknij TEST THE FUNCTION (PRZETESTUJ FUNKCJĘ) lub uruchom w terminalu Cloud Shell, w zależności od tego, co chcesz użyć. Po prawej stronie, pod tytułem „Dane wyjściowe”, powinien pojawić się wynik:

d7ba57cf5e5ca553.png

12. Gratulacje

Gratulacje! Udało Ci się utworzyć solidne i w pełni modułowe narzędzie, które może wchodzić w interakcje z bazami danych, platformami i platformami orkiestracji generatywnej AI, aby pomóc Ci w tworzeniu aplikacji opartej na agentach.