Creare un'esperienza di ordinazione multimodale utilizzando l'API di streaming

Questa guida fornisce istruzioni e best practice per gli ingegneri che creano esperienze di ordinazione di cibo con il metodo RPC FoodOrderingService.BidiProcessOrder. Questa API di streaming bidirezionale in tempo reale è il fulcro dell'agente AI per l'ordinazione di cibo, in quanto consente l'acquisizione di ordini dinamici e conversazionali in varie applicazioni come app mobile, assistenti vocali, drive-through e chioschi.

Panoramica di BidiProcessOrder

Il metodo BidiProcessOrder stabilisce un canale di comunicazione bidirezionale persistente tra l'applicazione client e l'agente AI per l'ordinazione di cibo. A differenza delle RPC standard di richiesta e risposta unarie, questo approccio di streaming consente di:

• Interazione a bassa latenza:scambio continuo di informazioni senza l'overhead di richieste HTTP ripetute.
• Input multimodale:gestione di flussi audio (per gli ordini vocali), input di testo ed eventi lato client.
• Risposte in tempo reale:l'agente può inviare audio, testo, aggiornamenti dell'ordine e altri segnali man mano che la conversazione si svolge.

BidiProcessOrder non può essere richiamato utilizzando REST. Le integrazioni devono utilizzare un protocollo orientato alla connessione:

• gRPC (consigliato): fornisce un framework solido ed efficiente per lo streaming bidirezionale.
• WebSocket: adatto a client o ambienti in cui gRPC non è adatto a causa di vincoli di linguaggio di programmazione o di rete.

Per definizioni dettagliate dei tipi, consulta il riferimento API BidiProcessOrder. Le integrazioni WebSocket utilizzano rappresentazioni JSON di questi tipi, come descritto nella sezione WebSocket.

Prerequisiti

Prima di eseguire l'integrazione con BidiProcessOrder:

1. Abilita l'API:assicurati che l'API Food Ordering AI Agent sia abilitata nel tuo progetto Google Cloud . bash gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT_ID
2. Autenticazione:decidi l'approccio di autenticazione e configura gli eventuali service account e ruoli IAM necessari, come descritto in Autenticazione.
3. Importazione menu:deve essere importato un menu valido e associato a un Store. Per informazioni dettagliate, consulta Integrazione dei dati del menu.

Autenticazione

Per connettersi in modo sicuro alla RPC BidiProcessOrder, l'applicazione deve autenticarsi utilizzando un service account Google Cloud .

1. Configura un service account

• Crea un service account:nel tuo progetto Google Cloud , crea un service account che la tua applicazione utilizzerà per l'autenticazione all'API Food Ordering AI Agent. Vedi Creazione e gestione degli account di servizio.

• Concedi ruoli IAM:concedi i ruoli IAM necessari a questo account di servizio. Il ruolo principale richiesto per chiamare BidiProcessOrder è:

  • Utente agente Food Ordering (roles/foodorderingaiagent.agentUser): consente al account di servizio di connettersi al servizio di ordinazione ed elaborare le sessioni.

  Puoi concedere questo ruolo utilizzando la console Google Cloud o gcloud: bash gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \ --role="roles/foodorderingaiagent.agentUser"

2. Flusso di autenticazione dell'applicazione

Il flusso di autenticazione esatto dipende dall'architettura dell'applicazione, in particolare se l'applicazione client (ad es. app mobile, software per chioschi) si connette direttamente o tramite il tuo backend.

Scenario comune: autenticazione di un'applicazione client rivolta ai consumatori

Questo è un pattern tipico per le applicazioni web o mobile:

1. Client-to-YourAuth::l'app client dell'utente finale (mobile, web) esegue l'autenticazione con il tuo sistema di autenticazione utente esistente (potrebbe trattarsi di Firebase Authentication, del tuo server OAuth e così via).
2. Scambio di token:l'app client, dopo aver autenticato l'utente, richiede un token di breve durata da un servizio di backend sicuro controllato da te (ad es. un "servizio di token API").

