Configurer les commandes de diffusion pour la recherche

Les contrôles de diffusion (également appelés "contrôles") modifient le comportement par défaut de la façon dont une requête est traitée lorsque des résultats sont renvoyés. Les contrôles de diffusion agissent au niveau du data store.

Par exemple, les contrôles peuvent booster et rétrograder les résultats, filtrer les entrées des résultats renvoyés, associer des chaînes entre elles en tant que synonymes ou rediriger les résultats vers des URI spécifiés.

Cette page décrit les contrôles de diffusion pour les applications de recherche. Pour savoir comment utiliser les contrôles de diffusion avec les recommandations de contenus multimédias, consultez Créer et gérer des configurations de diffusion de contenus multimédias.

À propos des commandes de diffusion

Pour modifier les résultats d'une requête, commencez par créer un contrôle de diffusion. Associez ensuite ce contrôle à la configuration de diffusion d'une application de recherche. Une configuration de diffusion configure les métadonnées utilisées pour générer les résultats au moment de la diffusion, tels que les résultats de recherche ou les réponses. Une commande de diffusion n'affecte les requêtes diffusées par l'application que si elle est associée à la configuration de diffusion de l'application.

Certains contrôles, tels que les contrôles d'optimisation, dépendent des data stores. Si un data store est supprimé d'une application, tous les contrôles qui en dépendent sont également supprimés de cette application et deviennent inactifs, mais ne sont pas supprimés.

Types de commandes de diffusion

Les types de contrôles de diffusion suivants sont disponibles :

Contrôle Description Disponible pour
Améliorer le contrôle Modifie l'ordre des résultats renvoyés Applications de recherche avec des data stores compatibles avec un schéma, comme les data stores contenant des données structurées, des sites Web avec des données structurées (indexation avancée de sites Web), des données non structurées avec des métadonnées ou des données multimédias
Commande de filtrage Supprime les entrées des résultats renvoyés Applications de recherche avec des data stores compatibles avec un schéma, tels que les data stores contenant des données structurées, des sites Web (indexation avancée de sites Web), des données non structurées avec des métadonnées ou des données multimédias
Contrôle des synonymes Associer des requêtes entre elles Applications de recherche avec des datastores de site Web (indexation avancée de site Web), de données structurées, non structurées ou multimédias
Contrôle des redirections Redirige vers un URI spécifié Toutes les applications de recherche
Commande de promotion Promouvoir un lien spécifique pour une requête Toutes les applications de recherche

À propos des conditions

Lorsque vous créez un contrôle, vous pouvez éventuellement définir une condition qui détermine quand le contrôle est appliqué. Les conditions sont définies à l'aide de champs de condition. Les champs de condition suivants sont disponibles :

  • Termes de la requête (queryTerms) : contrôle facultatif appliqué lorsque des requêtes spécifiques sont recherchées. Lorsque la condition queryTerms est utilisée, le contrôle est appliqué lorsque la valeur de queryTerms correspond à un terme dans SearchRequest.query. Les termes de requête ne peuvent être utilisés que lorsque Control.searchUseCase est défini sur SOLUTION_TYPE_SEARCH. Vous pouvez spécifier jusqu'à 10 queryTerms différents sur un même Control.condition. Si aucun terme de requête n'est spécifié, le champ queryTerms est ignoré.

    Pour un contrôle de diffusion de promotion, queryTerms ne peut pas être spécifié si vous spécifiez la condition queryRegex, qui ne s'applique qu'à la recherche de base sur le site Web. De plus, le champ fullMatch pour la recherche basique sur site Web doit être défini sur true si queryTerms est spécifié. Pour toutes les autres applications de recherche, seule queryTerms est acceptée et fullMatch peut être défini sur true ou false.

  • Période (activeTimeRange) : contrôle facultatif appliqué lorsqu'une requête se produit au cours d'une période spécifiée. Elle vérifie que l'heure à laquelle une requête a été reçue se situe entre activeTimeRange.startTime et activeTimeRange.endTime. Vous pouvez spécifier jusqu'à 10 plages activeTimeRange dans un même Control.condition. Si le champ activeTimeRange n'est pas spécifié, il est ignoré.

  • queryRegex. Disponible uniquement pour un paramètre de diffusion de la promotion pour la recherche de base sur le site Web. Il s'agit d'une condition facultative qui applique le contrôle lorsque la requête correspond à l'expression régulière spécifiée. Cette condition ne peut pas être spécifiée si vous spécifiez la condition queryTerms.

