Sprawdzanie faktów za pomocą agenta AI ADK i modelu Gemini

Poziom kodowania: zaawansowany
Czas trwania: 30 minut
Typ projektu: funkcja niestandardowa

Przegląd

Funkcja niestandardowa sprawdzania faktów w Arkuszach Google, która będzie używana jako projekt skryptu Google Apps Script powiązany z arkuszem i oparty na agencie Vertex AI oraz modelu Gemini.

Ten przykład pokazuje, jak używać w arkuszach kalkulacyjnych Google dwóch zaawansowanych typów zasobów AI:

1. Agenci AI do zaawansowanego, wieloetapowego wnioskowania z użyciem wielu narzędzi, którzy korzystają z agentów ADK wdrożonych w Vertex AI Agent Engine.
2. Modele AI do zaawansowanego rozumienia, generowania i streszczania treści za pomocą modeli Gemini z Vertex AI.

Cele

• Dowiedz się, co robi rozwiązanie.
• Dowiedz się, jak wdrożono rozwiązanie.
• Wdróż agenta Vertex AI.
• Skonfiguruj skrypt.
• Uruchom skrypt.

Informacje o rozwiązaniu

Funkcja niestandardowa Arkuszy ma nazwę FACT_CHECK i działa jako rozwiązanie kompleksowe. Analizuje ona wypowiedź, uzasadnia odpowiedź, korzystając z najnowszych informacji z internetu, i zwraca wynik w potrzebnym formacie:

• Użycie:
  • =FACT_CHECK("Your statement here"), aby uzyskać zwięzłe i podsumowane wyniki.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") w przypadku określonego formatu wyjściowego.
• Uzasadnienie: LLM Auditor ADK AI Agent (Python sample).
• Formatowanie danych wyjściowych: model Gemini.

To rozwiązanie wysyła żądania do interfejsów Vertex AI REST API za pomocą usługi UrlFetchApp.

Architektura

Poniższy diagram przedstawia architekturę zasobów Google Workspace i Google Cloud używanych przez funkcję niestandardową.

Wymagania wstępne

Aby użyć tego przykładu, musisz spełnić te wymagania wstępne:

• Konto Google (w przypadku kont Google Workspace może być wymagana zgoda administratora).

• przeglądarkę internetową z dostępem do internetu,

• Wymagania wstępne dotyczące agenta LLM Auditor ADK

  • Python 3.11 lub nowszy: aby zainstalować Pythona, postępuj zgodnie z instrukcjami na oficjalnej stronie internetowej Pythona.
  • Python Poetry: aby zainstalować to narzędzie, postępuj zgodnie z instrukcjami na oficjalnej stronie Poetry.
  • Google Cloud CLI: aby zainstalować interfejs, postępuj zgodnie z instrukcjami na oficjalnej stronie Google Cloud.

Przygotowywanie środowiska

W tej sekcji dowiesz się, jak utworzyć i skonfigurować projekt Google Cloud.

Tworzenie projektu Google Cloud

Konsola Google Cloud

1. W konsoli Google Cloud kliknij Menu  > Administracja > Utwórz projekt.

   Otwórz stronę Tworzenie projektu

2. W polu Nazwa projektu wpisz opisową nazwę projektu.

   Opcjonalnie: aby edytować identyfikator projektu, kliknij Edytuj. Po utworzeniu projektu nie można zmienić jego identyfikatora, więc wybierz taki, który będzie Ci odpowiadać przez cały okres jego istnienia.

3. W polu Lokalizacja kliknij Przeglądaj, aby wyświetlić potencjalne lokalizacje projektu. Następnie kliknij Wybierz.
   Uwaga: nie możesz znaleźć organizacji Google Workspace?
   Oznacza to, że nie korzystasz z konta Google Workspace. Niektóre funkcje opisane w dokumentacji dla deweloperów Google Workspace są dostępne tylko w projektach powiązanych z organizacją.
4. Kliknij Utwórz. W konsoli Google Cloud otworzy się strona Panel, a projekt zostanie utworzony w ciągu kilku minut.

interfejs wiersza poleceń gcloud

W jednym z tych środowisk programistycznych uzyskaj dostęp do interfejsu Google Cloud CLI (gcloud):

• Cloud Shell: aby używać terminala online z już skonfigurowanym interfejsem gcloud CLI, aktywuj Cloud Shell.
  Aktywuj Cloud Shell
• Lokalna powłoka: aby używać lokalnego środowiska programistycznego, zainstaluj i zainicjuj interfejs wiersza poleceń gcloud.
  Aby utworzyć projekt w Google Cloud, użyj polecenia gcloud projects create:

  gcloud projects create PROJECT_ID

  Zastąp PROJECT_ID identyfikatorem projektu, który chcesz utworzyć.