3. Generazione del token di accesso:il tuo servizio di backend, utilizzando le credenziali dell'entità dell'account di servizio configurata nel passaggio 1, genera un token di accesso OAuth 2.0 standard per l'ambito https://www.googleapis.com/auth/cloud-platform. Google Cloud A tale scopo, utilizza le Google Cloud librerie client di autenticazione.

   • Sicurezza:le chiavi o le credenziali del service account utilizzate per generare questi token devono essere archiviate e gestite in modo sicuro nel backend. Non esporre mai direttamente le chiavi private del account di servizio alle applicazioni client dell'utente finale. Consulta Best practice per la gestione delle chiavi degli account di servizio.
   Nota: il token di accesso fornito ai client deve essere associato a un'entità con autorizzazioni IAM minime (ovvero solo il ruolo Food Ordering AI Agent User). Gli utenti pubblici possono abusare facilmente del token di accesso per richiamare API Google Cloud arbitrarie per conto del account di servizio, pertanto è fondamentale che IAM sia configurato correttamente per rifiutare tali chiamate.

4. Token al client:il servizio di backend restituisce il token di accesso Google generato all'app client.

5. Chiamata API:l'app client utilizza questo token di accesso Google per autenticare la connessione gRPC o WebSocket all'RPC BidiProcessOrder.

Suggerimento :se il client BidiProcessOrder viene eseguito in un ambiente sicuro che può essere configurato con le credenziali dell'account di servizio (come Compute Engine, Google Kubernetes Engine o i server on-premise), può utilizzare le credenziali predefinite dell'applicazione (ADC) per autenticare le chiamate all'API Food Ordering AI Agent. Queste indicazioni in genere si applicano ai casi d'uso in cui l'audio e gli eventi vengono trasmessi in streaming da un server edge on-premise o da un'applicazione basata sul cloud che funge da proxy lato server per i client basati su browser.

3. Utilizzo del token

• gRPC:le librerie client gRPC di Google in genere gestiscono l'aggiornamento e l'inclusione dei token nei metadati della chiamata quando vengono fornite le credenziali del account di servizio.
• WebSocket (non browser): includi il token nell'intestazione Authorization: Bearer TOKEN.
• WebSocket (browser): come indicato nella sezione WebSocket, le connessioni WebSocket dirette del browser non possono utilizzare le intestazioni di autorizzazione. Per autenticare la connessione dei client a Google Cloud, è necessario un proxy di streaming lato server.

Connessione all'API

Puoi stabilire un flusso utilizzando le librerie client gRPC o una connessione WebSocket.

gRPC

L'utilizzo di gRPC è l'approccio consigliato. Utilizzerai le librerie client per la lingua che preferisci (ad es. Java, Go, Python, Node.js) basate sul riferimento API BidiProcessOrder.

I passaggi di base prevedono:

1. Crea un canale gRPC all'endpoint API dell'agente AI per l'ordinazione di cibo (ad es. foodorderingaiagent.googleapis.com).
2. Ottieni uno stub client per FoodOrderingService.
3. Invoca il metodo BidiProcessOrder, che restituisce un oggetto stream per l'invio di richieste e la ricezione di risposte.
4. Implementa la logica di business in base al tuo caso d'uso, che contemporaneamente:
   • Invia input audio, di testo e di eventi dall'utente finale.
   • Gestisce i messaggi dell'agente, inclusi audio, testo ed eventi.

WebSocket

Per le connessioni WebSocket, il percorso dell'URL è:

wss://foodorderingaiagent.googleapis.com/ws/google.cloud.foodorderingaiagent.v1beta.FoodOrderingService/BidiProcessOrder/locations/LOCATION

• LOCATION: ad es. us

Intestazioni obbligatorie:

• Authorization: Bearer TOKEN, dove TOKEN è un token di accesso OAuth 2.0 ottenuto per il tuo account di servizio.

Nota: i browser web non consentono a JavaScript di impostare intestazioni personalizzate nelle richieste di connessione WebSocket. Pertanto, una connessione WebSocket non può essere autenticata direttamente da un browser. Per integrarti in modo sicuro con l'API BidiProcessOrder utilizzando WebSocket da un'applicazione web, devi utilizzare un intermediario o un proxy lato server. Questo server intermediario può stabilire la connessione WebSocket all'API Food Ordering AI Agent, inclusi gli header di autenticazione necessari, e quindi inoltrare i messaggi tra il client browser e l'API. Per saperne di più sulle opzioni di autenticazione, consulta Autenticazione.

