Przejście na tryb multimodalny dzięki pakietowi dla programistów: asystent wydatków osobistych z Gemini 2.5, Firestore i Cloud Run

1. 📖 Wprowadzenie

db9331886978d543.png

Czy zdarzyło Ci się kiedyś odczuwać frustrację i niechęć do zarządzania wszystkimi wydatkami osobistymi? Ja też! Dlatego w tym ćwiczeniu utworzymy osobistego asystenta do zarządzania wydatkami, który będzie korzystać z Gemini 2.5, aby wykonywać za nas wszystkie zadania. Od zarządzania przesłanymi paragonami po analizę, czy nie wydajesz za dużo na kawę.

Asystent będzie dostępny w przeglądarce w formie interfejsu internetowego czatu, w którym można się z nim komunikować, przesyłać obrazy rachunków i prosić asystenta o ich zapisanie lub wyszukiwać rachunki, aby pobrać plik i przeprowadzić analizę wydatków. Wszystko to jest oparte na platformie Google Agent Development Kit.

Sama aplikacja jest podzielona na 2 usługi: frontend i backend. Dzięki temu możesz szybko utworzyć prototyp i wypróbować go, a także zrozumieć, jak wygląda umowa dotycząca interfejsu API, aby zintegrować obie usługi.

W tym ćwiczeniu wykonasz te czynności:

  1. przygotować projekt Google Cloud i włączyć w nim wszystkie wymagane interfejsy API;
  2. Konfigurowanie zasobnika w Google Cloud Storage i bazy danych w Firestore
  3. Tworzenie indeksowania Firestore
  4. Konfigurowanie obszaru roboczego dla środowiska kodowania
  5. strukturyzowanie kodu źródłowego agenta ADK, narzędzi, promptów itp.;
  6. Testowanie agenta za pomocą lokalnego interfejsu internetowego ADK do tworzenia stron internetowych
  7. utworzyć usługę frontendu – interfejs czatu przy użyciu biblioteki Gradio, aby wysyłać zapytania i przesyłać obrazy paragonów;
  8. utworzyć usługę backendu – serwer HTTP korzystający z FastAPI, w którym znajduje się kod agenta ADK, SessionService i Artifact Service;
  9. zarządzać zmiennymi środowiskowymi i konfigurować pliki wymagane do wdrożenia aplikacji w Cloud Run;
  10. Wdrażanie aplikacji w Cloud Run

Architecture Overview

90805d85052a5e5a.jpeg

Wymagania wstępne

  • Znajomość języka Python
  • znajomość podstawowej architektury full-stack z wykorzystaniem usługi HTTP;

Czego się nauczysz

  • prototypowanie frontendu stron internetowych za pomocą Gradio,
  • tworzenie usług backendu za pomocą FastAPI i Pydantic;
  • Projektowanie agenta ADK z wykorzystaniem jego różnych funkcji
  • Korzystanie z narzędzi
  • Zarządzanie sesjami i artefaktami
  • Wykorzystanie wywołania zwrotnego do modyfikacji danych wejściowych przed wysłaniem do Gemini
  • Wykorzystanie BuiltInPlanner do ulepszenia wykonywania zadań dzięki planowaniu
  • Szybkie debugowanie za pomocą lokalnego interfejsu internetowego ADK
  • Strategia optymalizacji interakcji multimodalnych przez analizowanie i pobieranie informacji za pomocą inżynierii promptów oraz modyfikowanie żądań Gemini za pomocą wywołania zwrotnego ADK
  • Generowanie wspomagane zbieraniem informacji przez agenta z użyciem Firestore jako wektorowej bazy danych
  • Zarządzanie zmiennymi środowiskowymi w pliku YAML za pomocą Pydantic-settings
  • Wdrażanie aplikacji w Cloud Run za pomocą pliku Dockerfile i podawanie zmiennych środowiskowych w pliku YAML

Czego potrzebujesz

  • Przeglądarka Chrome
  • konto Gmail,
  • projekt w chmurze z włączonymi płatnościami,

To ćwiczenie z programowania jest przeznaczone dla deweloperów na wszystkich poziomach zaawansowania (w tym dla początkujących) i wykorzystuje Pythona w przykładowej aplikacji. Jednak znajomość Pythona nie jest wymagana do zrozumienia przedstawionych pojęć.

2. 🚀 Zanim zaczniesz

Wybieranie aktywnego projektu w konsoli Cloud

W tym ćwiczeniu zakładamy, że masz już projekt Google Cloud z włączonymi płatnościami. Jeśli nie masz jeszcze konta, możesz je utworzyć, postępując zgodnie z instrukcjami poniżej.

  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.

fcdd90149a030bf5.png

Przygotowywanie bazy danych Firestore

Następnie musimy utworzyć bazę danych Firestore. Firestore w trybie natywnym to baza danych dokumentów NoSQL zaprojektowana pod kątem automatycznego skalowania, wysokiej wydajności i łatwego tworzenia aplikacji. Może też działać jako wektorowa baza danych, która może obsługiwać technikę generowania rozszerzonego przez pobieranie w naszym module.

  1. Na pasku wyszukiwania wpisz firestore i kliknij usługę Firestore.

44bbce791824bed6.png

  1. Następnie kliknij przycisk Utwórz bazę danych Firestore.
  2. Użyj (default) jako nazwy identyfikatora bazy danych i pozostaw zaznaczoną opcję Standard Edition. Na potrzeby tego modułu demonstracyjnego użyj Firestore Native z otwartymi regułami zabezpieczeń.
  1. Zauważysz też, że ta baza danych ma użycie na poziomie bezpłatnym. Następnie kliknij przycisk Utwórz bazę danych.

b97d210c465be94c.png

Po wykonaniu tych czynności powinno nastąpić przekierowanie do utworzonej bazy danych Firestore.

Konfigurowanie projektu w chmurze w terminalu Cloud Shell

  1. Użyjesz Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud, które ma wstępnie zainstalowane narzędzie bq. Kliknij Aktywuj Cloud Shell na górze konsoli Google Cloud.

26f20e837ff06119.png

  1. Po połączeniu z Cloud Shell sprawdź, czy uwierzytelnianie zostało już przeprowadzone, a projekt jest ustawiony na Twój identyfikator projektu. Aby to zrobić, użyj 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:
gcloud config set project <YOUR_PROJECT_ID>

Identyfikator PROJECT_ID możesz też zobaczyć w konsoli.

bb98435b79995b15.jpeg

Kliknij go, a po prawej stronie zobaczysz wszystkie swoje projekty i identyfikator projektu.

ffa73dee57de5307.jpeg

  1. Włącz wymagane interfejsy API za pomocą polecenia pokazanego poniżej. Może to potrwać kilka minut, więc prosimy o cierpliwość.
gcloud services enable aiplatform.googleapis.com \
                       firestore.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com

Po pomyślnym wykonaniu polecenia powinien wyświetlić się komunikat podobny do tego poniżej:

Operation "operations/..." finished successfully.

Zamiast polecenia gcloud możesz użyć konsoli, wyszukując każdą usługę lub korzystając z tego linku.

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

Polecenia gcloud i sposób ich użycia znajdziesz w dokumentacji.

Przygotowywanie zasobnika Cloud Storage w Google Cloud Storage

Następnie w tym samym terminalu musimy przygotować zasobnik GCS do przechowywania przesłanego pliku. Uruchom poniższe polecenie, aby utworzyć zasobnik. Potrzebna będzie unikalna, ale odpowiednia nazwa zasobnika, która będzie pasować do rachunków osobistego asystenta ds. wydatków. Dlatego użyjemy poniższej nazwy zasobnika połączonej z identyfikatorem projektu.

