Configurazione della ricerca nel datastore

Puoi influenzare i risultati di ricerca recuperati dagli strumenti del datastore di Dialogflow CX configurando le specifiche di boost e filtro. In questo modo, puoi avere interazioni più personalizzate e sensibili al contesto quando l'agente utilizza un datastore per trovare informazioni.

Se vuoi, puoi includere espressioni dinamiche per perfezionare i risultati in base al contesto della conversazione. Ad esempio, l'agente ha acquisito informazioni che indicano che l'utente finale possiede un "cellulare". Puoi configurare lo strumento del datastore per dare un boost ai documenti relativi ai cellulari quando rispondi a una query generica più avanti nella conversazione, ad esempio "Come faccio a controllare la segreteria?".

Puoi configurare i risultati di ricerca del datastore utilizzando la console, l'API o l'integrazione di Dialogflow CX Messenger.

Input delle condizioni di ricerca

Puoi configurare i risultati di ricerca utilizzando i campi specifica di boost (BoostSpec) e specifica di filtro (FilterSpec) in un oggetto SearchConfig. Queste configurazioni si applicano per datastore all'interno dello strumento, consentendoti di controllare il comportamento di ogni datastore connesso.

Puoi configurare le condizioni di ricerca in uno dei due modi seguenti: utilizzando la console o inviando una chiamata API diretta.

Esistono importanti differenze tra i due:

  • Chiamata API: invii BoostSpec e FilterSpec in un SearchConfig utilizzando una chiamata API DetectIntent. Devi fornire un oggetto SearchConfig completo nella richiesta. Un SearchConfig inviato tramite chiamata API diretta esegue sempre l'override di un SearchConfig inviato tramite la console. Le espressioni dinamiche e i riferimenti ai parametri non sono supportati.

  • Console: la console utilizza le configurazioni BoostSpec e FilterSpec per creare un oggetto SearchConfig che invia con la richiesta di ricerca. Se vuoi, puoi includere riferimenti ai parametri ed espressioni dinamiche per personalizzare i risultati in base ai dati di contesto registrati dalla conversazione. Devi solo fornire oggetti ConditionBoostSpec e un elenco di stringhe di filtro per creare FilterSpecs anziché un oggetto SearchConfig completo.

Le informazioni sull'utente finale vengono fornite come JSON in detectIntentRequest. Non esiste uno schema previsto, quindi puoi definire le proprietà dell'oggetto.

Migliora le specifiche (Boost specs)

Le specifiche di boost ti consentono di modificare il ranking dei risultati di ricerca applicando un valore di boost a documenti specifici. Puoi aggiungere più specifiche di boosting a un singolo datastore.

Inserisci ogni specifica di boost come stringa JSON che rappresenta un singolo oggetto ConditionBoostSpec.

Campi chiave:

  • condition: (Stringa) Un'espressione che specifica quando deve essere applicato il boost. Viene utilizzata la sintassi delle espressioni di filtro standard. Puoi utilizzare le espressioni di Dialogflow CX per rendere dinamici i risultati, ad esempio $session.params.YOUR_PARAM_NAME o $request.end-user-metadata.YOUR_KEY.
  • boost: (numero) un valore compreso tra -1,0 e 1,0 che determina l'intensità del boost.
    • Un valore positivo promuove i documenti corrispondenti. Un valore pari a 1.0 offre una promozione forte.
    • Un valore negativo retrocede i documenti corrispondenti. Un valore pari a -1.0 comporta una forte retrocessione.
    • Un valore pari a 0.0 non applica alcun boost e non è consentito.
  • boostControlSpec: fornisce più controlli per un ranking personalizzato rispetto alla combinazione di base di condizione e boost. Per saperne di più sulla configurazione di questo campo, consulta la documentazione di riferimento.

Esempio di input della console:

Se configuri l'agente nella console, fornisci un elenco di ConditionBoostSpecs nel seguente formato:

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 0.5
}

Esempio di input dell'API:

