Vertex AI Search pour le commerce est en cours de rebaptisement en Vertex AI Search pour le commerce. Nous mettons à jour le contenu pour refléter le nouveau branding.

Cette page a été traduite par l'API Cloud Translation.

Guide du développeur d'agents de commerce conversationnel

Ce guide explique comment intégrer l'API Conversational pour offrir à vos clients des expériences de chat dynamiques optimisées par l'IA. En comprenant les différents types de requêtes et en exploitant les réponses de l'API, vous pouvez proposer des recherches de produits pertinentes, répondre aux questions de vos clients et guider vos utilisateurs finaux tout au long de leur parcours d'achat.

Le conversationalFilteringMode de l'API Conversationnelle permet de distinguer clairement l'agent de commerce conversationnel du filtrage conversationnel des produits.

Configuration

L'API Conversational est compatible avec la fonctionnalité d'agent de commerce conversationnel :

gRPC : conversationalSearchService
REST : conversationalSearch

L'API Conversational permet une expérience de chat dans laquelle vos utilisateurs envoient des requêtes et le système renvoie une réponse textuelle, des types de requêtes classés et des options de recherche affinées potentielles.

Cette API fonctionne comme un service de streaming, ce qui permet de détecter rapidement l'intention de la requête. Les interactions ultérieures dans la conversation nécessitent l'ajout d'un conversation_id.

Pour renvoyer des résultats de recherche, l'ancienne API Retail doit être appelée en parallèle de l'API Conversational.

Envoyer une requête de l'utilisateur final

Cette section décrit comment lancer une expérience d'agent Conversational Commerce. Par exemple, votre utilisateur peut saisir Aide-moi à organiser une fête dans le champ de recherche.

Envoyer une requête à Vertex AI Search pour le commerce

Il existe deux points de terminaison d'API différents :

L'API Conversational doit être utilisée pour récupérer l'expérience conversationnelle.
L'API Search principale doit être utilisée pour récupérer les résultats de recherche.

Point de terminaison 1 : requête de l'API Conversationnelle

Vous devez créer une demande d'agent Conversational Commerce en définissant l'entrée de votre utilisateur comme requête.
La requête doit être envoyée en tant que requête HTTP POST au point de terminaison projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Méthode HTTP et point de terminaison

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

Requête API conversationnelle :

Requête initiale

{
  "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 : nom de ressource de l'emplacement (par exemple, projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Il s'agit d'un paramètre de chemin d'accès obligatoire.
query : requête de recherche brute de votre utilisateur. Ce champ est obligatoire.
branch : nom de la ressource de branche, par exemple projects/P/locations/L/catalogs/C/branches/B. Si ce paramètre n'est pas défini, default_branch est utilisé. Ce champ est obligatoire.
visitorId : identifiant unique permettant d'effectuer le suivi des visiteurs. Ce champ est obligatoire.
conversationId : ID unique permettant de suivre les sessions de conversation. Pour la première demande dans une nouvelle conversation, ce champ doit être vide. Pour les requêtes suivantes dans la même conversation, il doit être défini sur le conversation_id reçu dans le ConversationalSearchResponse précédent.
searchParams : (facultatif) paramètres standards du moteur de recherche principal (par exemple, filter, canonicalFilter, sortBy, boostSpec). Il est essentiel que ces paramètres reflètent la configuration utilisée dans vos appels principaux à l'API Search pour garantir la cohérence entre les réponses du LLM et les résultats de recherche de produits affichés.
userInfo : (facultatif) Informations sur l'utilisateur pour une personnalisation améliorée. Peut inclure userId, user_agent et direct_user_request (booléen).
conversationalFilteringSpec : (facultatif) spécifie le mode de filtrage conversationnel. Si cette valeur n'est pas définie, la valeur par défaut est "DISABLED" (DÉSACTIVÉ).
mode : intégrez l'API Conversationnelle à l'aide de l'un de ces trois modes pour contrôler le filtrage des produits conversationnels :

DISABLED : dans ce mode, le client n'implémente que la recherche d'agents de commerce conversationnel. Il s'agit du mode préféré pour ce guide d'implémentation sur la recherche d'agents de commerce conversationnel.

Exemple de requête API

        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
        }

Exemple de réponse de l'API

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

ENABLED : dans ce mode, le client implémente toutes les fonctionnalités conversationnelles, y compris la recherche d'agents de commerce conversationnel et le filtrage conversationnel des produits.

Exemple de requête API

        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
        }

Exemple de réponse de l'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 : si cette option est choisie, le client implémente uniquement le filtrage conversationnel des produits. Lorsque ce mode est sélectionné, l'utilisateur ne bénéficie que du filtrage conversationnel des produits, sans génération de réponse LLM, de classification des requêtes ni de suggestions de requêtes de recherche.