gsutil mb -l us-central1 gs://personal-expense-{your-project-id}

Wyświetli się ten wynik:

Creating gs://personal-expense-{your-project-id}

Możesz to sprawdzić, klikając menu nawigacyjne w lewym górnym rogu przeglądarki i wybierając Cloud Storage -> Zasobnik.

7b9fd51982d351fa.png

Firestore to natywna baza danych NoSQL, która oferuje doskonałą wydajność i elastyczność modelu danych, ale ma ograniczenia, jeśli chodzi o złożone zapytania. Ponieważ planujemy użyć kilku złożonych zapytań obejmujących wiele pól i wyszukiwania wektorowego, najpierw musimy utworzyć indeks. Więcej informacji znajdziesz w tej dokumentacji.

  1. Aby utworzyć indeks obsługujący zapytania złożone, uruchom to polecenie:
gcloud firestore indexes composite create \
        --collection-group=personal-expense-assistant-receipts \
        --field-config field-path=total_amount,order=ASCENDING \
        --field-config field-path=transaction_time,order=ASCENDING \
        --field-config field-path=__name__,order=ASCENDING \
        --database="(default)"
  1. Uruchom to polecenie, aby obsługiwać wyszukiwanie wektorowe
gcloud firestore indexes composite create \
        --collection-group="personal-expense-assistant-receipts" \
        --query-scope=COLLECTION \
        --field-config field-path="embedding",vector-config='{"dimension":"768", "flat": "{}"}' \
        --database="(default)"

Możesz sprawdzić utworzony indeks, otwierając Firestore w konsoli Cloud, klikając instancję bazy danych (domyślną) i wybierając Indeksy na pasku nawigacyjnym.

9849724dd55dfab7.png

Otwieranie edytora Cloud Shell i konfigurowanie katalogu roboczego aplikacji

Teraz możemy skonfigurować edytor kodu, aby zacząć kodować. W tym celu użyjemy edytora Cloud Shell.

  1. Kliknij przycisk Otwórz edytor, aby otworzyć edytor Cloud Shell, w którym możesz napisać kod.168eacea651b086c.png
  2. Następnie musimy sprawdzić, czy powłoka jest już skonfigurowana na prawidłowy IDENTYFIKATOR PROJEKTU. Jeśli w terminalu przed ikoną $ widzisz wartość w nawiasie ( ) (na zrzucie ekranu poniżej jest to "adk-multimodal-tool"), oznacza to, że jest to skonfigurowany projekt dla aktywnej sesji powłoki.

10a99ff80839b635.png

Jeśli wyświetlana wartość jest już prawidłowa, możesz pominąć następne polecenie. Jeśli jednak jest nieprawidłowy lub go brakuje, uruchom to polecenie:

gcloud config set project <YOUR_PROJECT_ID>
  1. Następnie sklonuj katalog roboczy szablonu tego ćwiczenia z GitHuba, uruchamiając to polecenie. Spowoduje to utworzenie katalogu roboczego w katalogu personal-expense-assistant.
git clone https://github.com/alphinside/personal-expense-assistant-adk-codelab-starter.git personal-expense-assistant
  1. Następnie przejdź do górnej sekcji edytora Cloud Shell i kliknij Plik -> Otwórz folder, znajdź katalog nazwa użytkownika i katalog personal-expense-assistant, a następnie kliknij przycisk OK. Spowoduje to, że wybrany katalog stanie się głównym katalogiem roboczym. W tym przykładzie nazwa użytkownika to alvinprayuda, więc ścieżka katalogu wygląda tak:

c87d2b76896d0c59.png524b9e6369f68cca.png

Edytor Cloud Shell powinien teraz wyglądać tak:

9a58ccc43f48338d.png

Konfiguracja środowiska

Przygotowanie środowiska wirtualnego Pythona

Kolejnym krokiem jest przygotowanie środowiska programistycznego. Bieżący aktywny terminal powinien znajdować się w katalogu roboczym personal-expense-assistant. W tym ćwiczeniu użyjemy Pythona 3.12 i menedżera projektów uv python, aby uprościć tworzenie wersji Pythona i środowiska wirtualnego oraz zarządzanie nimi.

  1. Jeśli terminal nie jest jeszcze otwarty, otwórz go, klikając Terminal -> New Terminal (Nowy terminal) lub używając skrótu Ctrl + Shift + C. Spowoduje to otwarcie okna terminala w dolnej części przeglądarki.

8635b60ae2f45bbc.jpeg

  1. Teraz zainicjujmy środowisko wirtualne za pomocą uv. Uruchom te polecenia:
cd ~/personal-expense-assistant
uv sync --frozen

Spowoduje to utworzenie katalogu .venv i zainstalowanie zależności. Szybki rzut oka na plik pyproject.toml dostarczy Ci informacji o zależnościach, które wyglądają tak:

dependencies = [
    "datasets>=3.5.0",
    "google-adk==1.18",
    "google-cloud-firestore>=2.20.1",
    "gradio>=5.23.1",
    "pydantic>=2.10.6",
    "pydantic-settings[yaml]>=2.8.1",
]

Konfigurowanie plików konfiguracji

Teraz musimy skonfigurować pliki konfiguracji dla tego projektu. Do odczytywania konfiguracji z pliku YAML używamy pydantic-settings.

Szablon pliku znajduje się w pliku settings.yaml.example. Musimy skopiować ten plik i zmienić jego nazwę na settings.yaml. Uruchom to polecenie, aby utworzyć plik

cp settings.yaml.example settings.yaml

Następnie skopiuj do pliku tę wartość:

GCLOUD_LOCATION: "us-central1"
GCLOUD_PROJECT_ID: "your-project-id"
BACKEND_URL: "http://localhost:8081/chat"
STORAGE_BUCKET_NAME: "personal-expense-{your-project-id}"
DB_COLLECTION_NAME: "personal-expense-assistant-receipts"

W tym ćwiczeniu użyjemy wstępnie skonfigurowanych wartości dla GCLOUD_LOCATION, BACKEND_URL, i DB_COLLECTION_NAME.

Teraz możemy przejść do kolejnego kroku, czyli utworzenia agenta, a następnie usług.

3. 🚀 Tworzenie agenta za pomocą pakietu Google ADK i Gemini 2.5

Wprowadzenie do struktury katalogów ADK

Zacznijmy od zapoznania się z możliwościami ADK i sposobem tworzenia agenta. Pełną dokumentację pakietu ADK znajdziesz pod tym adresem URL. ADK oferuje wiele narzędzi w ramach wykonywania poleceń CLI. Oto niektóre z nich :

  • Konfigurowanie struktury katalogów agenta
  • Szybkie testowanie interakcji za pomocą danych wejściowych i wyjściowych interfejsu wiersza poleceń
  • Szybkie konfigurowanie interfejsu internetowego lokalnego środowiska programistycznego

Teraz utwórzmy strukturę katalogów agenta za pomocą polecenia interfejsu wiersza poleceń. Uruchom podane niżej polecenie.

uv run adk create expense_manager_agent

Gdy pojawi się pytanie, wybierz model gemini-2.5-flash i backend Vertex AI. Kreator poprosi o podanie identyfikatora projektu i lokalizacji. Możesz zaakceptować opcje domyślne, naciskając Enter, lub zmienić je w razie potrzeby. Sprawdź, czy używasz prawidłowego identyfikatora projektu utworzonego wcześniej w tym module. Dane wyjściowe będą wyglądać tak:

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [going-multimodal-lab]: 
Enter Google Cloud region [us-central1]: 