Se chiami l'API direttamente, devi fornire ConditionBoostSpecs in un oggetto SearchConfig completo. La seguente configurazione di ricerca descrive una specifica di boost:

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "1.0"
          }
        }
      ]
    }
  ]
}

Specifiche dei filtri (specifiche dei filtri)

Le specifiche dei filtri limitano i risultati di ricerca in modo da includere solo i documenti che corrispondono ai criteri definiti. Puoi aggiungere più specifiche di filtro a un singolo datastore.

Ogni specifica di filtro deve essere inserita come espressione di stringa. La stringa deve essere conforme alla sintassi delle espressioni di filtro standard. Puoi utilizzare le espressioni di Dialogflow CX all'interno di questa stringa per rendere dinamici i risultati, ad esempio $session.params.YOUR_PARAM_NAME o $request.end-user-metadata.YOUR_KEY.

Esempio di stringa di specifica del filtro della console:

Se configuri l'agente utilizzando la console, devi fornire un elenco di stringhe filter per formare un oggetto FilterSpec.

In questo esempio, il filtro restituisce solo i documenti con numeric_field maggiore o uguale al valore di $session.params.min_value e in cui stock_availability è "IN_STOCK":

"numeric_field >= $session.params.min_value AND stock_availability: ANY(\"IN_STOCK\")"

Esempio di configurazione del filtro API:

Se chiami direttamente l'API, devi fornire stringhe filter in un oggetto SearchConfig completo:

"searchConfig": {
  "filterSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "filter": "CONDITION"
    }
  ]
}

Espressioni dinamiche di Dialogflow CX

Sia le condizioni BoostSpec che le stringhe FilterSpec possono incorporare espressioni di Dialogflow CX per renderle dinamiche. In questo modo, puoi personalizzare il comportamento di ricerca in base ai dati di contesto recuperati da una conversazione in corso. Le espressioni dinamiche non sono supportate nelle chiamate API dirette e possono essere utilizzate solo se la configurazione viene eseguita tramite la console.

Puoi accedere ai dati di contesto della conversazione in due modi:

  • Parametri di sessione: i valori raccolti durante la conversazione utilizzando $session.params.YOUR_PARAMETER_ID.
  • Metadati dell'utente finale:i metadati relativi all'utente finale passati in DetectIntentRequest utilizzando $request.end-user-metadata.YOUR_KEY. Per rendere disponibile questa opzione, verifica che end_user_metadata sia incluso nel QueryParameters delle chiamate DetectIntent. Per saperne di più, consulta endUserMetadata.

Per saperne di più sulle funzioni di sistema disponibili e sulla sintassi delle espressioni, consulta il riferimento per le condizioni e le funzioni di sistema.

Condizioni di ricerca applicate in fase di runtime

Quando lo strumento datastore esegue una ricerca:

  1. Valuta le stringhe JSON fornite per le specifiche di boost. Ogni stringa JSON valida viene convertita in un oggetto ConditionBoostSpec. Questi vengono poi raggruppati in un oggetto BoostSpecs per la connessione al datastore specifico, che viene aggiunto all'oggetto SearchConfig complessivo.
  2. Valuta le stringhe fornite per le specifiche dei filtri come espressioni di Dialogflow CX. Ogni stringa di filtro risultante viene utilizzata per creare un oggetto FilterSpecs per il datastore, che viene aggiunto anche a SearchConfig.
  3. Includi questo SearchConfig costruito dinamicamente nel QueryParameters della richiesta di ricerca inviata al datastore.

Configura le condizioni di ricerca

Per configurare le condizioni di ricerca, assicurati di aver completato i seguenti prerequisiti:

  • Un agente Dialogflow CX esistente.
  • Uno strumento datastore configurato per l'agente con uno o più datastore abilitati.