Pour en savoir plus, consultez le guide du développeur sur les filtres de produits conversationnels. Veuillez consulter le guide supplémentaire sur l'intégration des deux produits conversationnels.

Point de terminaison 2 : requête de l'API Core Search

Il existe deux approches principales pour afficher les résultats de recherche dans votre UI :

Option 1 : Toujours afficher les résultats de recherche

Si votre conception de l'expérience utilisateur exige que les résultats de recherche soient toujours affichés, quelle que soit la sortie conversationnelle (par exemple, dans une zone de résultats de recherche dédiée à côté du chat), envoyez la requête d'origine de l'utilisateur à l'API Product Search principale avec votre appel à l'API Conversational. Cela permet de s'assurer que les fiches produit sont immédiatement disponibles.
Option 2 : Afficher les résultats de recherche en fonction de la réponse conversationnelle

Si la conception de votre expérience utilisateur est plus dynamique et que vous ne souhaitez afficher les résultats de recherche qu'en fonction de la réponse de l'API Conversational, par exemple uniquement pour les requêtes SIMPLE_PRODUCT_SEARCH ou chaque fois que des suggestions refined_search sont fournies, attendez la réponse de l'API Conversational avant d'envoyer des requêtes à l'API Product Search principale. S'il y a une réponse, utilisez la requête refined_search fournie pour récupérer les résultats des produits.

Quelle que soit l'option d'interface utilisateur choisie, vous pouvez appeler l'API Retail lorsque vous avez besoin d'extraire les résultats des produits. Pour en savoir plus, consultez Étape 2c. Comprendre les types de requêtes et les actions des marchands

Méthode HTTP et point de terminaison

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

Requête API Recherche de produits principaux :