Agent created in /home/username/personal-expense-assistant/expense_manager_agent:
- .env
- __init__.py
- agent.py

Spowoduje to utworzenie tej struktury katalogów agenta:

expense_manager_agent/
├── __init__.py
├── .env
├── agent.py

Jeśli sprawdzisz pliki init.py i agent.py, zobaczysz ten kod:

# __init__.py

from . import agent
# agent.py

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

Teraz możesz przetestować tę funkcję, uruchamiając

uv run adk run expense_manager_agent

Po zakończeniu testowania możesz wyjść z agenta, wpisując exit lub naciskając Ctrl+D.

Tworzenie agenta do zarządzania wydatkami

Zbudujmy agenta do zarządzania wydatkami. Otwórz plik expense_manager_agent/agent.py i skopiuj poniższy kod, który będzie zawierać root_agent.

# expense_manager_agent/agent.py

from google.adk.agents import Agent
from expense_manager_agent.tools import (
    store_receipt_data,
    search_receipts_by_metadata_filter,
    search_relevant_receipts_by_natural_language_query,
    get_receipt_data_by_image_id,
)
from expense_manager_agent.callbacks import modify_image_data_in_history
import os
from settings import get_settings
from google.adk.planners import BuiltInPlanner
from google.genai import types

SETTINGS = get_settings()
os.environ["GOOGLE_CLOUD_PROJECT"] = SETTINGS.GCLOUD_PROJECT_ID
os.environ["GOOGLE_CLOUD_LOCATION"] = SETTINGS.GCLOUD_LOCATION
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"

# Get the code file directory path and read the task prompt file
current_dir = os.path.dirname(os.path.abspath(__file__))
prompt_path = os.path.join(current_dir, "task_prompt.md")
with open(prompt_path, "r") as file:
    task_prompt = file.read()

root_agent = Agent(
    name="expense_manager_agent",
    model="gemini-2.5-flash",
    description=(
        "Personal expense agent to help user track expenses, analyze receipts, and manage their financial records"
    ),
    instruction=task_prompt,
    tools=[
        store_receipt_data,
        get_receipt_data_by_image_id,
        search_receipts_by_metadata_filter,
        search_relevant_receipts_by_natural_language_query,
    ],
    planner=BuiltInPlanner(
        thinking_config=types.ThinkingConfig(
            thinking_budget=2048,
        )
    ),
    before_model_callback=modify_image_data_in_history,
)

Wyjaśnienie kodu

Ten skrypt zawiera inicjowanie agenta, w którym inicjujemy te elementy:

  • Ustaw model, który ma być używany, na gemini-2.5-flash
  • Skonfiguruj opis i instrukcje agenta jako prompt systemowy, który jest odczytywany z task_prompt.md
  • Zapewnij niezbędne narzędzia do obsługi funkcji agenta.
  • Włącz planowanie przed wygenerowaniem ostatecznej odpowiedzi lub wykonaniem działania, korzystając z możliwości Flash Thinking modelu Gemini 2.5 Flash
  • Skonfiguruj przechwytywanie wywołania zwrotnego przed wysłaniem żądania do Gemini, aby ograniczyć liczbę danych obrazu wysyłanych przed wygenerowaniem podpowiedzi

4. 🚀 Konfigurowanie narzędzi agenta

Nasz agent do zarządzania wydatkami będzie miał te możliwości:

  • Wyodrębnij dane z obrazu rachunku i zapisz dane oraz plik
  • Dokładne wyszukiwanie danych o wydatkach
  • Wyszukiwanie kontekstowe danych o wydatkach

Dlatego potrzebujemy odpowiednich narzędzi, które będą obsługiwać tę funkcję. Utwórz nowy plik w katalogu expense_manager_agent i nazwij go tools.py.

touch expense_manager_agent/tools.py

Otwórz plik expense_manage_agent/tools.py, a następnie skopiuj poniższy kod.

# expense_manager_agent/tools.py

import datetime
from typing import Dict, List, Any
from google.cloud import firestore
from google.cloud.firestore_v1.vector import Vector
from google.cloud.firestore_v1 import FieldFilter
from google.cloud.firestore_v1.base_query import And
from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
from settings import get_settings
from google import genai

SETTINGS = get_settings()
DB_CLIENT = firestore.Client(
    project=SETTINGS.GCLOUD_PROJECT_ID
)  # Will use "(default)" database
COLLECTION = DB_CLIENT.collection(SETTINGS.DB_COLLECTION_NAME)
GENAI_CLIENT = genai.Client(
    vertexai=True, location=SETTINGS.GCLOUD_LOCATION, project=SETTINGS.GCLOUD_PROJECT_ID
)
EMBEDDING_DIMENSION = 768
EMBEDDING_FIELD_NAME = "embedding"
INVALID_ITEMS_FORMAT_ERR = """
Invalid items format. Must be a list of dictionaries with 'name', 'price', and 'quantity' keys."""
RECEIPT_DESC_FORMAT = """
Store Name: {store_name}
Transaction Time: {transaction_time}
Total Amount: {total_amount}
Currency: {currency}
Purchased Items:
{purchased_items}
Receipt Image ID: {receipt_id}
"""


def sanitize_image_id(image_id: str) -> str:
    """Sanitize image ID by removing any leading/trailing whitespace."""
    if image_id.startswith("[IMAGE-"):
        image_id = image_id.split("ID ")[1].split("]")[0]

    return image_id.strip()


def store_receipt_data(
    image_id: str,
    store_name: str,
    transaction_time: str,
    total_amount: float,
    purchased_items: List[Dict[str, Any]],
    currency: str = "IDR",
) -> str:
    """
    Store receipt data in the database.

    Args:
        image_id (str): The unique identifier of the image. For example IMAGE-POSITION 0-ID 12345,
            the ID of the image is 12345.
        store_name (str): The name of the store.
        transaction_time (str): The time of purchase, in ISO format ("YYYY-MM-DDTHH:MM:SS.ssssssZ").
        total_amount (float): The total amount spent.
        purchased_items (List[Dict[str, Any]]): A list of items purchased with their prices. Each item must have:
            - name (str): The name of the item.
            - price (float): The price of the item.
            - quantity (int, optional): The quantity of the item. Defaults to 1 if not provided.
        currency (str, optional): The currency of the transaction, can be derived from the store location.
            If unsure, default is "IDR".

    Returns:
        str: A success message with the receipt ID.

    Raises:
        Exception: If the operation failed or input is invalid.
    """
    try:
        # In case of it provide full image placeholder, extract the id string
        image_id = sanitize_image_id(image_id)

        # Check if the receipt already exists
        doc = get_receipt_data_by_image_id(image_id)

        if doc:
            return f"Receipt with ID {image_id} already exists"

        # Validate transaction time
        if not isinstance(transaction_time, str):
            raise ValueError(
                "Invalid transaction time: must be a string in ISO format 'YYYY-MM-DDTHH:MM:SS.ssssssZ'"
            )
        try:
            datetime.datetime.fromisoformat(transaction_time.replace("Z", "+00:00"))
        except ValueError:
            raise ValueError(
                "Invalid transaction time format. Must be in ISO format 'YYYY-MM-DDTHH:MM:SS.ssssssZ'"
            )

        # Validate items format
        if not isinstance(purchased_items, list):
            raise ValueError(INVALID_ITEMS_FORMAT_ERR)

        for _item in purchased_items:
            if (
                not isinstance(_item, dict)
                or "name" not in _item
                or "price" not in _item
            ):
                raise ValueError(INVALID_ITEMS_FORMAT_ERR)

            if "quantity" not in _item:
                _item["quantity"] = 1

        # Create a combined text from all receipt information for better embedding
        result = GENAI_CLIENT.models.embed_content(
            model="text-embedding-004",
            contents=RECEIPT_DESC_FORMAT.format(
                store_name=store_name,
                transaction_time=transaction_time,
                total_amount=total_amount,
                currency=currency,
                purchased_items=purchased_items,
                receipt_id=image_id,
            ),
        )

        embedding = result.embeddings[0].values

        doc = {
            "receipt_id": image_id,
            "store_name": store_name,
            "transaction_time": transaction_time,
            "total_amount": total_amount,
            "currency": currency,
            "purchased_items": purchased_items,
            EMBEDDING_FIELD_NAME: Vector(embedding),
        }

        COLLECTION.add(doc)

        return f"Receipt stored successfully with ID: {image_id}"
    except Exception as e:
        raise Exception(f"Failed to store receipt: {str(e)}")


