Best practice per l'utilizzo del servizio

Questa guida fornisce le best practice per l'utilizzo del servizio Dialogflow. Queste linee guida sono progettate per una maggiore efficienza e accuratezza, nonché per tempi di risposta ottimali da parte del servizio.

Consulta anche la guida generale alla progettazione degli agenti per tutti i tipi di agenti, e la guida alla progettazione degli agenti vocali specificamente per la progettazione di agenti vocali.

Produzione

Prima di eseguire l'agente in produzione, assicurati di implementare le seguenti best practice:

• Utilizza le versioni dell'agente
• Riutilizza i client di sessione
• Implementa la gestione degli errori con i tentativi

Abilita audit log

Abilita gli audit log dell'accesso ai dati per l'API Dialogflow nel tuo progetto. In questo modo puoi monitorare le modifiche in fase di progettazione negli agenti Dialogflow collegati a questo progetto.

Versioni dell'agente

Devi sempre utilizzare le versioni dell'agente per il traffico di produzione. Per maggiori dettagli, consulta Versioni e ambienti.

Crea backup dell'agente

Conserva un backup dell'agente esportato aggiornato. In questo modo, puoi eseguire rapidamente il ripristino se tu o i membri del tuo team eliminate accidentalmente l'agente o il progetto.

Riutilizzo del client

Puoi migliorare il rendimento della tua applicazione riutilizzando le istanze della libreria client *Client per la durata del ciclo di vita di esecuzione dell'applicazione.

Ancora più importante, puoi migliorare il rendimento delle chiamate API di rilevamento dell'intent riutilizzando un'istanza della libreria client SessionsClient.

Consulta il riferimento Sessions.

Per saperne di più, consulta la guida Best practice con le librerie client.

Aggiornamenti batch dell'agente

Se invii molte richieste API di aggiornamento dell'agente individuali in un breve periodo di tempo, le richieste potrebbero essere soggette a limitazione. Questi metodi API in fase di progettazione non sono implementati per gestire frequenze di aggiornamento elevate per un singolo agente.

Alcuni tipi di dati hanno metodi batch per questo scopo:

• Anziché inviare molte EntityTypes create, patch, o delete richieste, utilizza i metodi batchUpdate o batchDelete.
• Anziché inviare molte Intents create, patch, o delete richieste, utilizza i metodi batchUpdate o batchDelete.

Tentativi di errore API

Quando chiami i metodi API, potresti ricevere risposte di errore. Esistono alcuni errori per i quali è necessario riprovare, perché spesso sono dovuti a problemi temporanei. Ci sono due tipi di errori:

• Errori dell'API Cloud.
• Errori inviati dal tuo servizio webhook.

Inoltre, devi implementare un backoff esponenziale per i tentativi. In questo modo, il sistema può trovare una frequenza accettabile mentre il servizio API è sottoposto a un carico elevato.

Errori dell'API Cloud

Se utilizzi una libreria client fornita da Google, i tentativi di errore dell'API Cloud con backoff esponenziale vengono implementati automaticamente, .

Se hai implementato la tua libreria client utilizzando REST o gRPC, devi implementare i tentativi per il client. Per informazioni sugli errori per i quali è necessario riprovare o meno, consulta Proposte di miglioramento dell'API: configurazione automatica dei tentativi.

Errori del webhook

Se la chiamata API attiva una chiamata webhook, il webhook potrebbe restituire un errore. Anche se utilizzi una libreria client fornita da Google, non verrà eseguito automaticamente un nuovo tentativo per gli errori del webhook. Il codice deve riprovare a eseguire gli errori 503 Service Unavailable ricevuti dal webhook. Per informazioni sui tipi di errori del webhook e su come verificarli, consulta la documentazione del servizio webhook.

Test di carico

È una best practice eseguire il test di carico del sistema prima di rilasciare il codice in produzione. Tieni presente questi punti prima di implementare i test di carico:

Riepilogo	Dettagli
Aumenta il carico.	Il test di carico deve aumentare il carico applicato al servizio Dialogflow. Il servizio non è progettato per gestire picchi di carico improvvisi, che si verificano raramente con il traffico reale. Il servizio impiega del tempo per adattarsi alle richieste di carico, quindi aumenta lentamente il tasso di richieste finché il test non raggiunge il carico desiderato.
Le chiamate API sono a pagamento.	Ti verranno addebitati i costi per le chiamate API durante un test e le chiamate saranno limitate dalla quota del progetto.
Utilizza i test double.	Potresti non dover chiamare l'API durante il test di carico. Se lo scopo del test di carico è determinare in che modo il sistema gestisce il carico, spesso è meglio utilizzare un test double al posto delle chiamate effettive all'API. Il test double può simulare il comportamento dell'API sotto carico.
Utilizza i tentativi.	Il test di carico deve eseguire i tentativi con un backoff.

