Guida per gli sviluppatori di agenti di commercio conversazionale

Questa guida descrive in dettaglio come eseguire l'integrazione con l'API Conversational per fornire ai tuoi clienti esperienze di chat dinamiche basate sull'AI. Comprendendo i diversi tipi di query e sfruttando le risposte dell'API, puoi fornire ricerche di prodotti pertinenti, rispondere alle domande dei clienti e guidare gli utenti finali nel loro percorso di acquisto.

conversationalFilteringMode nell'API Conversazionale chiarisce le differenze tra l'agente di commercio conversazionale e il filtro conversazionale dei prodotti.

Configurazione

L'API Conversational supporta la funzionalità dell'agente di commercio conversazionale:

• gRPC: conversationalSearchService
• REST: conversationalSearch

L'API Conversational consente un'esperienza di chat in cui gli utenti inviano query e il sistema restituisce una risposta di testo, i tipi di query classificati e potenziali opzioni di ricerca perfezionate.

Questa API funziona come un servizio di streaming, consentendo il rilevamento anticipato dell'intento della query. Le interazioni successive nella conversazione richiedono l'allegato di un conversation_id.

Per restituire i risultati di ricerca, l'API Retail precedente deve essere chiamata in parallelo all'API Conversational.

Invia una query dall'utente finale

Questa sezione descrive come avviare un'esperienza di agente Conversational Commerce. Ad esempio, l'utente potrebbe inserire Aiutami a organizzare una festa nel campo di ricerca.

Invia una richiesta a Vertex AI Search for Commerce

Esistono due endpoint API diversi:

1. Per recuperare l'esperienza conversazionale, devi utilizzare l'API Conversazionale.
2. Per recuperare i risultati di ricerca, è necessario utilizzare l'API Search principale.

Endpoint 1: richiesta API conversazionale

• Devi creare una richiesta di agente di Conversational Commerce impostando l'input dell'utente come query.
• La richiesta deve essere inviata come richiesta HTTP POST all'endpoint projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Metodo HTTP ed endpoint

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

Richiesta API conversazionale:

Query iniziale

{
  "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: il nome risorsa del posizionamento (ad esempio projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Si tratta di un parametro di percorso obbligatorio.
• query: la query di ricerca non elaborata dell'utente. Questo campo è obbligatorio.
• branch: il nome della risorsa ramo, ad esempio projects/P/locations/L/catalogs/C/branches/B. Se non è impostato, viene utilizzato default_branch. Questo campo è obbligatorio.
• visitorId: un identificatore univoco per monitorare i visitatori. Questo campo è obbligatorio.
• conversationId: un ID univoco per monitorare le sessioni di conversazione. Per la richiesta iniziale in una nuova conversazione, questo campo deve essere vuoto. Per le richieste successive all'interno della stessa conversazione, deve essere impostato sul conversation_id ricevuto nel ConversationalSearchResponse precedente.
• searchParams: (facoltativo) Parametri di ricerca principali standard (ad es. filter, canonicalFilter, sortBy, boostSpec). È fondamentale che questi parametri riflettano la configurazione utilizzata nelle chiamate API Search principali per garantire la coerenza tra le risposte del LLM e i risultati di ricerca dei prodotti visualizzati.
• userInfo: (facoltativo) informazioni sull'utente per una personalizzazione avanzata. Può includere userId, user_agent, direct_user_request (booleano).
• conversationalFilteringSpec: (facoltativo) specifica la modalità di filtro conversazionale. Se non viene impostato, il valore predefinito è DISABLED.

  mode: integra l'API Conversational utilizzando una di queste tre modalità per controllare il filtro dei prodotti conversazionale:

• DISABLED: in questa modalità, il client implementa solo la ricerca di agenti di Conversational Commerce. Questa è la modalità preferita per questa guida all'implementazione della ricerca di agenti di Conversational Commerce.

Richiesta API di esempio

        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
        }
      

Esempio di risposta dell'API

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
      

• ENABLED: in questa modalità, il client implementa tutte le funzionalità conversazionali, inclusa la ricerca di agenti di Conversational Commerce e il filtro conversazionale dei prodotti.

Richiesta API di esempio

        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
        }
      

Esempio di risposta dell'API

        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: se selezionato, il cliente implementa il filtro dei prodotti conversazionale solo. Con questa modalità selezionata, l'utente sperimenta solo il filtro conversazionale dei prodotti senza generare una risposta LLM, una classificazione delle query o query di ricerca suggerite.