Włączanie płatności za projekt Cloud

Jeśli nie możesz połączyć konta rozliczeniowego, oznacza to, że nie masz uprawnień potrzebnych do wprowadzenia tej zmiany. Więcej informacji znajdziesz w artykule Uprawnienia wymagane do włączenia rozliczeń.

Konsola Google Cloud

1. W konsoli Google Cloud wybierz Płatności. Kliknij Menu > Rozliczenia > Moje projekty.

   Otwórz stronę Płatności za moje projekty

2. W sekcji Wybierz organizację wybierz organizację powiązaną z Twoim projektem Google Cloud.
3. W wierszu projektu otwórz menu Działania (), kliknij Zmień ustawienia płatności i wybierz konto Cloud Billing.
4. Kliknij Ustaw konto.

interfejs wiersza poleceń gcloud

1. Aby wyświetlić listę dostępnych kont rozliczeniowych, uruchom to polecenie:

   gcloud billing accounts list

2. Połącz konto rozliczeniowe z projektem Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Zastąp następujące elementy:

   • PROJECT_ID to identyfikator projektu projektu Cloud, w którym chcesz włączyć płatności.
   • BILLING_ACCOUNT_ID to identyfikator konta rozliczeniowego, które ma zostać połączone z projektem Google Cloud.

Włączanie interfejsu Vertex AI API

Konsola Google Cloud

1. Włącz interfejs Vertex AI API w konsoli Google Cloud.

   Włączanie interfejsów API

2. Sprawdź, czy włączasz interfejs Vertex AI API w odpowiednim projekcie Cloud, a potem kliknij Dalej.

3. Sprawdź, czy włączasz odpowiedni interfejs API, a potem kliknij Włącz.

interfejs wiersza poleceń gcloud

1. W razie potrzeby ustaw bieżący projekt Cloud na ten, który został utworzony za pomocą polecenia gcloud config set project:

   gcloud config set project PROJECT_ID

   Zastąp PROJECT_ID identyfikatorem projektu utworzonego projektu w Cloud.

2. Włącz interfejs Vertex AI API za pomocą polecenia gcloud services enable:

   gcloud services enable aiplatform.googleapis.com

Tworzenie konta usługi w konsoli Google Cloud

Utwórz nowe konto usługi z rolą Vertex AI User, wykonując te czynności:

Konsola Google Cloud

1. W konsoli Google Cloud otwórz Menu  > Administracja > Konta usługi.

   Otwórz stronę Konta usługi

2. Kliknij Utwórz konto usługi.
3. Wpisz szczegóły konta usługi, a następnie kliknij Utwórz i kontynuuj.
   Uwaga: domyślnie Google tworzy unikalny identyfikator konta usługi. Jeśli chcesz zmienić identyfikator, zmodyfikuj go w polu identyfikatora konta usługi.
4. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.
5. Kliknij Dalej.
6. Opcjonalnie: wpisz użytkowników lub grupy, które mogą zarządzać tym kontem usługi i wykonywać na nim działania. Więcej informacji znajdziesz w artykule Zarządzanie przejmowaniem tożsamości konta usługi.
7. Kliknij Gotowe. Zanotuj adres e-mail konta usługi.

interfejs wiersza poleceń gcloud

1. Utwórz konto usługi:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.

Konto usługi pojawi się na stronie kont usługi. Następnie utwórz klucz prywatny dla konta usługi.

Tworzenie klucza prywatnego

Ostrzeżenie: w tym przykładzie użyto wyeksportowanego klucza konta usługi, aby uprościć kod. Eksportowanie klucza prywatnego nie jest zalecane w środowisku produkcyjnym, ponieważ nie powinien on być przechowywany w niezabezpieczonym miejscu, np. w systemie kontroli wersji.

Więcej informacji o bezpiecznych wdrożeniach kont usługi i sprawdzonych metodach znajdziesz w artykule Wybieranie sytuacji, w których należy używać kont usługi.

Aby utworzyć i pobrać klucz prywatny dla konta usługi, wykonaj te czynności:

1. W konsoli Google Cloud otwórz Menu  > Administracja > Konta usługi.

   Otwórz stronę Konta usługi

2. Wybierz konto usługi.
3. Kliknij Klucze > Dodaj klucz > Utwórz nowy klucz.
4. Wybierz JSON, a potem kliknij Utwórz.

   Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Jest to jedyna kopia tego klucza. Informacje o tym, jak bezpiecznie przechowywać klucz, znajdziesz w artykule Zarządzanie kluczami konta usługi.

5. Kliknij Zamknij.

Więcej informacji o kontach usługi znajdziesz w artykule Konta usługi w dokumentacji Google Cloud IAM.

