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

Configurer les commandes de diffusion pour la recherche

Les commandes de diffusion (également appelées commandes) modifient le comportement par défaut de la diffusion d'une requête lorsque des résultats sont renvoyés. Les commandes de diffusion agissent au niveau du magasin de données.

Par exemple, les commandes peuvent mettre en avant et masquer des résultats, filtrer les entrées des résultats renvoyés, associer des chaînes les unes aux autres en tant que synonymes ou rediriger les résultats vers des URI spécifiés.

Cette page décrit les commandes de diffusion pour les applications de recherche. Pour en savoir plus sur l'utilisation des commandes de diffusion avec les recommandations multimédias, consultez Créer et gérer des configurations de diffusion.

À 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 des résultats au moment de la diffusion, tels que des résultats de recherche ou des 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.

Certaines commandes, comme les commandes de boost, dépendent des magasins de données. Si un data store est supprimé d'une application, toutes les commandes dépendant de cet data store sont également supprimées de cette application et deviennent inactives, mais ne sont pas supprimées.

Types de commandes de diffusion

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

Contrôle	Description	Disponible pour
Contrôle du boost	Modifie l'ordre des résultats renvoyés	Applications de recherche avec des datastores compatibles avec un schéma, tels que des datastores contenant des données structurées, des sites Web avec des données structurées (indexation avancée des 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 datastores compatibles avec un schéma, tels que des datastores contenant des données structurées, des sites Web (indexation avancée et recherche de base sur les sites Web), des données non structurées avec des métadonnées ou des données multimédias
Contrôle des synonymes	Associe les requêtes les unes aux autres	Applications de recherche avec des data stores de site Web (indexation avancée de site Web), structurés, non structurés ou multimédias
Contrôle des redirections	Redirection vers un URI spécifié	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:

queryTerms : commande facultative appliquée 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é.
activeTimeRange : commande facultative appliquée lorsqu'une requête se produit dans une période spécifiée. Elle vérifie que l'heure à laquelle une requête a été reçue est comprise entre activeTimeRange.startTime et activeTimeRange.endTime. Vous pouvez spécifier jusqu'à 10 plages activeTimeRange sur un seul Control.condition. Si le champ activeTimeRange n'est pas spécifié, il est ignoré.

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

Prenons l'exemple suivant, dans lequel deux termes de requête sont spécifiés:

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

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

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

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 optimisée

Une commande de diffusion optimisée est définie comme une commande avec un boostAction.

Suivez les instructions ci-dessous pour créer une commande de diffusion optimisée.

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.

Recherchez votre ID d'application. Si vous disposez déjà de votre ID d'application, passez à l'étape suivante.
1. Dans la console Google Cloud, accédez à la page Agent Builder.
  
  Accédez à "Applications".
2. Sur la page Applications, recherchez le nom de votre application et obtenez son ID dans la colonne ID.
Exécutez les commandes curl suivantes pour créer vos commandes.
```
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 de la commande. L'ID peut contenir [1-63] caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
- DISPLAY_NAME: nom lisible de la commande. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
- 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 à faire correspondre. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ ne peut contenir au maximum que 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 la requête. Lorsque la valeur est true, SearchRequest.query doit correspondre complètement à queryTerm.value. Lorsque cette valeur est définie sur false, SearchRequest.query doit contenir queryTerm.value en tant que sous-chaîne.
  - START_TIMESTAMP: code temporel au format "Zulu" UTC RFC 3339 pour indiquer le début d'une plage horaire.
  - END_TIMESTAMP: code temporel au format "Zulu" UTC RFC 3339 pour indiquer la fin d'une plage temporelle.
- 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, aucune modification n'est apportée. Si ce champ est vide, l'amélioration est appliquée à tous les documents du data store. Pour connaître la syntaxe de filtrage, consultez la section 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 de l'espace de data store dont les documents doivent être optimisés 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.

Associez la commande à 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 une commande 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.

Recherchez votre ID d'application. Si vous disposez déjà de votre ID d'application, passez à l'étape suivante.
1. Dans la console Google Cloud, accédez à la page Agent Builder.
  
  Accédez à "Applications".
2. Sur la page Applications, recherchez le nom de votre application et obtenez son ID dans la colonne ID.
Exécutez les commandes curl suivantes pour créer vos commandes.
```
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 de la commande. L'ID peut contenir [1-63] caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
- DISPLAY_NAME: nom lisible de la commande. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
- 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 à faire correspondre. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ ne peut contenir au maximum que 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 la requête. Lorsque la valeur est true, SearchRequest.query doit correspondre complètement à queryTerm.value. Lorsque cette valeur est définie sur false, SearchRequest.query doit contenir queryTerm.value en tant que sous-chaîne.
  - START_TIMESTAMP: code temporel au format "Zulu" UTC RFC 3339 pour indiquer le début d'une plage horaire.
  - END_TIMESTAMP: code temporel au format "Zulu" UTC RFC 3339 pour indiquer la fin d'une plage temporelle.
