Entwicklerleitfaden für die dialogbasierte Suche

In diesem Leitfaden wird beschrieben, wie Sie die Conversational API einbinden, um Ihren Kunden dynamische, KI-basierte Chatfunktionen zu bieten. Wenn Sie die verschiedenen Anfragetypen kennen und die Antworten der API nutzen, können Sie relevante Produktsuchen durchführen, Kundenanfragen beantworten und Endnutzer durch den Kaufprozess führen.

Das conversationalFilteringMode in der Conversational API verdeutlicht die Unterschiede zwischen der konversationellen Suche und der dialogbasierten Produktfilterung.

API-Einrichtung und ‑Aufrufabfolge

Die Conversational API unterstützt die konversationelle Suche:

Die Conversational API ermöglicht eine Chatfunktion, bei der Ihre Nutzer Anfragen senden und das System eine Textantwort, klassifizierte Anfragetypen und potenzielle verfeinerte Suchoptionen zurückgibt.

Diese API funktioniert als Streamingdienst und ermöglicht die frühzeitige Erkennung der Suchanfrage. Für nachfolgende Interaktionen in der Unterhaltung muss eine conversation_id angehängt werden.

Um Suchergebnisse zurückzugeben, muss die klassische AI Commerce Search API parallel zur Conversational API aufgerufen werden.

Anfrage vom Endnutzer senden

In diesem Abschnitt wird beschrieben, wie Sie eine Konversationssuche starten. Ein Nutzer könnte beispielsweise Hilf mir, eine Party zu planen in das Suchfeld eingeben.

Anfrage an AI Commerce Search senden

Es gibt zwei verschiedene API-Endpunkte:

  1. Die Conversational API muss verwendet werden, um den Konversationsmodus abzurufen.
  2. Die Search API muss verwendet werden, um Suchergebnisse abzurufen.