Per ulteriori informazioni, consulta la guida per gli sviluppatori del filtro dei prodotti conversazionale. Consulta la guida aggiuntiva su come integrare entrambi i prodotti conversazionali.

Endpoint 2: richiesta API Core Search

Esistono due approcci principali per visualizzare i risultati di ricerca nella tua UI:

• Opzione 1: mostra sempre i risultati di ricerca

  Se la progettazione dell'esperienza utente prevede che i risultati di ricerca vengano sempre visualizzati indipendentemente dall'output conversazionale, ad esempio in un'area dedicata ai risultati di ricerca accanto alla chat, invia la query originale dell'utente all'API Product Search principale con la chiamata all'API Conversational. In questo modo, le schede di prodotto sono immediatamente disponibili.

• Opzione 2: mostrare i risultati di ricerca in base all'output conversazionale

Se il design dell'esperienza utente è più dinamico e vuoi visualizzare i risultati di ricerca solo in base alla risposta dell'API Conversational, ad esempio solo per le query SIMPLE_PRODUCT_SEARCH o ogni volta che vengono forniti suggerimenti refined_search, attendi la risposta dell'API Conversational prima di inviare query all'API Product Search principale. Se è presente una risposta, utilizza la query refined_search fornita per recuperare i risultati dei prodotti.

Indipendentemente dall'opzione dell'interfaccia utente scelta, quando devi recuperare i risultati effettivi dei prodotti, puoi effettuare una chiamata all'API Retail. Per ulteriori informazioni, vedi Passaggio 2c. Comprendere i tipi di query e le azioni del rivenditore.

Metodo HTTP ed endpoint

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

Richiesta dell'API Core Product Search:

Query iniziale

    {
      "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 (obbligatorio): il nome risorsa della configurazione di pubblicazione di Retail Search o del posizionamento legacy. Esempio: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
• query: obbligatorio. La query di ricerca. Può trattarsi dell'input grezzo dell'utente, ad esempio Aiutami a organizzare una festa, o di un refinedSearch.query più ottimizzato (ad esempio articoli per l'organizzazione di feste, decorazioni) ottenuto dalla risposta dell'API Conversational Commerce.
• visitorId: obbligatorio. Un identificatore univoco per il monitoraggio dei visitatori. Questo valore deve essere coerente con visitorId inviato all'API Conversational Commerce per lo stesso utente finale.
• branch (obbligatorio): il nome della risorsa del ramo, ad esempio projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
• pageSize (facoltativo): il numero massimo di prodotti da restituire.
• filter (facoltativo): utilizzato per filtrare i risultati di ricerca. È qui che applicheresti tutti i filtri che rispecchiano ciò che invii in `searchParams` all'API Conversational Commerce per coerenza.
• orderBy (facoltativo): specifica l'ordine in cui vengono restituiti i prodotti (ad esempio per pertinenza o per prezzo).
• userInfo (Facoltativo): informazioni utente per la personalizzazione, devono essere coerenti con la chiamata API Conversational Commerce.
• searchMode (facoltativo): definisce il comportamento di ricerca. PRODUCT_SEARCH è comune per le query generali sui prodotti.

Comprendere la risposta

Questo esempio di codice mostra una risposta dell'API Conversational Commerce.

La risposta dell'API (ConversationalSearchResponse) include query_types, conversational_text_response (se applicabile), opzioni refined_search e potenzialmente un followup_question o un conversational_filtering_result. Il conversation_id è essenziale per continuare la sessione.

Risposta di Vertex AI Search per l'e-commerce

Questo esempio di codice mostra una risposta dell'API Conversational:

Risposta iniziale

    {
      "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"
    }
    

Cosa devono fare i rivenditori con la risposta (generale)

Visualizza questi campi dalla risposta:

• user_query_types: questo campo fornisce la classificazione o le classificazioni dell'intent dell'utente. Per azioni dettagliate basate su questi tipi, consulta [Comprendere i tipi di query e le azioni del rivenditore](#step-2c).
• conversation_id: puoi memorizzare questo ID univoco nell'archivio della sessione del browser o in un archivio lato client simile per mantenere la sessione conversazionale con il server. Questo è fondamentale per distinguere tra più conversazioni in corso per un singolo acquirente. Il modello conserva il contesto per un determinato conversation_id. L'invio di un nuovo conversation_id avvia una nuova sessione. Ti consigliamo di definire la durata della sessione, ad esempio 30 minuti di inattività.
• refined_search: questo è un elenco di query di ricerca perfezionate proposte utilizzate per recuperare i risultati di ricerca pertinenti. Per SIMPLE_PRODUCT_SEARCH, sarà sempre una singola query. Per le altre query che cercano risposte LLM, sarà uno o più. Le query refined_search possono essere utilizzate per le chiamate all'API Search principale (SearchService.Search) o possono anche essere visualizzate all'utente come suggerimenti.
• conversational_text_response: mostra questo testo all'utente come risposta principale generata dall'AI alla sua query.
• followup_question: facoltativo. Viene visualizzato followup_question.
• state: questo campo indica lo stato della generazione della risposta (STREAMING o SUCCEEDED). Puoi utilizzarlo per il feedback dell'interfaccia utente, ad esempio per mostrare un indicatore di caricamento fino a SUCCEEDED. Per maggiori dettagli, consulta il passaggio 2b. Informazioni sull'API Streaming

Informazioni sull'API di streaming

L'API Conversational Commerce funziona come un'API di streaming. Ciò significa che l'utente riceve parti della risposta in più blocchi anziché un singolo payload completo.

Il primo blocco della risposta include le query query_types e refined_search e il relativo state è indicato come STREAMING. Questa rilevazione precoce dell'intent e la disponibilità immediata dei perfezionamenti della ricerca consentono al modello di prendere decisioni rapide su come gestire la query dell'utente e la sua esperienza in termini di latenza delle risposte LLM:

• Per i tipi di query che _non_ prevedono una risposta di testo conversazionale (ad esempio SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT): poiché query_types si trovano nel primo blocco, il sistema sa immediatamente che non arriverà alcuna risposta del modello LLM. Puoi procedere con la gestione predefinita per questi tipi, ad esempio visualizzare un messaggio statico, reindirizzare all'assistenza, senza attendere ulteriori output conversazionali.
• Nello specifico per SIMPLE_PRODUCT_SEARCH, il tuo sistema può effettuare immediatamente una chiamata diretta all'API Search principale utilizzando la query refined_search ricevuta nel primo blocco. Ciò contribuisce a garantire che i risultati di ricerca vengano visualizzati con un ritardo minimo, rispettando i tipici SLA dell'esperienza di ricerca.
• Per i tipi di query che prevedono una risposta di testo conversazionale (ad esempio INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT)
• Ricevi le query query_types e refined_search nel blocco iniziale. Puoi avviare immediatamente una chiamata parallela all'API Search principale utilizzando queste query refined_search per iniziare a caricare i risultati dei prodotti.
• I chunk successivi vengono trasmessi in streaming e contengono sezioni diverse della risposta di testo conversazionale. Durante questo periodo, state rimane "STREAMING".
• Infine, l'ultimo blocco include la risposta completa in formato di testo conversazionale e il relativo state cambia in "COMPLETED".
• Questo approccio di streaming consente un'esperienza utente finale fluida in cui i risultati di ricerca possono iniziare a caricarsi mentre viene generato il riepilogo dell'AI. Puoi scegliere di visualizzare un indicatore di caricamento per la risposta conversazionale o di presentarla dopo che è stata completamente trasmessa in streaming.

Informazioni sui tipi di query e sulle azioni dei rivenditori

Il campo query_types nella risposta è un elenco che indica la classificazione o le classificazioni dell'intent dell'utente. Il sistema dovrebbe gestirli nel seguente modo. Tieni presente che conversational_text_response si riferisce alla risposta in linguaggio naturale generata dall'AI dall'API.

L'agente Conversational Commerce utilizza le categorie di query di ricerca per determinare se viene generata una risposta basata su LLM e come vengono gestite le query degli utenti finali dalle API Conversational e Search per questi scenari:

Categorie	Classificazioni delle query
#1. Query non pertinenti che non richiedono una risposta LLM	QUERY_TYPE_UNSPECIFIED: Tipo di query non specificato. RETAIL_IRRELEVANT: query non pertinenti al dominio della vendita al dettaglio, ad esempio una query ostile (come come costruire una bomba), una query colloquiale (come come stai) o una query di jailbreak (come scrivi una poesia). BLOCKLISTED: query bloccate esplicitamente dai clienti di commercio (ad esempio Quali sono gli effetti collaterali di Advil?).
#2. Richieste di assistenza e informazioni	ORDER_SUPPORT: query ausiliaria o di assistenza (ad esempio Traccia il mio ordine, Stato ordine 12345). DEALS_AND_COUPONS: query pertinenti a offerte, promozioni, offerte di prodotti e sconti (ad esempio Esistono offerte per il giorno del Ringraziamento?). STORE_RELEVANT: query pertinenti per le sedi dei negozi, gli orari di lavoro, la disponibilità di scorte di prodotti e così via (ad esempio Abbiamo latte in magazzino?). RETAIL_SUPPORT: query pertinenti ad acquisti, metodi di pagamento e così via (ad esempio Quale metodo di pagamento accettate?).
#3. Ricerche di parole chiave che non richiedono LLM Richiesta API conversazionale: Query iniziale { "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" } Risposta dell'API conversazionale: Risposta iniziale { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } Richiesta dell'API Search: Query di follow-up { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	SIMPLE_PRODUCT_SEARCH: ricerca di base di prodotti, ad esempio vestito rosso o mostrami alcune bevande Monster.
#4. Query di ricerca di risposte LLM Richiesta API conversazionale: Query iniziale { "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" } Risposta dell'API conversazionale: Risposta iniziale { "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" } ] } Richiesta dell'API Search: Query di follow-up { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "1% milk", "visitorId": "test" }	PRODUCT_DETAILS: l'utente sta cercando dettagli e specifiche del prodotto, ad esempio mostrami le specifiche di [nome prodotto], qual è il contenuto proteico del latte al 2%? PRODUCT_COMPARISON: confronto di prodotti, ad esempio confronta [nome prodotto] e [nome prodotto], confronta latte all'1% con latte al 2%). BEST_PRODUCT: query con il pattern di corrispondenza più elevato, ad esempio Qual è il biscotto più sano? Quale marca di latte è la migliore?).
#5. Perfezionamento dell'intent Richiesta API conversazionale: Query iniziale { "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" } Risposta dell'API conversazionale: Risposta iniziale { "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: il tipo non è chiaro e potrebbe essere necessario un ulteriore scambio di battute o un perfezionamento per chiarire il tipo, ad esempio Aiutami a organizzare una festa. Si tratta spesso dell'intent più popolare nelle conversazioni.

Categoria 1. Query non pertinenti che non richiedono una risposta LLM

• QUERY_TYPE_UNSPECIFIED:
• Non è stato fornito alcun conversational_text_response.
• Azione: gestisci come caso predefinito o di errore. Potresti chiedere all'utente di fornire chiarimenti o indirizzarlo a una pagina in cui può ricevere assistenza generale.
• RETAIL_IRRELEVANT:
• Non è stato fornito alcun conversational_text_response.
• Azione: gestisci la situazione mostrando un messaggio appropriato, ad esempio Non posso rispondere a questa domanda o Sono un assistente allo shopping.Come posso aiutarti?, come definito dalla progettazione della tua applicazione.
• BLOCKLISTED:
• Non è stato fornito alcun conversational_text_response.
• Azione: gestisci in base alle norme relative alla lista bloccata, in genere mostrando un messaggio generico Impossibile soddisfare questa richiesta.

Categoria 2. Richieste di assistenza e informazioni

Per questi tipi, l'API non fornisce un conversational_text_response diretto per impostazione predefinita, ma hai opzioni per indirizzare ai link o alle risorse giusti.

• ORDER_SUPPORT:
• Azione predefinita: non viene fornito alcun conversational_text_response. La tua UI deve mostrare un messaggio standard, link pertinenti o reindirizzare la query alla tua API di assistenza dedicata o al tuo canale di assistenza clienti.
• DEALS_AND_COUPONS:
• Azione predefinita: non viene fornito alcun conversational_text_response. La tua UI deve mostrare un messaggio standard, link pertinenti o reindirizzare la query al tuo sistema di offerte o promozioni.
• STORE_RELEVANT:
• Azione predefinita: non viene fornito alcun conversational_text_response. La tua UI deve mostrare un messaggio standard, link pertinenti o reindirizzare la query al tuo sistema di informazioni o localizzatore di negozi.
• RETAIL_SUPPORT:
• Azione predefinita: non viene fornito alcun conversational_text_response. La tua UI deve mostrare un messaggio standard, link pertinenti o reindirizzare la query al tuo sistema di domande frequenti e informazioni.

Categoria 3. Ricerche di parole chiave che non richiedono risposte LLM

• SIMPLE_PRODUCT_SEARCH:
• Non viene generata alcuna risposta di testo conversazionale.
• Azione: la risposta API restituisce sempre una singola query refined_search. Questa query perfezionata funge da termine di ricerca suggerito. Chiama direttamente l'API Search principale (SearchService.Search) e recupera i risultati dei prodotti pertinenti utilizzando la query originale o la query refined_search. refined_search.query potrebbe non provenire direttamente dall'input utente finale corrente, ma può essere derivato anche dal contesto della cronologia della chat, ad esempio se un utente finale ha precedentemente perfezionato abito da festa in abiti rossi, la query perfezionata potrebbe diventare abito da festa rosso.
• Per le interfacce conversazionali (come i chatbot): è vivamente consigliato utilizzare l'refined_search.query fornito dall'API. In un flusso conversazionale, le query in linguaggio naturale come "puoi aiutarmi a trovare le banane?" vengono ottimizzate automaticamente dall'API in un termine di ricerca di prodotto preciso ("banane"), il che porta a risultati di prodotto più pertinenti.
• Per le esperienze di ricerca principali (ad esempio la pagina dei risultati di ricerca): puoi utilizzare in modo flessibile il refined_search.query dell'API o la query originale fornita dall'utente finale, perché è più probabile che la query originale sia già un termine di ricerca di prodotto preciso. Scegli l'opzione più adatta alla tua strategia di visualizzazione dell'interfaccia utente e dei risultati di ricerca.
• Opzioni di esperienza utente: la conversazione non deve terminare per le query SIMPLE_PRODUCT_SEARCH. L'utente può continuare la conversazione passando il conversation_id nelle richieste successive.
• Opzione A: termina l'interfaccia utente conversazionale: molti rivenditori scelgono di reindirizzare l'utente a una pagina dei risultati di ricerca standard una volta rilevato un SIMPLE_PRODUCT_SEARCH, chiudendo di fatto la finestra di chat. In questo scenario, se l'utente finale inserisce una nuova query nella casella di ricerca standard senza il precedente conversation_id, viene trattata come una nuova conversazione separata e viene emesso un nuovo conversation_id.
• Opzione B: continua con l'interfaccia utente conversazionale. I rivenditori possono scegliere di mantenere aperta la finestra della chat. In questo modo, l'utente può tornare alla modalità conversazionale. La decisione di implementare l'opzione A o B dipende interamente dall'esperienza utente preferita dal rivenditore.

Per attribuire con precisione le query di ricerca alle interazioni conversazionali e utilizzare tutte le funzionalità di analisi in Vertex AI Search per il commercio, è fondamentale taggare correttamente gli eventi:

1. Recupera conversation_id: quando effettui una chiamata API conversationalSearch, viene restituito ConversationalSearchResponse.conversation_id.
2. Tagga gli eventi utente: nei casi in cui la risposta conversazionale porta a una query di ricerca, ad esempio se il sistema esegue automaticamente una ricerca in base alla query perfezionata per SIMPLE_PRODUCT_SEARCH, devi taggare l'evento utente di ricerca successivo (UserEvent) con lo stesso conversation_id ricevuto in ConversationalSearchResponse.

Se tagghi correttamente UserEvent.conversation_id, Analytics può attribuire con precisione le query di ricerca alle interazioni conversazionali precedenti, fornendo informazioni preziose sul comportamento e sui percorsi di conversione degli utenti.

Categoria 4. Query di ricerca di risposte LLM

Per questi tipi di query, l'API genera una conversational_text_response (risposta LLM) e potrebbe anche fornire una o più query refined_search. La conversazione non termina e l'utente finale può continuare.

• PRODUCT_DETAILS:
• Azione: conversational_text_response fornirà i dettagli del prodotto richiesti. Il tuo sistema deve mostrare chiaramente queste informazioni all'utente.
• La risposta includerà anche refined_search (una o più query di ricerca suggerite, ordinate e classificate) che devono essere utilizzate per recuperare i risultati di ricerca utilizzando l'API Search principale.
• PRODUCT_COMPARISON:
• Azione: il conversational_text_response fornirà un confronto tra i prodotti specificati. Il tuo sistema deve mostrare chiaramente queste informazioni all'utente.
• La risposta includerà refined_search (una o più query di ricerca suggerite, ordinate e classificate) che devono essere utilizzate per recuperare i risultati di ricerca utilizzando l'API Search principale.
• BEST_PRODUCT:
• Azione: conversational_text_response fornisce consigli o informazioni sui prodotti "migliori" in base alla query. Il sistema dovrebbe visualizzare queste informazioni.
• La risposta include refined_search (una o più query di ricerca suggerite, ordinate e classificate) che devono essere utilizzate per recuperare i risultati di ricerca utilizzando l'API Search principale.

Categoria 5. Perfezionamento dell'intent

• INTENT_REFINEMENT:
• Azione: la risposta includerà conversational_text_response, un followup_question e refined_search (una o più query di ricerca suggerite). L'ordine di visualizzazione consigliato è il seguente:
1. conversational_text_response
2. Suggerimenti refined_search: sono ordinati e classificati, quindi è importante visualizzarli nello stesso ordine della risposta.
3. Followup_question
• La risposta includerà refined_search (una o più query di ricerca suggerite, ordinate e classificate) che devono essere utilizzate per recuperare i risultati di ricerca utilizzando l'API Search principale.
• Per le interazioni successive, invia la risposta dell'utente insieme a conversation_id.

Mostra query suggerite per i prodotti

Ecco come configurare la Ricerca Google per mostrare domande e suggerimenti sui prodotti nell'agente di commercio conversazionale.

Quando l'API Conversazionale restituisce query refinedSearch, queste query rappresentano ottime opportunità per indirizzare l'utente finale verso prodotti pertinenti. Ciò è particolarmente utile per la categoria 4 (query di ricerca di risposte LLM) e la categoria 5 (INTENT_REFINEMENT).

Consiglio

• Visualizzazione: mostra all'utente le prime N (1-3, in attesa di test sul numero ideale per la tua UI) query refinedSearch.
• Meccanismo: queste query suggerite devono essere eseguite in background o in seguito all'interazione dell'utente tramite l'API Search principale (SearchService.Search).
• Presentazione: mostra i risultati come caroselli interattivi o schede cliccabili, consentendo all'utente di sfogliare categorie di prodotti correlate o articoli specifici. In questo modo, si ottiene un valore immediato e si colma il divario tra l'interazione conversazionale e la scoperta dei prodotti.

Richiesta dell'API Search:

Query di follow-up

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

Eventi da inviare a Vertex AI Search for Commerce

È importante attribuire con precisione le query di ricerca alle interazioni conversazionali e utilizzare tutte le funzionalità di analisi in Vertex AI Search for Commerce utilizzando il tagging degli eventi corretto:

1. Recupera conversation_id: quando effettui una chiamata API conversationalSearch, viene restituito ConversationalSearchResponse.conversation_id.
2. Tagga gli eventi utente: nei casi in cui la risposta conversazionale porta a una query di ricerca, ad esempio visualizzando un suggerimento refined_search su cui l'utente finale fa clic, o se il sistema esegue automaticamente una ricerca in base alla query perfezionata, devi taggare l'evento utente di ricerca successivo (UserEvent) con lo stesso conversation_id ricevuto nella ConversationalSearchResponse.

Se tagghi correttamente UserEvent.conversation_id, Analytics può attribuire con precisione le query di ricerca alle interazioni conversazionali precedenti, fornendo informazioni preziose sul comportamento degli utenti e sui percorsi di conversione.

Continua la conversazione

Questa sezione descrive in che modo le sessioni dell'agente di Conversational Commerce vengono gestite dall'API Conversational e continuano in questo passaggio finale.

L'API Conversazionale utilizza un conversation_id per gestire le conversazioni in corso. Per garantire la coerenza tra le risposte del modello linguistico di grandi dimensioni e i risultati di ricerca, le richieste Conversational API successive devono includere SearchParams che rispecchiano la configurazione delle chiamate API di ricerca principali.

Visualizza tabella

Gestione delle sessioni	Descrizione	Integrazione dell'API Conversational
Inizia una nuova conversazione	Per avviare una nuova conversazione, il client omette conversation_id dalla richiesta API.	Richiesta API di esempio 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" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Esempio di risposta dell'API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Continua la conversazione	L'API Conversational restituisce un conversation_id come parte della risposta dell'API. Questo ID può essere inviato nelle richieste successive per continuare la stessa conversazione. In questo modo, l'agente di Conversational Commerce risponde alle query dell'utente in base alla cronologia della conversazione nella sessione.	Richiesta API di esempio placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Esempio di risposta dell'API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Garantire la coerenza dei risultati di ricerca	Per garantire che le risposte del LLM siano coerenti con i risultati di ricerca mostrati, il client deve utilizzare SearchParams nella richiesta dell'API Conversational. Questi parametri di ricerca devono avere la stessa configurazione dell'API Search principale.	Richiesta API di esempio placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" search_params { filter: "filter" canonical_filter: "canonical_filter" sort_by: "sort_by" boost_spec { condition_boost_specs { condition: "condition" } } }

Gestione delle sessioni

• Avvia una nuova conversazione:
  • Descrizione: per iniziare una nuova conversazione, il client omette conversationId dalla richiesta API.
  • Quando avviare una nuova conversazione: un client vorrebbe avviare una nuova conversazione, ottenendo così un nuovo conversationId dalla risposta dell'API, in diversi scenari comuni di esperienza utente:
    • Nuova scheda o sessione: quando un cliente apre il tuo sito in una nuova scheda del browser o avvia una sessione completamente nuova.
    • Nuova query originale: in alcuni design UX, se un cliente inserisce una nuova query non correlata, puoi scegliere di riavviare il flusso conversazionale per garantire il contesto più pertinente.
    • Pulsante Riavvia conversazione: se la tua UI fornisce un pulsante esplicito "Avvia nuova chat" o "Reimposta conversazione", facendo clic su questo pulsante si avvierà una nuova sessione di conversazione.
  • Integrazione dell'API conversazionale: la risposta dell'API includerà un nuovo conversationId utilizzato per le richieste successive.
• Continua la conversazione:
  • Descrizione: Conversational API restituisce un conversation_id come parte della risposta dell'API. Questo ID deve essere inviato nelle richieste successive per continuare la stessa conversazione. In questo modo, l'agente di Conversational Commerce risponde alle query dell'utente in base alla cronologia della conversazione all'interno della sessione, coprendo l'query dell'utente finale, l'conversational_text_response e l'followup_question.
  • Integrazione dell'API conversazionale: il client passa conversation_id dalla risposta precedente in ConversationalSearchRequest.
• Garantisci la coerenza dei risultati di ricerca:
  • Descrizione: per garantire che le risposte del modello LLM siano coerenti con i risultati di ricerca mostrati all'utente, il client deve utilizzare searchParams nella richiesta Conversational API. Questi parametri di ricerca devono avere la stessa configurazione (ad esempio filtri, ordine di ordinamento) delle chiamate Search API effettuate per recuperare i risultati dei prodotti.
  • Integrazione dell'API conversazionale: l'oggetto searchParams all'interno di ConversationalSearchRequest deve essere compilato in modo identico a SearchRequest utilizzato per la ricerca di prodotti di base.

Invia una richiesta a Vertex AI Search for Commerce

Puoi recuperare conversation_id dall'archiviazione della sessione. La richiesta deve includere il nuovo query del cliente, che potrebbe essere una risposta alla domanda della risposta precedente. La richiesta deve includere anche l'refined_search.query più recente della risposta precedente se l'utente finale agisce in base a una query perfezionata. In caso contrario, deve includere una query completamente nuova e non correlata e il conversationId. Ricorda di includere sempre searchParams coerenti.

Nota :il mantenimento o il ripristino di conversationId per una nuova query dell'utente finale dipende dalle tue scelte specifiche in termini di UX e dall'esperienza utente selezionata. conversationId funge da memoria di sistema per una determinata sessione conversazionale.

• Scenario 1: singola barra di ricerca e conversazione persistente: se l'interfaccia di ricerca ha una sola barra di ricerca principale o una finestra di conversazione persistente, non reimposterai conversationId, anche se l'utente finale digita una query nuova e apparentemente non correlata. Il sistema utilizzerà la cronologia delle conversazioni esistente (associata a conversationId) per fornire risposte contestualmente pertinenti.
• Scenario 2: finestra di conversazione e finestra di query separate: se l'interfaccia di ricerca include una finestra di chat conversazionale distinta e una barra di query di ricerca standard separata (ad esempio una casella di ricerca a livello di sito), l'inserimento di una nuova query nella barra di ricerca standard potrebbe segnalare implicitamente l'intenzione di avviare una nuova ricerca non correlata, il che potrebbe comportare il ripristino di conversationId per questa specifica azione di ricerca. Tuttavia, all'interno della finestra di conversazione dedicata, il conversationId deve essere sempre mantenuto per garantire la continuità.

In definitiva, la decisione su quando riutilizzare o reimpostare il conversationId è una scelta di progettazione per ottimizzare l'esperienza conversazionale per i tuoi clienti.

Metodo HTTP ed endpoint (uguale alla query iniziale)

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

Richiesta API conversazionale:

Query di follow-up

{
  "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\")"
  }
}
  

Risposta dell'API conversazionale:

Risposta di follow-up

{
  "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"
}
  

Esempi di un utente finale che continua a ricevere domande:

• Domanda dell'utente: Aiutami a organizzare una festa
• Risposta del sistema: Che tipo di festa stai organizzando?
• Risposta dell'utente: Una festa di compleanno

Cosa devono fare i rivenditori con la risposta

Il modo di eseguire il rendering dei campi è simile alla risposta iniziale, ma tieni presente le modifiche che riflettono la conversazione continua:

• refined_search: questo campo contiene le query aggiornate che incorporano l'ultimo input dell'utente finale. Devi aggiornare la console client per la query corrente di conseguenza (ad esempio, mostrando la query rivolta agli utenti che è cambiata da "decorazioni" a "decorazioni per feste di compleanno" o "articoli per feste di compleanno"). Le query refined_search possono essere utilizzate per le chiamate all'API Search principale (SearchService.Search) o possono anche essere visualizzate all'utente finale come suggerimenti.
• conversational_text_response: mostra la nuova risposta di testo generata dall'AI pertinente all'ultimo turno.
• followup_question: se la conversazione deve continuare per ulteriori perfezionamenti, verrà fornito un nuovo followup_question.

Eventi da inviare a Vertex AI Search for Commerce

Il tagging degli eventi è importante per attribuire con precisione le query di ricerca alle interazioni conversazionali e per utilizzare le funzionalità di analisi in Vertex AI Search for Commerce.

Il processo di tagging degli eventi prevede due passaggi:

1. Recupera conversation_id: quando effettui una chiamata API conversationalSearch, viene restituito ConversationalSearchResponse.conversation_id.
2. Tagga gli eventi utente: nei casi in cui la risposta conversazionale porta a una query di ricerca, ad esempio visualizzando un suggerimento refined_search, o se il sistema esegue automaticamente una ricerca in base alla query perfezionata, devi taggare l'evento utente di ricerca successivo (UserEvent) con lo stesso conversation_id ricevuto in ConversationalSearchResponse.

Se tagghi correttamente UserEvent.conversation_id, Analytics può attribuire con precisione le query di ricerca alle interazioni conversazionali precedenti, fornendo informazioni preziose sul comportamento degli utenti finali e sui percorsi di conversione.

Ulteriori considerazioni e best practice

Quando implementi l'interfaccia dell'agente Conversational Commerce, devi prendere in considerazione ulteriori aspetti e best practice:

• Coerenza dell'ID visitatore: contribuisci a garantire che un visitor_id univoco venga inviato in modo coerente con ogni richiesta per un determinato utente finale. Questo è fondamentale per una personalizzazione e un addestramento del modello accurati. Idealmente, questo identificatore dovrebbe rimanere coerente per un utente finale in tutte le sessioni e gli stati di accesso o disconnessione.
• Gestione filiali: anche se default_branch è comune, assicurati di utilizzare l'ID filiale corretto se il catalogo prodotti è strutturato con più filiali.
• Interazione con l'API Search: per SIMPLE_PRODUCT_SEARCH e per tutti i casi in cui viene fornito refined_search, ricorda di effettuare una chiamata separata all'API Search principale (SearchService.Search) utilizzando query dal campo refined_search o la query originale per ottenere le schede di prodotto effettive. L'API conversazionale si concentra principalmente sull'esperienza conversazionale e sulla comprensione dell'intent dell'utente, anziché restituire direttamente i risultati dei prodotti.
• Progettazione dell'interfaccia utente: progetta la tua UI in modo da presentare chiaramente le opzioni conversational_text_response, followup_question e refined_search in modo intuitivo per guidare l'utente.

Passaggi successivi

Per ulteriori risorse di supporto, consulta le domande frequenti sulle funzionalità conversazionali.