Wdrażanie agenta AI LLM Auditor ADK

1. Jeśli nie zostało to jeszcze zrobione, uwierzytelnij się na koncie Google Cloud i skonfiguruj Google Cloud CLI do korzystania z Twojego projektu Google Cloud.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Zastąp PROJECT_ID identyfikatorem utworzonego projektu w Cloud.

2. Pobieranie repozytorium GitHub

   Pobierz

3. W preferowanym lokalnym środowisku programistycznym wyodrębnij pobrany plik archiwum i otwórz katalog adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. Utwórz nowy zasobnik Cloud Storage przeznaczony dla agenta ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Zastąp następujące elementy:

   1. CLOUD_STORAGE_BUCKET_NAME z unikalną nazwą zasobnika, której chcesz użyć.
   2. PROJECT_ID z identyfikatorem utworzonego projektu Cloud.
   3. PROJECT_LOCATION z lokalizacją utworzonego projektu w chmurze.

5. Ustaw następujące zmienne środowiskowe:

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   Zastąp następujące elementy:

   1. CLOUD_STORAGE_BUCKET_NAME nazwą utworzonego zasobnika.
   2. PROJECT_ID z identyfikatorem utworzonego projektu Cloud.
   3. PROJECT_LOCATION z lokalizacją utworzonego projektu w chmurze.

6. Zainstaluj i wdroż agenta ADK ze środowiska wirtualnego.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Pobierz identyfikator agenta. Będzie on potrzebny później do skonfigurowania funkcji niestandardowej.

   python3 deployment/deploy.py --list

Sprawdź przykładowy kod

Opcjonalnie: zanim utworzysz nowy arkusz kalkulacyjny, poświęć chwilę na zapoznanie się z przykładowym kodem hostowanym w GitHubie.

Wyświetl w GitHubie

Tworzenie i konfigurowanie w nowym arkuszu

1. Kliknij poniższy przycisk i utwórz pełną kopię przykładowego arkusza kalkulacyjnego Google, w tym powiązanego z nim projektu Apps Script.

   Kopiowanie arkusza kalkulacyjnego Arkuszy Google

2. W nowo utworzonym arkuszu kalkulacyjnym kliknij Rozszerzenia > Apps Script.

3. W projekcie Apps Script otwórz Ustawienia projektu, kliknij Edytuj właściwości skryptu, a potem kliknij Dodaj właściwość skryptu, aby dodać te właściwości skryptu:

   1. LOCATION z lokalizacją projektu Google Cloud utworzonego w poprzednich krokach, np. us-central1.
   2. GEMINI_MODEL_ID z modelem Gemini, którego chcesz użyć, np.gemini-2.5-flash-lite.
   3. REASONING_ENGINE_ID z identyfikatorem agenta ADK audytora LLM wdrożonego w poprzednich krokach, np. 1234567890.
   4. SERVICE_ACCOUNT_KEY z kluczem JSON z konta usługi pobranym w poprzednich krokach, np. { ... }.

4. Kliknij Zapisz właściwości skryptu.

Testowanie funkcji niestandardowej

1. Otwórz nowo utworzony arkusz kalkulacyjny.
2. Zmień stwierdzenia w kolumnie A.
3. Formuły w kolumnie B są wykonywane, a następnie wyświetlają wyniki weryfikacji.

Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym samouczku, zalecamy usunięcie projektu w Cloud.

Ostrzeżenie: usunięcie projektu spowoduje, że:

• Wszystkie dane projektu zostaną usunięte. Jeśli na potrzeby tego samouczka został przez Ciebie użyty istniejący projekt, po jego usunięciu usuniesz też wszystkie inne wykonane w nim zadania.
• Niestandardowe identyfikatory projektu zostaną utracone. Podczas tworzenia tego projektu możesz utworzyć niestandardowy identyfikator projektu, którego chcesz używać w przyszłości. Aby zachować adresy URL, które używają identyfikatora projektu, np. adres URL w domenie appspot.com, usuń wybrane zasoby w projekcie zamiast usuwać cały projekt.

Jeśli zamierzasz skorzystać z innych samouczków i krótkich wprowadzeń, ponowne wykorzystanie tych samych projektów może pomóc Ci uniknąć przekroczenia Iimitów związanych z projektami.

1. W konsoli Google Cloud otwórz stronę Zarządzanie zasobami. Kliknij Menu > Administracja > Zarządzaj zasobami.

   Otwórz Menedżera zasobów

2. Z listy projektów wybierz projekt do usunięcia, a potem kliknij Usuń .
3. W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.

Dalsze kroki

• Funkcje niestandardowe w Arkuszach Google
• Rozszerzanie Arkuszy Google