1. Einführung
In diesem Codelab fügen Sie einem Onlineshop für Outdoorausrüstung namens Rugged Terrain Guide ein intelligentes Chat-Widget für den Kundensupport hinzu. Sie verwenden Firebase AI Logic, um diesen Agent zu erstellen, und erfahren, wie Sie eine serverseitige Prompt-Vorlage (product-agent) konfigurieren, die die KI-Rolle, strenge Regeln für Kulanzleistungen und den Produktkatalog als dynamischen Kontext verwendet.
Aufgaben:
- Rufen Sie den Starter-Code für die Web-App dieses Codelabs ab.
- Richten Sie ein Firebase-Projekt ein.
- Firebase-Dienste (z. B. Firebase AI Logic) in einer Web-App einrichten und initialisieren
- Konfigurieren Sie eine serverseitige Prompt-Vorlage in der Firebase Console.
- Greifen Sie über einen Aufruf des generativen KI-Dienstes von einem React-ähnlichen TypeScript-Frontend aus auf die Vorlage zu.
Sie benötigen Folgendes:
- Ein Webbrowser wie Chrome.
- Grundkenntnisse in TypeScript und Node.js.
- Eine IDE oder ein Texteditor Ihrer Wahl. Antigravity ist eine gute Wahl.
2. Starter-Code abrufen
- Klonen Sie in Ihrem Terminal das Start-Repository:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git - Wechseln Sie zum Codeverzeichnis und installieren Sie die Abhängigkeiten:
cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab npm install
3. Firebase-Projekt einrichten
Firebase-Projekt erstellen
- Melden Sie sich mit Ihrem Google-Konto in der Firebase Console an.
- Klicken Sie auf die Schaltfläche, um ein neues Projekt zu erstellen, und geben Sie dann einen Projektnamen ein (z. B.
rugged-terrain-ai).
- Klicken Sie auf Weiter.
- Lesen und akzeptieren Sie die Nutzungsbedingungen von Firebase, falls Sie dazu aufgefordert werden, und klicken Sie dann auf Weiter.
- Optional: Aktivieren Sie die KI-Unterstützung in der Firebase Console („Gemini in Firebase“).
- Für dieses Codelab benötigen Sie kein Google Analytics. Deaktivieren Sie daher die Google Analytics-Option.
- Klicken Sie auf Projekt erstellen, warten Sie, bis Ihr Projekt bereitgestellt wurde, und klicken Sie dann auf Weiter.
Firebase-Tarif upgraden
Damit Sie die Firebase-Dienste in diesem Codelab verwenden können, muss für Ihr Firebase-Projekt der Blaze-Tarif (Pay as you go) aktiviert sein. Das bedeutet, dass es mit einem Cloud-Rechnungskonto verknüpft ist.
- Für ein Cloud-Rechnungskonto ist eine Zahlungsmethode wie eine Kreditkarte erforderlich.
- Bei besonderen Werbeaktionen oder wenn Sie dieses Codelab im Rahmen einer Veranstaltung durchführen, sind möglicherweise Google Cloud-Guthaben verfügbar.
- Wenn Sie neu bei Firebase und Google Cloud sind, können Sie prüfen, ob Sie Anspruch auf ein Guthaben von 300 $ und ein Cloud-Rechnungskonto für den kostenlosen Testzeitraum haben.
So führen Sie ein Upgrade Ihres Projekts auf den Blaze-Tarif durch:
- Wählen Sie in der Firebase Console die Option zum Upgraden Ihres Plans aus.
- Wählen Sie den Blaze-Tarif aus. Folgen Sie der Anleitung auf dem Bildschirm, um ein Cloud-Rechnungskonto mit Ihrem Projekt zu verknüpfen.
- Wenn Sie für dieses Codelab Google Cloud-Guthaben verwenden, heißt das Rechnungskonto wahrscheinlich
Google Cloud Platform Trial Billing AccountoderMy Billing Account. - Wenn Sie im Rahmen dieses Upgrades ein Cloud-Rechnungskonto erstellen mussten, müssen Sie möglicherweise zur Vervollständigung des Upgrades zur Upgrade-Ablauf in der Firebase Console zurückkehren.
- Wenn Sie für dieses Codelab Google Cloud-Guthaben verwenden, heißt das Rechnungskonto wahrscheinlich
4. Firebase-Dienste einrichten und App verbinden
Für dieses Codelab müssen Sie Cloud Storage for Firebase und Firebase AI Logic in Ihrem Firebase-Projekt einrichten. Außerdem müssen Sie den Quellcode Ihrer App mit Ihrem Firebase-Projekt verknüpfen.
Cloud Storage for Firebase einrichten
In diesem Codelab wird Cloud Storage for Firebase zum Speichern von Produktbeschreibungen verwendet.
- Rufen Sie in der Firebase Console Databases & Storage > Storage auf.
- Klicken Sie auf Jetzt starten.
- Wählen Sie einen Speicherort für Ihren Standard-Storage-Bucket aus.
Buckets inUS-WEST1,US-CENTRAL1undUS-EAST1können das kostenlose Kontingent für Google Cloud Storage nutzen. Für Buckets an allen anderen Standorten gelten die Preise und die Nutzung von Google Cloud Storage. - Klicken Sie auf Produktionsmodus. In den folgenden Schritten aktualisieren Sie diese Sicherheitsregeln, damit sie für dieses Codelab spezifisch sind.
- Klicken Sie auf Erstellen.
- Sicherheitsregeln aktualisieren:
- Wenn der Bucket bereitgestellt wurde, wechseln Sie zum Tab Regeln.
- Kopieren Sie die folgenden Regeln und fügen Sie sie ein:
rules_version = '2'; service firebase.storage { match /b/{bucket}/o { match /products.txt { allow read; } } } - Klicken Sie auf Veröffentlichen.
- Laden Sie die Produktbeschreibungen aus dem Starter-Code hoch:
- Klicken Sie für Ihren Storage-Bucket auf den Tab Dateien.
- Klicken Sie auf Datei hochladen und laden Sie dann die Datei
products.txtaus dem Startcode hoch. Diese Datei befindet sich unter:src/data/products.txt.
Firebase AI Logic konfigurieren
Firebase AI Logic ist der wichtigste Firebase-Dienst, den Sie in diesem Codelab verwenden.
- Rufen Sie in der Firebase Console AI Services > AI Logic auf.
- Klicken Sie auf Jetzt starten.
- Klicken Sie auf der Karte Agent Platform Gemini API auf Erste Schritte mit dieser API und folgen Sie der Anleitung auf dem Bildschirm. In diesem Ablauf werden die erforderlichen APIs aktiviert, damit Sie Firebase AI Logic mit der Agent Platform Gemini API verwenden können.
- (Optional) Wählen Sie AI Monitoring aktivieren aus, um verschiedene Messwerte und die Nutzung auf App-Ebene zu beobachten und so einen umfassenden Überblick über Ihre Anfragen über Firebase AI Logic zu erhalten.
Code mit Ihrem Firebase-Projekt verbinden
Im Rahmen der Einrichtung von Firebase AI Logic werden Sie aufgefordert, eine Firebase Web-App zu erstellen und die Konfiguration Ihrem Quellcode hinzuzufügen.
- Klicken Sie im Einrichtungsablauf von Firebase AI Logic auf das Symbol Web (
), um eine neue Web-App zu registrieren. - Geben Sie der App einen Namen (z. B.
Rugged Web). - Kopieren Sie das
firebaseConfig-Objekt aus der Einrichtungsanleitung.
Aktualisieren Sie als Nächstes den Starter-Code:
- Öffnen Sie
src/firebase.tsin Ihrem Code-Editor. - Ersetzen Sie die vorhandene
firebaseConfigdurch die, die Sie aus der Firebase-Konsole kopiert haben.
Ihre Datei sollte nun in etwa so aussehen:
import { getAI, getTemplateGenerativeModel, AgentPlatformBackend } 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 AgentPlatformBackend() });
5. Serverseitige Prompt-Vorlage erstellen
Anstatt komplexe KI-Prompts in die Client-App zu codieren, verwenden Sie die Dotprompt-Syntax, um Anweisungen sicher auf dem Server zu verwalten.
So wird verhindert, dass Endnutzer die geheimen Regeln für das Kulanzbudget sehen.
- Rufen Sie in der Firebase Console AI Services > AI Logic > Tab Prompt-Vorlagen auf.
- Klicken Sie auf Vorlage erstellen und wählen Sie Leere Vorlage aus.
- Legen Sie als Vorlagennamen
Product Agentund als IDproduct-agentfest. - Stellen Sie das Modell auf
gemini-3.1-flash-lite(oder die neueste verfügbare Version) ein. - Kopieren Sie aus dem für dieses Codelab bereitgestellten Startcode den Inhalt von
product-agent.prompt(diese Datei befindet sich im Stammverzeichnis). Fügen Sie diesen Inhalt dann in der Firebase Console in das Feld Prompt und (optionale) Systemanweisungen der Server-Promptvorlage ein. Diese Inhalte weisen das Modell sicher an, wie es sich als „Rugged Operator“ verhalten und auf den Produktkatalog verweisen soll. - Definieren Sie im Feld Testeingabe das Eingabeschema genau wie folgt:
{ "type": "object", "required": [ "query" ], "properties": { "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" } } } } } } - Klicken Sie auf Vorlage speichern, um die
product-agent-Vorlage zu speichern und zu veröffentlichen.
6. KI-Modell aufrufen
Nachdem die Vorlage sicher auf dem Server definiert wurde, müssen Sie sie nur noch über das Frontend Ihrer App aufrufen.
- Kehren Sie in Ihrem Code-Editor zu
src/firebase.tszurück. - Verwenden Sie unterhalb der Initialisierung
getTemplateGenerativeModel, um eine Verbindung zur Vorlage herzustellen: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. Agent mit Firebase App Check schützen
KI-Modelle sind leistungsstark, können aber auch missbraucht werden, wenn öffentliche Endpunkte nicht geschützt sind. Sie sollten immer Firebase App Check verwenden, um sicherzustellen, dass nur Ihre tatsächliche Web-App erfolgreiche Anfragen an die Gemini API stellen kann. Dadurch werden Bots und nicht autorisierte Clients blockiert.
- Wechseln Sie in der Google Cloud Console zu Sicherheit > Fraud Defense.
- Klicken Sie auf Schlüssel erstellen und füllen Sie die Felder aus:
- Display name (Anzeigename):
Codelab Key. - Anwendungstyp: Web
- Domainliste: Fügen Sie
localhostund127.0.0.1hinzu, damit Ihr lokaler Vite-Server Anfragen senden darf.
- Display name (Anzeigename):
- Klicken Sie auf Schlüssel erstellen, um den Schlüssel zu registrieren.
- Kopieren Sie oben auf der Seite „Fraud Defense Key Details“ (Fraud Defense-Schlüsseldetails) die Website-Schlüssel-ID in die Zwischenablage.
- Rufen Sie in der Firebase Console Sicherheit > App Check auf.
- Klicken Sie auf den Tab Apps, maximieren Sie Ihre Web-App (
Rugged Web) und klicken Sie auf den Anbieter reCAPTCHA Enterprise. - Fügen Sie im Feld reCAPTCHA Enterprise-Websiteschlüssel die ID des Websiteschlüssels von der Seite „Fraud Defense-Schlüsseldetails“ ein und klicken Sie auf Speichern.
- Öffnen Sie
src/firebase.tsnoch einmal in Ihrem Code-Editor. - Fügen Sie oben die folgenden Importe hinzu:
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check"; - Fügen Sie die App Check-Initialisierung direkt nach Ihrem
initializeApp(firebaseConfig)-Aufruf ein und fügen Sie die kopierte Website-Schlüssel-ID ein:// Initialize App Check const appCheck = initializeAppCheck(app, { provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'), isTokenAutoRefreshEnabled: true }); - Aktualisieren Sie den Aufruf der Funktion
getAI(), um diese Tokens zu verwenden. Nehmen Sie die folgende Änderung vor: Wenn Sie den Wert vonconst ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });useLimitedUseAppCheckTokensauf „true“ setzen, werden kurzlebige Tokens angewendet, um den Missbrauch Ihres Back-Ends zu begrenzen.
8. Anwendung ausführen
Nachdem Sie die Firebase-Konfiguration eingerichtet und das Support-Chat-Widget verknüpft haben, können Sie die App ausführen.
- Führen Sie den Vite-Entwicklungsserver in Ihrem Terminal aus:
npm run dev - Öffnen Sie die angegebene lokale URL (normalerweise
http://localhost:5173/). - Klicken Sie rechts unten auf den unverankerten Aktionsbutton (UAB) Taktischer Support.
- Stellen Sie Fragen zu den Produkten, z. B.
- „Ich suche eine wetterfeste Jacke.“
- „Meine Sub-Zero-Mütze ist defekt. Was kann ich tun?“
- Lassen Sie sich nicht abwimmeln, um die Logik für das „Kulanzbudget“ der KI auszulösen.
9. (Optional) Ressourcen aus dem Codelab bereinigen
Um mögliche Gebühren für Ihr Google Cloud-Abrechnungskonto zu vermeiden, können Sie die in diesem Codelab erstellten Ressourcen löschen.
- Rufen Sie in der Firebase-Konsole die Einstellungen > Allgemein auf.
- Achten Sie darauf, dass das Projekt, das Sie sich ansehen, das Projekt ist, das Sie für dieses Codelab verwendet haben. Wenn es sich nicht um das Projekt Ihres Codelabs handelt, können Sie das Projekt über das Drop-down-Menü zur Projektauswahl oben links ändern.
- Scrollen Sie zum Ende der Seite und klicken Sie auf Projekt löschen.
- Folgen Sie der Anleitung auf dem Bildschirm, um das Löschen zu bestätigen.
10. Glückwunsch!
🎊 Mission abgeschlossen! Sie haben einen robusten, vorlagenbasierten KI-Kundenservicemitarbeiter integriert.
Was Sie erreicht haben:
- Firebase und das Agent Platform-Backend in einer Client-App initialisiert.
- Eine sichere serverseitige Prompt-Vorlage mit Handlebars und strengen Eingabeschemas konfiguriert, um das komplexe Verhalten des KI-Agenten zu definieren.
- Dynamischer Aufruf eines LLM, bei dem der Chatverlauf und die kontextbezogenen Produkt-IDs sicher übergeben werden, ohne die interne Prompt-Logik für den Client offenzulegen.
Nächste Schritte
- Firebase App Check: Schützen Sie Ihre KI-Endpunkte vor Missbrauch.