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 dem Conversational Commerce-Agent und der konversationellen Produktfilterung.
Einrichtung
Die Conversational API unterstützt die Agent-Funktion für Conversational Commerce:
- gRPC:
conversationalSearchService
- REST:
conversationalSearch
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 so 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 alte Retail API parallel zur Conversational API aufgerufen werden.
Anfrage vom Endnutzer senden
In diesem Abschnitt wird beschrieben, wie Sie eine Conversational Commerce-Agent-Erfahrung starten. Ein Nutzer gibt beispielsweise Hilf mir, eine Party zu planen in das Suchfeld ein.
Anfrage an Vertex AI Search for Commerce senden
Es gibt zwei verschiedene API-Endpunkte:
- Die Conversational API muss verwendet werden, um die Konversationsfunktion abzurufen.
- Die Search API muss verwendet werden, um Suchergebnisse abzurufen.
Endpunkt 1: Conversational API-Anfrage
- Sie sollten eine Anfrage für einen Conversational Commerce-Agent 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/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
Konversationelle API-Anfrage:
Ausgangsanfrage
{ "query": "Help me plan a party", "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch", "placement": "projects/799252947591/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 unbearbeitete 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, wirddefault_branch
verwendet. Dies ist ein Pflichtfeld. -
visitorId
: Eine eindeutige Kennung für das Tracking von Besuchern. Dies ist ein Pflichtfeld. -
conversationId
: Eine eindeutige ID zum Nachverfolgen 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 denconversation_id
-Wert gesetzt werden, der in der vorherigenConversationalSearchResponse
empfangen wurde. -
searchParams
: (Optional) Standardparameter für die Kernsuche (z.B.filter
,canonicalFilter
,sortBy
,boostSpec
). Es ist wichtig, dass diese Parameter der Konfiguration in Ihren Haupt-Search API-Aufrufen entsprechen, um die Konsistenz zwischen LLM-Antworten und angezeigten Produktsuchergebnissen zu gewährleisten. -
userInfo
: (Optional) Nutzerinformationen für eine verbesserte Personalisierung. KannuserId
,user_agent
,direct_user_request
(boolescher Wert) enthalten. -
conversationalFilteringSpec
: (Optional) Gibt den Konversationsfiltermodus an. Wenn nicht festgelegt, wird standardmäßig DISABLED verwendet.mode
: Integrieren Sie die Conversational API in einem der drei Modi, um die Filterung von Conversational-Produkten zu steuern: DISABLED
: In diesem Modus implementiert der Client nur die Suche nach Conversational Commerce-Agenten. Dies ist der bevorzugte Modus für dieses Implementierungshandbuch zur Suche nach Conversational Commerce-Agents.ENABLED
: In diesem Modus implementiert der Client alle Unterhaltungsfunktionen, einschließlich der Suche nach Conversational Commerce-Agents und der Filterung von Produkten in Unterhaltungen.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 dem Nutzer nur ein dialogorientierter Produktfilter angezeigt, ohne dass eine LLM-Antwort, eine Anfrageklassifizierung oder vorgeschlagene Suchanfragen generiert werden.
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" }
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" } } } }
Weitere Informationen finden Sie im Entwicklerhandbuch für konversationelle Produktfilter. Weitere Informationen zur Integration der beiden Konversationsprodukte finden Sie in der zusätzlichen Anleitung.
Endpunkt 2: Core Search API-Anfrage
Es gibt zwei primäre Ansätze zum Anzeigen von Suchergebnissen in Ihrer Benutzeroberfläche:
Option 1: Suchergebnisse immer anzeigen
Wenn in Ihrem UX-Design festgelegt ist, dass Suchergebnisse immer angezeigt werden sollen, unabhängig von der Ausgabe des Konversationsmodells, 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 Product Search 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 Core Product Search 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 Retail API aufrufen, wenn Sie tatsächliche Produktergebnisse abrufen möchten. Weitere Informationen finden Sie unter Schritt 2c. Informationen zu Anfragetypen und Händleraktionen
HTTP-Methode und Endpunkt
POST https://retail.googleapis.com/v2beta/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search
Core Product Search API-Anfrage:
Ausgangsanfrage
{ "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 Serving-Konfiguration für die Einzelhandelssuche oder des alten Placements. Beispiel:projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search
.query
: Erforderlich. Die Suchanfrage. Das kann die Roh-Eingabe des Nutzers sein, z. B. Hilf mir, eine Party zu planen, oder ein optimierterrefinedSearch.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 demvisitorId
ü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 Filtern 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 Vertex AI Search for Commerce
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 [Suchanfragetypen und Händleraktionen verstehen](#step-2c).conversation_id
: Sie können diese eindeutige ID im Browsersitzungsspeicher oder in einem ähnlichen clientseitigen Speicher speichern, um die Konversationssitzung 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 bestimmtesconversation_id
bei. Wenn Sie ein neuesconversation_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. BeiSIMPLE_PRODUCT_SEARCH
ist es immer eine einzelne Anfrage. Bei anderen Anfragen, bei denen eine LLM-Antwort gesucht wird, sind es ein oder mehrere. Dierefined_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 dem 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 Antwortgenerierung an (STREAMING
oderSUCCEEDED
). Sie können es für UI-Feedback verwenden, z. B. um eine Ladeanzeige bisSUCCEEDED
anzuzeigen. Weitere Informationen finden Sie unter Schritt 2b. Informationen zur Streaming API
Streaming API
Die Conversational Commerce API ist eine Streaming-API. Das bedeutet, dass Ihr Nutzer Teile der Antwort in mehreren Chunks anstelle einer einzelnen, vollständigen Nutzlast erhält.
Der erste Teil der Antwort enthält die Abfragen query_types
und refined_search
. Der state
-Wert ist STREAMING
. Durch die frühzeitige Erkennung der Intention und die sofortige Verfügbarkeit von Suchverfeinerungen kann Ihr Modell schnell entscheiden, wie die Anfrage des Nutzers behandelt werden soll und wie die Latenz bei LLM-Antworten für den Nutzer gehandhabt werden soll:
- Bei Abfragetypen, bei denen _keine_ Antwort in Form von Konversations-Text erwartet wird (z. B.
SIMPLE_PRODUCT_SEARCH
,RETAIL_IRRELEVANT
,BLOCKLISTED
,QUERY_TYPE_UNSPECIFIED
,ORDER_SUPPORT
,DEALS_AND_COUPONS
,STORE_RELEVANT
): Da sichquery_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 empfangenenrefined_search
-Anfrage sofort einen direkten Aufruf der Core Search API ausführen. So werden Suchergebnisse mit minimaler Verzögerung angezeigt und die SLAs für die typische Suchfunktion werden eingehalten. - Für Anfragetypen, bei denen keine Antwort in Form von Konversationstext erwartet wird (z. B.
INTENT_REFINEMENT
,PRODUCT_DETAILS
,PRODUCT_COMPARISON
,BEST_PRODUCT
) - Sie erhalten die
query_types
- undrefined_search
-Abfragen im ersten Chunk. Sie können mit diesenrefined_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 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.
Abfragetypen und Händleraktionen
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.
Der Conversational Commerce-Agent verwendet Suchanfragekategorien, um zu bestimmen, ob eine LLM-basierte Antwort generiert wird und wie Endnutzeranfragen in den folgenden Szenarien von den Conversational- und Search-APIs verarbeitet werden:
Kategorien | Abfrageklassifizierungen |
---|---|
1. Irrelevante Anfragen, die keine LLM-Antwort erfordern |
|
2. Support- und Informationsanfragen |
|
3. Keyword-Suchanfragen, für die kein LLM erforderlich ist Konversationelle API-Anfrage: Ausgangsanfrage { "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" } |
|
4. Anfragen, die auf LLM-Antworten abzielen Konversationelle API-Anfrage: Ausgangsanfrage { "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" } |
|
5. Zweck eingrenzen Konversationelle API-Anfrage: Ausgangsanfrage { "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" } |
|
Kategorie 1 Irrelevante Anfragen, für die keine LLM-Antwort erforderlich ist
-
QUERY_TYPE_UNSPECIFIED
: - Es ist kein
conversational_text_response
verfügbar. - Aktion: Als Standard- oder Fehlerfall behandeln. Sie können den Nutzer um eine Klarstellung bitten oder ihn an eine Stelle verweisen, an der er allgemeine Hilfe erhalten kann.
RETAIL_IRRELEVANT
:- Es ist kein
conversational_text_response
verfügbar. - Maßnahme: Reagieren Sie darauf mit einer angemessenen Meldung, 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 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
angegeben. Auf Ihrer Benutzeroberfläche muss eine Standardmeldung mit relevanten Links angezeigt werden oder die Anfrage muss an Ihre eigene Support-API oder Ihren Kundenservicekanal weitergeleitet werden. DEALS_AND_COUPONS
:- Standardaktion: Es wird kein
conversational_text_response
bereitgestellt. In der Benutzeroberfläche muss eine Standardmeldung, relevante Links oder eine Umleitung der Anfrage an Ihr Angebots- oder Promotionsystem angezeigt werden. STORE_RELEVANT
:- Standardaktion: Es wird kein
conversational_text_response
bereitgestellt. Auf Ihrer Benutzeroberfläche muss eine Standardmeldung mit relevanten Links angezeigt oder die Anfrage an Ihre eigene Standortsuche oder Ihr eigenes Informationssystem weitergeleitet werden. RETAIL_SUPPORT
:- Standardaktion: Es wird kein
conversational_text_response
bereitgestellt. In Ihrer Benutzeroberfläche muss eine Standardmitteilung mit relevanten Links angezeigt oder die Anfrage an Ihr eigenes System mit häufig gestellten Fragen und Informationen weitergeleitet werden.
Kategorie 3. Keyword-Suchanfragen, für die keine LLM-Antworten erforderlich sind
SIMPLE_PRODUCT_SEARCH
:- Es wird keine Antwort in Form von Konversationstext 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 derrefined_search
-Anfrage ab. Dierefined_search.query
muss nicht direkt aus der aktuellen Eingabe des Endnutzers stammen, 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 Produktsuchbegriff („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 Benutzeroberflä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 erconversation_id
in nachfolgenden Anfragen übergibt. - Option A: Konversationsoberfläche beenden: Viele Einzelhändler leiten Nutzer nach Erkennung eines
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 vorherigeconversation_id
, wird dies als neue, separate Konversation behandelt und ein neuesconversation_id
wird ausgegeben. - Option B: Chat-Benutzeroberfläche beibehalten: Einzelhändler können das Chatfenster geöffnet lassen. So kann der Nutzer wieder in den Unterhaltungsmodus wechseln. Die Entscheidung, ob Option A oder B implementiert werden soll, hängt ganz davon ab, welche Nutzerfreundlichkeit der Einzelhändler bevorzugt.
conversation_id
abrufen: Wenn Sie einenconversationalSearch
API-Aufruf ausführen, wirdConversationalSearchResponse.conversation_id
zurückgegeben.- Nutzerereignisse taggen: Wenn die Antwort im Dialog 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 Suchnutzerereignis (UserEvent
) mit derselbenconversation_id
taggen, die in derConversationalSearchResponse
empfangen wurde.
Damit Suchanfragen Conversational-Interaktionen korrekt zugeordnet werden und Sie alle Analysefunktionen in Vertex AI Search for Commerce nutzen können, ist eine korrekte Event-Kennzeichnung unerlässlich:
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, die auf Antworten abzielen
Bei diesen 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: Der
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 verwendet werden sollten, um Suchergebnisse mit der Core Search API abzurufen. PRODUCT_COMPARISON
:- Aktion: Der
conversational_text_response
vergleicht die 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 verwendet werden sollten, um Suchergebnisse mit der Core Search API abzurufen. BEST_PRODUCT
:- Aktion: Der
conversational_text_response
gibt Empfehlungen oder Informationen zu den „besten“ Produkten basierend auf der Anfrage. Diese Informationen sollten in Ihrem System angezeigt werden. - Die Antwort enthält
refined_search
(ein oder mehrere vorgeschlagene Suchanfragen, sortiert und gerankt), die verwendet werden sollten, um Suchergebnisse mit der Core Search API abzurufen.
Kategorie 5. Intent-Optimierung
INTENT_REFINEMENT
:- Aktion: Die Antwort enthält
conversational_text_response
, einfollowup_question
undrefined_search
(eine oder mehrere vorgeschlagene Suchanfragen). Die empfohlene Reihenfolge ist: conversational_text_response
refined_search
-Vorschläge: Diese werden sortiert und gerankt. Es ist daher wichtig, sie in derselben Reihenfolge wie in der Antwort anzuzeigen.Followup_question
- Die Antwort enthält
refined_search
(ein oder mehrere vorgeschlagene Suchanfragen, sortiert und gerankt), die verwendet werden sollten, um Suchergebnisse mit der Core Search API abzurufen. - 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 im Conversational Commerce-Agent 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 (Anfragen, bei denen nach LLM-Antworten gesucht wird) und Kategorie 5 (INTENT_REFINEMENT
).
Empfehlung
- Anzeigen: Zeigen Sie dem Nutzer die
N
(1–3, je nach Tests zur idealen Anzahl für Ihre Benutzeroberfläche)refinedSearch
-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 hilft, die Lücke zwischen Konversation und Produktentdeckung zu schließen.
Search API-Anfrage:
Weiterführende Anfrage
{ "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "Decorations", "visitorId": "test" }
Ereignisse, die an Vertex AI Search for Commerce gesendet werden
Es ist wichtig, Suchanfragen korrekt konversationellen Interaktionen zuzuordnen und die vollständigen Analysefunktionen in Vertex AI Search for Commerce mit dem richtigen Event-Tagging zu nutzen:
conversation_id
abrufen: Wenn Sie einenconversationalSearch
API-Aufruf ausführen, wirdConversationalSearchResponse.conversation_id
zurückgegeben.- 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 Suchnutzerereignis (UserEvent
) mit demselbenconversation_id
taggen, das in derConversationalSearchResponse
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 Conversational Commerce-Agentsitzungen von der Conversational API verwaltet werden und in diesem letzten Schritt fortgesetzt werden.
Die Conversational API verwendet eine conversation_id
, um laufende Unterhaltungen zu verwalten. Damit die Antworten des LLM und die 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
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 auf Ihrer Benutzeroberfläche eine explizite Schaltfläche „Neuen Chat starten“ oder „Unterhaltung zurücksetzen“ vorhanden ist, wird durch Klicken darauf eine neue Unterhaltungssitzung ausgelöst.
- Integration der Conversational API: Die API-Antwort enthält ein neues
conversationId
, das für nachfolgende Anfragen verwendet wird.
- Beschreibung: Wenn der Client eine neue Unterhaltung beginnen möchte, lässt er
- Unterhaltung fortsetzen:
- Beschreibung: Die
Conversational API
gibt als Teil der API-Antwort einconversation_id
zurück. Diese ID muss in Folgeanfragen gesendet werden, um dieselbe Unterhaltung fortzusetzen. So wird sichergestellt, dass der Conversational Commerce-Agent auf die Anfragen Ihres Nutzers basierend auf dem Unterhaltungsverlauf in dieser Sitzung antwortet und dabei den Endnutzerquery
, denconversational_text_response
und denfollowup_question
berücksichtigt. - Integration der Conversational API: Der Client übergibt die
conversation_id
aus der vorherigen Antwort in derConversationalSearchRequest
.
- Beschreibung: Die
- Für konsistente Suchergebnisse sorgen:
- Beschreibung: Damit die LLM-Antworten mit den Suchergebnissen übereinstimmen, die dem Nutzer angezeigt werden, muss der Client
searchParams
in derConversational API
-Anfrage verwenden. Diese Suchparameter sollten dieselbe Konfiguration wie dieSearch API
-Aufrufe zum Abrufen von Produktergebnissen haben, z. B. Filter und Sortierreihenfolge. - Integration der Conversational API: Das
searchParams
-Objekt innerhalb vonConversationalSearchRequest
sollte identisch mit demSearchRequest
sein, das für die Suche nach Kernprodukten verwendet wird.
- Beschreibung: Damit die LLM-Antworten mit den Suchergebnissen übereinstimmen, die dem Nutzer angezeigt werden, muss der Client
Anfrage an Vertex AI Search for Commerce 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 das 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 Unterhaltung: Wenn Ihre Suchoberfläche nur eine Hauptsuchleiste oder ein fortlaufendes Unterhaltungsfenster hat, wird
conversationId
nicht zurückgesetzt, auch wenn der Endnutzer eine neue, scheinbar nicht zusammenhängende Anfrage eingibt. Das System verwendet den vorhandenen Unterhaltungsverlauf (der mitconversationId
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 signalisieren, dass eine neue, unabhängige Suche gestartet werden soll. Dies kann dazu führen, dass der
conversationId
für diese bestimmte Suchaktion zurückgesetzt wird. Im entsprechenden Unterhaltungsfenster sollte dieconversationId
jedoch immer beibehalten werden, um die Kontinuität zu gewährleisten.
Letztendlich ist die Entscheidung, wann der conversationId
wiederverwendet oder zurückgesetzt wird, eine Designentscheidung, mit der die Konversationserfahrung für Ihre Kunden optimiert werden soll.
HTTP-Methode und Endpunkt (wie bei der ursprünglichen Anfrage)
POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
Konversationelle 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, eine Party zu planen
- 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 neuerfollowup_question
bereitgestellt.
Ereignisse, die an Vertex AI Search for Commerce gesendet werden
Das Tagging von Ereignissen ist wichtig, um Suchanfragen konversationellen Interaktionen korrekt zuzuordnen und die Analysefunktionen in Vertex AI Search for Commerce zu nutzen.
Das Tagging von Ereignissen erfolgt in zwei Schritten:
conversation_id
abrufen: Wenn Sie einenconversationalSearch
API-Aufruf ausführen, wirdConversationalSearchResponse.conversation_id
zurückgegeben.- 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 das nachfolgende Suchnutzerereignis (UserEvent
) mit demselbenconversation_id
taggen, das imConversationalSearchResponse
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 Verhalten von Endnutzern und in Conversion-Pfade.
Zusätzliche Hinweise und Best Practices
Bei der Implementierung der Benutzeroberfläche Ihres Conversational Commerce-Agents sind zusätzliche Überlegungen und Best Practices zu berücksichtigen:
- Konsistenz der Besucher-ID: Sorgen Sie dafür, dass für einen bestimmten Endnutzer bei jeder Anfrage eine eindeutige
visitor_id
gesendet wird. Das ist für eine genaue Personalisierung und das Modelltraining unerlässlich. Diese Kennung sollte idealerweise für einen Endnutzer über Sitzungen und An- oder Abmeldestatus hinweg konsistent bleiben. - Filialverwaltung:
default_branch
ist zwar üblich, aber Sie sollten die richtige Filial-ID verwenden, wenn Ihr Produktkatalog mehrere Filialen umfasst. - Search API-Interaktion: Denken Sie bei
SIMPLE_PRODUCT_SEARCH
und allen Fällen, in denenrefined_search
angegeben ist, daran, einen separaten Aufruf der Core Search API (SearchService.Search
) mit demquery
aus dem Feldrefined_search
oder der ursprünglichen Anfrage zu senden, um die tatsächlichen Produkteinträge abzurufen. Bei der Conversational API geht es in erster Linie um die Konversationsfunktion und das Verständnis der Nutzerabsicht und nicht darum, direkt Produktergebnisse zurückzugeben. - Design der Benutzeroberfläche: Gestalten Sie die Benutzeroberfläche so, dass die Optionen
conversational_text_response
,followup_question
undrefined_search
intuitiv präsentiert werden, um den Nutzer zu führen.
Nächste Schritte
Weitere Supportressourcen finden Sie in den FAQs zu konversationellen Funktionen.