Tworzenie agenta obsługi klienta opartego na AI za pomocą Firebase AI Logic

1. Wprowadzenie

W tym laboratorium kodowania dodasz inteligentny widżet czatu obsługi klienta do sklepu internetowego ze sprzętem turystycznym o nazwie Rugged Terrain Guide. Do utworzenia tego agenta użyjesz Firebase AI Logic. Dowiesz się, jak skonfigurować szablon prompta po stronie serwera (product-agent), który obsługuje personę AI, ścisłe reguły budżetu na rekompensaty i dynamicznie wykorzystuje katalog produktów jako kontekst.

Co musisz zrobić:

  • Pobierz kod startowy aplikacji internetowej na potrzeby tego modułu.
  • Skonfiguruj projekt w Firebase.
  • Skonfiguruj i zainicjuj usługi Firebase (np. Firebase AI Logic) w aplikacji internetowej.
  • Skonfiguruj szablon prompta po stronie serwera w konsoli Firebase.
  • Uzyskaj dostęp do szablonu z wywołania usługi generatywnej AI z frontendu TypeScript podobnego do Reacta.

Co będzie Ci potrzebne

  • przeglądarka, np. Chrome;
  • Podstawowa znajomość TypeScript i Node.js.
  • Wybrane środowisko IDE lub edytor tekstu. Antygrawitacja to dobry wybór.

2. Pobieranie kodu startowego

  1. W terminalu sklonuj repozytorium początkowe:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. Przejdź do katalogu z kodem i zainstaluj zależności:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Konfigurowanie projektu w Firebase

Tworzenie projektu w Firebase

  1. Zaloguj się w konsoli Firebase, korzystając ze swojego konta Google.
  2. Kliknij przycisk, aby utworzyć nowy projekt, a potem wpisz jego nazwę (np. rugged-terrain-ai).
  3. Kliknij Dalej.
  4. Po wyświetleniu monitu zapoznaj się z warunkami usługi Firebase i zaakceptuj je, a potem kliknij Dalej.
  5. (Opcjonalnie) Włącz w konsoli Firebase pomoc AI (nazywaną „Gemini w Firebase”).
  6. W tym samouczku nie potrzebujesz Google Analytics, więc wyłącz opcję Google Analytics.
  7. Kliknij Utwórz projekt, poczekaj, aż projekt zostanie udostępniony, a następnie kliknij Dalej.

Przejście na wyższy abonament Firebase

Aby korzystać z usług Firebase w tym ćwiczeniu, Twój projekt w Firebase musi być objęty abonamentem Blaze (płatność według wykorzystania), co oznacza, że musi być połączony z kontem rozliczeniowym Cloud.

Aby przenieść projekt na abonament Blaze:

  1. W konsoli Firebase wybierz przejście na wyższy abonament.
  2. Wybierz pakiet Blaze. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby połączyć konto rozliczeniowe Cloud z projektem.
    Jeśli w ramach tego przejścia na wyższy abonament konieczne było utworzenie konta rozliczeniowego Cloud, może być konieczne powrócenie do procesu przejścia na wyższy abonament w konsoli Firebase, aby go dokończyć.

4. Konfigurowanie usług Firebase i łączenie aplikacji

W tym ćwiczeniu musisz skonfigurować w projekcie w Firebase Cloud Storage dla Firebase i Firebase AI Logic. Musisz też połączyć kod źródłowy aplikacji z projektem w Firebase.

Konfigurowanie Cloud Storage dla Firebase

W tym ćwiczeniu do przechowywania opisów produktów używana jest usługa Cloud Storage dla Firebase.

  1. W konsoli Firebase kliknij Bazy danych i miejsce na dane > Miejsce na dane.
  2. Kliknij Rozpocznij.
  3. Wybierz lokalizację domyślnego zasobnika Storage.
    Zasobniki w lokalizacjach US-WEST1, US-CENTRAL1 i US-EAST1 mogą korzystać z poziomu „Zawsze bezpłatny” w Google Cloud Storage. W przypadku zasobników w innych lokalizacjach obowiązuje cennik i zasady użytkowania Google Cloud Storage.
  4. Kliknij Tryb produkcyjny. W krokach poniżej zaktualizujesz te reguły zabezpieczeń, aby były dostosowane do tego laboratorium.
  5. Kliknij Utwórz.
  6. Zaktualizuj reguły zabezpieczeń:
    1. Po utworzeniu zasobnika otwórz kartę Reguły.
    2. Skopiuj i wklej te reguły:
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. Kliknij Opublikuj.
  7. Prześlij opisy produktów z kodu startowego:
    1. Kliknij kartę Pliki w zasobniku na dane.
    2. Kliknij Prześlij plik, a następnie prześlij plik products.txt z kodu startowego. Ten plik znajdziesz w lokalizacji: src/data/products.txt.