def search_receipts_by_metadata_filter(
    start_time: str,
    end_time: str,
    min_total_amount: float = -1.0,
    max_total_amount: float = -1.0,
) -> str:
    """
    Filter receipts by metadata within a specific time range and optionally by amount.

    Args:
        start_time (str): The start datetime for the filter (in ISO format, e.g. 'YYYY-MM-DDTHH:MM:SS.ssssssZ').
        end_time (str): The end datetime for the filter (in ISO format, e.g. 'YYYY-MM-DDTHH:MM:SS.ssssssZ').
        min_total_amount (float): The minimum total amount for the filter (inclusive). Defaults to -1.
        max_total_amount (float): The maximum total amount for the filter (inclusive). Defaults to -1.

    Returns:
        str: A string containing the list of receipt data matching all applied filters.

    Raises:
        Exception: If the search failed or input is invalid.
    """
    try:
        # Validate start and end times
        if not isinstance(start_time, str) or not isinstance(end_time, str):
            raise ValueError("start_time and end_time must be strings in ISO format")
        try:
            datetime.datetime.fromisoformat(start_time.replace("Z", "+00:00"))
            datetime.datetime.fromisoformat(end_time.replace("Z", "+00:00"))
        except ValueError:
            raise ValueError("start_time and end_time must be strings in ISO format")

        # Start with the base collection reference
        query = COLLECTION

        # Build the composite query by properly chaining conditions
        # Notes that this demo assume 1 user only,
        # need to refactor the query for multiple user
        filters = [
            FieldFilter("transaction_time", ">=", start_time),
            FieldFilter("transaction_time", "<=", end_time),
        ]

        # Add optional filters
        if min_total_amount != -1:
            filters.append(FieldFilter("total_amount", ">=", min_total_amount))

        if max_total_amount != -1:
            filters.append(FieldFilter("total_amount", "<=", max_total_amount))

        # Apply the filters
        composite_filter = And(filters=filters)
        query = query.where(filter=composite_filter)

        # Execute the query and collect results
        search_result_description = "Search by Metadata Results:\n"
        for doc in query.stream():
            data = doc.to_dict()
            data.pop(
                EMBEDDING_FIELD_NAME, None
            )  # Remove embedding as it's not needed for display

            search_result_description += f"\n{RECEIPT_DESC_FORMAT.format(**data)}"

        return search_result_description
    except Exception as e:
        raise Exception(f"Error filtering receipts: {str(e)}")


def search_relevant_receipts_by_natural_language_query(
    query_text: str, limit: int = 5
) -> str:
    """
    Search for receipts with content most similar to the query using vector search.
    This tool can be use for user query that is difficult to translate into metadata filters.
    Such as store name or item name which sensitive to string matching.
    Use this tool if you cannot utilize the search by metadata filter tool.

    Args:
        query_text (str): The search text (e.g., "coffee", "dinner", "groceries").
        limit (int, optional): Maximum number of results to return (default: 5).

    Returns:
        str: A string containing the list of contextually relevant receipt data.

    Raises:
        Exception: If the search failed or input is invalid.
    """
    try:
        # Generate embedding for the query text
        result = GENAI_CLIENT.models.embed_content(
            model="text-embedding-004", contents=query_text
        )
        query_embedding = result.embeddings[0].values

        # Notes that this demo assume 1 user only,
        # need to refactor the query for multiple user
        vector_query = COLLECTION.find_nearest(
            vector_field=EMBEDDING_FIELD_NAME,
            query_vector=Vector(query_embedding),
            distance_measure=DistanceMeasure.EUCLIDEAN,
            limit=limit,
        )

        # Execute the query and collect results
        search_result_description = "Search by Contextual Relevance Results:\n"
        for doc in vector_query.stream():
            data = doc.to_dict()
            data.pop(
                EMBEDDING_FIELD_NAME, None
            )  # Remove embedding as it's not needed for display
            search_result_description += f"\n{RECEIPT_DESC_FORMAT.format(**data)}"

        return search_result_description
    except Exception as e:
        raise Exception(f"Error searching receipts: {str(e)}")


def get_receipt_data_by_image_id(image_id: str) -> Dict[str, Any]:
    """
    Retrieve receipt data from the database using the image_id.

    Args:
        image_id (str): The unique identifier of the receipt image. For example, if the placeholder is
            [IMAGE-ID 12345], the ID to use is 12345.

    Returns:
        Dict[str, Any]: A dictionary containing the receipt data with the following keys:
            - receipt_id (str): The unique identifier of the receipt image.
            - store_name (str): The name of the store.
            - transaction_time (str): The time of purchase in UTC.
            - total_amount (float): The total amount spent.
            - currency (str): The currency of the transaction.
            - purchased_items (List[Dict[str, Any]]): List of items purchased with their details.
        Returns an empty dictionary if no receipt is found.
    """
    # In case of it provide full image placeholder, extract the id string
    image_id = sanitize_image_id(image_id)

    # Query the receipts collection for documents with matching receipt_id (image_id)
    # Notes that this demo assume 1 user only,
    # need to refactor the query for multiple user
    query = COLLECTION.where(filter=FieldFilter("receipt_id", "==", image_id)).limit(1)
    docs = list(query.stream())

    if not docs:
        return {}

    # Get the first matching document
    doc_data = docs[0].to_dict()
    doc_data.pop(EMBEDDING_FIELD_NAME, None)

    return doc_data

Wyjaśnienie kodu

W tej implementacji funkcji narzędzi projektujemy narzędzia wokół tych 2 głównych koncepcji:

  • Analizowanie danych z paragonu i mapowanie ich na oryginalny plik za pomocą zmiennej ciągu znaków identyfikatora obrazu [IMAGE-ID <hash-of-image-1>]
  • przechowywanie i pobieranie danych za pomocą bazy danych Firestore,

Narzędzie „store_receipt_data”

747fb55e801455f4.png

To narzędzie do optycznego rozpoznawania znaków, które analizuje wymagane informacje z danych obrazu, rozpoznaje ciąg identyfikatora obrazu i mapuje je razem, aby zapisać je w bazie danych Firestore.

Dodatkowo to narzędzie konwertuje zawartość paragonu na wektor dystrybucyjny za pomocą text-embedding-004, dzięki czemu wszystkie metadane i wektor dystrybucyjny są przechowywane i indeksowane razem. Zapewnia elastyczność, umożliwiając pobieranie danych za pomocą zapytania lub wyszukiwania kontekstowego.

