Konfiguration der Datenspeichersuche

Sie können die Suchergebnisse, die mit Tools für Datenspeicher für Conversational Agents (Dialogflow CX) abgerufen werden, beeinflussen, indem Sie Boost- und Filterspezifikationen konfigurieren. So können personalisierte und kontextbezogene Interaktionen ermöglicht werden, wenn Ihr Agent einen Datenspeicher verwendet, um Informationen zu finden.

Optional können Sie dynamische Ausdrücke einfügen, um die Ergebnisse basierend auf dem Kontext der Unterhaltung zu optimieren. Ihr Agent hat beispielsweise Informationen erfasst, die darauf hindeuten, dass der Endnutzer ein „Mobiltelefon“ besitzt. Sie können das Tool für den Datenspeicher so konfigurieren, dass Dokumente zu Mobiltelefonen bei der Beantwortung einer allgemeinen Anfrage wie „Wie rufe ich meine Voicemail ab?“ später im Gespräch priorisiert werden.

Sie können die Suchergebnisse des Datenspeichers über die Konsole, die API oder die Dialogflow CX Messenger-Integration konfigurieren.

Eingaben für Suchbedingungen

Suchergebnisse werden mit den Feldern Boost-Spezifikation (BoostSpec) und Filterspezifikation (FilterSpec) in einem SearchConfig-Objekt konfiguriert. Diese Konfigurationen werden pro Datenspeicher im Tool angewendet. So haben Sie die Möglichkeit, das Verhalten jedes verbundenen Datenspeichers genau zu steuern.

Sie können Suchbedingungen auf zwei Arten konfigurieren: über die Console oder durch Senden eines direkten API-Aufrufs. Es gibt wichtige Unterschiede zwischen den beiden.

• API-Aufruf: BoostSpec und FilterSpec werden in einem SearchConfig mit einem DetectIntent-API-Aufruf gesendet. In der Anfrage muss ein vollständiges SearchConfig-Objekt angegeben werden. Eine SearchConfig, die über einen direkten API-Aufruf gesendet wird, überschreibt immer eine SearchConfig, die über die Console gesendet wird. Dynamische Ausdrücke und Parameterreferenzen werden nicht unterstützt.

• Console: Ihre BoostSpec- und FilterSpec-Konfigurationen werden verwendet, um ein SearchConfig-Objekt zu erstellen, das mit der Suchanfrage gesendet wird. Optional können Sie Parameterreferenzen und dynamische Ausdrücke einfügen, um die Ergebnisse an Kontextdaten anzupassen, die während der Unterhaltung aufgezeichnet wurden. Sie müssen nur ConditionBoostSpec-Objekte und eine Liste von Filterstrings bereitstellen, um FilterSpecs zu erstellen, anstatt eines vollständigen SearchConfig-Objekts.

Endnutzerinformationen werden als JSON bereitgestellt. Es gibt kein erwartetes Schema. Sie können die Objekteigenschaften also frei definieren.

Boost-Spezifikationen

Mit Boost-Spezifikationen können Sie das Ranking der Suchergebnisse ändern, indem Sie bestimmten Dokumenten einen Boost-Wert zuweisen. Sie können einem einzelnen Datenspeicher mehrere Boost-Spezifikationen hinzufügen.

Jede Boost-Spezifikation wird als JSON-String eingegeben. Dieser JSON-String muss ein einzelnes ConditionBoostSpec-Objekt darstellen.

Wichtigste Felder:

• condition: (String) Ein Ausdruck, der angibt, wann der Boost angewendet werden soll. Dabei wird die standardmäßige Syntax für Filterausdrücke verwendet. Sie können Dialogflow-Ausdrücke verwenden, um die Ergebnisse dynamisch zu gestalten, z. B. $session.params.YOUR_PARAM_NAME oder $request.end-user-metadata.YOUR_KEY.
• boost: (Zahl) Ein Wert zwischen -1,0 und 1,0, der die Stärke der Optimierung bestimmt.
  • Ein positiver Wert fördert übereinstimmende Dokumente. Ein Wert von 1.0 führt zu einer starken Aufwertung.
  • Ein negativer Wert stuft übereinstimmende Dokumente herab. Der Wert -1.0 führt zu einer starken Herabstufung.
  • Ein Wert von 0.0 wendet keinen Boost an und ist nicht zulässig.
• boostControlSpec: Bietet mehr Steuerungsmöglichkeiten für ein benutzerdefiniertes Ranking als die einfache Kombination aus Bedingung und Steigerung. Weitere Informationen zum Konfigurieren dieses Felds finden Sie in der Referenzdokumentation.

Beispiel für Konsoleneingabe:

Wenn Sie Ihren Agent in der Console konfigurieren, müssen Sie eine Liste mit ConditionBoostSpecs im folgenden Format angeben.

In diesem Beispiel werden Dokumente mit einem URI, der dem Wert des Sitzungsparameters $session.params.doc_id entspricht, mit einer Stärke von 0,5 bewertet. JSON in diesem Format

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

Beispiel für API-Eingabe:

Wenn Sie die API direkt aufrufen, müssen Sie ConditionBoostSpecs in einem vollständigen SearchConfig-Objekt angeben.Die folgende Suchkonfiguration beschreibt eine Boost-Spezifikation:

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

Hinweis :DATASTORE_ID ist der vollständige Name des Datenspeichers: projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name,
CONDITION muss der Syntax für Filterausdrücke von AI Applications entsprechen.
und der Optimierungswert müssen zwischen -1,0 und 1,0 liegen.

Filterspezifikationen

Filterspezifikationen beschränken die Suchergebnisse auf Dokumente, die den definierten Kriterien entsprechen. Sie können einem einzelnen Datenspeicher mehrere Filterspezifikationen hinzufügen.

Jede Filterspezifikation muss als Stringausdruck eingegeben werden. Der String muss der Standard-Filterausdruckssyntax entsprechen. Sie können Dialogflow-Ausdrücke in diesem String verwenden, um die Ergebnisse dynamisch zu gestalten, z. B. $session.params.YOUR_PARAM_NAME oder $request.end-user-metadata.YOUR_KEY.

Beispiel für einen Konsolenfilterspezifikationsstring:

Wenn Sie Ihren Agenten über die Console konfigurieren, müssen Sie eine Liste mit filter-Strings angeben, um ein FilterSpec-Objekt zu erstellen.

In diesem Beispiel werden mit dem Filter nur Dokumente zurückgegeben, bei denen numeric_field größer oder gleich dem Wert von $session.params.min_value ist UND stock_availability gleich "IN_STOCK" ist.

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

Beispiel für die Konfiguration eines API-Filters:

Wenn Sie die API direkt aufrufen, müssen Sie filter-Strings in einem vollständigen SearchConfig-Objekt angeben:

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

Hinweis: DATASTORE_ID ist der vollständige Name des Datenspeichers: projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name,
und CONDITION müssen der Syntax für Filterausdrücke von AI Applications entsprechen.

Dynamische Dialogflow-Ausdrücke

Hinweis :Dynamische Ausdrücke sind nur für Datenspeichertools verfügbar. Sie sind nicht für Datenspeicher-Handler verfügbar.

Sowohl BoostSpec-Bedingungen als auch FilterSpec-Strings können Dialogflow-Ausdrücke enthalten, um sie dynamisch zu gestalten. So können Sie das Suchverhalten an Kontextdaten anpassen, die aus einer laufenden Unterhaltung abgerufen werden. Dynamische Ausdrücke werden bei direkten API-Aufrufen nicht unterstützt und können nur verwendet werden, wenn Sie die Konfiguration über die Console vornehmen.

Sie haben zwei Möglichkeiten, auf Daten zum Unterhaltungskontext zuzugreifen:

• Sitzungsparameter:Werte, die während der Unterhaltung mit $session.params.YOUR_PARAMETER_ID erfasst werden.
• Endnutzermetadaten:Metadaten zum Endnutzer, die über $request.end-user-metadata.YOUR_KEY im DetectIntentRequest übergeben werden. Damit diese Option verfügbar ist, muss end_user_metadata in den QueryParameters Ihrer DetectIntent-Anrufe enthalten sein. Weitere Informationen finden Sie unter endUserMetadata.

Weitere Informationen zu den verfügbaren Systemfunktionen und zur Ausdruckssyntax finden Sie in der Referenz zu Bedingungen und Systemfunktionen.

Zur Laufzeit angewendete Suchbedingungen

Wenn Ihr Datenspeichertool eine Suche ausführt, gilt Folgendes:

1. Die von Ihnen für Boost-Spezifikationen angegebenen JSON-Strings werden ausgewertet. Jeder gültige JSON-String wird in ein ConditionBoostSpec-Objekt konvertiert. Diese werden dann in einem BoostSpecs-Objekt für die jeweilige Datenspeicherverbindung gruppiert, das dem allgemeinen SearchConfig hinzugefügt wird.
2. Die von Ihnen angegebenen Strings für Filterspezifikationen werden als Dialogflow-Ausdrücke ausgewertet. Jeder resultierende Filterstring wird verwendet, um ein FilterSpecs-Objekt für den Datenspeicher zu erstellen, das auch dem SearchConfig hinzugefügt wird.
3. Diese dynamisch erstellte SearchConfig wird dann in die QueryParameters der Suchanfrage eingefügt, die an den Datenspeicher gesendet wird.

Suchbedingungen konfigurieren

Bevor Sie Suchbedingungen konfigurieren, müssen Sie Folgendes prüfen:

• Ein vorhandener Konversations-Agent (Dialogflow CX).
• Ein Datenspeichertool, das für Ihren Agenten konfiguriert ist und für das mindestens ein Datenspeicher aktiviert ist.

Konsolenkonfiguration

