1. Introduzione
In questo codelab, aggiungerai un widget di chat intelligente per l'assistenza clienti a un negozio di e-commerce di attrezzature per attività all'aperto chiamato Rugged Terrain Guide. Utilizzerai Firebase AI Logic per creare questo agente e imparerai a configurare un template di prompt lato server (product-agent) che gestisce il ruolo dell'AI, regole rigorose del budget di compensazione e utilizza dinamicamente il catalogo dei prodotti come contesto.
Passaggi:
- Recupera il codice di avvio dell'app web di questo codelab.
- Configura un progetto Firebase.
- Configura e inizializza i servizi Firebase (come Firebase AI Logic) in un'app web.
- Configura un modello di prompt lato server nella console Firebase.
- Accedi al modello da una chiamata al servizio di AI generativa da un frontend TypeScript simile a React.
Di che cosa hai bisogno:
- Un browser web come Chrome.
- Conoscenza di base di TypeScript e Node.js.
- Un IDE o un editor di testo a tua scelta. Antigravità è una buona scelta.
2. Recupera il codice di avvio
- Nel terminale, clona il repository iniziale:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git - Vai alla directory del codice e installa le dipendenze:
cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab npm install
3. Configura un progetto Firebase
Crea un progetto Firebase
- Accedi alla console Firebase utilizzando il tuo Account Google.
- Fai clic sul pulsante per creare un nuovo progetto, quindi inserisci un nome per il progetto (ad esempio,
rugged-terrain-ai).
- Fai clic su Continua.
- Se richiesto, leggi e accetta i termini di Firebase e poi fai clic su Continua.
- (Facoltativo) Attiva l'assistenza AI nella console Firebase (denominata "Gemini in Firebase").
- Per questo codelab, non hai bisogno di Google Analytics, quindi disattiva l'opzione Google Analytics.
- Fai clic su Crea progetto, attendi il provisioning del progetto e poi fai clic su Continua.
Esegui l'upgrade del piano tariffario Firebase
Per utilizzare i servizi Firebase in questo codelab, il tuo progetto Firebase deve essere incluso nel piano tariffario con pagamento a consumo (Blaze), il che significa che è collegato a un account di fatturazione Cloud.
- Un account di fatturazione Cloud richiede un metodo di pagamento, ad esempio una carta di credito.
- Durante promozioni speciali o se stai svolgendo questo codelab nell'ambito di un evento, potrebbero essere disponibili crediti Google Cloud.
- Se non hai mai utilizzato Firebase e Google Cloud, verifica se hai diritto a un credito di 300$e a un account di fatturazione Cloud per la prova senza costi.
Per eseguire l'upgrade del progetto al piano Blaze:
- Nella console Firebase, seleziona l'opzione per eseguire l'upgrade del piano.
- Seleziona il piano Blaze. Segui le istruzioni sullo schermo per collegare un account di fatturazione Cloud al tuo progetto.
- Se utilizzi crediti Google Cloud per questo codelab, l'account di fatturazione si chiama probabilmente
Google Cloud Platform Trial Billing AccountoMy Billing Account. - Se hai dovuto creare un account di fatturazione Cloud nell'ambito di questo upgrade, potresti dover tornare al flusso di upgrade nella console Firebase per completarlo.
- Se utilizzi crediti Google Cloud per questo codelab, l'account di fatturazione si chiama probabilmente
4. Configurare i servizi Firebase e connettere l'app
Per questo codelab, devi configurare Cloud Storage for Firebase e Firebase AI Logic nel tuo progetto Firebase. Devi anche connettere il codice sorgente della tua app al tuo progetto Firebase.
Configura Cloud Storage for Firebase
Questo codelab utilizza Cloud Storage for Firebase per archiviare le descrizioni dei prodotti.
- Nella console Firebase, vai a Database e archiviazione > Storage.
- Fai clic su Inizia.
- Seleziona una posizione per il bucket di archiviazione predefinito.
I bucket inUS-WEST1,US-CENTRAL1eUS-EAST1possono usufruire del livello "Sempre senza costi" per Google Cloud Storage. I bucket in tutte le altre località seguono i prezzi e l'utilizzo di Google Cloud Storage. - Fai clic su Modalità di produzione. Nei passaggi successivi, aggiornerai queste regole di sicurezza in modo che siano specifiche per questo codelab.
- Fai clic su Crea.
- Aggiorna le regole di sicurezza:
- Dopo il provisioning del bucket, vai alla scheda Regole.
- Copia e incolla le seguenti regole:
rules_version = '2'; service firebase.storage { match /b/{bucket}/o { match /products.txt { allow read; } } } - Fai clic su Pubblica.
- Carica le descrizioni dei prodotti dal codice di avvio:
- Fai clic sulla scheda File per il bucket Storage.
- Fai clic su Carica file e poi carica il file
products.txtdal codice di avvio. Questo file si trova in:src/data/products.txt.
Configura Firebase AI Logic
Firebase AI Logic è il servizio Firebase principale che utilizzerai in questo codelab.
- Nella console Firebase, vai a Servizi AI > AI Logic.
- Fai clic su Inizia.
- Nella scheda API Gemini di Agent Platform, fai clic su Inizia a utilizzare questa API e segui le istruzioni sullo schermo. Questo flusso attiverà le API richieste per utilizzare Firebase AI Logic con l'API Gemini di Agent Platform.
- (Facoltativo) Seleziona per abilitare il monitoraggio AI in modo da poter osservare varie metriche e l'utilizzo a livello di app per ottenere una visibilità completa delle tue richieste tramite Firebase AI Logic.
Connettere il codice al progetto Firebase
Nell'ambito della configurazione di Firebase AI Logic, ti verrà chiesto di creare un'app web Firebase e di aggiungere la configurazione al codice sorgente.
- Quando ti viene richiesto nel flusso di configurazione di Firebase AI Logic, fai clic sull'icona Web (
) per registrare una nuova app web. - Assegna un nome all'app (ad esempio,
Rugged Web). - Copia l'oggetto
firebaseConfigdalle istruzioni di configurazione.
Successivamente, aggiorna il codice di avvio:
- Nell'editor di codice, apri
src/firebase.ts. - Sostituisci il valore
firebaseConfigesistente con quello copiato dalla console Firebase.
Il file dovrebbe avere il seguente aspetto:
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. Crea il template di prompt lato server
Anziché codificare in modo permanente prompt AI complessi nell'app client, utilizzerai la sintassi Dotprompt per gestire le istruzioni in modo sicuro sul server.
In questo modo, gli utenti finali non vedono le regole segrete del "Budget di compensazione".
- Nella console Firebase, vai alla scheda Servizi AI > Logica AI > Modelli di prompt.
- Fai clic su Crea modello e scegli Modello vuoto.
- Imposta il nome del modello su
Product Agente l'ID suproduct-agent. - Imposta il modello su
gemini-3.1-flash-lite(o l'ultima versione disponibile). - Dal codice di avvio fornito per questo codelab, copia i contenuti di
product-agent.prompt(trova questo file nella directory root). Poi, incolla questo contenuto nel campo Prompt e istruzioni di sistema (facoltative) del modello di prompt del server nella console Firebase. Questi contenuti indicano in modo sicuro al modello come comportarsi come "Rugged Operator" e fare riferimento al catalogo dei prodotti. - Nel campo Input di test definisci lo schema di input esattamente come segue:
{ "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" } } } } } } - Fai clic su Salva modello per salvare e pubblicare il modello
product-agent.
6. Chiama il modello di AI
Ora che il modello è definito in modo sicuro sul server, devi solo chiamarlo dal frontend della tua app.
- Nell'editor di codice, torna a
src/firebase.ts. - Sotto l'inizializzazione, utilizza
getTemplateGenerativeModelper connetterti al modello: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. Proteggere l'agente con Firebase App Check
I modelli di AI sono potenti, ma possono anche essere usati in modo improprio se gli endpoint pubblici non sono protetti. Devi sempre utilizzare Firebase App Check per assicurarti che solo la tua app web effettiva possa effettuare richieste riuscite all'API Gemini, bloccando bot e client non autorizzati.
- Nella console Google Cloud, vai a Sicurezza > Fraud Defense.
- Fai clic su Crea chiave e compila i campi:
- Nome visualizzato:
Codelab Key - Tipo di applicazione: web
- Elenco di domini: aggiungi
localhoste127.0.0.1in modo che il server Vite locale sia autorizzato a effettuare richieste.
- Nome visualizzato:
- Fai clic su Crea chiave per registrare la chiave.
- Nella parte superiore della pagina Dettagli chiave Fraud Defense, copia l'ID chiave del sito negli appunti.
- Nella console Firebase, vai a Sicurezza > App Check.
- Fai clic sulla scheda App, espandi la tua app web (
Rugged Web) e fai clic sul provider reCAPTCHA Enterprise. - Nel campo Chiave di sito reCAPTCHA Enterprise, incolla l'ID della chiave di sito dalla pagina dei dettagli di Fraud Defense e fai clic su Salva.
- Nell'editor di codice, apri di nuovo
src/firebase.ts. - Aggiungi le seguenti importazioni all'inizio:
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check"; - Aggiungi l'inizializzazione di App Check subito dopo la chiamata
initializeApp(firebaseConfig)e incolla l'ID della chiave del sito che hai copiato:// Initialize App Check const appCheck = initializeAppCheck(app, { provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'), isTokenAutoRefreshEnabled: true }); - Aggiorna la chiamata di funzione
getAI()per utilizzare questi token. Apporta la seguente modifica: Se imposti il valore diconst ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });useLimitedUseAppCheckTokenssu true, ti assicuri che i token di breve durata vengano applicati per contribuire a limitare gli abusi che il tuo backend potrebbe ricevere.
8. Esegui l'app
Con la configurazione di Firebase in posizione e il widget di chat di assistenza collegato, è il momento di eseguire l'app.
- Nel terminale, esegui il server di sviluppo Vite:
npm run dev - Apri l'URL locale fornito (di solito
http://localhost:5173/). - Fai clic sul Floating Action Button (FAB) Supporto tattico nell'angolo in basso a destra.
- Prova a fare domande sui prodotti, ad esempio:
- "Sto cercando un guscio resistente alle intemperie"
- "Il mio berretto Sub-Zero è difettoso. Che cosa posso fare?"
- Continua a respingere per attivare la logica del "budget di pacificazione " dell'AI.
9. (Facoltativo) Esegui la pulizia delle risorse del codelab
Per evitare possibili addebiti al tuo account di fatturazione Google Cloud, puoi eliminare le risorse create durante questo codelab.
- Nella console Firebase, vai alla scheda Impostazioni > Generali.
- Assicurati che il progetto che stai visualizzando sia quello che hai utilizzato per questo codelab. Se non è il progetto del tuo codelab, puoi utilizzare il menu a discesa del selettore di progetti nell'angolo in alto a sinistra per cambiare progetto.
- Vai in fondo alla pagina e fai clic su Elimina progetto.
- Segui le istruzioni sullo schermo per confermare l'eliminazione.
10. Complimenti!
🎊 Missione completata. Hai integrato correttamente un agente di assistenza clienti AI solido e basato su modelli.
Cosa hai ottenuto:
- Firebase inizializzato e il backend di Agent Platform in un'app client.
- Configurato un template di prompt lato server sicuro utilizzando Handlebars e schemi di input rigorosi per definire il comportamento complesso dell'agente.
- Chiamata dinamica di un LLM che trasmette in modo sicuro la cronologia della chat e gli ID prodotto contestuali senza esporre la logica del prompt interno al client.
Passaggi successivi
- Firebase App Check: proteggi i tuoi endpoint AI da comportamenti illeciti.