Po pomyślnym wykonaniu tego narzędzia zobaczysz, że dane z paragonu są już zindeksowane w bazie danych Firestore, jak pokazano poniżej.

636d56be9880f3c7.png

Narzędzie „search_receipts_by_metadata_filter”

6d8fbd9b43ff7ea7.png

To narzędzie konwertuje zapytanie użytkownika na filtr zapytania o metadane, który obsługuje wyszukiwanie według zakresu dat lub łącznej liczby transakcji. Zwróci wszystkie dopasowane dane paragonu, przy czym w tym procesie usuniemy pole wektora dystrybucyjnego, ponieważ nie jest ono potrzebne agentowi do zrozumienia kontekstu.

Narzędzie „search_relevant_receipts_by_natural_language_query”

7262c75114af0060.png

To jest nasze narzędzie do generowania rozszerzonego przez wyszukiwanie w zapisanych informacjach (RAG). Nasz agent może zaprojektować własne zapytanie, aby pobrać odpowiednie rachunki z wektorowej bazy danych, i może też wybrać, kiedy użyć tego narzędzia. Koncepcja umożliwienia agentowi samodzielnego decydowania, czy użyje tego narzędzia RAG, i tworzenia własnego zapytania jest jedną z definicji podejścia agentowej RAG.

Nie tylko pozwalamy mu na tworzenie własnego zapytania, ale też na wybór liczby odpowiednich dokumentów, które chce pobrać. W połączeniu z odpowiednią inżynierią promptów, np.

# Example prompt

Always filter the result from tool
search_relevant_receipts_by_natural_language_query as the returned 
result may contain irrelevant information

Dzięki temu narzędzie będzie mogło wyszukiwać niemal wszystko, choć może nie zwracać wszystkich oczekiwanych wyników ze względu na niedokładny charakter wyszukiwania najbliższego sąsiada.

5. 🚀 Modyfikowanie kontekstu rozmowy za pomocą wywołań zwrotnych

Google ADK umożliwia „przechwytywanie” Agent Runtime na różnych poziomach. Więcej informacji o tej funkcji znajdziesz w tej dokumentacji. W tym module używamy before_model_callback, aby zmodyfikować żądanie przed wysłaniem go do LLM i usunąć dane obrazu ze starego kontekstu historii rozmów ( uwzględniamy tylko dane obrazu z ostatnich 3 interakcji użytkownika) w celu zwiększenia wydajności.

Chcemy jednak, aby agent miał w razie potrzeby dostęp do kontekstu danych obrazu. Dlatego dodajemy mechanizm, który po każdym bajcie danych obrazu w rozmowie dodaje obiekt zastępczy identyfikatora obrazu w postaci ciągu znaków. Pomoże to agentowi połączyć identyfikator obrazu z rzeczywistymi danymi pliku, które można wykorzystać zarówno podczas przechowywania, jak i pobierania obrazu. Struktura będzie wyglądać tak:

<image-byte-data-1>
[IMAGE-ID <hash-of-image-1>]
<image-byte-data-2>
[IMAGE-ID <hash-of-image-2>]
And so on..

Gdy dane bajtowe stają się nieaktualne w historii rozmowy, identyfikator ciągu znaków nadal tam jest, aby umożliwić dostęp do danych za pomocą narzędzia. Przykładowa struktura historii po usunięciu danych obrazu

[IMAGE-ID <hash-of-image-1>]
[IMAGE-ID <hash-of-image-2>]
And so on..

Rozpocznij Utwórz nowy plik w katalogu expense_manager_agent i nadaj mu nazwę callbacks.py.

touch expense_manager_agent/callbacks.py

Otwórz plik expense_manager_agent/callbacks.py i skopiuj poniższy kod.

# expense_manager_agent/callbacks.py

import hashlib
from google.genai import types
from google.adk.agents.callback_context import CallbackContext
from google.adk.models.llm_request import LlmRequest


def modify_image_data_in_history(
    callback_context: CallbackContext, llm_request: LlmRequest
) -> None:
    # The following code will modify the request sent to LLM
    # We will only keep image data in the last 3 user messages using a reverse and counter approach

    # Count how many user messages we've processed
    user_message_count = 0

    # Process the reversed list
    for content in reversed(llm_request.contents):
        # Only count for user manual query, not function call
        if (content.role == "user") and (content.parts[0].function_response is None):
            user_message_count += 1
            modified_content_parts = []

            # Check any missing image ID placeholder for any image data
            # Then remove image data from conversation history if more than 3 user messages
            for idx, part in enumerate(content.parts):
                if part.inline_data is None:
                    modified_content_parts.append(part)
                    continue

                if (
                    (idx + 1 >= len(content.parts))
                    or (content.parts[idx + 1].text is None)
                    or (not content.parts[idx + 1].text.startswith("[IMAGE-ID "))
                ):
                    # Generate hash ID for the image and add a placeholder
                    image_data = part.inline_data.data
                    hasher = hashlib.sha256(image_data)
                    image_hash_id = hasher.hexdigest()[:12]
                    placeholder = f"[IMAGE-ID {image_hash_id}]"

                    # Only keep image data in the last 3 user messages
                    if user_message_count <= 3:
                        modified_content_parts.append(part)

                    modified_content_parts.append(types.Part(text=placeholder))

                else:
                    # Only keep image data in the last 3 user messages
                    if user_message_count <= 3:
                        modified_content_parts.append(part)

            # This will modify the contents inside the llm_request
            content.parts = modified_content_parts

6. 🚀 Prompt

Zaprojektowanie agenta o złożonych interakcjach i możliwościach wymaga znalezienia wystarczająco dobrego prompta, który będzie nim kierować, aby zachowywał się tak, jak chcemy.

Wcześniej mieliśmy mechanizm obsługi danych obrazu w historii rozmów, a także narzędzia, które mogły nie być łatwe w użyciu, takie jak search_relevant_receipts_by_natural_language_query.. Chcemy też, aby agent mógł wyszukiwać i pobierać prawidłowy obraz paragonu. Oznacza to, że musimy odpowiednio przekazać wszystkie te informacje w odpowiedniej strukturze promptu.

Poprosimy agenta o uporządkowanie danych wyjściowych w następującym formacie Markdown, aby przeanalizować proces myślowy, ostateczną odpowiedź i załącznik ( jeśli istnieje):

# THINKING PROCESS

Thinking process here

# FINAL RESPONSE

Response to the user here

Attachments put inside json block

{
    "attachments": [
      "[IMAGE-ID <hash-id-1>]",
      "[IMAGE-ID <hash-id-2>]",
      ...
    ]
}

Zacznijmy od tego prompta, aby uzyskać oczekiwane zachowanie agenta do zarządzania wydatkami. Plik task_prompt.md powinien już znajdować się w naszym katalogu roboczym, ale musimy go przenieść do katalogu expense_manager_agent. Aby go przenieść, uruchom to polecenie:

mv task_prompt.md expense_manager_agent/task_prompt.md

7. 🚀 Testowanie agenta

Teraz spróbujmy skomunikować się z agentem za pomocą interfejsu wiersza poleceń. Uruchom to polecenie:

uv run adk run expense_manager_agent

Wyświetlą się dane wyjściowe podobne do tych, w których możesz rozmawiać z agentem, ale za pomocą tego interfejsu możesz wysyłać tylko tekst.