Konfigurowanie Firebase AI Logic

Firebase AI Logic to główna usługa Firebase, z której będziesz korzystać w tym laboratorium.

  1. W konsoli Firebase kliknij Usługi AI > Logika AI.
  2. Kliknij Rozpocznij.
  3. Na karcie Vertex AI Gemini API kliknij Rozpocznij korzystanie z tego interfejsu API i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie. Ten proces włączy wymagane interfejsy API, aby umożliwić Ci korzystanie z Firebase AI Logic z Gemini API w Vertex AI.
  4. (Opcjonalnie) Kliknij Włącz monitorowanie wykorzystania AI, aby obserwować różne dane i statystyki użycia na poziomie aplikacji i uzyskać pełny wgląd w swoje żądania za pomocą Firebase AI Logic.

Łączenie kodu z projektem w Firebase

W ramach konfigurowania Firebase AI Logic pojawi się prośba o utworzenie aplikacji internetowej Firebase i dodanie konfiguracji do kodu źródłowego.

  1. Gdy w procesie konfiguracji Firebase AI Logic pojawi się odpowiedni prompt, kliknij ikonę Internet , aby zarejestrować nową aplikację internetową.
  2. Nadaj aplikacji nazwę (np. Rugged Web).
  3. Skopiuj obiekt firebaseConfig z instrukcji konfiguracji.

Następnie zaktualizuj kod startowy:

  1. W edytorze kodu otwórz src/firebase.ts.
  2. Zastąp istniejący klucz firebaseConfig kluczem skopiowanym z konsoli Firebase.

Plik powinien wyglądać tak:

import { getAI, getTemplateGenerativeModel, VertexAIBackend } from "firebase/ai";
import { initializeApp } from "firebase/app";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.firebasestorage.app",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID"
};

// Initialize Firebase
export const app = initializeApp(firebaseConfig);

const ai = getAI(app, { backend: new VertexAIBackend() });

5. Tworzenie szablonu promptu po stronie serwera

Zamiast na stałe kodować złożone prompty AI w aplikacji klienckiej, możesz używać składni Dotprompt, aby bezpiecznie zarządzać instrukcjami na serwerze.

Dzięki temu użytkownicy nie będą widzieć tajnych reguł „Budżet na rekompensaty”.

  1. W konsoli Firebase otwórz sekcję Vertex AI lub Zarządzanie promptami.
  2. Utwórz nowy szablon prompta i nadaj mu nazwę product-agent.
  3. Ustaw model na gemini-2.5-flash.
  4. Zdefiniuj schemat danych wejściowych w ten sposób:
    input:
  schema:
    query:
      type: string
      description: the customers ask of the robot
    productId?:
      type: string
      description: the product the customer is looking at right now
    history?:
      type: array
      description: list of previous history between the user and system
      items:
        type: object
        required: [role, contents]
        properties:
          role:
            type: string
          contents:
            type: string
  5. Skopiuj zawartość agent-product.prompt z katalogu głównego i wklej ją w polu Prompt i opcjonalne instrukcje systemowe. W bezpieczny sposób instruuje model, jak ma się zachowywać jako „Rugged Operator”, i wstrzykuje katalog produktów.
  6. W konsoli Firebase zapisz i opublikuj szablon product-agent.

6. Wywołaj model AI

Teraz, gdy szablon jest bezpiecznie zdefiniowany na serwerze, wystarczy wywołać go z frontendu aplikacji.

  1. W edytorze kodu wróć do sekcji src/firebase.ts.
  2. Po inicjalizacji użyj getTemplateGenerativeModel, aby połączyć się z szablonem:
    const model = getTemplateGenerativeModel(ai);