Requête initiale

    {
      "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 (obligatoire) : nom de la ressource de la configuration de diffusion Retail Search ou de l'emplacement existant. Exemple : projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
query : obligatoire. Requête de recherche. Il peut s'agir de la saisie brute de l'utilisateur, comme Aide-moi à organiser une fête, ou d'une refinedSearch.query plus optimisée (comme fournitures pour organiser une fête, décorations) obtenue à partir de la réponse de l'API Conversational Commerce.
visitorId : obligatoire. Identifiant unique permettant d'effectuer le suivi des visiteurs. Cette valeur doit être cohérente avec le visitorId envoyé à l'API Conversational Commerce pour le même utilisateur final.
branch (obligatoire) : nom de la ressource de branche, tel que projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
pageSize (facultatif) : nombre maximal de produits à renvoyer.
filter (facultatif) : utilisé pour filtrer les résultats de recherche. C'est ici que vous appliquerez les filtres qui reflètent ce que vous envoyez dans `searchParams` à l'API Conversational Commerce pour assurer la cohérence.
orderBy (facultatif) : spécifie l'ordre dans lequel les produits sont renvoyés (par pertinence ou par prix, par exemple).
userInfo (facultatif) : informations utilisateur pour la personnalisation. Elles doivent être cohérentes avec l'appel de l'API Conversational Commerce.
searchMode (facultatif) : définit le comportement de recherche. PRODUCT_SEARCH est courant pour les requêtes générales sur les produits.

Comprendre la réponse

Cet exemple de code montre une réponse de l'API Conversational Commerce.

La réponse de l'API (ConversationalSearchResponse) inclut query_types, conversational_text_response (le cas échéant), les options refined_search et potentiellement un followup_question ou un conversational_filtering_result. Le conversation_id est essentiel pour poursuivre la session.

Réponse de Vertex AI Search pour le commerce

Cet exemple de code montre une réponse de l'API Conversational :

Réponse initiale

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

Que doivent faire les marchands avec la réponse (général)

Affichez les champs suivants de la réponse :

user_query_types : ce champ fournit la ou les classifications de l'intention de votre utilisateur. Pour en savoir plus sur les actions détaillées en fonction de ces types, consultez [Comprendre les types de requêtes et les actions des marchands](#step-2c).
conversation_id : vous pouvez stocker cet ID unique dans le stockage de session de votre navigateur ou dans un stockage côté client similaire pour maintenir la session de conversation avec le serveur. Cela est essentiel pour faire la distinction entre plusieurs conversations en cours pour un même client. Votre modèle conserve le contexte pour un conversation_id donné. L'envoi d'une nouvelle conversation_id démarre une nouvelle session. Nous vous recommandons de définir la durée de votre session, par exemple 30 minutes d'inactivité.
refined_search : liste des requêtes de recherche affinées proposées pour récupérer les résultats de recherche pertinents. Pour SIMPLE_PRODUCT_SEARCH, il s'agira toujours d'une seule requête. Pour les autres requêtes visant à obtenir une réponse LLM, il y en aura une ou plusieurs. Les requêtes refined_search peuvent être utilisées pour les appels à l'API Search principale (SearchService.Search) ou peuvent également être affichées à l'utilisateur sous forme de suggestions.
conversational_text_response : affichez ce texte à l'utilisateur comme réponse principale générée par l'IA à sa requête.
followup_question : facultatif. L'état followup_question s'affiche.
state : ce champ indique l'état de la génération de la réponse (STREAMING ou SUCCEEDED). Vous pouvez l'utiliser pour les commentaires de l'UI, par exemple pour afficher un indicateur de chargement jusqu'à SUCCEEDED. Pour en savoir plus, consultez l'étape 2b. Comprendre l'API Streaming

Comprendre l'API Streaming

L'API Conversational Commerce fonctionne comme une API de streaming. Cela signifie que votre utilisateur reçoit des parties de la réponse dans plusieurs blocs plutôt que dans une seule charge utile complète.

Le premier bloc de la réponse inclut les requêtes query_types et refined_search, et son state est indiqué comme STREAMING. Cette détection précoce de l'intention et la disponibilité immédiate des affinements de recherche permettent à votre modèle de prendre des décisions rapides sur la façon de traiter la requête de votre utilisateur et de gérer son expérience en termes de latence des réponses du LLM :

Pour les types de requêtes qui n'attendent pas de réponse textuelle conversationnelle (comme SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT) : comme query_types se trouve dans le premier bloc, votre système sait immédiatement qu'aucune réponse LLM n'est à venir. Vous pouvez poursuivre le traitement prédéfini pour ces types, par exemple en affichant un message statique ou en redirigeant l'utilisateur vers l'assistance, sans attendre d'autres résultats conversationnels.

Plus précisément pour SIMPLE_PRODUCT_SEARCH, votre système peut immédiatement effectuer un appel direct à l'API Search principale à l'aide de la requête refined_search reçue dans le premier bloc. Cela permet de s'assurer que les résultats de recherche s'affichent avec un délai minimal, conformément aux SLA habituels de l'expérience de recherche.

Pour les types de requêtes qui s'attendent à une réponse textuelle conversationnelle (comme INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT)

Vous recevez les requêtes query_types et refined_search dans le bloc initial. Vous pouvez immédiatement lancer un appel parallèle à l'API Search principale à l'aide de ces requêtes refined_search pour commencer à charger les résultats de produits.
Les blocs suivants sont diffusés en streaming et contiennent différentes sections de la réponse textuelle conversationnelle. Pendant ce temps, l'état state reste "STREAMING".
Enfin, le dernier bloc inclut la réponse textuelle complète de la conversation, et son state passe à "COMPLETED".
Cette approche de streaming permet une expérience utilisateur fluide, où les résultats de recherche peuvent commencer à se charger pendant que le résumé de l'IA est généré. Vous pouvez choisir d'afficher un indicateur de chargement pour la réponse conversationnelle ou de la présenter une fois qu'elle a été entièrement diffusée.

Comprendre les types de requêtes et les actions des marchands

Le champ query_types de la réponse est une liste indiquant la ou les classifications de l'intention de votre utilisateur. Votre système doit les gérer comme suit. Notez que conversational_text_response fait référence à la réponse en langage naturel générée par l'IA à partir de l'API.

L'agent Conversational Commerce utilise des catégories de requêtes de recherche pour déterminer si une réponse basée sur un LLM est générée et comment les requêtes des utilisateurs finaux sont traitées par les API Conversational et Search dans les scénarios suivants :

Catégories	Classifications des requêtes
1. Requêtes non pertinentes qui ne nécessitent pas de réponse du LLM	`QUERY_TYPE_UNSPECIFIED` : type de requête non spécifié. `RETAIL_IRRELEVANT` : requêtes non pertinentes pour le domaine du commerce, par exemple une requête contradictoire (comme comment fabriquer une bombe), une requête bavarde (comme comment allez-vous) ou une requête de jailbreak (comme écrire un poème). `BLOCKLISTED` : requêtes explicitement bloquées par les clients commerciaux (par exemple, Quels sont les effets secondaires de l'Advil ?).
2. Demandes d'assistance et d'informations	`ORDER_SUPPORT` : requête auxiliaire ou d'assistance (par exemple, Suivre ma commande, état de la commande 12345). `DEALS_AND_COUPONS` : requêtes liées aux offres, aux promotions, aux offres de produits et aux remises (par exemple, Y a-t-il des offres pour Thanksgiving ?). `STORE_RELEVANT` : requêtes liées aux adresses des magasins, aux horaires d'ouverture, à la disponibilité des produits en stock, etc. (par exemple, Avez-vous du lait en stock ?). `RETAIL_SUPPORT` : requêtes liées aux achats, aux modes de paiement, etc. (par exemple, Quels sont les modes de paiement acceptés ?).
3. Recherches par mots clés ne nécessitant pas de LLM Requête API conversationnelle : Requête initiale { "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" } Réponse de l'API conversationnelle : Réponse initiale { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } Requête API Search : Requête complémentaire { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	`SIMPLE_PRODUCT_SEARCH` : recherche de produits de base, comme robe rouge ou montre-moi des Monster Energy.
4. Requêtes de recherche de réponses LLM Requête API conversationnelle : Requête initiale { "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" } Réponse de l'API conversationnelle : Réponse initiale { "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" } ] } Requête API Search : Requête complémentaire { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "1% milk", "visitorId": "test" }	`PRODUCT_DETAILS` : votre utilisateur recherche des informations et des caractéristiques sur un produit, par exemple montre-moi les caractéristiques de [nom du produit], quelle est la teneur en protéines du lait à 2 % ? `PRODUCT_COMPARISON` : comparaison de produits, par exemple compare [nom du produit] et [nom du produit], compare le lait à 1 % et le lait à 2 %. `BEST_PRODUCT` : requêtes correspondant le mieux au modèle, comme Quel est le cookie le plus sain ? Quelle est la meilleure marque de lait ?
5. Affiner l'intention Requête API conversationnelle : Requête initiale { "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" } Réponse de l'API conversationnelle : Réponse initiale { "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` : le type n'est pas clair et une conversation ou une clarification complémentaire peuvent être nécessaires pour le préciser, par exemple Aide-moi à organiser une fête. Il s'agit souvent de l'intention la plus populaire dans les conversations.

Catégorie 1. Requêtes non pertinentes qui ne nécessitent pas de réponse de LLM

QUERY_TYPE_UNSPECIFIED :

Aucun conversational_text_response n'est fourni.
Action : gérez-le comme un cas par défaut ou d'erreur. Vous pouvez demander à l'utilisateur de fournir des précisions ou l'orienter vers un endroit où il peut obtenir de l'aide générale.

RETAIL_IRRELEVANT :

Aucun conversational_text_response n'est fourni.
Action : gérez cela en affichant un message approprié, tel que Je ne peux pas répondre à cette question. ou Je suis un assistant shopping, comment puis-je vous aider ?, comme défini par la conception de votre application.

BLOCKLISTED :

Aucun conversational_text_response n'est fourni.
Action : gérez la demande conformément à votre règlement sur la liste de blocage, généralement en affichant un message générique Impossible de traiter cette demande.

Catégorie 2. Demandes d'assistance et d'informations

Pour ces types, l'API ne fournit pas de conversational_text_response direct par défaut, mais vous avez la possibilité de rediriger les utilisateurs vers les liens ou ressources appropriés.

ORDER_SUPPORT :

Action par défaut : aucune conversational_text_response n'est fournie. Votre UI doit afficher un message standard, des liens pertinents ou rediriger la requête vers votre propre API d'assistance ou canal de service client dédié.

DEALS_AND_COUPONS :

Action par défaut : aucune conversational_text_response n'est fournie. Votre UI doit afficher un message standard, des liens pertinents ou rediriger la requête vers votre système d'offres ou de promotions.

STORE_RELEVANT :

Action par défaut : aucune conversational_text_response n'est fournie. Votre UI doit afficher un message standard, des liens pertinents ou rediriger la requête vers votre propre outil de localisation de magasin ou système d'information.

RETAIL_SUPPORT :

Action par défaut : aucune conversational_text_response n'est fournie. Votre UI doit afficher un message standard, des liens pertinents ou rediriger la requête vers votre propre système de questions fréquentes et d'informations.

Catégorie 3. Recherches par mots clés ne nécessitant pas de réponses LLM

SIMPLE_PRODUCT_SEARCH :

Aucune réponse textuelle conversationnelle n'est générée.
Action : la réponse de l'API renvoie toujours une seule requête refined_search. Cette requête affinée sert de terme de recherche suggéré. Appelez directement l'API Search principale (SearchService.Search) et récupérez les résultats de produits pertinents à l'aide de la requête d'origine ou de la requête refined_search. La refined_search.query ne provient pas forcément directement de la saisie de l'utilisateur final actuel, mais peut également être dérivée du contexte de l'historique des discussions. Par exemple, si un utilisateur final a précédemment affiné la requête robe de soirée en robes rouges, la requête affinée peut devenir robe de soirée rouge.

Pour les interfaces conversationnelles (comme les chatbots) : il est fortement recommandé d'utiliser le refined_search.query fourni par l'API. Dans un flux conversationnel, les requêtes en langage naturel telles que "peux-tu m'aider à trouver des bananes" sont automatiquement optimisées par l'API en un terme de recherche de produit précis ("bananes"), ce qui permet d'obtenir des résultats de produits plus pertinents.
Pour les expériences de recherche principales (comme la page de résultats de recherche) : vous pouvez utiliser le refined_search.query de l'API ou la requête d'origine fournie par l'utilisateur final, car il est plus probable que la requête d'origine soit déjà un terme de recherche de produit précis. Choisissez l'option qui correspond le mieux à votre stratégie d'affichage de l'UI et des résultats de recherche.

Options d'expérience utilisateur : la conversation n'a pas besoin de se terminer pour les requêtes SIMPLE_PRODUCT_SEARCH. Votre utilisateur peut poursuivre la conversation en transmettant le conversation_id dans les requêtes suivantes.

Option A : Mettre fin à l'UI conversationnelle : de nombreux marchands choisissent de rediriger l'utilisateur vers une page de résultats de recherche standard lorsqu'un SIMPLE_PRODUCT_SEARCH est détecté, ce qui ferme la fenêtre de chat. Dans ce scénario, si l'utilisateur final saisit une nouvelle requête dans le champ de recherche standard sans le conversation_id précédent, elle est traitée comme une nouvelle conversation distincte et un nouveau conversation_id est émis.
Option B : Continuer l'interface utilisateur conversationnelle : les marchands peuvent choisir de laisser la fenêtre de chat ouverte. Cela permet à votre utilisateur de revenir à un mode conversationnel. Le choix entre l'option A et l'option B dépend entièrement de l'expérience utilisateur préférée du marchand.

Pour attribuer précisément les requêtes de recherche aux interactions conversationnelles et utiliser toutes les fonctionnalités d'analyse dans Vertex AI Search pour le commerce, il est essentiel de taguer correctement les événements :

Récupérer conversation_id : lorsque vous effectuez un appel d'API conversationalSearch, le ConversationalSearchResponse.conversation_id est renvoyé.
Taguer les événements utilisateur : lorsque la réponse conversationnelle conduit à une requête de recherche, par exemple si votre système exécute automatiquement une recherche basée sur la requête affinée pour SIMPLE_PRODUCT_SEARCH, vous devez taguer cet événement utilisateur de recherche ultérieur (UserEvent) avec le même conversation_id reçu dans ConversationalSearchResponse.

En taguant correctement UserEvent.conversation_id, vos données analytiques peuvent attribuer précisément les requêtes de recherche aux interactions conversationnelles précédentes. Vous obtenez ainsi des insights précieux sur le comportement de vos utilisateurs et les chemins de conversion.

Catégorie 4. Requêtes de recherche de réponses LLM

Pour ces types de requêtes, l'API génère une conversational_text_response (réponse LLM) et peut également fournir une ou plusieurs requêtes refined_search. La conversation ne se termine pas et l'utilisateur final peut la poursuivre.

PRODUCT_DETAILS :

Action : l'conversational_text_response fournira les informations demandées sur le produit. Votre système doit afficher clairement ces informations à l'utilisateur.
La réponse inclura également refined_search (une ou plusieurs requêtes de recherche suggérées, classées et ordonnées) qui doivent être utilisées pour récupérer les résultats de recherche à l'aide de l'API Search principale.

PRODUCT_COMPARISON :

Action : conversational_text_response comparera les produits spécifiés. Votre système doit afficher clairement ces informations à l'utilisateur.
La réponse inclura refined_search (une ou plusieurs requêtes de recherche suggérées, classées et ordonnées) qui devraient être utilisées pour récupérer les résultats de recherche à l'aide de l'API Search principale.

BEST_PRODUCT :

Action : le conversational_text_response fournit des recommandations ou des informations sur les "meilleurs" produits en fonction de la requête. Votre système doit afficher ces informations.
La réponse inclut refined_search (une ou plusieurs requêtes de recherche suggérées, classées et ordonnées) qui doivent être utilisées pour récupérer les résultats de recherche à l'aide de l'API Search principale.

INTENT_REFINEMENT :

Action : la réponse inclut conversational_text_response, followup_question et refined_search (une ou plusieurs requêtes de recherche suggérées). L'ordre d'affichage recommandé est le suivant :

conversational_text_response
Suggestions refined_search : elles sont classées et ordonnées. Il est donc important de les afficher dans le même ordre que dans la réponse.
Followup_question

La réponse inclura refined_search (une ou plusieurs requêtes de recherche suggérées, classées et ordonnées) qui devraient être utilisées pour récupérer les résultats de recherche à l'aide de l'API Search principale.
Pour les interactions suivantes, envoyez la réponse de l'utilisateur avec le conversation_id.

Afficher les requêtes suggérées pour les produits

Voici comment configurer la recherche Google pour afficher des questions et des suggestions de produits dans l'agent de commerce conversationnel.

Lorsque l'API Conversational renvoie des requêtes refinedSearch, celles-ci représentent d'excellentes opportunités pour orienter l'utilisateur final vers des produits pertinents. Cela est particulièrement utile pour la catégorie 4 (requêtes de recherche de réponses LLM) et la catégorie 5 (INTENT_REFINEMENT).

Recommandation

Affichage : présentez à l'utilisateur les N requêtes les plus pertinentes (entre 1 et 3, en fonction des tests sur le nombre idéal pour votre UI).refinedSearch
Mécanisme : ces requêtes suggérées doivent être exécutées en arrière-plan ou lors d'une interaction utilisateur via l'API Search principale (SearchService.Search).
Présentation : affichez les résultats sous forme de carrousels interactifs ou de fiches cliquables, permettant à vos utilisateurs de parcourir des catégories de produits associées ou des articles spécifiques. Cela offre une valeur immédiate et permet de combler le fossé entre l'interaction conversationnelle et la découverte de produits.

Requête API Search :

Requête complémentaire

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

Événements à envoyer à Vertex AI Search pour le commerce

Il est important d'attribuer précisément les requêtes de recherche aux interactions conversationnelles et d'utiliser toutes les fonctionnalités d'analyse dans Vertex AI Search pour le commerce en utilisant le taggage d'événements approprié :

Récupérer conversation_id : lorsque vous effectuez un appel d'API conversationalSearch, le ConversationalSearchResponse.conversation_id est renvoyé.
Taguer les événements utilisateur : lorsque la réponse conversationnelle génère une requête de recherche (par exemple, en affichant une suggestion refined_search sur laquelle l'utilisateur final clique) ou si votre système exécute automatiquement une recherche en fonction de la requête affinée, vous devez taguer cet événement utilisateur de recherche ultérieur (UserEvent) avec le même conversation_id reçu dans ConversationalSearchResponse.

Continuez la conversation

Cette section explique comment les sessions d'agent de commerce conversationnel sont gérées par l'API Conversational et se poursuivent dans cette dernière étape.

L'API Conversational utilise un conversation_id pour gérer les conversations en cours. Pour assurer la cohérence entre les réponses du LLM et les résultats de recherche, les requêtes Conversational API ultérieures doivent inclure SearchParams qui reflètent la configuration des appels de l'API Search principale.

Afficher la table

Gestion des sessions Description Intégration de l'API conversationnelle

Démarrer une conversation

Gestion des sessions	Description	Intégration de l'API conversationnelle
Démarrer une conversation	Pour démarrer une nouvelle conversation, le client omet le `conversation_id` de la requête API.	Exemple de requête API 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" Exemple de réponse de l'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" }
Continuez la conversation	L'API Conversational renvoie un `conversation_id` dans la réponse de l'API. Cet ID peut être envoyé dans les requêtes de suivi pour poursuivre la même conversation. Cela permet de s'assurer que l'agent de commerce conversationnel répond aux requêtes de vos utilisateurs en fonction de l'historique des conversations de cette session.	Exemple de requête API 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" Exemple de réponse de l'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" }
Assurer la cohérence des résultats de recherche	Pour s'assurer que les réponses du LLM sont cohérentes avec les résultats de recherche affichés, le client doit utiliser `SearchParams` dans la requête de l'API Conversationnelle. Ces paramètres de recherche doivent avoir la même configuration que l'API Search principale.	Exemple de requête API 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" } } }

Pour démarrer une nouvelle conversation, le client omet le conversation_id de la requête API.

Exemple de requête API

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"

Exemple de réponse de l'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"
}

Continuez la conversation

L'API Conversational renvoie un conversation_id dans la réponse de l'API. Cet ID peut être envoyé dans les requêtes de suivi pour poursuivre la même conversation. Cela permet de s'assurer que l'agent de commerce conversationnel répond aux requêtes de vos utilisateurs en fonction de l'historique des conversations de cette session.

Exemple de requête API

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"

Exemple de réponse de l'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"
}

Assurer la cohérence des résultats de recherche

Pour s'assurer que les réponses du LLM sont cohérentes avec les résultats de recherche affichés, le client doit utiliser SearchParams dans la requête de l'API Conversationnelle. Ces paramètres de recherche doivent avoir la même configuration que l'API Search principale.

Exemple de requête API

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

Gestion des sessions

Démarrer une conversation :
- Description : pour démarrer une conversation, le client omet le conversationId de la requête API.
- Quand démarrer une nouvelle conversation : un client peut vouloir démarrer une nouvelle conversation (et ainsi obtenir un nouvel conversationId dans la réponse de l'API) dans plusieurs scénarios d'expérience utilisateur courants :
  - Nouvel onglet ou nouvelle session : lorsqu'un client ouvre votre site dans un nouvel onglet de navigateur ou démarre une toute nouvelle session.
  - Nouvelle requête d'origine : dans certaines conceptions UX, si un client saisit une nouvelle requête sans rapport, vous pouvez choisir de redémarrer le flux de conversation pour garantir le contexte le plus pertinent.
  - Bouton "Redémarrer la conversation" : si votre UI fournit un bouton explicite "Démarrer une nouvelle discussion" ou "Réinitialiser la conversation", le fait de cliquer dessus déclenchera une nouvelle session de conversation.
- Intégration de l'API Conversationnel : la réponse de l'API inclura un nouveau conversationId qui sera utilisé pour les requêtes suivantes.
Continuer la conversation :
- Description : Conversational API renvoie un conversation_id dans la réponse de l'API. Cet ID doit être envoyé dans les demandes de suivi pour poursuivre la même conversation. Cela permet de s'assurer que l'agent de commerce conversationnel répond aux requêtes de vos utilisateurs en fonction de l'historique des conversations de cette session, en couvrant l'query, le conversational_text_response et le followup_question de l'utilisateur final.
- Intégration de l'API conversationnelle : le client transmet le conversation_id de la réponse précédente dans le ConversationalSearchRequest.
Assurez-vous de la cohérence des résultats de recherche :
- Description : pour s'assurer que les réponses du LLM sont cohérentes avec les résultats de recherche affichés à l'utilisateur, le client doit utiliser searchParams dans la requête Conversational API. Ces paramètres de recherche doivent avoir la même configuration (filtres, ordre de tri, etc.) que les appels Search API effectués pour récupérer les résultats des produits.
- Intégration de l'API conversationnelle : l'objet searchParams dans ConversationalSearchRequest doit être renseigné de la même manière que SearchRequest utilisé pour la recherche de produits principale.

Envoyer une requête à Vertex AI Search pour le commerce

Vous pouvez récupérer le conversation_id à partir du stockage de session. La requête doit inclure le nouveau query du client, qui peut être une réponse à la question de la réponse précédente. La requête doit également inclure le refined_search.query le plus récent de la réponse précédente si l'utilisateur final agit sur une requête affinée. Sinon, elle doit inclure une requête totalement nouvelle et sans rapport, ainsi que conversationId. N'oubliez pas d'inclure des searchParams cohérents.

Scénario 1 : Barre de recherche unique et conversation persistante : si votre interface de recherche ne comporte qu'une seule barre de recherche principale ou une fenêtre de conversation persistante, vous ne réinitialiserez pas conversationId, même si l'utilisateur final saisit une nouvelle requête qui semble sans rapport. Le système utilisera l'historique des conversations existant (associé à conversationId) pour fournir des réponses adaptées au contexte.
Scénario 2 : Fenêtre de conversation et fenêtre de requête distinctes : si votre interface de recherche comporte une fenêtre de chat conversationnel distincte et une barre de requête de recherche standard distincte (comme une zone de recherche à l'échelle du site), la saisie d'une nouvelle requête dans la barre de recherche standard peut signaler implicitement l'intention de lancer une nouvelle recherche sans rapport, ce qui peut entraîner la réinitialisation de conversationId pour cette action de recherche spécifique. Toutefois, dans la fenêtre de conversation dédiée, la conversationId doit toujours être conservée pour assurer la continuité.

En fin de compte, la décision de réutiliser ou de réinitialiser le conversationId est un choix de conception visant à optimiser l'expérience conversationnelle pour vos clients.

Méthode HTTP et point de terminaison (identiques à la requête initiale)

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

Requête API conversationnelle :

Requête complémentaire

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

Réponse de l'API conversationnelle :

Réponse complémentaire

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

Exemples de cas où un utilisateur final continue de recevoir des questions :

Question de l'utilisateur : Aide-moi à organiser une fête
Réponse du système : Quel type de fête prévoyez-vous d'organiser ?
Réponse de l'utilisateur : Une fête d'anniversaire

Que doivent faire les marchands avec la réponse ?

La façon d'afficher les champs est semblable à la réponse initiale, mais notez les modifications qui reflètent la poursuite de la conversation :

refined_search : ce champ contient les requêtes mises à jour qui intègrent la dernière entrée de l'utilisateur final. Vous devez mettre à jour la console client pour la requête actuelle en conséquence (par exemple, en montrant que la requête visible par l'utilisateur est passée de "décorations" à "décorations pour une fête d'anniversaire" ou "articles pour une fête d'anniversaire"). Les requêtes refined_search peuvent être utilisées pour les appels à l'API Search principale (SearchService.Search) ou peuvent également être affichées à l'utilisateur final sous forme de suggestions.
conversational_text_response : affiche la nouvelle réponse textuelle générée par l'IA et pertinente pour le dernier tour.
followup_question : si la conversation doit se poursuivre pour affiner davantage la réponse, un nouveau followup_question sera fourni.

Événements à envoyer à Vertex AI Search pour le commerce

Le taggage des événements est important pour attribuer précisément les requêtes de recherche aux interactions conversationnelles et pour utiliser les fonctionnalités d'analyse de Vertex AI Search pour le commerce.

Le processus de taggage d'événements comporte deux étapes :

Récupérer conversation_id : lorsque vous effectuez un appel d'API conversationalSearch, le ConversationalSearchResponse.conversation_id est renvoyé.
Taguer les événements utilisateur : dans les cas où la réponse conversationnelle conduit à une requête de recherche, par exemple en affichant une suggestion refined_search, ou si votre système exécute automatiquement une recherche en fonction de la requête affinée, vous devez taguer cet événement utilisateur de recherche ultérieur (UserEvent) avec le même conversation_id reçu dans le ConversationalSearchResponse.

En taggant correctement UserEvent.conversation_id, vos données analytiques peuvent attribuer avec précision les requêtes de recherche aux interactions conversationnelles précédentes. Vous obtenez ainsi des insights précieux sur le comportement des utilisateurs finaux et les chemins de conversion.

Autres points à prendre en compte et bonnes pratiques

Vous devez tenir compte d'autres considérations et bonnes pratiques lorsque vous implémentez l'interface de votre agent de commerce conversationnel :

Cohérence des ID de visiteur : permet de s'assurer qu'un visitor_id unique est envoyé de manière cohérente avec chaque requête pour un utilisateur final donné. C'est essentiel pour une personnalisation et un entraînement de modèle précis. Dans l'idéal, cet identifiant doit rester cohérent pour un utilisateur final, quelle que soit la session et qu'il soit connecté ou déconnecté.
Gestion des branches : bien que default_branch soit courant, assurez-vous d'utiliser le bon ID de branche si votre catalogue de produits est structuré avec plusieurs branches.
Interaction avec l'API Search : pour SIMPLE_PRODUCT_SEARCH et tous les cas où refined_search est fourni, n'oubliez pas d'effectuer un appel distinct à l'API Search principale (SearchService.Search) en utilisant le query du champ refined_search ou la requête d'origine pour obtenir les fiches produit réelles. L'API Conversationnelle se concentre principalement sur l'expérience conversationnelle et la compréhension de l'intention de l'utilisateur, plutôt que sur le renvoi direct de résultats de produits.
Conception de l'interface utilisateur : concevez votre UI de manière à présenter clairement les options conversational_text_response, followup_question et refined_search de manière intuitive pour guider l'utilisateur.

Étapes suivantes

Pour obtenir d'autres ressources d'assistance, consultez les questions fréquentes sur les fonctionnalités conversationnelles.

Guide du développeur d'agents de commerce conversationnel Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Configuration

Envoyer une requête de l'utilisateur final

Envoyer une requête à Vertex AI Search pour le commerce

Point de terminaison 1 : requête de l'API Conversationnelle

Point de terminaison 2 : requête de l'API Core Search

Comprendre la réponse

Réponse de Vertex AI Search pour le commerce

Que doivent faire les marchands avec la réponse (général)

Comprendre l'API Streaming

Comprendre les types de requêtes et les actions des marchands

Catégorie 1. Requêtes non pertinentes qui ne nécessitent pas de réponse de LLM

Catégorie 2. Demandes d'assistance et d'informations

Catégorie 3. Recherches par mots clés ne nécessitant pas de réponses LLM

Catégorie 4. Requêtes de recherche de réponses LLM

Catégorie 5. Affinement des intents

Afficher les requêtes suggérées pour les produits

Recommandation

Événements à envoyer à Vertex AI Search pour le commerce

Continuez la conversation

Gestion des sessions

Envoyer une requête à Vertex AI Search pour le commerce

Que doivent faire les marchands avec la réponse ?

Événements à envoyer à Vertex AI Search pour le commerce

Autres points à prendre en compte et bonnes pratiques

Étapes suivantes

Guide du développeur d'agents de commerce conversationnel