Si plusieurs conditions sont spécifiées pour un contrôle, celui-ci est appliqué à la demande de recherche lorsque les deux types de conditions sont remplis. Si plusieurs valeurs sont spécifiées pour la même condition, une seule d'entre elles doit correspondre pour que la condition soit remplie.

Par exemple, considérons la condition suivante avec deux termes de requête spécifiés :

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

La condition sera remplie pour une requête avec SearchRequest.query="gShoe" ou SearchRequest.query="gBoot", mais pas avec SearchRequest.query="gSandal" ni aucune autre chaîne.

Si aucune condition n'est spécifiée, le contrôle est toujours appliqué.

Pour en savoir plus, consultez le champ Condition dans la documentation de référence de l'API.

Créer et associer des contrôles de diffusion de boost

Un contrôle de diffusion d'optimisation réorganise les résultats en les promouvant ou en les rétrogradant en fonction des conditions appliquées. Le boost fonctionne en appliquant un facteur de multiplication au classement d'un document qui répond aux conditions de boost.

Pour créer et associer un contrôle de l'amplification :

Console

  1. Dans la console Google Cloud , accédez à la page Applications d'IA.

    AI Applications

  2. Sélectionnez l'application pour laquelle vous souhaitez créer la commande de boost.

  3. Sur la page "Vue d'ensemble" de votre application, sélectionnez Booster/Enfouir dans l'étape Signal.

  4. Sur la page Signal, cliquez sur Créer un contrôle.

  5. Dans le volet Créer un contrôle, procédez comme suit :

    1. Saisissez un nom pour votre commande de boosting/rétrogradation, puis cliquez sur Continuer.

    2. Définissez les conditions suivantes qui déclenchent le contrôle. Si aucune condition n'est configurée, la commande est toujours opérationnelle :

      1. Ajoutez des termes de requête à correspondance partielle. La commande prend effet lorsque ces termes de requête correspondent partiellement.

      2. Ajoutez des termes de requête à correspondance exacte. La commande prend effet lorsque ces termes de requête correspondent exactement.

      3. Pour ajouter une plage horaire active, cliquez sur Ajouter une plage horaire, puis définissez Heure de début 1 et Heure de fin 1. Cela définit la période pendant laquelle la condition est active. Vous pouvez ajouter jusqu'à 10 périodes.

      4. Cliquez sur Continuer.

    3. Définissez les actions que vous souhaitez déclencher avec cette commande :

      1. Sélectionnez un data store dans la liste. Si vous souhaitez que l'action s'applique à plusieurs data stores, créez un contrôle pour chacun d'eux.

      2. Ajouter un filtre.

        Il s'agit d'une chaîne spécifiant les exigences que le document doit respecter. La condition d'optimisation n'est appliquée que si le document répond à toutes les exigences. Sinon, rien ne change. Si vous ne spécifiez pas de filtres, l'augmentation est appliquée à tous les documents du data store.

        Pour savoir comment écrire des expressions de filtre, consultez Syntaxe des expressions de filtre et Exemples d'expressions de filtre.

      3. Sélectionnez une valeur de boost/d'enfouissement comprise entre -1 et 1 à l'aide du curseur. Le curseur se déplace par incréments de 0,01.

      4. Cliquez sur Continuer.

    4. Si vous souhaitez appliquer le contrôle dès sa création, activez l'option Publier cette commande immédiatement, puis cliquez sur Continuer.

  6. Cliquez sur Envoyer.

  7. Pour modifier la configuration d'un contrôle, procédez comme suit :

    1. Sur la page Signal, dans la liste des commandes d'amplification/d'enfouissement de l'application, cliquez sur  pour une commande que vous souhaitez modifier, puis sur Modifier.

    2. Modifiez le contrôle dans le volet Modifier le contrôle.

  8. Pour activer ou désactiver un contrôle, sur la page Signal, dans la liste des contrôles d'amplification/d'enfouissement de l'application, cliquez sur  pour le contrôle que vous souhaitez activer ou désactiver, puis cliquez sur Activer ou Désactiver, respectivement.

  9. Pour supprimer un contrôle, sur la page Signal, dans la liste des contrôles d'amplification/d'enfouissement de l'application, cliquez sur  pour le contrôle que vous souhaitez supprimer, puis sur Supprimer.