export const callCustomerSupportModel = async (query: string, productId?: string, history?: { role: string, contents: string }[]) => {
    // Generate content using the published 'product-agent' template
    const result = await model.generateContent('product-agent', {
        query,
        productId,
        history,
    });
    return result.response.text();
}

7. Zabezpieczanie agenta za pomocą funkcji Sprawdzanie aplikacji Firebase

Modele AI są bardzo przydatne, ale mogą być też wykorzystywane w nieodpowiedni sposób, jeśli publiczne punkty końcowe nie są chronione. Zawsze używaj Sprawdzania aplikacji Firebase, aby mieć pewność, że tylko Twoja prawdziwa aplikacja internetowa może wywoływać model generatywny Vertex AI, blokując boty i nieautoryzowanych klientów.

  1. W konsoli Firebase kliknij Kompilacja > Sprawdzanie aplikacji.
  2. Kliknij kartę Aplikacje, rozwiń aplikację internetową (Rugged Web) i kliknij dostawcę reCAPTCHA Enterprise.
  3. Kliknij Utwórz nowy klucz reCAPTCHA Enterprise i wypełnij wyświetlony formularz:
    • Nazwa: Codelab Key
    • Domains (Domeny): dodaj localhost i 127.0.0.1, aby lokalny serwer Vite mógł wysyłać żądania.
  4. Aby zarejestrować aplikację, kliknij Zapisz.
  5. Po zarejestrowaniu w konsoli Firebase pojawi się klucz witryny. Skopiuj ten ciąg znaków.
  6. W edytorze kodu ponownie otwórz src/firebase.ts.
  7. Na górze dodaj te instrukcje importu:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. Dodaj inicjację Sprawdzania aplikacji bezpośrednio po wywołaniu funkcji initializeApp(firebaseConfig) i wklej skopiowany klucz witryny:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. Zaktualizuj wywołanie funkcji getAI(), aby używać tych tokenów. Wprowadź te zmiany:
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    Ustawiając wartość useLimitedUseAppCheckTokens na „true”, masz pewność, że będą stosowane krótkotrwałe tokeny, które pomogą ograniczyć nadużycia, jakie może otrzymywać Twój backend.

8. Uruchamianie aplikacji

Po skonfigurowaniu Firebase i podłączeniu widżetu czatu pomocy możesz uruchomić aplikację.

  1. W terminalu uruchom serwer programistyczny Vite:
    npm run dev
  2. Otwórz podany lokalny adres URL (zwykle http://localhost:5173/).
  3. W prawym dolnym rogu kliknij pływający przycisk polecenia (FAB) Pomoc taktyczna.
  4. Spróbuj zadać pytania o produkty, na przykład:
    • Szukam kurtki odpornej na warunki atmosferyczne
    • „Moja czapka zimowa jest wadliwa. Co mogę zrobić?”
    • Nadal odmawiaj, aby uruchomić logikę „Budżetu na uspokojenie” AI.

9. (Opcjonalnie) Zwalnianie miejsca z zasobów z ćwiczeń z programowania

Aby uniknąć możliwych opłat na koncie rozliczeniowym Google Cloud, możesz usunąć zasoby utworzone podczas tego ćwiczenia.

  1. Otwórz konsolę Firebase.
  2. Wybierz projekt rugged-terrain-ai.
  3. Kliknij Ustawienia projektu (ikona koła zębatego).
  4. Przewiń w dół i kliknij Usuń projekt.
  5. Aby potwierdzić usunięcie, postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.

10. Gratulacje!

🎊 Misja ukończona! Udało Ci się zintegrować solidnego agenta obsługi klienta opartego na AI, który korzysta z szablonów.

Co udało Ci się osiągnąć:

  • Zainicjowano Firebase i backend Vertex AI w aplikacji klienckiej.
  • Skonfigurowano bezpieczny szablon prompta po stronie serwera przy użyciu Handlebars i ścisłych schematów wejściowych, aby zdefiniować złożone zachowanie agenta.
  • Dynamiczne wywoływanie LLM z bezpiecznym przekazywaniem historii czatu i kontekstowych identyfikatorów produktów bez ujawniania klientowi wewnętrznej logiki promptu.

Co dalej?