Configurazione della ricerca nel datastore

Puoi influenzare i risultati di ricerca recuperati dagli strumenti del datastore Conversational Agents (Dialogflow CX) configurando le specifiche di boost e filtro. Ciò consente 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, il tuo agente ha acquisito informazioni che indicano che l'utente finale possiede un "cellulare". Puoi configurare lo strumento di archiviazione dei dati per dare priorità ai documenti relativi ai cellulari quando rispondi a una domanda generica più avanti nella conversazione, ad esempio "Come faccio a controllare la segreteria?".

Puoi configurare i risultati della ricerca nell'datastore utilizzando la console, l'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 datastore all'interno dello strumento, offrendoti un controllo granulare sul comportamento di ogni datastore connesso.

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

  • Chiamata API: BoostSpec e FilterSpec vengono inviati in un SearchConfig utilizzando una chiamata API DetectIntent. Nella richiesta deve essere fornito un oggetto SearchConfig completo. Un SearchConfig inviato tramite chiamata API diretta esegue sempre l'override di 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 costruire un oggetto SearchConfig che viene inviato con la richiesta di ricerca. Se vuoi, puoi includere riferimenti ai parametri ed espressioni dinamiche per personalizzare i risultati in base ai dati contestuali registrati dalla conversazione. Devi fornire solo ConditionBoostSpec oggetti e un elenco di stringhe di filtro per costruire FilterSpecs anziché un oggetto SearchConfig completo.

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

Specifiche del boost

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.

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 l'incremento. Viene utilizzata la sintassi delle espressioni di filtro standard. Puoi utilizzare le espressioni Dialogflow per rendere i risultati dinamici, ad esempio $session.params.YOUR_PARAM_NAME o $request.end-user-metadata.YOUR_KEY.
  • boost: (Number) Un valore compreso tra -1,0 e 1,0 che determina l'intensità del boost.
    • Un valore positivo favorisce la corrispondenza dei documenti. Un valore di 1.0 offre una promozione efficace.
    • Un valore negativo declassa i documenti corrispondenti. Un valore di -1.0 comporta una forte retrocessione.
    • Un valore di 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 incremento. Per ulteriori informazioni sulla configurazione di questo campo, consulta la documentazione di riferimento.

Input di esempio 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 potenziati con un'intensità 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 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 del filtro

Le specifiche del 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 unicodatastorei.

Ogni specifica del filtro deve essere inserita come espressione stringa. La stringa deve rispettare la sintassi standard dell'espressione di filtro. Puoi utilizzare le espressioni Dialogflow 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

Sia le condizioni BoostSpec sia le stringhe FilterSpec possono incorporare espressioni Dialogflow per renderle dinamiche. In questo modo puoi personalizzare il comportamento di ricerca in base ai dati contestuali 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 del 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 incluso nel QueryParameters delle chiamate DetectIntent. Per maggiori informazioni, consulta endUserMetadata.

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

Condizioni di ricerca applicate in fase di runtime

Quando lo strumento del datastore esegue una ricerca:

  1. Le stringhe JSON che hai fornito per le specifiche di Boost vengono valutate. Ogni stringa JSON valida viene convertita in un oggetto ConditionBoostSpec. Questi vengono poi raggruppati in un oggetto BoostSpecs per la connessione specifica all&#39datastorei, che viene aggiunto al SearchConfig complessivo.
  2. Le stringhe che hai fornito per le specifiche del filtro vengono valutate come espressioni Dialogflow. Ogni stringa di filtro risultante viene utilizzata per creare un oggetto FilterSpecs per l'datastore, che viene aggiunto anche a SearchConfig.
  3. Questo SearchConfig creato dinamicamente viene poi incluso nel QueryParameters della richiesta di ricerca inviata al datastore.

Configurare le condizioni di ricerca

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

  • Un agente Conversational Agents (Dialogflow CX) esistente.
  • Uno strumento datastore configurato per il tuo agente con uno o più datastore abilitati.

Configurazione della console

  1. Apri la console Conversational Agents e scegli un progetto Google Cloud.
  2. Seleziona un agente dal menu a discesa.
  3. Vai al menu a sinistra e fai clic su Strumenti. Seleziona lo strumento datastorei 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 le specifiche di boost e filtro per modificare i risultati di ricerca.
    • Per una specifica di boost, fornisci un oggetto JSON che definisce un ConditionBoostSpec. Per i dettagli, consulta le specifiche del boost.
    • Per una specifica del filtro, fornisci una stringa che definisca i criteri del filtro. Per maggiori dettagli, vedi Specifiche del filtro.
  6. Dopo aver aggiunto e configurato le specifiche, fai clic su Conferma in fondo al riquadro laterale.
  7. Fai clic su Salva nella pagina di modifica dello strumento datastore per salvare le modifiche.

Configurazione API

Puoi fornire dati di configurazione della ricerca a Conversational Agents (Dialogflow CX) quando invii richieste di rilevamento dell'intent. Queste informazioni devono essere fornite in ogni richiesta di rilevamento dell'intent, 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 alla sessione:

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

Per applicare una specifica di ricerca o una configurazione di ricerca, è necessario 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>

Consulta il metodo setQueryParameters.

Risoluzione dei problemi

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

Espressioni non valide

Se una condizione Boost Spec o una stringa Filter Spec contiene un'espressione Conversational Agents (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 dell'espressione vengono in genere restituiti in DetectIntentResponse all'interno del campo diagnostic_info come SystemFunctionResults.

JSON ConditionBoostSpec non valido

La console Agenti conversazionali esegue alcune operazioni di convalida sulla stringa JSON ConditionBoostSpec durante il salvataggio. per verificare che sia un file JSON 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 di runtime

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

Rivedi il SearchConfig compilato

SearchConfig applicato quando viene eseguita la query è disponibile in search_signals nella risposta. La revisione del SearchConfig potrebbe fornire informazioni su problemi aggiuntivi non descritti qui.

Passaggi successivi