REST

Un contrôle de diffusion avec boost est défini comme un contrôle avec un boostAction.

Suivez les instructions ci-dessous pour créer un contrôle de diffusion d'amplification.

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous avez déjà votre ID d'application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Applications d'IA.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": [
  "USE_CASE"
],
"conditions": {
 "queryTerms": [
   {
     "value": "VALUE",
     "fullMatch": FULL_MATCH
   }
 ],
 "activeTimeRange": [
   {
     "startTime": "START_TIMESTAMP",
     "endTime": "END_TIMESTAMP"
   }
 ]
},
"boostAction": {
  "boost": BOOST_VALUE,
  "filter": "FILTER",
  "dataStore": "DATA_STORE_RESOURCE_PATH"
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application Vertex AI Search.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir entre 1 et 63 caractères (lettres, chiffres, tirets et traits de soulignement).
    • DISPLAY_NAME : nom lisible du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
    • USE_CASE : doit être défini sur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit le moment où le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut contenir au maximum trois termes séparés par des espaces.
      • FULL_MATCH : valeur booléenne indiquant si la requête de recherche doit correspondre exactement au terme de requête. Lorsqu'il est défini sur true, il exige que SearchRequest.query corresponde entièrement à queryTerm.value. Lorsqu'il est défini sur false, il exige que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
      • START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage de temps.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant la fin d'une période.
    • BOOST_VALUE : nombre à virgule flottante compris dans la plage [-1,1]. Lorsque la valeur est négative, les résultats sont rétrogradés (ils apparaissent plus bas dans les résultats). Lorsque la valeur est positive, les résultats sont mis en avant (ils apparaissent plus haut dans les résultats). Pour en savoir plus, consultez la page sur la méthode boostAction.
    • FILTER : chaîne spécifiant les exigences que le document doit respecter. Si le document répond à toutes les exigences, le boost est appliqué. Sinon, rien ne change. Si ce champ est vide, l'augmentation s'applique à tous les documents du data store. Pour connaître la syntaxe de filtrage, consultez Syntaxe des expressions de filtre. Remarque : Le champ de document title ne peut pas être filtré.
    • DATA_STORE_RESOURCE_PATH : chemin d'accès complet à la ressource du data store dont les documents doivent être mis en avant par ce contrôle. Le format du chemin d'accès complet à la ressource est projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Ce data store doit être associé au moteur spécifié dans la requête.

  3. Associez le contrôle à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
-d '{
 "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
}'

    Remplacez BOOST_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

Créer et associer des contrôles de diffusion de filtres

Un contrôle de diffusion de filtre est défini comme un contrôle avec un filterAction.

Suivez les instructions ci-dessous pour créer un contrôle de diffusion de filtre.

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous avez déjà votre ID d'application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Applications d'IA.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"filterAction": {
  "filter": "FILTER"
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application Vertex AI Search.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir entre 1 et 63 caractères (lettres, chiffres, tirets et traits de soulignement).
    • DISPLAY_NAME : nom lisible du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
    • USE_CASE : doit être défini sur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit le moment où le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut contenir au maximum trois termes séparés par des espaces.
      • FULL_MATCH : valeur booléenne indiquant si la requête de recherche doit correspondre exactement au terme de requête. Lorsqu'il est défini sur true, il exige que SearchRequest.query corresponde entièrement à queryTerm.value. Lorsqu'il est défini sur false, il exige que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
      • START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage de temps.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant la fin d'une période.
    • FILTER : chaîne spécifiant les exigences que le document doit respecter. Si le document répond à toutes les exigences, il est renvoyé dans les résultats. Sinon, le document ne figure pas dans les résultats. Pour connaître la syntaxe de filtrage, consultez la section Syntaxe des expressions de filtre. Pour en savoir plus, consultez la section consacrée à filterAction. Remarque : Le champ de document title ne peut pas être filtré.

  3. Associez le contrôle à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
-d '{
  "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
}'

    Remplacez FILTER_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

