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, le interazioni diventano 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 in modo da aumentare i documenti relativi ai cellulari quando rispondi a una query generale più avanti nella conversazione, ad esempio "Come faccio a controllare la segreteria telefonica?".

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

Input delle condizioni di ricerca

I risultati di ricerca vengono configurati utilizzando i campi specifica di boost (BoostSpec) e specifica di filtro (FilterSpec) in un oggetto SearchConfig. Queste configurazioni vengono applicate per ogni datastore all'interno dello strumento, il che ti consente di controllare in modo preciso il comportamento di ogni datastore connesso.

Puoi configurare le condizioni di ricerca in due modi: utilizzando la console, o inviando una chiamata API diretta. Esistono differenze importanti tra i due metodi.

  • Chiamata API: BoostSpec e FilterSpec vengono inviati in un SearchConfig utilizzando una chiamata API DetectIntent. Nella richiesta deve essere fornito un oggetto completo SearchConfig. Un SearchConfig inviato tramite chiamata API diretta sostituisce sempre un SearchConfig inviato utilizzando la console. Le espressioni dinamiche e i riferimenti ai parametri non sono supportati.

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

Le informazioni dell'utente finale vengono fornite in formato JSON. Non è previsto uno schema, quindi puoi definire liberamente le proprietà dell'oggetto.

Specifiche di boost

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

Ogni specifica di boost viene inserita come stringa JSON. Questa stringa JSON deve rappresentare un singolo oggetto ConditionBoostSpec.

Campi chiave:

  • condition: (stringa) un'espressione che specifica quando deve essere applicato il boost. Utilizza la sintassi standard delle espressioni di filtro. 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 la forza del boost.
    • Un valore positivo promuove i documenti corrispondenti. Un valore di 1.0 offre una promozione efficace.
    • Un valore negativo declassa i documenti corrispondenti. Un valore di -1.0 offre una declassificazione efficace.
    • Un valore di 0.0 non applica alcun boost e non è consentito.
  • boostControlSpec: fornisce più controlli per una classificazione personalizzata rispetto alla combinazione di base di condizione e boost. Per ulteriori informazioni sulla configurazione di questo campo, consulta la documentazione di riferimento.

Esempio di input della console:

Se stai configurando l'agente nella console, devi fornire un elenco di ConditionBoostSpecs nel seguente formato.

In questo esempio, i documenti con un URI corrispondente al valore del parametro di sessione $session.params.doc_id verranno aumentati con una forza di 0,5. JSON di questo formato

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

Esempio di input dell'API:

Se chiami direttamente l'API, 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 di filtro

Le specifiche di filtro 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 standard delle espressioni di filtro. 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 di filtro della console:

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

In questo esempio, il filtro restituisce solo i documenti con numeric_field maggiore o uguale al valore di $session.params.min_value E dove 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 sia 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: valori raccolti durante la conversazione utilizzando $session.params.YOUR_PARAMETER_ID.
  • Metadati dell'utente finale: metadati relativi all'utente finale passati in DetectIntentRequest utilizzando $request.end-user-metadata.YOUR_KEY. Affinché questa opzione sia disponibile, verifica che end_user_metadata sia inclusa in QueryParameters delle chiamate DetectIntent. Per ulteriori informazioni, consulta endUserMetadata.

Per ulteriori dettagli sulle funzioni di sistema e sulla sintassi delle espressioni disponibili, consulta il riferimento alle condizioni e alle funzioni di sistema.

Condizioni di ricerca applicate al runtime

Quando lo strumento del datastore esegue una ricerca:

  1. Vengono valutate 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 del datastore specifico, che viene aggiunto a SearchConfig complessivo.
  2. Le stringhe fornite per le specifiche di filtro vengono valutate 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. SearchConfig creato dinamicamente viene quindi incluso in QueryParameters della richiesta di ricerca inviata al datastore.

Configurare le condizioni di ricerca

Prima di configurare le condizioni di ricerca, verifica di avere:

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

Configurazione della console

  1. Apri la console Conversational Agents e scegli un Google Cloud progetto.
  2. Seleziona un agente dal menu a discesa.
  3. Vai al menu a sinistra e fai clic su Strumenti. Seleziona lo strumento del 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 Specifiche di boost.
    • Per una specifica di filtro, fornisci una stringa che definisce i criteri di filtro. Per maggiori dettagli, consulta Specifiche di filtro.
  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 del datastore per salvare le modifiche.

Configurazione dell'API

Puoi fornire i dati di configurazione della ricerca a Dialogflow CX quando invii richieste di rilevamento dell'intento. Queste informazioni devono essere fornite in ogni richiesta di rilevamento dell'intento, perché non vengono mantenute nella sessione.

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

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

Protocollo V3 V3beta1
REST Risorsa sessione Risorsa sessione
RPC Interfaccia sessione Interfaccia 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 ulteriori informazioni, consulta il metodo setContext.

Per applicare una specifica di ricerca o una configurazione di ricerca, il seguente snippet deve essere aggiunto 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>

Consulta il metodo setQueryParameters.

Risoluzione dei problemi

Questa sezione illustra le soluzioni ad alcuni problemi comuni riscontrati durante la configurazione. Testa sempre attentamente le configurazioni simulando conversazioni che attivano diversi parametri di sessione e valori dei metadati dell'utente finale.

Espressioni non valide

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

JSON ConditionBoostSpec non valido

La console Conversational Agents esegue alcune convalide sulla stringa JSON ConditionBoostSpec quando la salva. In questo modo, verifica che il JSON sia valido e che la sua struttura possa 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 al runtime

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

Esaminare SearchConfig compilato

Il SearchConfig applicato quando viene eseguita la query è disponibile in search_signals nella risposta. L'esame di SearchConfig potrebbe fornire informazioni su altri problemi non descritti qui.

Passaggi successivi

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