Formato messaggio:

• Client-server: messaggi inviati all'API (ad es. Config, AudioInput, TextInput, EventInput) devono essere rappresentazioni JSON del proto BidiProcessOrderRequest, inviate come websocket.TextMessage.
• Da server a client:i messaggi ricevuti dall'API (BidiProcessOrderResponse) verranno inviati come websocket.BinaryMessage, ma il contenuto di questi messaggi binari è un payload JSON.
• Dati binari: dati binari all'interno dei payload JSON (ad es. customerAudio in AudioInput, agentAudio in AgentAudio) deve essere codificato in base64.

Ciclo di vita della sessione

Ogni chiamata a BidiProcessOrder avvia una sessione. La sessione rimane attiva finché lo stream è aperto.

1. Inizio (messaggio di configurazione):

   • Una volta stabilita la connessione, il primo messaggio inviato dal client deve essere un BidiProcessOrderRequest contenente il messaggio Config.
   • Campi obbligatori in Config:
     • session: un identificatore di sessione univoco generato dal client. Formato: projects/PROJECT/locations/LOCATION/sessions/SESSION_ID.
     • store: il nome della risorsa di Store. Formato: projects/PROJECT/locations/LOCATION/brands/BRAND/stores/STORE.
   • L'agente utilizza store per caricare il menu e la configurazione appropriati.
   Suggerimento: se lo stream si disconnette inaspettatamente, puoi riprendere la sessione riconnettendoti e inviando lo stesso messaggio Config con lo stesso ID session.

2. Invio di input:

   • Dopo l'Config iniziale, il client può inviare un flusso di messaggi BidiProcessOrderRequest contenenti uno dei seguenti input:
     • AudioInput: dati audio non elaborati (in genere PCM lineare a 16 bit a 16000 Hz, senza intestazioni). Utilizzato per le interazioni vocali.
     • TextInput: messaggi di testo dell'utente.
     • EventInput: indicatori per eventi come DriveOffEvent (per i casi d'uso drive-through quando il veicolo parte), CrewInterjectionEvent (per qualsiasi situazione in cui una persona assume il ruolo di presa degli ordini a metà conversazione) o OrderStateUpdateEvent (se l'ordine viene modificato sul lato client, ad esempio utilizzando un'interfaccia touch).

3. Ricezione delle risposte:

   • Contemporaneamente, l'agente invia un flusso di messaggi BidiProcessOrderResponse. Il tuo cliente deve essere pronto a gestire vari tipi di risposta all'interno del campo oneof response:
     • AgentAudio: byte audio sintetizzati da riprodurre per l'utente, utilizzati per le interazioni vocali.
     • AgentText: versione testuale della risposta dell'agente.
     • SpeechRecognition: trascrizione del discorso dell'utente riconosciuto.
     • UpdatedOrderState: contiene lo stato attuale completo del Order del cliente ogni volta che viene aggiornato dall'agente. Utilizza questo campo per aggiornare la rappresentazione dell'ordine della tua applicazione. In genere, questo dovrebbe comportare un aggiornamento di un'interfaccia utente o di un sistema di registrazione per le informazioni sullo stato dell'ordine, ad esempio un sistema POS.
     • InterruptionSignal: indica che l'utente ha interrotto il discorso dell'agente. Il client deve interrompere immediatamente la riproduzione di qualsiasi AgentAudio in uscita.
     • AgentEvent: eventi speciali, ad esempio RestartOrder, che richiedono l'intervento del cliente.
     • SuggestedOptions: fornisce opzioni contestualmente pertinenti che un utente potrebbe selezionare successivamente, utili per la visualizzazione su uno schermo.
     • EndSession: indica che la sessione è stata terminata dall'agente (ad es. ordine completato, utente che si allontana o escalation dell'agente).

4. Chiusura dello stream:

   • Lo stream può essere chiuso dal client o dal server. In genere, il server segnala la fine di una conversazione utilizzando un messaggio EndSession. Il client deve chiudere lo stream quando riceve questo messaggio.