Créer et associer des contrôles de diffusion de synonymes

Un contrôle de diffusion de synonymes est défini comme un contrôle avec un synonymsAction.

Suivez les instructions ci-dessous pour créer un contrôle de diffusion des synonymes.

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous avez déjà votre ID d'application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Applications d'IA.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"synonymsAction": {
  "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application Vertex AI Search.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir entre 1 et 63 caractères (lettres, chiffres, tirets et traits de soulignement).
    • DISPLAY_NAME : nom lisible du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
    • USE_CASE : doit être défini sur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit le moment où le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut contenir au maximum trois termes séparés par des espaces.
      • FULL_MATCH : valeur booléenne indiquant si la requête de recherche doit correspondre exactement au terme de requête. Lorsqu'il est défini sur true, il exige que SearchRequest.query corresponde entièrement à queryTerm.value. Lorsqu'il est défini sur false, il exige que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
      • START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage de temps.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant la fin d'une période.
    • SYNONYMS_N : liste de chaînes associées les unes aux autres, ce qui augmente la probabilité que chacune d'elles affiche des résultats similaires. Bien qu'il soit plus probable que vous obteniez des résultats similaires lorsque vous recherchez chacune des entrées de synonymes, il est possible que vous ne receviez pas tous les résultats pertinents pour tous les synonymes associés. Vous devez spécifier au moins deux synonymes et vous pouvez en spécifier jusqu'à 100. Chaque synonyme doit être encodé au format UTF-8 et en minuscules. Les chaînes en double ne sont pas autorisées. Par exemple, vous pouvez ajouter "pixel", "téléphone Android" et "téléphone Google" comme synonymes. Pour en savoir plus, consultez synonymsAction.

  3. Associez le contrôle à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
-d '{
  "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
}'

    Remplacez SYNONYMS_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

Créer et associer des contrôles de diffusion de redirection

Une commande de diffusion de redirection permet de rediriger les utilisateurs vers un URI fourni. Les contrôles de redirection sont définis comme des contrôles avec un redirectAction.

Suivez les instructions ci-dessous pour créer un contrôle de diffusion de redirection.

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous avez déjà votre ID d'application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Applications d'IA.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"redirectAction": {
  "redirectURI": "REDIRECT_URI"
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application Vertex AI Search.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir entre 1 et 63 caractères (lettres, chiffres, tirets et traits de soulignement).
    • DISPLAY_NAME : nom lisible du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
    • USE_CASE : doit être défini sur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • CONDITION : champ facultatif qui définit le moment où le contrôle doit être appliqué. Contient les champs suivants :
      • VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ peut contenir au maximum trois termes séparés par des espaces.
      • FULL_MATCH : valeur booléenne indiquant si la requête de recherche doit correspondre exactement au terme de requête. Lorsqu'il est défini sur true, il exige que SearchRequest.query corresponde entièrement à queryTerm.value. Lorsqu'il est défini sur false, il exige que SearchRequest.query contienne queryTerm.value en tant que sous-chaîne.
      • START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage de temps.
      • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant la fin d'une période.
    • REDIRECT_URI_N : URI vers lequel vous êtes redirigé. Ne doit pas comporter plus de 2 000 caractères. Par exemple, si la valeur du terme de requête est "assistance", vous pouvez définir une redirection vers votre page d'assistance technique au lieu de renvoyer (ou de ne pas renvoyer) des résultats de recherche pour "assistance". Dans cet exemple, l'URI de redirection devient "https://www.example.com/support". Pour en savoir plus, consultez la section consacrée à redirectAction.

  3. Associez le contrôle à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
-d '{
  "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
}'

    Remplacez REDIRECT_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

Créer et associer des contrôles de diffusion de promotion