Endpunkt 1: Conversational API-Anfrage

  • Sie sollten eine konversationelle Suchanfrage erstellen, indem Sie die Eingabe des Nutzers als query festlegen.
  • Die Anfrage sollte als HTTP-POST-Anfrage an den projects/*/locations/*/catalogs/*/placements/*:conversationalSearch-Endpunkt gesendet werden.

HTTP-Methode und Endpunkt

  POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Conversational API-Anfrage:

Erste Anfrage

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/default_catalog/branches/default_branch",
  "placement": "projects/{project_id}/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}
  • placement: Der Ressourcenname der Platzierung (z. B. projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Dies ist ein Pfadparameter und erforderlich.
  • query: Die einfache Suchanfrage des Nutzers. Dies ist ein Pflichtfeld.
  • branch: Der Ressourcenname des Zweigs, z. B. projects/P/locations/L/catalogs/C/branches/B. Wenn kein Wert angegeben ist, wird default_branch verwendet. Dies ist ein Pflichtfeld.
  • visitorId: Eine eindeutige Kennung zum Tracken von Besuchern. Dies ist ein Pflichtfeld.
  • conversationId: Eine eindeutige ID zum Tracking von Unterhaltungssitzungen. Bei der ersten Anfrage in einer neuen Unterhaltung sollte dieses Feld leer sein. Für nachfolgende Anfragen innerhalb derselben Unterhaltung muss es auf die conversation_id gesetzt werden, die in der vorherigen ConversationalSearchResponse empfangen wurde.
  • searchParams: (Optional) Standard-Kernparameter für die Suche, z. B. filter, canonicalFilter, sortBy und boostSpec. Es ist wichtig, dass diese Parameter der Konfiguration entsprechen, die in Ihren Haupt-Search API-Aufrufen verwendet wird, um die Konsistenz zwischen LLM-Antworten und allen angezeigten Produktsuchergebnissen zu gewährleisten.
  • userInfo: (Optional) Nutzerinformationen für eine verbesserte Personalisierung. Kann userId, user_agent, direct_user_request (boolescher Wert) enthalten.
  • conversationalFilteringSpec: (Optional) Gibt den Konversationsfiltermodus an. Wenn nicht festgelegt, ist der Standardwert DISABLED.

    mode: Sie können die Conversational API in einem der folgenden drei Modi einbinden, um die Filterung von Produkten in Unterhaltungen zu steuern:

    • DISABLED: In diesem Modus implementiert der Client nur die konversationelle Suche. Dies ist der bevorzugte Modus für diese Implementierungsanleitung zur konversationellen Suche.

      • Beispiel für eine API-Anfrage

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }

      Beispiel für eine API-Antwort

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
    • ENABLED: In diesem Modus implementiert der Client alle dialogbasierten Funktionen, einschließlich der dialogbasierten Suche und der dialogbasierten Produktfilterung.

      • Weitere Informationen zum Integrieren beider Konversationsprodukte

      Beispiel für eine API-Anfrage

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }

      Beispiel für eine API-Antwort

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
    • CONVERSATIONAL_FILTER_ONLY: Wenn diese Option ausgewählt ist, implementiert der Kunde nur die Konversationsfilterung für Produkte. Wenn dieser Modus ausgewählt ist, wird nur eine unterhaltungsbasierte Produktfilterung ohne LLM-Antwort, Abfrageklassifizierung oder vorgeschlagene Suchanfragen durchgeführt.

      • Weitere Informationen finden Sie im Entwicklerhandbuch für dialogorientierte Produktfilter.

Endpunkt 2: Core Search API-Anfrage

Es gibt zwei primäre Ansätze zum Anzeigen von Suchergebnissen in Ihrer Weboberfläche.

Option 1: Suchergebnisse immer anzeigen

Wenn in Ihrem UX-Design festgelegt ist, dass Suchergebnisse immer angezeigt werden sollen, unabhängig von der Ausgabe der Konversations-API, z. B. in einem speziellen Suchergebnisbereich neben dem Chat, senden Sie die ursprüngliche Anfrage des Nutzers mit Ihrem Aufruf der Conversational API an die Core Produktsuche API. So sind Produkteinträge sofort verfügbar.

Option 2: Suchergebnisse basierend auf der Konversationsausgabe anzeigen

Wenn Ihr UX-Design dynamischer ist und Sie Suchergebnisse nur in Abhängigkeit von der Antwort der Conversational API anzeigen möchten, z. B. nur für SIMPLE_PRODUCT_SEARCH-Anfragen oder wenn refined_search-Vorschläge bereitgestellt werden, warten Sie auf die Antwort der Conversational API, bevor Sie Anfragen an die Produktsuche API senden. Wenn eine Antwort vorhanden ist, verwenden Sie die bereitgestellte refined_search-Anfrage, um Produktergebnisse abzurufen.

Unabhängig davon, welche Benutzeroberflächenoption Sie auswählen, können Sie die AI Commerce Search API aufrufen, wenn Sie tatsächliche Produktergebnisse abrufen müssen. Weitere Informationen finden Sie unter Nutzerabsichtsklassifizierung und Händleraktionen.

HTTP-Methode und Endpunkt

    POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search

Core Product Search API-Anfrage:

Erste Anfrage

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
  • placement (Erforderlich): Der Ressourcenname der Bereitstellungskonfiguration für die KI-basierte Suche für Commerce oder des alten Placements. Beispiel: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
  • query: Erforderlich. Die Suchanfrage. Das kann die Rohdaten-Eingabe des Nutzers sein, z. B. Hilf mir, eine Party zu planen, oder ein optimierter refinedSearch.query, z. B. Partyplanungszubehör, Dekorationen, der aus der Antwort der Conversational Commerce API stammt.
  • visitorId: Erforderlich. Eine eindeutige Kennung für das Tracking von Besuchern. Dieser Wert sollte mit dem visitorId übereinstimmen, der für denselben Endnutzer an die Conversational Commerce API gesendet wird.
  • branch (erforderlich): Der Ressourcenname des Zweigs, z. B. projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
  • pageSize (Optional): Die maximale Anzahl der zurückzugebenden Produkte.
  • filter (Optional): Wird verwendet, um Suchergebnisse zu filtern. Hier wenden Sie alle Filter an, die den Parametern entsprechen, die Sie in `searchParams` an die Conversational Commerce API senden, um die Konsistenz zu wahren.
  • orderBy (Optional): Gibt die Reihenfolge an, in der Produkte zurückgegeben werden (z. B. nach Relevanz oder Preis).
  • userInfo (Optional): Nutzerinformationen zur Personalisierung, die mit dem Conversational Commerce API-Aufruf übereinstimmen sollten.
  • searchMode (Optional): Definiert das Suchverhalten. PRODUCT_SEARCH ist bei allgemeinen Produktanfragen üblich.

Antwort verstehen

Dieses Codebeispiel zeigt eine Antwort der Conversational Commerce API.

Die API-Antwort (ConversationalSearchResponse) enthält query_types, conversational_text_response (falls zutreffend), refined_search-Optionen und möglicherweise followup_question oder conversational_filtering_result. Die conversation_id ist für die Fortsetzung der Sitzung erforderlich.

Antwort von AI Commerce Search

In diesem Codebeispiel wird eine Antwort der Conversational API veranschaulicht:

Erste Antwort

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }

Was Einzelhändler mit der Antwort tun sollten (allgemein)

Rendern Sie die folgenden Felder aus der Antwort:

  • user_query_types: Dieses Feld enthält die Klassifizierung(en) der Intention des Nutzers. Detaillierte Aktionen basierend auf diesen Typen finden Sie unter Klassifizierung der Nutzerabsicht und Händleraktionen.
  • conversation_id: Sie können diese eindeutige ID im Browserspeicher oder in einem ähnlichen clientseitigen Speicher speichern, um die Unterhaltungssitzung mit dem Server aufrechtzuerhalten. Das ist wichtig, um zwischen mehreren laufenden Unterhaltungen für einen einzelnen Käufer zu unterscheiden. Ihr Modell behält den Kontext für ein bestimmtes conversation_id bei. Wenn Sie ein neues conversation_id senden, wird eine neue Sitzung gestartet. Es wird empfohlen, die Sitzungsdauer zu definieren, z. B. 30 Minuten Inaktivität.
  • refined_search: Dies ist eine Liste mit vorgeschlagenen verfeinerten Suchanfragen, die zum Abrufen der relevanten Suchergebnisse verwendet werden. Bei SIMPLE_PRODUCT_SEARCH handelt es sich immer um eine einzelne Anfrage. Bei anderen Anfragen, bei denen eine LLM-Antwort gesucht wird, ist es eine oder mehrere. Die refined_search-Anfragen können für Aufrufe der Core Search API (SearchService.Search) verwendet oder Ihren Nutzern als Vorschläge angezeigt werden.
  • conversational_text_response: Zeigen Sie diesen Text Ihrem Nutzer als primäre KI-generierte Antwort auf seine Anfrage an.
  • followup_question: Optional. followup_question wird angezeigt.
  • state: Dieses Feld gibt den Status der Generierung von Antworten an ("STREAMING" oder "SUCCEEDED"). Sie können es für Feedback zur Nutzerfreundlichkeit verwenden, z. B. um eine Ladeanzeige bis "SUCCEEDED" einzublenden. Weitere Informationen dazu finden Sie im nächsten Abschnitt.

Streaming API verstehen

Die Conversational Commerce API funktioniert als Streamingdienst. Das bedeutet, dass Ihr Nutzer Teile der Antwort in mehreren Chunks anstelle einer einzelnen, vollständigen Nutzlast erhält.

  • Warum Streaming? Die Textgenerierung durch LLMs kann einige Zeit in Anspruch nehmen. Durch Streaming können Sie schneller reagieren.
  • Erster Antwort-Chunk (sofort):
  • Enthält userQueryTypes- und refinedSearch-Anfragen.
  • state: "STREAMING"
  • Nachfolgende Chunks:
  • Enthält Teile von conversationalTextResponse, während es generiert wird.
  • Letzter Chunk:
  • Enthält die vollständige conversationalTextResponse.
  • state: "SUCCEEDED"
  • Umsetzbare Informationen:Sie können die Intention des Nutzers sofort anhand des ersten Chunks ermitteln und parallel mit dem Abrufen von Produktergebnissen beginnen, während die KI-Textantwort noch geladen wird.

Der erste Teil der Antwort enthält die Abfragen query_types und refined_search. Der state-Wert ist STREAMING. Durch diese frühe Erkennung der Intention und die sofortige Verfügbarkeit von Suchverfeinerungen kann Ihr Modell schnell entscheiden, wie die Anfrage des Nutzers behandelt und die Latenz bei LLM-Antworten für den Nutzer optimiert werden soll:

  • Bei Anfragetypen, bei denen keine Antwort in Form von Konversationstext erwartet wird, z. B. SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT:
    • Da sich query_types im ersten Chunk befinden, weiß Ihr System sofort, dass keine LLM-Antwort kommt. Sie können mit der vordefinierten Verarbeitung für diese Typen fortfahren, z. B. eine statische Meldung anzeigen oder an den Support weiterleiten, ohne auf weitere Conversational-Ausgaben zu warten.
    • Speziell für SIMPLE_PRODUCT_SEARCH kann Ihr System mit der im ersten Chunk empfangenen refined_search-Anfrage sofort einen direkten Aufruf der Core Search API ausführen. So können Suchergebnisse mit minimaler Verzögerung angezeigt werden, was den typischen SLAs für die Suche entspricht.
  • Bei Abfragetypen, bei denen keine Antwort in Form von Konversations-Text erwartet wird, z. B. INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT:
    • Sie erhalten die query_types- und refined_search-Anfragen im ersten Chunk. Sie können mit diesen refined_search-Abfragen sofort einen parallelen Aufruf der Core Search API initiieren, um mit dem Laden von Produktergebnissen zu beginnen.
    • Nachfolgende Chunks werden gestreamt und enthalten verschiedene Abschnitte der Antwort im Konversationsstil. Während dieser Zeit bleibt state "STREAMING".
    • Der letzte Chunk enthält schließlich die vollständige Antwort im Unterhaltungstext und sein state ändert sich zu "COMPLETED".
    • Dieser Streamingansatz ermöglicht eine flüssige Nutzererfahrung, da die Suchergebnisse geladen werden können, während die KI-Zusammenfassung generiert wird. Sie können auswählen, ob ein Ladeindikator für die Konversationsantwort angezeigt werden soll oder ob die Konversationsantwort erst präsentiert werden soll, wenn sie vollständig gestreamt wurde.

Klassifizierung der Nutzerabsicht und Händleraktionen

Der Intent-Klassifikator entscheidet, wie die Nutzeranfrage behandelt wird und welcher Konversationsmodus gestartet wird.

Das Feld query_types in der Antwort ist eine Liste, die die Klassifizierung(en) der Intention des Nutzers angibt. Ihr System sollte diese so verarbeiten. conversational_text_response bezieht sich auf die KI-generierte Antwort in natürlicher Sprache von der API.

Das Feld userQueryTypes (im ersten Antwort-Chunk) ist das wichtigste Feld, um die nächste Aktion Ihrer Anwendung zu bestimmen:

  • SIMPLE_PRODUCT_SEARCH: rotes Kleid
    • API-Antwort: Keine conversational_text_response. Gibt eine einzelne refinedSearch-Anfrage zurück.
    • Ihre Aktion: Rufen Sie die Search API sofort mit dem refinedSearch.query auf. Übergang zu einer Standard-Suchergebnisseite oder Anzeige von Ergebnissen.
  • INTENT_REFINEMENT / PRODUCT_COMPARISON / BEST_PRODUCT: Plane eine Party.
    • API-Antwort: Enthält conversationalTextResponse- und refinedSearch-Anfragen sowie möglicherweise eine followupQuestion.
    • Ihre Aktion: Hier wird die KI-Textantwort angezeigt. Mit den refinedSearch-Abfragen können Sie Produktkarussells oder Vorschläge erstellen. Zeigen Sie die followupQuestion an.
  • Supportanfragen: Schließen Sie ORDER_SUPPORT und STORE_RELEVANT ein.
    • API-Antwort: Keine conversational_text_response.
    • Ihre Aktion: Leiten Sie den Nutzer auf die entsprechende Seite weiter, z. B. zur Sendungsverfolgung oder zur Händlersuche, oder zeigen Sie eine Standardantwort an.

Bei der konversationellen Suche werden Suchanfragekategorien verwendet, um zu bestimmen, ob eine auf einem LLM basierende Antwort generiert wird und wie Endnutzeranfragen von den Conversational- und Search-APIs für diese Szenarien verarbeitet werden:

Kategorien Abfrageklassifizierungen
1. Irrelevante Anfragen, die keine LLM-Antwort erfordern
  • QUERY_TYPE_UNSPECIFIED: Nicht angegebener Abfragetyp.
  • RETAIL_IRRELEVANT: Anfragen, die für die Einzelhandelsdomain irrelevant sind, z. B. eine feindselige Anfrage (z. B. Wie baue ich eine Bombe?),eine gesprächige Anfrage (z. B. Wie geht es dir?) oder eine Jailbreak-Anfrage (z. B. Schreibe ein Gedicht.).
  • BLOCKLISTED: Anfragen, die von den Commerce-Kunden explizit blockiert werden (z. B. Welche Nebenwirkungen hat Advil?).
2. Support- und Informationsanfragen
  • ORDER_SUPPORT: Zusätzliche oder Supportanfrage (z. B. Meine Bestellung verfolgen, Status der Bestellung 12345).
  • DEALS_AND_COUPONS: Anfragen zu Angeboten, Promotions, Produktangeboten und Rabatten (z. B. Gibt es Angebote für Thanksgiving?).
  • STORE_RELEVANT: Anfragen zu Filialstandorten, einschließlich Arbeitszeiten und Produktverfügbarkeit (z. B. Haben wir Milch auf Lager?).
  • RETAIL_SUPPORT: Anfragen zu Käufen, einschließlich Zahlungsmethoden (Welche Zahlungsmethoden werden akzeptiert?)
3. Keyword-Suchanfragen, für die kein LLM erforderlich ist

Anfrage an die Conversational API:

Erste Anfrage

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "show me some monster energy drinks",
  "visitorId": "test"
}

Antwort der Conversational API:

Erste Antwort

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9",
  "refinedSearch": [
    {
      "query": "monster energy drinks"
    }
  ]
}

Search API-Anfrage:

Weiterführende Anfrage

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  • SIMPLE_PRODUCT_SEARCH: einfache Produktsuche, z. B. Rotes Kleid oder Zeige mir einige Monster-Drinks.
4. LLM-Anfragen zur Suche nach Antworten

Anfrage an die Conversational API:

Erste Anfrage

  {
    "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
    "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
    "query": "Compare 1% milk with 2% milk",
    "visitorId": "test"
  }

Antwort der Conversational API:

Erste Antwort

{
  "userQueryTypes": ["PRODUCT_COMPARISON"],
  "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.",
  "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba",
  "refinedSearch": [
    {
      "query": "1% milk"
    },
    {
      "query": "2% milk"
    }
  ]
}

Search API-Anfrage:

Weiterführende Anfrage

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "1% milk",
  "visitorId": "test"
}
  • PRODUCT_DETAILS: Der Nutzer sucht nach Produktdetails und ‑spezifikationen, z. B. Zeige mir die Spezifikationen von [Produktname]. Wie hoch ist der Proteingehalt von Milch mit 2% Fett?
  • PRODUCT_COMPARISON: Produktvergleich, z. B. Vergleiche [Produktname] und [Produktname], Vergleiche 1% ige Milch mit 2% iger Milch.
  • BEST_PRODUCT: Anfragen mit dem am besten passenden Muster, z. B. Was ist der gesündeste Keks? Welche Milchmarke ist die beste?
5. Absicht eingrenzen

Anfrage an die Conversational API:

Erste Anfrage

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "Help me plan a party",
  "visitorId": "test"
}

Antwort der Conversational API:

Erste Antwort

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}
  • INTENT_REFINEMENT: Der Typ ist unklar und es ist möglicherweise ein Folgegespräch oder eine Präzisierung erforderlich, um den Typ zu klären, z. B. Hilf mir, eine Party zu planen. Dies ist oft die beliebteste Intention in Unterhaltungen.

Kategorie 1: Irrelevante Anfragen, für die keine LLM-Antwort erforderlich ist

  • QUERY_TYPE_UNSPECIFIED:
    • Es wurde kein conversational_text_response angegeben.
    • Aktion: Als Standard- oder Fehlerfall behandeln. Sie können den Nutzer um eine Klarstellung bitten oder ihn an eine Stelle weiterleiten, an der er allgemeine Hilfe erhalten kann.
  • RETAIL_IRRELEVANT:
    • Es wurde kein conversational_text_response angegeben.
    • Maßnahme: Reagieren Sie darauf, indem Sie eine geeignete Meldung anzeigen, z. B. Ich kann diese Frage nicht beantworten oder Ich bin ein Shopping-Assistent. Wie kann ich Ihnen helfen?, wie im Design Ihrer Anwendung festgelegt.
  • BLOCKLISTED:
    • Es ist kein conversational_text_response verfügbar.
    • Aktion: Gemäß Ihrer Blockierungsrichtlinie vorgehen, in der Regel durch Anzeigen einer allgemeinen Meldung wie Diese Anfrage kann nicht ausgeführt werden.

Kategorie 2 Support- und Informationsanfragen

Für diese Typen wird von der API standardmäßig kein direkter conversational_text_response bereitgestellt. Sie haben jedoch die Möglichkeit, auf die richtigen Links oder Ressourcen zu verweisen.

  • ORDER_SUPPORT:
    • Standardaktion: Es wird kein conversational_text_response bereitgestellt. In Ihrer Weboberfläche muss eine Standardmeldung mit relevanten Links angezeigt oder die Anfrage an Ihre eigene Support-API oder Ihren Kundenservice weitergeleitet werden.
  • DEALS_AND_COUPONS:
    • Standardaktion: Es wird kein conversational_text_response bereitgestellt. Ihre Weboberfläche muss eine Standardmitteilung, relevante Links oder eine Umleitung der Anfrage an Ihr Angebots- oder Promotionsystem anzeigen.
  • STORE_RELEVANT:
    • Standardaktion: Es wird kein conversational_text_response bereitgestellt. Ihre Weboberfläche muss eine Standardmeldung, relevante Links oder eine Umleitung der Anfrage an Ihre eigene Filialsuche oder Ihr eigenes Informationssystem anzeigen.
  • RETAIL_SUPPORT:
    • Standardaktion: Es wird kein conversational_text_response bereitgestellt. Ihre Weboberfläche muss eine Standardmeldung, relevante Links oder eine Umleitung der Anfrage zu Ihrem eigenen System mit häufig gestellten Fragen und Informationen anzeigen.

Kategorie 3. Schlüsselwortsuchen, für die keine LLM-Antworten erforderlich sind

  • SIMPLE_PRODUCT_SEARCH:
    • Es wird keine Konversationsantwort generiert.
    • Aktion: Die API-Antwort gibt immer eine einzelne refined_search-Anfrage zurück. Diese verfeinerte Anfrage dient als vorgeschlagener Suchbegriff. Rufen Sie die Search API (SearchService.Search) direkt auf und rufen Sie relevante Produktergebnisse entweder mit der ursprünglichen Anfrage oder mit der refined_search-Anfrage ab. Die refined_search.query stammt möglicherweise nicht direkt aus der aktuellen Eingabe des Endnutzers, sondern kann auch aus dem Kontext des Chatverlaufs abgeleitet werden. Wenn ein Endnutzer beispielsweise zuvor Partykleid in rote geändert hat,kann die verfeinerte Anfrage rotes Partykleid lauten.
      • Für dialogorientierte Benutzeroberflächen (z. B. Chatbots): Es wird dringend empfohlen, die von der API bereitgestellte refined_search.query zu verwenden. In einem Konversationsablauf werden Anfragen in natürlicher Sprache wie „Kannst du mir helfen, Bananen zu finden?“ automatisch von der API in einen präzisen Produkt-Suchbegriff („Bananen“) optimiert, was zu relevanteren Produktergebnissen führt.
      • Für die wichtigsten Suchfunktionen (z. B. die Suchergebnisseite): Sie können entweder die refined_search.query aus der API oder die vom Endnutzer bereitgestellte Originalanfrage verwenden, da die Originalanfrage mit größerer Wahrscheinlichkeit bereits ein präziser Produktsuchbegriff ist. Wählen Sie die Option aus, die am besten zu Ihrer Weboberfläche und Ihrer Strategie für die Anzeige von Suchergebnissen passt.
    • Optionen für die Nutzerfreundlichkeit: Die Unterhaltung muss bei SIMPLE_PRODUCT_SEARCH-Anfragen nicht beendet werden. Ihr Nutzer kann die Unterhaltung fortsetzen, indem er die conversation_id in nachfolgenden Anfragen übergibt.
      • Option A: Konversationsbasierte Weboberfläche beenden: Viele Einzelhändler leiten den Nutzer nach Erkennung von SIMPLE_PRODUCT_SEARCH auf eine Standard-Suchergebnisseite weiter und schließen so das Chatfenster. Wenn der Endnutzer in diesem Szenario dann eine neue Anfrage in das Standard-Suchfeld eingibt, ohne das vorherige conversation_id, wird dies als neue, separate Konversation behandelt und ein neues conversation_id wird ausgegeben.
      • Option B: Konversationsoberfläche im Web fortsetzen: Einzelhändler können das Chatfenster geöffnet lassen. So kann der Nutzer wieder in den Konversationsmodus wechseln. Die Entscheidung, ob Option A oder B implementiert werden soll, hängt ganz von der bevorzugten Nutzerfreundlichkeit des Einzelhändlers ab.

    Damit Suchanfragen dialogorientierten Interaktionen korrekt zugeordnet werden und Sie alle Analysefunktionen in AI Commerce Search nutzen können, ist eine korrekte Ereignis-Tagging-Implementierung unerlässlich:

    1. conversation_id abrufen: Wenn Sie einen conversationalSearch API-Aufruf ausführen, wird ConversationalSearchResponse.conversation_id zurückgegeben.
    2. Nutzerereignisse taggen Wenn die Antwort im Konversationsstil zu einer Suchanfrage führt, z. B. wenn Ihr System automatisch eine Suche basierend auf der verfeinerten Anfrage für SIMPLE_PRODUCT_SEARCH ausführt, müssen Sie dieses nachfolgende Nutzerereignis für die Suche (UserEvent) mit derselben conversation_id taggen, die in der ConversationalSearchResponse empfangen wurde.

Wenn Sie UserEvent.conversation_id richtig taggen, können Suchanfragen in Ihren Analysen den vorherigen dialogorientierten Interaktionen korrekt zugeordnet werden. So erhalten Sie wertvolle Einblicke in das Nutzerverhalten und die Conversion-Pfade.

Kategorie 4. LLM-Anfragen zur Suche nach Antworten

Für diese Abfragetypen generiert die API eine conversational_text_response (LLM-Antwort) und stellt möglicherweise auch eine oder mehrere refined_search-Anfragen bereit. Die Unterhaltung wird nicht beendet und der Endnutzer kann sie fortsetzen.

  • PRODUCT_DETAILS:
    • Aktion: conversational_text_response liefert die angeforderten Produktdetails. Diese Informationen sollten dem Nutzer in Ihrem System deutlich angezeigt werden.
    • Die Antwort enthält auch refined_search (ein oder mehrere vorgeschlagene Suchanfragen, sortiert und gerankt), die zum Abrufen von Suchergebnissen über die Core Search API verwendet werden sollten.
  • PRODUCT_COMPARISON:
    • Aktion: Das conversational_text_response bietet einen Vergleich der angegebenen Produkte. Diese Informationen sollten dem Nutzer in Ihrem System deutlich angezeigt werden.
    • Die Antwort enthält refined_search (ein oder mehrere vorgeschlagene Suchanfragen, sortiert und gerankt), die zum Abrufen von Suchergebnissen über die Core Search API verwendet werden sollten.
  • BEST_PRODUCT:
    • Aktion: conversational_text_response gibt Empfehlungen oder Informationen zu Produkten, die am besten zur Suchanfrage passen. Diese Informationen sollten in Ihrem System angezeigt werden.
    • Die Antwort enthält refined_search (ein oder mehrere vorgeschlagene Suchanfragen, sortiert und gerankt), die zum Abrufen von Suchergebnissen über die Core Search API verwendet werden sollten.

Kategorie 5. Intent-Optimierung

  • INTENT_REFINEMENT:
    • Aktion: Die Antwort enthält conversational_text_response, ein followup_question und refined_search (eine oder mehrere vorgeschlagene Suchanfragen). Die empfohlene Reihenfolge für die Anzeige ist:
      1. conversational_text_response
      2. refined_search-Vorschläge: Diese werden sortiert und gerankt. Es ist daher wichtig, sie in derselben Reihenfolge wie in der Antwort anzuzeigen.
      3. Followup_question
    • Die Antwort enthält refined_search (ein oder mehrere vorgeschlagene Suchanfragen, sortiert und gerankt), die zum Abrufen von Suchergebnissen über die Core Search API verwendet werden sollten.
    • Senden Sie bei nachfolgenden Interaktionen die Antwort des Nutzers zusammen mit dem conversation_id.

Vorgeschlagene Anfragen für Produkte anzeigen

So konfigurieren Sie die Google Suche, damit Fragen und Produktvorschläge in der konversationellen Suche angezeigt werden.

Wenn die Conversational API refinedSearch-Anfragen zurückgibt, bieten diese Anfragen eine hervorragende Möglichkeit, den Endnutzer auf relevante Produkte hinzuweisen. Das ist besonders wertvoll für Kategorie 4 (LLM-Anfragen zur Suche nach Antworten) und Kategorie 5 (INTENT_REFINEMENT).

Empfehlung

  • Anzeigen: Zeigen Sie dem Nutzer die N (1–3, je nach Tests zur Ermittlung der idealen Anzahl für Ihre Weboberfläche) refinedSearch häufigsten Suchanfragen an.
  • Mechanismus: Diese vorgeschlagenen Suchanfragen sollten im Hintergrund oder bei Nutzerinteraktion über die Core Search API (SearchService.Search) ausgeführt werden.
  • Präsentation: Die Ergebnisse werden als interaktive Karussells oder anklickbare Karten angezeigt, sodass Nutzer verwandte Produktkategorien oder bestimmte Artikel durchsuchen können. Das bietet sofortigen Mehrwert und schließt die Lücke zwischen Konversationsinteraktion und Produktentdeckung.

Search API-Anfrage:

Weiterführende Anfrage

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}

Ereignisse, die an AI Commerce Search gesendet werden

Es ist wichtig, Suchanfragen dialogbasierten Interaktionen korrekt zuzuordnen und die vollständigen Analysefunktionen in der KI-basierten Suche für den Handel mithilfe des richtigen Ereignis-Tagging zu nutzen:

  1. conversation_id abrufen: Wenn Sie einen conversationalSearch API-Aufruf ausführen, wird ConversationalSearchResponse.conversation_id zurückgegeben.
  2. Nutzerereignisse taggen Wenn die Antwort im Dialog zu einer Suchanfrage führt, z. B. durch die Anzeige eines refined_search-Vorschlags, auf den der Endnutzer klickt, oder wenn Ihr System automatisch eine Suche basierend auf der verfeinerten Anfrage ausführt, müssen Sie dieses nachfolgende Nutzerereignis für die Suche (UserEvent) mit demselben conversation_id taggen, das im ConversationalSearchResponse empfangen wurde.

Wenn Sie UserEvent.conversation_id richtig taggen, können Suchanfragen in Ihren Analysen den vorherigen dialogorientierten Interaktionen korrekt zugeordnet werden. So erhalten Sie wertvolle Einblicke in das Nutzerverhalten und die Conversion-Pfade.

Unterhaltung fortsetzen

In diesem Abschnitt wird beschrieben, wie Sitzungen für die konversationelle Suche von der Conversational API verwaltet werden und wie sie in diesem letzten Schritt fortgesetzt werden.

Die Conversational API verwendet eine conversation_id, um laufende Unterhaltungen zu verwalten. Damit die LLM-Antworten und Suchergebnisse übereinstimmen, müssen nachfolgende Conversational API-Anfragen SearchParams enthalten, die der Konfiguration der wichtigsten Search API-Aufrufe entsprechen.

Sitzungsverwaltung

  • So starten Sie eine neue Unterhaltung:
    • Beschreibung: Wenn der Client eine neue Unterhaltung beginnen möchte, lässt er das conversationId in der API-Anfrage weg.
    • Wann sollte eine neue Unterhaltung begonnen werden? Ein Client möchte in mehreren gängigen Szenarien eine neue Unterhaltung beginnen und so eine neue conversationId aus der API-Antwort erhalten:
      • Neuer Tab oder neue Sitzung: Wenn ein Kunde Ihre Website in einem neuen Browsertab öffnet oder eine völlig neue Sitzung startet.
      • Neue Originalanfrage: Wenn ein Kunde in einigen UX-Designs eine neue, nicht verwandte Anfrage eingibt, können Sie den Konversationsfluss neu starten, um den relevantesten Kontext zu gewährleisten.
      • Schaltfläche „Unterhaltung neu starten“: Wenn Ihre Weboberfläche eine explizite Schaltfläche Neuen Chat starten oder Unterhaltung zurücksetzen bietet, wird durch Klicken darauf eine neue Unterhaltungssitzung ausgelöst.
    • Integration der Conversational API: Die API-Antwort enthält eine neue conversationId, die für nachfolgende Anfragen verwendet wird.
  • Unterhaltung fortsetzen:
    • Beschreibung: Die Conversational API gibt als Teil der API-Antwort ein conversation_id zurück. Diese ID muss in Folgeanfragen gesendet werden, um dieselbe Unterhaltung fortzusetzen. So wird sichergestellt, dass die konversationelle Suche auf die Anfragen Ihrer Nutzer basierend auf dem Unterhaltungsverlauf in dieser Sitzung reagiert und dabei den Endnutzer query, die conversational_text_response und die followup_question berücksichtigt.
    • Integration der Conversational API: Der Client übergibt die conversation_id aus der vorherigen Antwort in der ConversationalSearchRequest.
  • Konsistenz der Suchergebnisse sicherstellen:
    • Beschreibung: Damit die LLM-Antworten mit den Suchergebnissen übereinstimmen, die dem Nutzer angezeigt werden, muss der Client searchParams in der Conversational API-Anfrage verwenden. Diese Suchparameter sollten dieselbe Konfiguration (z. B. Filter, Sortierreihenfolge) wie die Search API-Aufrufe zum Abrufen von Produktergebnissen haben.
    • Integration der Conversational API: Das searchParams-Objekt innerhalb von ConversationalSearchRequest sollte identisch mit dem SearchRequest sein, das für die Suche nach Kernprodukten verwendet wird.

Anfrage an AI Commerce Search senden

Sie können die conversation_id aus dem Sitzungsspeicher abrufen. Die Anfrage sollte die neue Kunden-query enthalten, die möglicherweise eine Antwort auf die Frage aus der vorherigen Antwort ist. Die Anfrage sollte auch die letzte refined_search.query aus der vorherigen Antwort enthalten, wenn der Endnutzer auf eine verfeinerte Anfrage reagiert. Andernfalls sollte sie eine völlig neue und unabhängige Anfrage sowie die conversationId enthalten. Denken Sie daran, immer einheitliche searchParams zu verwenden.

  • Szenario 1: Einzelne Suchleiste und fortlaufende Konversation: Wenn Ihre Suchoberfläche nur eine Hauptsuchleiste oder ein fortlaufendes Konversationsfenster hat, wird der conversationId nicht zurückgesetzt, auch wenn der Endnutzer eine neue, scheinbar nicht zusammenhängende Anfrage eingibt. Das System verwendet den vorhandenen Unterhaltungsverlauf (der mit der conversationId verknüpft ist), um kontextbezogene Antworten zu geben.
  • Szenario 2: Separates Unterhaltungsfenster und Abfragefenster: Wenn Ihre Suchoberfläche ein separates Unterhaltungsfenster und eine separate, standardmäßige Suchleiste (z. B. ein websiteweites Suchfeld) bietet, kann die Eingabe einer neuen Anfrage in die standardmäßige Suchleiste implizit darauf hindeuten, dass eine neue, unabhängige Suche gestartet werden soll. Dies kann dazu führen, dass die conversationId für diese bestimmte Suchaktion zurückgesetzt wird. Im entsprechenden Unterhaltungsfenster sollte die conversationId jedoch immer beibehalten werden, um die Kontinuität zu wahren.

Letztendlich ist die Entscheidung, wann der conversationId wiederverwendet oder zurückgesetzt wird, eine Designentscheidung, um das Gesprächserlebnis für Ihre Kunden zu optimieren.

HTTP-Methode und ‑Endpunkt (wie bei der ursprünglichen Anfrage)

POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Conversational API-Anfrage:

Weiterführende Anfrage

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}

Antwort der Conversational API:

Folgeantwort

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Beispiele dafür, dass ein Endnutzer weiterhin Fragen erhält:

  • Nutzerfrage: Hilf mir bei der Planung einer Party.
  • Antwort des Systems: Welche Art von Party planst du?
  • Antwort des Nutzers: Eine Geburtstagsfeier.

Was Einzelhändler mit der Antwort tun sollten

Die Felder werden ähnlich wie in der ursprünglichen Antwort gerendert. Beachten Sie jedoch die Änderungen, die sich aus der fortgesetzten Unterhaltung ergeben:

  • refined_search: Dieses Feld enthält aktualisierte Anfragen, in die die letzten Eingaben des Endnutzers einbezogen wurden. Sie sollten die Clientkonsole für die aktuelle Anfrage entsprechend aktualisieren, z. B. indem Sie die für Nutzer sichtbare Anfrage von „Dekorationen“ in „Dekorationen für Geburtstagsfeiern“ oder „Zubehör für Geburtstagsfeiern“ ändern. Die verfeinerten Suchanfragen können für Aufrufe der Core Search API (SearchService.Search) verwendet oder dem Endnutzer als Vorschläge angezeigt werden.
  • conversational_text_response: Zeigt die neue KI-generierte Textantwort an, die für den letzten Turn relevant ist.
  • followup_question: Wenn die Unterhaltung zur weiteren Optimierung fortgesetzt werden muss, wird ein neues followup_question bereitgestellt.

Ereignisse, die an AI Commerce Search gesendet werden müssen

Das Tagging von Ereignissen ist wichtig, um Suchanfragen Conversational-Interaktionen genau zuzuordnen und die Analysefunktionen in Agent Search für den Handel zu nutzen.

Das Tagging von Ereignissen erfolgt in zwei Schritten:

  1. conversation_id abrufen: Wenn Sie einen conversationalSearch API-Aufruf ausführen, wird ConversationalSearchResponse.conversation_id zurückgegeben.

  2. Nutzerereignisse taggen Wenn die Antwort im Dialog zu einer Suchanfrage führt, z. B. durch die Anzeige eines refined_search-Vorschlags, oder wenn Ihr System automatisch eine Suche basierend auf der verfeinerten Anfrage ausführt, müssen Sie dieses nachfolgende Nutzerereignis für die Suche (UserEvent) mit demselben onversation_id taggen, das im ConversationalSearchResponse empfangen wurde.

Wenn Sie UserEvent.conversation_id richtig taggen, können Suchanfragen in Ihren Analysen den vorherigen dialogorientierten Interaktionen korrekt zugeordnet werden. So erhalten Sie wertvolle Einblicke in das Nutzerverhalten und die Conversion-Pfade.

Agent in die konversationelle Produktfilterung einbinden

In dieser Anleitung wird beschrieben, wie Sie die Conversational API und die konversationelle Produktfilterung einbinden, um ein KI-gestütztes Einkaufserlebnis zu bieten. Wenn conversationalFilteringSpec.mode auf ENABLED gesetzt ist, kann Ihr System direkt zwischen offenen Konversationsinteraktionen und geführter Produktfilterung wechseln. So wird ein sehr optimierter Conversion-Pfad ermöglicht.

Zusammenhang verstehen

Wenn sowohl die konversationelle Suche als auch die konversationelle Produktfilterung aktiviert sind, nutzt das System die Stärken beider Funktionen. Die dialogbasierte Suche verarbeitet allgemeine Anfragen, liefert KI-generierte Antworten und verfeinert ursprüngliche Intentionen. Die dialogbasierte Produktfilterung führt Nutzer durch die Auswahl bestimmter Produktattribute mithilfe eines vereinfachten chip- oder kachelbasierten Interaktionsmodells.

Der Interaktionspunkt und der potenzielle Übergang zwischen diesen beiden Modi treten auf, wenn die Klassifizierung der Conversational Commerce API zu einer produktorientierten Suche führt, insbesondere SIMPLE_PRODUCT_SEARCH. An diesem Punkt kann die API entweder eine direkte Suchanfrage bereitstellen oder, wenn die Absicht des Nutzers weiter verfeinert werden kann, einen geführten Filtervorgang durch dialogbasierte Produktfilterung auslösen.

Ein wichtiger Grundsatz dieser Integration ist, dass alle Freitext-Eingaben von der Conversational Commerce API verarbeitet werden, während Klicks auf vorgeschlagene Antworten, die als Chips angezeigt werden, von der Konversationsproduktfilterung verarbeitet werden.

Nutzeranfrage senden

Beispiel für Nutzereingabe: Hilf mir bei der Planung einer Party.

Wenn Sie sowohl die konversationelle Suche als auch die dialogbasierte Produktfilterung aktivieren möchten, muss Ihre ConversationalSearchRequest diese Konfiguration enthalten:

Conversational Commerce API-Anfrage – Erste Anfrage

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

Die wichtigsten Konfigurationen sind:

  • Conversational_filtering_mode: ENABLED: Wenn Sie dieses Feld in Ihrem conversationalFilteringSpec auf ENABLED setzen, wird der API mitgeteilt, dass Ihr System die konversationelle Produktfilterung verarbeiten kann. So kann die API relevante filterungsspezifische Antworten liefern.

Erste Antwort: Intention verfeinern

Das Feld userQueryTypes ist weiterhin von zentraler Bedeutung, um die Nutzerabsicht zu verstehen. Bei einer ersten allgemeinen Anfrage wie Hilf mir, eine Party zu planen wird die API sie wahrscheinlich als INTENT_REFINEMENT klassifizieren, wenn keine genauere Produktsuche sofort ersichtlich ist.

Antwort von Google

Antwort der Conversational Commerce API – Erste Anfrage

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}

Aktion

  1. Zeigen Sie die conversationalTextResponse an.
  2. Präsentiere die refinedSearch-Vorschläge als anklickbare Chips für Dekorationen, Snacks. Alternativ können Sie die Commerce Search API parallel mit den refined_search-Anfragen aufrufen, um relevante Produktergebnisse wie Dekorationen, Snacks als Karussell neben dem Konversationsaustausch anzuzeigen.
  3. Zeige die followupQuestion an: Welche Art von Party planst du?
  4. Freiform-Nutzereingaben zulassen, um die Unterhaltung fortzusetzen.

Ereignis-Tagging und ‑Analyse

So sorgen Sie für genaue Analysen und Attributionen für die erste Unterhaltung:

  • conversation_id abrufen: Erfassen Sie die conversation_id aus dem ConversationalSearchResponse. Diese ID ist wichtig, um alle nachfolgenden Aktionen mit dieser bestimmten Konversationssitzung zu verknüpfen.
  • Nutzerereignisse taggen Wenn die Antwort im Konversationsstil zu einer Suchanfrage führt, z. B. wenn Ihr System automatisch eine Suche basierend auf einer refined_search-Anfrage ausführt oder wenn der Nutzer auf einen refined_search-Vorschlag klickt, müssen Sie dieses nachfolgende Nutzerereignis für die Suche (UserEvent) mit derselben conversation_id kennzeichnen.

Weiterführende Anfrage

Wenn der Nutzer auf followupQuestion antwortet, wird die Unterhaltung verfeinert.

Beispiel für Nutzereingabe: Eine Geburtstagsfeier

Absichtsverfeinerung | Code-Snippets

Conversational Commerce API-Anfrage – Folgeanfrage

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Antwort der Conversational Commerce API – Folgeanfrage

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Aktion

  1. Aktualisieren Sie die Weboberfläche mit den neuen conversationalTextResponse, refinedSearch-Vorschlägen und followupQuestion.
  2. Setzen Sie die Unterhaltung fort und fordern Sie weitere Details an.

Ereignis-Tagging und ‑Analyse

Wenn der Nutzer die Unterhaltung fortsetzt:

  • conversation_id abrufen: Achten Sie darauf, dass die conversation_id aus dem vorherigen ConversationalSearchResponse im aktuellen ConversationalSearchRequest übergeben wird.
  • Nutzerereignisse taggen Wenn die Antwort im Dialog zu einer neuen Suchanfrage führt, z. B. weil ein Nutzer auf einen refined_search-Vorschlag klickt oder Ihr System einen parallelen Suchaufruf ausführt, taggen Sie das nachfolgende Nutzerereignis für die Suche (UserEvent) mit derselben conversation_id. So lässt sich der Verlauf von Unterhaltungen über mehrere Runden nachvollziehen.

Umstellung auf die dialogbasierte Produktfilterung

Wenn die Unterhaltung spezifischer wird, kann das System den Intent als SIMPLE_PRODUCT_SEARCH klassifizieren und gegebenenfalls die konversationelle Produktfilterung auslösen.

Beispiel für Nutzereingabe: Prinzessinnen-Thema

Conversational Commerce API-Anfrage – Folgeanfrage

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Wenn eine Anfrage als SIMPLE_PRODUCT_SEARCH klassifiziert wird, gibt es zwei mögliche API-Antworten, je nachdem, ob die Konversationsbasierte Produktfilterung ausgelöst wird. Der Hauptunterschied liegt im Vorhandensein und Inhalt des Felds conversationalFilteringResult.

Ergebnis 1: Filterung wird ausgelöst

Dies tritt auf, wenn die Anfrage so allgemein ist, dass sie durch Produktattribute weiter verfeinert werden kann. Die Antwort enthält conversationalFilteringResult, die von Ihrer Weboberfläche priorisiert werden sollte.

Conversational Commerce API-Antwort – Umstellung auf Produktfilterung: 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Balloons"
        }
      },
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Streamers"
        }
      },
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Tablecloths"
        }
      }
    ]
  },
  "state": "SUCCEEDED"
}

Aktion

Die Anfrage wurde jetzt als SIMPLE_PRODUCT_SEARCH klassifiziert. In diesem Fall wird die dialogbasierte Produktfilterung ausgelöst. Es kann jedoch sein, dass die dialogbasierte Produktfilterung nicht ausgelöst wird.

  • Weboberfläche für die konversationelle Produktfilterung priorisieren:Wenn conversationalFilteringResult ausgefüllt ist, bedeutet das, dass Sie den Produktfiltermodus aufgerufen haben. Auf Ihrer Weboberfläche sollte der Schwerpunkt auf followupQuestion liegen, der auf der Benutzeroberfläche als Welche Art von Prinzessinnendekoration suchen Sie? angezeigt wird, und auf suggestedAnswers, z. B. als anklickbare Schaltflächen für Luftballons, Luftschlangen, Tischdecken.
  • Produkt-Suchergebnisse anzeigen: Rufen Sie die AI Commerce Search API sofort mit refined_search.query (Prinzessinnen-Geburtstagsdekoration) auf, um erste Produkt-Suchergebnisse zusammen mit den Filteroptionen anzuzeigen.
  • Empfohlene Vorgehensweise für die Nutzerfreundlichkeit: Es sollte ein einzelnes, dauerhaft sichtbares Freitext-Eingabefeld für die gesamte Interaktion geben. Diese Leiste bleibt immer aktiv, auch während eines dialogbasierten Produktfilterungsvorgangs. Wenn conversationalFilteringResult aktiv ist und Sie Antwortvorschläge als anklickbare Chips anzeigen, haben Nutzer zwei klare Optionen:
    • Setzen Sie den Filtervorgang fort, indem Sie auf eine vorgeschlagene Antwort klicken.
    • Neuen Gesprächsabschnitt starten: Geben Sie eine neue Anfrage in die aktive Textleiste ein. Diese neue Eingabe löst immer einen neuen Aufruf der Conversational Commerce API aus, wodurch der aktuelle Filtervorgang beendet wird.

Ergebnis 2: Es wird kein Filter ausgelöst

Wenn die Anfrage bereits spezifisch genug ist oder sich nicht für eine weitere Filterung eignet, enthält die Antwort nicht das Feld conversationalFilteringResult. In diesem Fall sollten Sie mit einer Standardsuche fortfahren.

Aktion

  • Behandeln Sie die Interaktion als Ende des Unterhaltungsablaufs und rufen Sie mit der refined_search-Abfrage die Retail Search API auf, um eine Standardseite mit Produktergebnissen anzuzeigen.

Ereignis-Tagging und ‑Analyse

Wenn die Unterhaltung zur Produktfilterung übergeht:

  • conversation_id abrufen: Verwenden Sie weiterhin dieselbe conversation_id.
  • Nutzerereignisse taggen Wenn der Übergang zu einer sofortigen Suche führt, taggen Sie UserEvent mit conversation_id. Wichtig: Wenn der Nutzer mit dem suggestedAnswers interagiert, z. B. wenn ein Endnutzer auf Luftballons klickt, sollte diese Aktion auch einen UserEvent auslösen, z. B. ein filter-Ereignis oder ein neues search-Ereignis, das mit demselben conversation_id getaggt ist. So können Filteraktionen im Konversationsablauf zugeordnet werden.

Mit der dialogbasierten Produktfilterung fortfahren

Wenn der Nutzer ein suggestedAnswer auswählt, senden Sie ein neues ConversationalSearchRequest.

Beispiel für Nutzereingabe (Klicken auf eine vorgeschlagene Antwort): Luftballons

Einfache Produktsuche | Code-Snippets

Conversational Commerce API-Anfrage – Filterung fortsetzen 

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Antwort der Conversational Commerce API – Filterung fortsetzen 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

Aktion

Die API antwortet mit einer SIMPLE_PRODUCT_SEARCH-Abfrage, aber ohne das Feld conversationalFilteringResult. Das bedeutet, dass der Ablauf für das geführte Filtern abgeschlossen ist.

  • Verwenden Sie die endgültige refinedSearch-Anfrage (princess birthday balloons), um die AI Commerce Search API direkt aufzurufen.
  • Zeigen Sie dem Nutzer die Ergebnisse des Endprodukts an. An diesem Punkt kann die Unterhaltung entweder beendet werden oder der Nutzer kann eine neue Anfrage eingeben, um eine neue Runde zu starten.

Ereignis-Tagging und ‑Analyse

Für jeden Schritt im Produktfilterprozess:

  • conversation_id abrufen: Verwenden Sie immer denselben conversation_id für alle Anfragen innerhalb der Filtersitzung.
  • Nutzerereignisse taggen Jede Nutzerinteraktion mit einem suggestedAnswer, z. B. ein Klick, sollte ein relevantes UserEvent auslösen, z. B. ein filter-Ereignis oder ein neues search-Ereignis, wenn eine neue Anfrage erstellt wird. Diese UserEvent muss mit dem conversation_id getaggt werden, damit der Filtervorgang und seine Auswirkungen auf die Conversion genau erfasst werden können.

Referenzarchitektur

Dies ist das Referenzarchitekturdesign für AI Commerce Search auf Google Cloud. In dieser Referenzarchitektur wird der Fluss von Daten und Diensten für eine konversationelle Suche dargestellt. Das Diagramm zeigt, wie Nutzerereignisse, Produktkatalogdaten und Betriebsprotokolle verarbeitet, transformiert und in einen generativen KI-Index und einen Retail Adapter-Dienst integriert werden, um Suchvorgänge zu verarbeiten und Nutzerabsichten zu erfüllen, um Suchergebnisse zurückzugeben. Die Architektur verbindet verschiedene Projekte, um eine umfassende KI-basierte Commerce Search-Funktionalität zu ermöglichen.

Commerce AI-Referenzarchitektur

Vorschaufunktionen: Agentenaufruf und Reasoning Engine

In dieser Vorabversion werden neue Funktionen eingeführt, mit denen die konversationelle Suche mit Agent-Workflows erweitert wird. Dabei wird die Reasoning Engine von Vertex AI für die Sitzungsverwaltung verwendet und die Integration mit externen Tools ermöglicht.

Informationen zum Aktivieren von Vorschaufunktionen finden Sie unter Registrieren.

Neue Funktionen

  • Integration der Reasoning Engine:Nutzt Vertex AI konversationelle Suchmaschinen-Sitzungen, um persistente Sitzungen zu verwalten. So kann die konversationelle Suche den Kontext über mehrere Unterhaltungsrunden hinweg beibehalten, indem die Sitzungspersistenz von „Vertex AI Agent Engine“ verwendet wird.
  • Unterstützung von MCP-Tools:Es wird Unterstützung für das Aufrufen von MCP-Tools (Model Context Protocol) hinzugefügt. Dadurch kann die konversationelle Suche Informationen aus externen Quellen abrufen und Aktionen ausführen, die über die standardmäßigen Funktionen der Einzelhandelssuche hinausgehen.

API-Änderungen

Die Nachrichten ConversationalSearchRequest und ConversationalSearchResponse wurden aktualisiert, um diese Funktionen zu unterstützen: Anfragefelder:

  • enableAgentInvocation (boolesch): Wenn „true“ festgelegt ist, wird der Workflow für den Aufruf der konversationellen Suche für die Anfrage aktiviert.
  • reasoningEngine (String): Der Ressourcenname der Reasoning Engine (konversationelle Suchmaschine), in der die konversationellen Suchsitzungen gehostet werden, formatiert als projects/*/locations/*/reasoningEngines/*.

Antwortfelder:

  • agentInvocations: Enthält Details zum Aufruf der konversationellen Suche, einschließlich Antworten von MCP-Tools.

Vorbereitung

Bevor Sie neue Funktionen verwenden können, müssen Sie die Voraussetzungen erfüllen.

Persistente Sitzungen einrichten

Wenn Sie persistente Sitzungen mit einer Reasoning Engine verwenden möchten, müssen Sie Ihr Projekt „Google Cloud“ so konfigurieren:

  1. Aktivieren Sie die Vertex AI API in Ihrem Projekt (weitere Informationen).
  2. IAM-Berechtigungen erteilen:Weisen Sie dem Dienstkonto cloud-ml-consumeragent-server@system.gserviceaccount.com die Rolle Vertex AI-Nutzer für Ihr Projekt zu.
  3. Agent-Engine erstellen:Sie müssen eine Reasoning Engine-Instanz erstellen, um Sitzungen zu verarbeiten. Sie können den Beispielen in der Vertex AI-Dokumentation folgen oder das folgende Python-Skript verwenden, um die Initialisierung durchzuführen.
import vertexai

from vertexai.preview import reasoning_engines

PROJECT_ID = "your-project-id"
LOCATION = "us-central1"
DISPLAY_NAME = "Session-Engine"
vertexai.init(project=PROJECT_ID, location=LOCATION)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
my_agent_engine_instance = client.agent_engines.create(
    config={
        "display_name": DISPLAY_NAME
    }
)

print(f"Successfully created Agent Engine: {my_agent_engine.resource_name}")

MCP-Tools einrichten

Sie können die konversationelle Suche mit Ihrer benutzerdefinierten Suche erweitern, indem Sie Ihren eigenen MCP-Server einrichten und die folgenden Details mit uns teilen:

  1. MCP-Serveradresse.
  2. Authentifizierungsmethode für den MCP-Server.
  3. Tool, das für die Suche zuständig ist.

Beispiel für die API-Nutzung

Das folgende Beispiel zeigt, wie die konversationelle Suche API mit aktivierter Aufrufung der konversationellen Suche aufgerufen wird. Wenn Sie eine Problemlösungs-Engine eingerichtet haben, geben Sie den Ressourcennamen an, um die Sitzung beizubehalten. 

{
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/default_catalog/branches/default_branch",
  "placement": "projects/{project_id}/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Help me plan a party",
  "visitorId": "your_visitor_id",
  "enableAgentInvocation": true,
  "reasoningEngine": "projects/{project_id}/locations/{location_id}/reasoningEngines/{reasoning_engine_id}"
}

SDKs für die private Vorschau

Greifen Sie hier auf die privaten SDKs für diese Funktionen zu: Google Drive link.

Wenn Sie keinen Zugriff auf den Ordner haben, fordern Sie ihn über Google Drive an.

Registrieren

Melden Sie sich über das Formular für den Vorabzugriff für die Funktion an.

Nächste Schritte

Weitere Supportressourcen finden Sie in den Antworten auf Fragen zu Unterhaltungsfunktionen.