Log setup complete: /tmp/agents_log/agent.xxxx_xxx.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent root_agent, type exit to exit.
user: hello
[root_agent]: Hello there! How can I help you today?
user: 

Oprócz interakcji z interfejsem wiersza poleceń ADK umożliwia też korzystanie z interfejsu programistycznego, który pozwala na interakcję i sprawdzanie, co się dzieje podczas interakcji. Uruchom to polecenie, aby uruchomić lokalny serwer UI do programowania:

uv run adk web --port 8080

Wygeneruje dane wyjściowe podobne do poniższego przykładu, co oznacza, że możemy już uzyskać dostęp do interfejsu internetowego.

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

Aby to sprawdzić, kliknij przycisk Podgląd w przeglądarce w górnej części edytora Cloud Shell i wybierz Podejrzyj na porcie 8080.

edc73e971b9fc60c.png

Zobaczysz tę stronę internetową, na której możesz wybrać dostępnych agentów w menu w lewym górnym rogu ( w naszym przypadku powinien to być expense_manager_agent) i wejść w interakcję z botem. W lewym oknie zobaczysz wiele informacji o szczegółach logów podczas działania Agent Runtime.

16c333a4b782eeba.png

Wypróbujmy kilka działań. Prześlij te 2 przykładowe rachunki ( źródło : zbiory danych Hugging Face mousserlane/id_receipt_dataset) . Kliknij prawym przyciskiem myszy każdy obraz i wybierz Zapisz obraz jako…. ( spowoduje to pobranie obrazu paragonu), a następnie prześlij plik do bota, klikając ikonę „spinacza”, i powiedz, że chcesz zapisać te paragony.

2975b3452e0ac0bd.png 143a2e147a18fc38.png

Następnie wypróbuj te zapytania, aby wyszukać lub pobrać pliki:

  • „Podaj zestawienie wydatków i ich sumę w 2023 r.”
  • „Daj mi plik z rachunkiem z Indomaret”

Gdy używa niektórych narzędzi, możesz sprawdzić, co się dzieje, w interfejsie programistycznym.

da461a67b7d81ad5.png

Zobacz, jak agent odpowiada, i sprawdź, czy przestrzega wszystkich reguł podanych w prompcie w pliku task_prompt.py. Gratulacje! Masz teraz kompletnego, działającego agenta programistycznego.

Teraz czas na dodanie odpowiedniego i ładnego interfejsu oraz funkcji przesyłania i pobierania pliku obrazu.

8. 🚀 Tworzenie usługi frontendu za pomocą Gradio

Utworzymy interfejs internetowy czatu, który wygląda tak:

db9331886978d543.png

Zawiera interfejs czatu z polem do wprowadzania danych, w którym użytkownicy mogą wysyłać tekst i przesyłać pliki graficzne z rachunkami.

Usługę frontendową utworzymy za pomocą Gradio.

Utwórz nowy plik i nadaj mu nazwę frontend.py.

touch frontend.py

następnie skopiuj poniższy kod i zapisz go

import mimetypes
import gradio as gr
import requests
import base64
from typing import List, Dict, Any
from settings import get_settings
from PIL import Image
import io
from schema import ImageData, ChatRequest, ChatResponse


SETTINGS = get_settings()


def encode_image_to_base64_and_get_mime_type(image_path: str) -> ImageData:
    """Encode a file to base64 string and get MIME type.

    Reads an image file and returns the base64-encoded image data and its MIME type.

    Args:
        image_path: Path to the image file to encode.

    Returns:
        ImageData object containing the base64 encoded image data and its MIME type.
    """
    # Read the image file
    with open(image_path, "rb") as file:
        image_content = file.read()

    # Get the mime type
    mime_type = mimetypes.guess_type(image_path)[0]

    # Base64 encode the image
    base64_data = base64.b64encode(image_content).decode("utf-8")

    # Return as ImageData object
    return ImageData(serialized_image=base64_data, mime_type=mime_type)


def decode_base64_to_image(base64_data: str) -> Image.Image:
    """Decode a base64 string to PIL Image.

    Converts a base64-encoded image string back to a PIL Image object
    that can be displayed or processed further.

    Args:
        base64_data: Base64 encoded string of the image.

    Returns:
        PIL Image object of the decoded image.
    """
    # Decode the base64 string and convert to PIL Image
    image_data = base64.b64decode(base64_data)
    image_buffer = io.BytesIO(image_data)
    image = Image.open(image_buffer)

    return image


def get_response_from_llm_backend(
    message: Dict[str, Any],
    history: List[Dict[str, Any]],
) -> List[str | gr.Image]:
    """Send the message and history to the backend and get a response.

    Args:
        message: Dictionary containing the current message with 'text' and optional 'files' keys.
        history: List of previous message dictionaries in the conversation.

    Returns:
        List containing text response and any image attachments from the backend service.
    """
    # Extract files and convert to base64
    image_data = []
    if uploaded_files := message.get("files", []):
        for file_path in uploaded_files:
            image_data.append(encode_image_to_base64_and_get_mime_type(file_path))

    # Prepare the request payload
    payload = ChatRequest(
        text=message["text"],
        files=image_data,
        session_id="default_session",
        user_id="default_user",
    )

    # Send request to backend
    try:
        response = requests.post(SETTINGS.BACKEND_URL, json=payload.model_dump())
        response.raise_for_status()  # Raise exception for HTTP errors

        result = ChatResponse(**response.json())
        if result.error:
            return [f"Error: {result.error}"]

        chat_responses = []

        if result.thinking_process:
            chat_responses.append(
                gr.ChatMessage(
                    role="assistant",
                    content=result.thinking_process,
                    metadata={"title": "🧠 Thinking Process"},
                )
            )

        chat_responses.append(gr.ChatMessage(role="assistant", content=result.response))

        if result.attachments:
            for attachment in result.attachments:
                image_data = attachment.serialized_image
                chat_responses.append(gr.Image(decode_base64_to_image(image_data)))

        return chat_responses
    except requests.exceptions.RequestException as e:
        return [f"Error connecting to backend service: {str(e)}"]


if __name__ == "__main__":
    demo = gr.ChatInterface(
        get_response_from_llm_backend,
        title="Personal Expense Assistant",
        description="This assistant can help you to store receipts data, find receipts, and track your expenses during certain period.",
        type="messages",
        multimodal=True,
        textbox=gr.MultimodalTextbox(file_count="multiple", file_types=["image"]),
    )

    demo.launch(
        server_name="0.0.0.0",
        server_port=8080,
    )

Następnie możemy spróbować uruchomić usługę frontendu za pomocą tego polecenia. Nie zapomnij zmienić nazwy pliku main.py na frontend.py.

uv run frontend.py

W konsoli Cloud zobaczysz dane wyjściowe podobne do tych:

* Running on local URL:  http://0.0.0.0:8080

To create a public link, set `share=True` in `launch()`.

Następnie możesz sprawdzić interfejs internetowy, klikając link do lokalnego adresu URL, przytrzymując klawisz Ctrl. Możesz też uzyskać dostęp do aplikacji frontendowej, klikając przycisk Podgląd w przeglądarce w prawym górnym rogu edytora Cloud i wybierając Podejrzyj na porcie 8080.

b477bc3c686a5fc3.jpeg

Zobaczysz interfejs internetowy, ale podczas próby przesłania czatu pojawi się oczekiwany błąd, ponieważ usługa backendu nie została jeszcze skonfigurowana.

b5de2f284155dac2.png

Teraz pozwól usłudze działać i nie wyłączaj jej jeszcze. Usługę backendu uruchomimy na innej karcie terminala.