Un contrôle de diffusion de promotion vous permet d'afficher un lien en tant que résultat sponsorisé. Il est disponible pour les types de magasins de données de recherche suivants :

  • Data stores de sites Web avec recherche de site Web de base : pour ces data stores, vous n'avez pas besoin d'associer un contrôle de promotion à la configuration de diffusion de l'application. La création et l'activation d'un contrôle de promotion activent le contrôle de promotion. Vous pouvez activer ou désactiver un contrôle de promotion.

  • Data stores avec données structurées et non structurées, données de site Web avec indexation avancée de sites Web et applications de recherche combinée : pour ces data stores, vous devez associer le contrôle de promotion à la configuration de diffusion.

Les contrôles de promotion sont définis à l'aide d'un promoteAction.

Pour créer un contrôle de promotion, l'un des champs suivants est obligatoire dans la demande de création :

  • queryTerms : cette condition ne peut pas être spécifiée si vous spécifiez la condition queryRegex, qui ne s'applique qu'à la recherche de base sur le Web. Pour la recherche de base sur un site Web, fullMatch doit être défini sur true si queryTerms est spécifié. Pour toutes les autres applications de recherche, seule queryTerms est acceptée et fullMatch peut être défini sur true ou false.
  • queryRegex. Disponible uniquement pour un paramètre de diffusion de la promotion pour la recherche de base sur le site Web. Cette condition applique le contrôle lorsque la requête correspond à l'expression régulière spécifiée. Cette condition ne peut pas être spécifiée si vous spécifiez la condition queryTerms.

Autrement dit, pour la recherche de base sur un site Web, vous devez soit spécifier le champ queryTerms avec fullMatch défini sur true, soit spécifier le champ queryRegex. Pour tous les autres types de recherche, spécifiez le champ queryTerms avec fullMatch défini sur true ou false.

Suivez les instructions ci-dessous pour créer un contrôle de promotion de la diffusion.