Gestione di tipi di messaggi specifici

Le sezioni seguenti descrivono come gestire tipi di risposta specifici che il client riceverà quando chiama BidiProcessOrder.

AudioInput

• Riproduci in streaming l'audio in blocchi man mano che diventano disponibili.
• Formato: PCM lineare a 16 bit, frequenza di campionamento di 16000 Hz.
• I blocchi audio non includono le intestazioni audio che in genere precedono un file WAV.
• Per gli scenari drive-through con la cancellazione eco dell'eco attivata (enable_echo_cancellation in Config), fornisci sia customer_audio che crew_audio.

UpdatedOrderState

• Questo messaggio fornisce lo stato completo dell'ordine ogni volta che viene inviato. Sostituisci qualsiasi cache locale dell'ordine con i contenuti del messaggio Order ricevuto.
• Utilizza custom_integration_attributes all'interno di elementi e modificatori Order per mappare i contenuti Order in entità equivalenti all'interno del sistema di registrazione della tua applicazione.

InterruptionSignal

• Al ricevimento, interrompi immediatamente la riproduzione di qualsiasi AgentAudio e cancella l'audio dell'agente memorizzato nel buffer. In questo modo, il flusso della conversazione è naturale quando l'utente interrompe il discorso dell'agente.

EndSession

• Controlla EndType (ad es. DRIVE_OFF, AGENT_ESCALATION).
• L'applicazione deve chiudere correttamente la connessione e gestire la transizione dell'utente in modo appropriato (ad esempio, inviare una notifica a un supervisore umano nel caso di AGENT_ESCALATION o passare a uno stato di conferma dell'ordine).

Best practice

• Gestisci i messaggi in modo asincrono:riduci al minimo la latenza utilizzando thread o I/O non bloccanti per inviare richieste ed elaborare le risposte in arrivo contemporaneamente.
• Logica di riconnessione:implementa una logica di riconnessione solida in caso di problemi di rete, ricordandoti di inviare il messaggio Config iniziale con lo stesso ID sessione per tentare la ripresa.
• Gestione degli errori:monitora lo stream per rilevare errori. Le librerie gRPC e WebSocket forniscono meccanismi per rilevare la chiusura dello stream o errori di trasporto. Registra questi eventi e gestiscili in modo appropriato.
• Buffer audio:gestisci attentamente i buffer audio, implementando il buffering se necessario, per garantire una riproduzione fluida di AgentAudio e una distribuzione tempestiva di AudioInput. Valuta attentamente il compromesso tra latenza e qualità di riproduzione quando decidi lo schema di buffering.
• Gestione ID sessione:assicurati che gli ID sessione siano univoci per ogni ordine/conversazione distinto.
• Gestione delle risorse:chiudi gli stream e rilascia le risorse al termine della sessione o se si verificano errori non recuperabili.
• Timeout:anche se lo stream stesso può durare a lungo (fino a 15 minuti per impostazione predefinita), se necessario, considera i timeout a livello di applicazione per stati specifici.

Flusso di integrazione di esempio (concettuale)

1. App client (ad es. app mobile) avvia un ordine.
2. Stabilisci una connessione gRPC/WebSocket a BidiProcessOrder.
3. Invia BidiProcessOrderRequest con Config (ID sessione, ID negozio).
4. Ricevi l'AgentAudio iniziale (ad es. il messaggio di benvenuto) e riproducilo.
5. L'utente parla: acquisisci l'audio e riproducilo in streaming nei messaggi di AudioInput.
6. Ricevi SpeechRecognition (visualizza la trascrizione), AgentAudio (riproduci la risposta) e potenzialmente UpdatedOrderState (aggiorna il carrello della UI).
7. Se l'utente interrompe, ricevi InterruptionSignal, interrompi la riproduzione.
8. Continua lo scambio di input audio o di testo e le risposte dell'agente.
9. L'utente conferma l'ordine: l'agente invia UpdatedOrderState finale.
10. L'agente invia EndSession: il cliente chiude lo stream e finalizza l'ordine nel sistema POS utilizzando i dati dell'ultimo UpdatedOrderState.