Wyjaśnienie kodu

W tym kodzie frontendu najpierw umożliwiamy użytkownikowi wysyłanie tekstu i przesyłanie wielu plików. Gradio pozwala nam utworzyć tego rodzaju funkcję za pomocą metody gr.ChatInterface połączonej z gr.MultimodalTextbox.

Zanim wyślemy plik i tekst do backendu, musimy określić typ MIME pliku, ponieważ jest on wymagany przez backend. Musimy też zakodować bajt pliku graficznego w formacie base64 i wysłać go razem z typem MIME.

class ImageData(BaseModel):
    """Model for image data with hash identifier.

    Attributes:
        serialized_image: Optional Base64 encoded string of the image content.
        mime_type: MIME type of the image.
    """

    serialized_image: str
    mime_type: str

Schemat używany do interakcji między frontendem a backendem jest zdefiniowany w pliku schema.py. Do wymuszania sprawdzania poprawności danych w schemacie używamy modelu Pydantic BaseModel.

Po otrzymaniu odpowiedzi już rozdzielamy, która część jest procesem myślowym, ostateczną odpowiedzią i załącznikiem. Możemy więc użyć komponentu Gradio, aby wyświetlić każdy komponent z komponentem interfejsu.

class ChatResponse(BaseModel):
    """Model for a chat response.

    Attributes:
        response: The text response from the model.
        thinking_process: Optional thinking process of the model.
        attachments: List of image data to be displayed to the user.
        error: Optional error message if something went wrong.
    """

    response: str
    thinking_process: str = ""
    attachments: List[ImageData] = []
    error: Optional[str] = None

9. 🚀 Tworzenie usługi backendu za pomocą FastAPI

Następnie musimy utworzyć backend, który może zainicjować naszego agenta wraz z innymi komponentami, aby umożliwić uruchomienie Agent Runtime.

Utwórz nowy plik i nadaj mu nazwę backend.py.

touch backend.py

i skopiuj ten kod:

from expense_manager_agent.agent import root_agent as expense_manager_agent
from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner
from google.adk.events import Event
from fastapi import FastAPI, Body, Depends
from typing import AsyncIterator
from types import SimpleNamespace
import uvicorn
from contextlib import asynccontextmanager
from utils import (
    extract_attachment_ids_and_sanitize_response,
    download_image_from_gcs,
    extract_thinking_process,
    format_user_request_to_adk_content_and_store_artifacts,
)
from schema import ImageData, ChatRequest, ChatResponse
import logger
from google.adk.artifacts import GcsArtifactService
from settings import get_settings

SETTINGS = get_settings()
APP_NAME = "expense_manager_app"


# Application state to hold service contexts
class AppContexts(SimpleNamespace):
    """A class to hold application contexts with attribute access"""

    session_service: InMemorySessionService = None
    artifact_service: GcsArtifactService = None
    expense_manager_agent_runner: Runner = None


# Initialize application state
app_contexts = AppContexts()


@asynccontextmanager
async def lifespan(app: FastAPI):
    # Initialize service contexts during application startup
    app_contexts.session_service = InMemorySessionService()
    app_contexts.artifact_service = GcsArtifactService(
        bucket_name=SETTINGS.STORAGE_BUCKET_NAME
    )
    app_contexts.expense_manager_agent_runner = Runner(
        agent=expense_manager_agent,  # The agent we want to run
        app_name=APP_NAME,  # Associates runs with our app
        session_service=app_contexts.session_service,  # Uses our session manager
        artifact_service=app_contexts.artifact_service,  # Uses our artifact manager
    )

    logger.info("Application started successfully")
    yield
    logger.info("Application shutting down")
    # Perform cleanup during application shutdown if necessary


# Helper function to get application state as a dependency
async def get_app_contexts() -> AppContexts:
    return app_contexts


# Create FastAPI app
app = FastAPI(title="Personal Expense Assistant API", lifespan=lifespan)


@app.post("/chat", response_model=ChatResponse)
async def chat(
    request: ChatRequest = Body(...),
    app_context: AppContexts = Depends(get_app_contexts),
) -> ChatResponse:
    """Process chat request and get response from the agent"""

    # Prepare the user's message in ADK format and store image artifacts
    content = await format_user_request_to_adk_content_and_store_artifacts(
        request=request,
        app_name=APP_NAME,
        artifact_service=app_context.artifact_service,
    )

    final_response_text = "Agent did not produce a final response."  # Default

    # Use the session ID from the request or default if not provided
    session_id = request.session_id
    user_id = request.user_id

    # Create session if it doesn't exist
    if not await app_context.session_service.get_session(
        app_name=APP_NAME, user_id=user_id, session_id=session_id
    ):
        await app_context.session_service.create_session(
            app_name=APP_NAME, user_id=user_id, session_id=session_id
        )

    try:
        # Process the message with the agent
        # Type annotation: runner.run_async returns an AsyncIterator[Event]
        events_iterator: AsyncIterator[Event] = (
            app_context.expense_manager_agent_runner.run_async(
                user_id=user_id, session_id=session_id, new_message=content
            )
        )
        async for event in events_iterator:  # event has type Event
            # Key Concept: is_final_response() marks the concluding message for the turn
            if event.is_final_response():
                if event.content and event.content.parts:
                    # Extract text from the first part
                    final_response_text = event.content.parts[0].text
                elif event.actions and event.actions.escalate:
                    # Handle potential errors/escalations
                    final_response_text = f"Agent escalated: {event.error_message or 'No specific message.'}"
                break  # Stop processing events once the final response is found

        logger.info(
            "Received final response from agent", raw_final_response=final_response_text
        )

        # Extract and process any attachments and thinking process in the response
        base64_attachments = []
        sanitized_text, attachment_ids = extract_attachment_ids_and_sanitize_response(
            final_response_text
        )
        sanitized_text, thinking_process = extract_thinking_process(sanitized_text)

        # Download images from GCS and replace hash IDs with base64 data
        for image_hash_id in attachment_ids:
            # Download image data and get MIME type
            result = await download_image_from_gcs(
                artifact_service=app_context.artifact_service,
                image_hash=image_hash_id,
                app_name=APP_NAME,
                user_id=user_id,
                session_id=session_id,
            )
            if result:
                base64_data, mime_type = result
                base64_attachments.append(
                    ImageData(serialized_image=base64_data, mime_type=mime_type)
                )

        logger.info(
            "Processed response with attachments",
            sanitized_response=sanitized_text,
            thinking_process=thinking_process,
            attachment_ids=attachment_ids,
        )

        return ChatResponse(
            response=sanitized_text,
            thinking_process=thinking_process,
            attachments=base64_attachments,
        )

    except Exception as e:
        logger.error("Error processing chat request", error_message=str(e))
        return ChatResponse(
            response="", error=f"Error in generating response: {str(e)}"
        )


# Only run the server if this file is executed directly
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8081)

Następnie możemy spróbować uruchomić usługę backendu. Pamiętaj, że w poprzednim kroku uruchomiliśmy usługę frontendową. Teraz musimy otworzyć nowy terminal i spróbować uruchomić usługę backendową.

  1. Utwórz nowy terminal. Przejdź do terminala w dolnej części i znajdź przycisk „+”, aby utworzyć nowy terminal. Możesz też nacisnąć Ctrl + Shift + C, aby otworzyć nowy terminal.

235e2f9144d82803.jpeg

  1. Następnie upewnij się, że jesteś w katalogu roboczym personal-expense-assistant, i uruchom to polecenie:
uv run backend.py
  1. Jeśli się uda, zobaczysz dane wyjściowe podobne do tych:
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

Wyjaśnienie kodu

Inicjowanie agenta ADK, SessionService i ArtifactService

Aby uruchomić agenta w usłudze backendu, musimy utworzyć Runnera, który będzie korzystał zarówno z SessionService, jak i z naszego agenta. SessionService będzie zarządzać historią i stanem rozmowy, więc po integracji z Runnerem umożliwi naszemu agentowi otrzymywanie kontekstu trwających rozmów.

Do obsługi przesłanego pliku używamy też ArtifactService. Więcej informacji o sesji i artefaktach ADK znajdziesz tutaj.

...

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Initialize service contexts during application startup
    app_contexts.session_service = InMemorySessionService()
    app_contexts.artifact_service = GcsArtifactService(
        bucket_name=SETTINGS.STORAGE_BUCKET_NAME
    )
    app_contexts.expense_manager_agent_runner = Runner(
        agent=expense_manager_agent,  # The agent we want to run
        app_name=APP_NAME,  # Associates runs with our app
        session_service=app_contexts.session_service,  # Uses our session manager
        artifact_service=app_contexts.artifact_service,  # Uses our artifact manager
    )

    logger.info("Application started successfully")
    yield
    logger.info("Application shutting down")
    # Perform cleanup during application shutdown if necessary

...

W tej wersji demonstracyjnej używamy usług InMemorySessionService i GcsArtifactService do integracji z naszym agentem Runner. Historia rozmów jest przechowywana w pamięci, więc zostanie utracona po zakończeniu lub ponownym uruchomieniu usługi backendu. Inicjujemy je w cyklu życia aplikacji FastAPI, aby zostały wstrzyknięte jako zależność w trasie /chat.

Przesyłanie i pobieranie obrazu za pomocą GcsArtifactService

Wszystkie przesłane obrazy będą przechowywane jako artefakty przez GcsArtifactService. Możesz to sprawdzić w funkcji format_user_request_to_adk_content_and_store_artifacts w pliku utils.py.

...    

# Prepare the user's message in ADK format and store image artifacts
content = await asyncio.to_thread(
    format_user_request_to_adk_content_and_store_artifacts,
    request=request,
    app_name=APP_NAME,
    artifact_service=app_context.artifact_service,
)

...

Wszystkie żądania, które będą przetwarzane przez agenta, muszą być sformatowane jako typ types.Content. W funkcji przetwarzamy też dane każdego obrazu i wyodrębniamy jego identyfikator, który ma zostać zastąpiony obiektem zastępczym identyfikatora obrazu.

Podobny mechanizm jest używany do pobierania załączników po wyodrębnieniu identyfikatorów obrazów za pomocą wyrażenia regularnego:

...
sanitized_text, attachment_ids = extract_attachment_ids_and_sanitize_response(
    final_response_text
)
sanitized_text, thinking_process = extract_thinking_process(sanitized_text)

# Download images from GCS and replace hash IDs with base64 data
for image_hash_id in attachment_ids:
    # Download image data and get MIME type
    result = await asyncio.to_thread(
        download_image_from_gcs,
        artifact_service=app_context.artifact_service,
        image_hash=image_hash_id,
        app_name=APP_NAME,
        user_id=user_id,
        session_id=session_id,
    )
...

10. 🚀 Test integracji

Teraz powinno być uruchomionych kilka usług na różnych kartach konsoli Cloud:

  • Usługa frontendowa działa na porcie 8080
* Running on local URL:  http://0.0.0.0:8080

To create a public link, set `share=True` in `launch()`.
  • Usługa backendu działa na porcie 8081
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

W obecnym stanie możesz przesyłać obrazy paragonów i bezproblemowo rozmawiać z asystentem w aplikacji internetowej na porcie 8080.

Kliknij przycisk Podgląd w przeglądarce w górnej części edytora Cloud Shell i wybierz Podejrzyj na porcie 8080.

edc73e971b9fc60c.png

Teraz wejdźmy w interakcję z asystentem.

Pobierz te potwierdzenia. Te dane z paragonów pochodzą z okresu od 2023 do 2024 r. Poproś asystenta o ich zapisanie lub przesłanie.

  • Receipt Drive ( źródło: zbiory danych Hugging Face mousserlane/id_receipt_dataset)

Zadawanie różnych pytań

  • „Podaj mi zestawienie miesięcznych wydatków w latach 2023–2024”.
  • „Pokaż mi rachunek za transakcję dotyczącą kawy”
  • „Podaj mi plik z rachunkiem z Yakiniku Like”
  • Etc

Oto fragment udanej interakcji:

e01dc7a8ec673aa4.png9341212f8d54c98a.png

11. 🚀 Wdrażanie w Cloud Run

Oczywiście chcemy mieć dostęp do tej niesamowitej aplikacji z dowolnego miejsca. W tym celu możemy umieścić tę aplikację w pakiecie i wdrożyć ją w Cloud Run. Na potrzeby tej wersji demonstracyjnej usługa zostanie udostępniona jako usługa publiczna, do której mogą mieć dostęp inne osoby. Pamiętaj jednak, że nie jest to najlepsza metoda w przypadku tego rodzaju aplikacji, ponieważ bardziej nadaje się do aplikacji osobistych.

90805d85052a5e5a.jpeg

W tym ćwiczeniu umieścimy zarówno usługę frontendu, jak i usługę backendu w 1 kontenerze. Do zarządzania obiema usługami potrzebujemy pomocy supervisord. Możesz sprawdzić plik supervisord.conf i plik Dockerfile, w którym ustawiliśmy supervisord jako punkt wejścia.

W tym momencie mamy już wszystkie pliki potrzebne do wdrożenia aplikacji w Cloud Run. Wdróżmy ją. Przejdź do terminala Cloud Shell i sprawdź, czy bieżący projekt jest skonfigurowany jako aktywny. Jeśli nie, użyj polecenia gcloud configure, aby ustawić identyfikator projektu:

gcloud config set project [PROJECT_ID]

Następnie uruchom to polecenie, aby wdrożyć ją w Cloud Run.

gcloud run deploy personal-expense-assistant \
                  --source . \
                  --port=8080 \
                  --allow-unauthenticated \
                  --env-vars-file=settings.yaml \
                  --memory 1024Mi \
                  --region us-central1

Jeśli pojawi się prośba o potwierdzenie utworzenia Artifact Registry dla repozytorium Dockera, wpisz Y. Pamiętaj, że zezwalamy tutaj na nieuwierzytelniony dostęp, ponieważ jest to aplikacja demonstracyjna. Zalecamy używanie odpowiedniego uwierzytelniania w aplikacjach firmowych i produkcyjnych.

Po zakończeniu wdrażania powinien pojawić się link podobny do tego:

https://personal-expense-assistant-*******.us-central1.run.app

Użyj aplikacji w oknie incognito lub na urządzeniu mobilnym. Powinna już być dostępna.

12. 🎯 Wyzwanie

Teraz masz szansę zabłysnąć i doszlifować swoje umiejętności eksploracji. Czy uda Ci się zmienić kod, aby backend mógł obsługiwać wielu użytkowników? Które komponenty wymagają aktualizacji?

13. 🧹 Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym ćwiczeniu, wykonaj te czynności:

  1. W konsoli Google Cloud otwórz stronę Zarządzanie zasobami.
  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.
  4. Możesz też przejść do Cloud Run w konsoli, wybrać wdrożoną usługę i ją usunąć.