Pour en savoir plus sur les champs, consultez la documentation de référence de l'API engines.controls et la documentation de référence de l'API engines.controls.create.

  1. Trouvez l'ID de votre application. Si vous avez déjà votre ID d'application, passez à l'étape suivante.

    1. Dans la console Google Cloud , accédez à la page Applications d'IA.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et récupérez son ID dans la colonne ID.

  2. Exécutez les commandes curl suivantes pour créer vos contrôles.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": true
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ],
  "queryRegex": "VALUE_REGEX"
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "DESCRIPTION",
     "enabled": ENABLED_TRUE|FALSE,
  }
 }
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : numéro ou ID de votre projet Google Cloud .
    • APP_ID : ID de l'application Vertex AI Search.
    • CONTROL_ID : identifiant unique du contrôle. L'ID peut contenir entre 1 et 63 caractères (lettres, chiffres, tirets et traits de soulignement).
    • DISPLAY_NAME : nom lisible du contrôle. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée au format UTF-8,dont la longueur est comprise entre 1 et 128.
    • USE_CASE : doit être défini sur SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Si SEARCH_USE_CASE_BROWSE est spécifié, Condition.queryTerms ne peut pas être utilisé dans la condition.
    • Condition : objet facultatif qui définit le moment où le contrôle doit être appliqué. Contient les champs suivants :
      • queryTerms : il ne peut pas être utilisé avec le champ queryRegex.
        • VALUE : valeur de requête spécifique à comparer. Il s'agit d'une chaîne UTF-8 en minuscules de longueur [1, 5000].
      • activeTimeRange :
        • START_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" pour indiquer le début d'une plage de temps.
        • END_TIMESTAMP : code temporel au format RFC 3339 UTC "Zulu" indiquant la fin d'une période.
      • queryRegex : uniquement disponible pour les data stores avec recherche de base sur le site Web. Ce champ ne peut pas être utilisé avec le champ queryTerms.
        • VALUE_REGEX : expression régulière à laquelle la requête doit correspondre.
    • DATA_STORE_RESOURCE_PATH : chemin d'accès complet à la ressource du data store dont les résultats de recherche contiennent l'URL promue. Le format du chemin d'accès complet à la ressource est projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Ce data store doit être associé au moteur spécifié dans la requête.
    • DOCUMENT_RESOURCE_PATH : champ permettant de spécifier le chemin d'accès à la ressource du document à promouvoir :
      • Pour les datastores de recherche contenant des données structurées et non structurées, vous devez fournir le chemin d'accès à la ressource du document dans le champ DOCUMENT_RESOURCE_PATH, l'URI dans le champ URI, ou les deux. Le format du chemin d'accès complet à la ressource est projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.
      • Pour les data stores de site Web, ce champ doit être non défini et le champ URI doit être défini à la place.
    • TITLE : champ obligatoire permettant de spécifier le titre du document ou de la page Web à promouvoir. Ce titre s'affiche dans le résultat de recherche.
    • URI : champ obligatoire permettant de spécifier le lien URI vers lequel le résultat de recherche redirige l'utilisateur. Cette URI n'a pas besoin d'être incluse dans le data store.
      • Pour les datastores de recherche contenant des données structurées et non structurées, vous devez fournir le chemin d'accès à la ressource du document dans le champ DOCUMENT_RESOURCE_PATH, l'URI dans le champ URI, ou les deux.
      • Pour les datastores de site Web, il s'agit d'un champ obligatoire que vous devez définir.
    • DESCRIPTION : champ facultatif permettant de décrire le document ou la page Web à promouvoir, qui s'affiche dans le résultat de recherche.
    • ENABLED_TRUE|FALSE : champ booléen facultatif permettant d'indiquer si le contrôle de promotion est activé et associé à l'application. Ce champ s'applique uniquement aux data stores de site Web avec la recherche de site Web de base. Lorsque vous définissez ce champ sur false, le paramètre de promotion de la diffusion est désactivé. Pour que le paramètre prenne effet, vous devez le mettre à jour en l'activant, comme expliqué à l'étape suivante. Pour en savoir plus, consultez la section consacrée à promoteAction.

  3. Pour toutes les applications de recherche, à l'exception de la recherche de base sur un site Web, associez le contrôle à la configuration de diffusion de l'application à l'aide de la méthode engines.servingConfigs.patch. L'ordre dans lequel les promoteControlIds sont associés dans la requête suivante correspond à l'ordre dans lequel les résultats sponsorisés sont renvoyés.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=promote_control_ids" \
-d '{
  "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]
}'

    Remplacez PROMOTE_ID_N par les ID de contrôle que vous avez créés à l'étape précédente.

  4. Facultatif : Pour la recherche de base sur le site Web, vous n'avez pas besoin d'associer le contrôle à la configuration de diffusion de l'application. Toutefois, pour la recherche de base sur le site Web, vous pouvez activer ou désactiver une commande de promotion après sa création en appelant la méthode engines.control.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled" \
-d '{
"promoteAction": {
  "searchLinkPromotion": {
     "enabled": ENABLED_TRUE|FALSE,
  }
}
}'

Exemple

Lorsque vous envoyez une requête de recherche à l'application avec une requête qui correspond à la requête ou à l'expression régulière de requête spécifiée pour le contrôle de promotion, le lien promu s'affiche dans la réponse.

Par exemple, supposons que vous créiez un contrôle de promotion avec la configuration suivante dans un data store avec une recherche de site Web de base :

{
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "artificial intelligence",
         "fullMatch": true
       }
     ]
   }
 ]"
 ...
 promoteAction": {
  "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \
  "searchLinkPromotion": {
    "title": "What is AI?",
    "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
    "description": "Explain what is AI"
    "enabled": true
  }
 }
}

Vous envoyez ensuite la requête search suivante :

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \
  -d '{
"query": "artificial intelligence"
}'

Vous devriez recevoir une réponse JSON semblable à la réponse tronquée suivante. La réponse contient le champ searchLinkPromotions qui contient le lien sponsorisé.

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

Étapes suivantes

  • Pour comprendre l'impact d'un contrôle de diffusion sur la qualité de recherche d'une application de recherche personnalisée, évaluez la qualité de recherche. Pour en savoir plus, consultez Évaluer la qualité de la recherche.