Configurazione della console

  1. Apri la console Conversational Agents e scegli un progettoGoogle Cloud .
  2. Seleziona un agente dal menu a discesa.
  3. Vai al menu a sinistra e fai clic su Strumenti. Seleziona lo strumento datastore che vuoi configurare.
  4. Nella pagina di modifica dello strumento, vai alla sezione Datastore. Fai clic sull'icona Impostazioni (⚙️) accanto al datastore che vuoi modificare.
  5. Viene visualizzato il menu Configura datastore. Qui puoi aggiungere specifiche di boost e specifiche di filtro per modificare i risultati di ricerca.
    • Per una specifica di boost, fornisci un oggetto JSON che definisce un ConditionBoostSpec. Per maggiori dettagli, consulta le specifiche di Boost.
    • Per una specifica del filtro, fornisci una stringa che definisce i criteri di filtro. Per maggiori dettagli, consulta le specifiche dei filtri.
  6. Dopo aver aggiunto e configurato le specifiche, fai clic su Conferma nella parte inferiore del riquadro laterale.
  7. Fai clic su Salva nella pagina di modifica dello strumento datastore per salvare le modifiche.

Configurazione API

Puoi fornire i dati di configurazione della ricerca a Dialogflow CX quando invii richieste di rilevamento intent. Devi fornire queste informazioni in ogni richiesta di rilevamento dell'intent, perché non vengono mantenute nella sessione.

Fornisci queste informazioni nel campo queryParams.searchConfig nel metodo Sessions.detectIntent.

Seleziona un protocollo e una versione per il riferimento alla sessione:

Protocollo V3 V3beta1
REST Risorsa Session Risorsa Session
RPC Interfaccia della sessione Interfaccia della sessione
C++ SessionsClient Non disponibile
C# SessionsClient Non disponibile
Vai SessionsClient Non disponibile
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP Non disponibile Non disponibile
Python SessionsClient SessionsClient
Ruby Non disponibile Non disponibile

Configurazione di Dialogflow CX Messenger

Puoi fornire i dati di configurazione della ricerca all'integrazione di Dialogflow CX Messenger. Per saperne di più, consulta il metodo setContext.

Per applicare una specifica o una configurazione di ricerca, devi aggiungere il seguente snippet al codice di Dialogflow CX Messenger quando lo incorpori in un sito web:

<script>
  document.addEventListener('df-messenger-loaded', () => {
    const dfMessenger = document.querySelector('df-messenger');
    const searchConfig = { ... }
    dfMessenger.setQueryParameters(searchConfig);
  });
</script>

Per saperne di più, consulta il metodo setQueryParameters.

Risoluzione dei problemi

Le seguenti soluzioni riguardano alcuni problemi comuni riscontrati durante la configurazione. Testa accuratamente le configurazioni simulando conversazioni che attivano diversi parametri di sessione e valori dei metadati degli utenti finali.

Espressioni non valide

Se una condizione della specifica di boost o una stringa della specifica di filtro contiene un'espressione Dialogflow CX non valida (ad esempio, sintassi errata o riferimento a un parametro inesistente), la compilazione dell'espressione non andrà a buon fine. Gli errori relativi alla compilazione delle espressioni vengono in genere restituiti in DetectIntentResponse nel campo diagnostic_info come SystemFunctionResults.

JSON ConditionBoostSpec non valido

La console Conversational Agents esegue una convalida della stringa JSON ConditionBoostSpec quando la salva per verificare se si tratta di un JSON valido e se la sua struttura può essere mappata a un oggetto ConditionBoostSpec. Se il JSON è valido, ma genera un SearchConfig non valido in base al servizio di ricerca sottostante (ad esempio, una stringa di condizione non valida dopo la sostituzione dei parametri), il servizio di ricerca restituirà un errore.

Errori di sostituzione in fase di runtime

Se una stringa JSON ConditionBoostSpec è valida e analizzabile, ma si verifica un errore durante la sostituzione in fase di runtime delle espressioni di Dialogflow CX all'interno dei suoi campi (ad esempio la stringa di condizione), questi errori verranno segnalati in diagnostic_info come SystemFunctionResults.

Esamina il file SearchConfig compilato

La SearchConfig applicata quando viene eseguita la query è disponibile in search_signals nella risposta. L'esame di SearchConfig può fornire informazioni su altri problemi non descritti qui.

Passaggi successivi

Indietro
Agenti ibridi del datastore
Avanti
Nozioni di base sugli agenti basati su flusso