Chiamare Dialogflow in modo sicuro da un dispositivo dell'utente finale

Non devi mai archiviare le chiavi private utilizzate per accedere all'API Dialogflow su un dispositivo dell'utente finale. Questo vale sia per l'archiviazione delle chiavi direttamente sul dispositivo sia per la codifica hardcoded delle chiavi nelle applicazioni. Quando l'applicazione client deve chiamare l'API Dialogflow, deve inviare le richieste a un servizio proxy di proprietà dello sviluppatore su una piattaforma sicura. Il servizio proxy può effettuare le chiamate Dialogflow effettive e autenticate.

Ad esempio, non devi creare un'applicazione mobile che chiama direttamente Dialogflow. In questo modo, dovresti archiviare le chiavi private su un dispositivo dell'utente finale. L'applicazione mobile deve invece passare le richieste tramite un servizio proxy sicuro.

Nota: alcune integrazioni di Dialogflow, come Dialogflow Messenger, forniscono sia il codice client sia un servizio proxy, simile alla descrizione riportata sopra. Il servizio proxy risponde alle richieste solo quando l'integrazione è abilitata. Per migliorare l'utilità di queste integrazioni, il servizio proxy potrebbe non richiedere l'autenticazione. L'API del servizio proxy è limitata a un piccolo sottoinsieme di metodi dell'API Dialogflow necessari per l'integrazione. Inoltre, il servizio proxy non fornisce mai l'accesso all'API amministrativa di Google Cloud o Dialogflow senza richiedere l'autenticazione. Questa API proxy limitata riduce la vulnerabilità agli abusi.

Prestazioni

Questa sezione descrive le informazioni sul rendimento per varie operazioni in Dialogflow. Comprendere la latenza è importante per progettare agenti reattivi e impostare aspettative di rendimento realistiche, anche se questi valori non fanno parte dell'SLA di Dialogflow.

Quando crei strumenti di monitoraggio e avviso, tieni presente che i modelli linguistici di grandi dimensioni (LLM) e l'elaborazione vocale vengono in genere gestiti utilizzando metodi di streaming. Le risposte vengono inviate al client il prima possibile, spesso molto prima di la durata totale della chiamata al metodo. Per saperne di più, consulta le Best practice con modelli linguistici di grandi dimensioni (LLM).

Rendimento per operazione

La tabella seguente fornisce informazioni sul rendimento tipico delle operazioni di Dialogflow:

Azione	Note
Rilevamento dell'intent (testo)	Operazione rapida
Rilevamento dei parametri (testo)	Operazione rapida
Riconoscimento vocale (streaming)	I dati vengono elaborati e le risposte vengono restituite il prima possibile. Il tempo totale di esecuzione è determinato principalmente dalla durata dell'audio di input. Non è consigliabile misurare la latenza utilizzando il tempo totale di esecuzione.
Sintesi vocale (streaming)	Il tempo totale di esecuzione è determinato principalmente dalla durata dell'audio di output. I dati vengono elaborati e le risposte vengono restituite il prima possibile.
Chiamate webhook	Il rendimento è determinato direttamente dal tempo di esecuzione del codice nel webhook.
Importa / Esporta agente	Il rendimento dipende dalle dimensioni dell'agente.
Addestramento dell'agente	Il rendimento dipende dal numero di flussi, intent e frasi di addestramento. L'addestramento di agenti di grandi dimensioni può richiedere decine di minuti.
Creazione dell'ambiente	La creazione di un ambiente comporta l'addestramento dell'agente, quindi il tempo totale dipenderà dalle dimensioni e dalla complessità dell'agente.

Note importanti:

• Streaming: per le chiamate di streaming (riconoscimento e sintesi vocale), i dati vengono elaborati man mano che arrivano e le risposte vengono restituite il prima possibile. Ciò significa che la risposta iniziale è in genere molto più rapida del tempo totale della chiamata.
• Playbook: un prompt LLM viene creato in base alle istruzioni del playbook, al contesto della conversazione e all'input dello strumento. È possibile eseguire più prompt LLM in una singola chiamata playbook. Per questo motivo, l'esecuzione del playbook è variabile, a seconda della quantità di prompt emessi e della complessità delle chiamate.

Considerazioni importanti sulla latenza

• Nessuna garanzia di latenza: gli SLA di Dialogflow non tengono conto della latenza, nemmeno con il Throughput riservato.
• Latenza LLM: tieni presente che l'elaborazione LLM può introdurre una latenza significativa. Tieni conto di questo aspetto nella progettazione dell'agente e nelle aspettative degli utenti.
• Monitoraggio e avvisi: quando configuri il monitoraggio e gli avvisi, tieni conto della natura in streaming delle risposte dei servizi LLM e vocali. Non dare per scontato che il tempo di risposta totale sia uguale al tempo per la prima risposta.