1. Öffnen Sie die Conversational Agents Console und wählen Sie ein Google Cloud-Projekt aus.
2. Wählen Sie im Drop-down-Menü einen Agent aus.
3. Klicken Sie im Menü auf der linken Seite auf Tools. Wählen Sie das Tool für den Datenspeicher aus, das Sie konfigurieren möchten.
4. Rufen Sie auf der Seite zum Bearbeiten des Tools den Bereich Datenspeicher auf. Klicken Sie neben dem Datenspeicher, den Sie ändern möchten, auf das Symbol Einstellungen (⚙️).
5. Das Menü Datenspeicher konfigurieren wird angezeigt. Hier können Sie Boost- und Filterspezifikationen hinzufügen, um Ihre Suchergebnisse zu ändern.
   • Geben Sie für eine Boost Spec ein JSON-Objekt an, das eine ConditionBoostSpec definiert. Weitere Informationen finden Sie unter Boost-Spezifikationen.
   • Geben Sie für eine Filter Spec einen String an, der die Filterkriterien definiert. Weitere Informationen finden Sie unter Filterspezifikationen.
6. Klicken Sie nach dem Hinzufügen und Konfigurieren der Spezifikationen unten in der Seitenleiste auf Bestätigen.
7. Klicken Sie auf der Seite zum Bearbeiten des Datenspeichertools auf Speichern, um die Änderungen zu speichern.

API-Konfiguration

Sie können Konversations-Agents (Dialogflow CX) Suchkonfigurationsdaten zur Verfügung stellen, wenn Sie Anfragen zum Erkennen von Intentionen senden. Diese Informationen müssen in jeder „detect intent“-Anfrage angegeben werden, da sie nicht in der Sitzung gespeichert werden.

Geben Sie diese Informationen im Feld queryParams.searchConfig in der Methode Sessions.detectIntent an.

Zur API-Referenz-Sitzung

Wählen Sie ein Protokoll und eine Version für die Sitzungsreferenz aus:

Protokoll	V3	V3beta1
REST	Sitzungsressource	Sitzungsressource
RPC	Sitzungsoberfläche	Sitzungsoberfläche
C++	SessionsClient	Nicht verfügbar
C#	SessionsClient	Nicht verfügbar
Go	SessionsClient	Nicht verfügbar
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Nicht verfügbar	Nicht verfügbar
Python	SessionsClient	SessionsClient
Ruby	Nicht verfügbar	Nicht verfügbar

Schließen

Dialogflow CX Messenger-Konfiguration

Sie können der Dialogflow CX Messenger-Integration Suchkonfigurationsdaten zur Verfügung stellen. Weitere Informationen finden Sie in der setContext-Methode.

Damit eine Suchspezifikation oder Suchkonfiguration angewendet werden kann, muss das folgende Snippet dem Dialogflow CX Messenger-Code hinzugefügt werden, wenn er in eine Website eingebettet wird:

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

Weitere Informationen finden Sie in der Methode setQueryParameters.

Fehlerbehebung

In diesem Abschnitt werden Lösungen für einige häufige Probleme beschrieben, die bei der Konfiguration auftreten können. Testen Sie Ihre Konfigurationen immer gründlich, indem Sie Konversationen simulieren, die verschiedene Sitzungsparameter und Metadatenwerte für Endnutzer auslösen.

Ungültige Ausdrücke

Wenn eine Boost Spec-Bedingung oder ein Filter Spec-String einen ungültigen Conversational Agents-Ausdruck (Dialogflow CX) enthält, z. B. eine falsche Syntax oder einen Verweis auf einen nicht vorhandenen Parameter, schlägt die Kompilierung des Ausdrucks fehl. Fehler im Zusammenhang mit der Kompilierung von Ausdrücken werden in der Regel im DetectIntentResponse im Feld diagnostic_info als SystemFunctionResults zurückgegeben.

Ungültiges ConditionBoostSpec-JSON

Die Conversational Agents Console führt beim Speichern eine Validierung des ConditionBoostSpec-JSON-Strings durch. So wird geprüft, ob es sich um gültiges JSON handelt und seine Struktur einem ConditionBoostSpec-Objekt zugeordnet werden kann. Wenn das JSON-Dokument gültig ist, aber gemäß dem zugrunde liegenden Suchdienst zu einem ungültigen SearchConfig führt (z. B. ein ungültiger Bedingungsstring nach der Parameterersetzung), gibt der Suchdienst einen Fehler zurück.

Laufzeitfehler bei der Ersetzung

Wenn ein ConditionBoostSpec-JSON-String gültig und parsbar ist, aber während der Laufzeitsubstitution von Dialogflow-Ausdrücken in seinen Feldern (z. B. dem Bedingungsstring) ein Fehler auftritt, werden diese Fehler in diagnostic_info als SystemFunctionResults gemeldet.

Kompilierte SearchConfig prüfen

Der beim Ausführen der Abfrage angewendete SearchConfig ist in der Antwort unter search_signals verfügbar. Wenn Sie die SearchConfig prüfen, erhalten Sie möglicherweise Informationen zu weiteren Problemen, die hier nicht aufgeführt sind.

Nächste Schritte

• Weitere Informationen zur Struktur von SearchConfig und seinen Komponenten finden Sie in der search_config-Dokumentation.
• Weitere Informationen zur Ausdruckssyntax finden Sie in der Referenz zu Dialogflow-Bedingungen und ‑Systemfunktionen.
• Weitere Informationen zur Syntax von Filterausdrücken für die Suche finden Sie unter Ergebnisse filtern und sortieren.