- 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é.

Associez la commande à 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 des 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.

Recherchez votre ID d'application. Si vous disposez déjà de votre ID d'application, passez à l'étape suivante.
1. Dans la console Google Cloud, accédez à la page Agent Builder.
  
  Accédez à "Applications".
2. Sur la page Applications, recherchez le nom de votre application et obtenez son ID dans la colonne ID.
Exécutez les commandes curl suivantes pour créer vos commandes.
```
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 de la commande. L'ID peut contenir [1-63] caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
- DISPLAY_NAME: nom lisible de la commande. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
- 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 à faire correspondre. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ ne peut contenir au maximum que 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 la requête. Lorsque la valeur est true, SearchRequest.query doit correspondre complètement à queryTerm.value. Lorsque cette valeur est définie sur false, SearchRequest.query doit contenir queryTerm.value en tant que sous-chaîne.
  - START_TIMESTAMP: code temporel au format "Zulu" UTC RFC 3339 pour indiquer le début d'une plage horaire.
  - END_TIMESTAMP: code temporel au format "Zulu" UTC RFC 3339 pour indiquer la fin d'une plage temporelle.
- SYNONYMS_N: liste de chaînes associées les unes aux autres, ce qui rend plus probable 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, vous risquez de ne pas recevoir 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é en 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.

Associez la commande à 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 commandes de redirection sont définies comme une commande avec un redirectAction.

Suivez les instructions ci-dessous pour créer une commande 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.

Recherchez votre ID d'application. Si vous disposez déjà de votre ID d'application, passez à l'étape suivante.
1. Dans la console Google Cloud, accédez à la page Agent Builder.
  
  Accédez à "Applications".
2. Sur la page Applications, recherchez le nom de votre application et obtenez son ID dans la colonne ID.
Exécutez les commandes curl suivantes pour créer vos commandes.
```
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 de la commande. L'ID peut contenir [1-63] caractères, qui peuvent être des lettres, des chiffres, des traits d'union et des traits de soulignement.
- DISPLAY_NAME: nom lisible de la commande. Google recommande que ce nom indique quand ou pourquoi utiliser le contrôle. Doit être une chaîne encodée en UTF-8 d'une longueur comprise entre 1 et 128 caractères.
- 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 à faire correspondre. Il s'agit d'une chaîne UTF-8 en minuscules d'une longueur de [1, 5000]. Si FULL_MATCH_1 est défini sur true, ce champ ne peut contenir au maximum que 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 la requête. Lorsque la valeur est true, SearchRequest.query doit correspondre complètement à queryTerm.value. Lorsque cette valeur est définie sur false, SearchRequest.query doit contenir queryTerm.value en tant que sous-chaîne.
  - START_TIMESTAMP: code temporel au format "Zulu" UTC RFC 3339 pour indiquer le début d'une plage horaire.
  - END_TIMESTAMP: code temporel au format "Zulu" UTC RFC 3339 pour indiquer la fin d'une plage temporelle.
- REDIRECT_URI_N: URI vers lequel vous êtes redirigé. Il peut comporter jusqu'à 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) les 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.

Associez la commande à 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.

Étape suivante

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