Importer les données de saisie semi-automatique pour la recherche

Aperçu {/10)

Cette fonctionnalité est régie par les Conditions des offres de pré-DG des conditions d'utilisation de Google Cloud. Les fonctionnalités pré-DG risquent de ne pas être compatibles, et les modifications apportées aux fonctionnalités pré-DG risquent de ne pas être compatibles avec d'autres versions pré-DG. Pour en savoir plus, consultez les descriptions des étapes de lancement.

La saisie semi-automatique permet de prédire le reste du mot saisi par l'utilisateur, ce qui peut améliorer l'expérience de recherche. Cette fonctionnalité peut fournir des suggestions basées sur l'ensemble de données ou sur les événements utilisateur que vous lui fournissez.

N'importez des données de saisie semi-automatique que si vous souhaitez disposer de commandes supplémentaires (liste à ne pas supprimer, liste de refus) ou si vous devez utiliser vos propres données de saisie semi-automatique. L'activation de l'apprentissage automatique suffit dans la plupart des cas. L'apprentissage automatique fournit un ensemble de données de suggestions basées sur le machine learning basé sur des événements de recherche d'utilisateurs. Consultez la section Saisie semi-automatique pour savoir comment activer l'apprentissage automatique.

Remarque:À partir de septembre 2022, vous pourrez utiliser l'interface utilisateur de Cloud Console > Commandes > Commandes de saisie semi-automatique pour déclencher l'importation de données.

Ces instructions ne concernent que l'importation de vos propres données de saisie semi-automatique. Tenez-le à jour si vous prévoyez d'utiliser votre ensemble de données de saisie semi-automatique en permanence. Pour découvrir comment obtenir des résultats de la saisie semi-automatique au moment de la requête, reportez-vous à CompletedService.CompleteQuery. Les données de saisie semi-automatique ne sont utilisées que pour Retail Search. Ces données ne sont pas utilisées par Recommendations AI.

Avant de commencer

Avant d'importer les informations de saisie semi-automatique, vous devez avoir suivi les instructions de la section Avant de commencer, en particulier la configuration de votre projet, la création d'un compte de service et l'ajout de ce compte à votre environnement local.

Vous devez disposer du rôle IAM Éditeur Retail pour effectuer l'importation.

Saisie semi-automatique : bonnes pratiques d'importation

Lorsque vous importez des données de saisie semi-automatique, veillez à appliquer les bonnes pratiques suivantes:

• Lisez le schéma BigQuery répertorié dans les sections suivantes et la documentation sur l'API.

• N'utilisez pas de valeurs d'espaces réservés.

• Incluez autant de champs que possible.

• Si vous envisagez d'utiliser un ensemble de données importé, assurez-vous que votre propre ensemble de données de saisie semi-automatique est à jour.

• L'importation de données à partir d'un autre projet n'est pas autorisée.

Importer les données de saisie semi-automatique

Importer les données de saisie semi-automatique depuis BigQuery

Retail accepte l'importation de données BigQuery pour les listes de refus, de ne pas supprimer et de termes de suggestion. Pour en savoir plus, consultez la section Saisie semi-automatique.

Pour importer des données de saisie semi-automatique au format approprié depuis BigQuery, utilisez le schéma de saisie semi-automatique pour le commerce afin de créer une table BigQuery au format approprié et de charger la table avec vos données de saisie semi-automatique. Ensuite, importez vos données dans Retail.

Pour plus d'informations sur les tables BigQuery, consultez la page Présentation des tables. Pour obtenir de l'aide sur les requêtes BigQuery, consultez la page Présentation des requêtes de données dans BigQuery.

Emplacement de l'ensemble de données BigQuery

Lorsque vous créez votre ensemble de données BigQuery pour vos tables BigQuery de saisie semi-automatique, assurez-vous que l'ensemble de données BigQuery est défini sur l'emplacement multirégional "US". Si vous ne la définissez pas correctement, votre requête d'importation échouera ultérieurement. Pour en savoir plus sur les emplacements d'ensembles de données BigQuery, consultez la page Emplacements des ensembles de données dans la documentation BigQuery.

Insérer les données dans BigQuery

Utilisez le schéma de saisie semi-automatique pour le commerce pour importer vos données de saisie semi-automatique dans BigQuery.

BigQuery peut utiliser le schéma pour vérifier si les données au format JSON présentent des noms et des types de champ corrects (tels que STRING, INTEGER et RECORD), mais n'est pas capable de vérifier :

• Si un champ de chaîne est mappé sur une valeur d'énumération reconnaissable.
• Si un champ de chaîne utilise le format approprié.
• Si la valeur d'un champ de type entier ou nombre à virgule flottante se situe dans une plage valide.
• Si un champ manquant est un champ obligatoire.

Pour garantir la qualité de vos données et de l'expérience de recherche des utilisateurs finaux, veillez à vous reporter au schéma et à la documentation de référence pour plus de détails sur les valeurs et sur les formats à utiliser.

Configurer l'accès à votre ensemble de données BigQuery

Pour configurer l'accès, assurez-vous que votre ensemble de données BigQuery se trouve dans le même projet que votre service Retail, puis suivez la procédure ci-dessous.

1. Ouvrez la page "IAM" dans Google Cloud Console.

   Ouvrir la page IAM

2. Sélectionnez votre projet Retail.

3. Sur la page IAM et administration, cliquez sur Accorder l'accès.

4. Dans le champ Nouveaux comptes principaux, saisissez [e-mail] et sélectionnez le rôle BigQuery > Lecteur de données BigQuery.

   Si vous ne souhaitez pas attribuer le rôle de lecteur de données sur l'ensemble du projet, vous pouvez l'ajouter directement au niveau de l'ensemble de données. En savoir plus

5. Cliquez sur Enregistrer.

Déclencher l'importation de données vers Retail

Console

1. Accéder à la page "Contrôles"

2. Accédez à l'onglet Commandes de saisie semi-automatique.

3. Dans la section Listes de termes, recherchez le type de liste que vous souhaitez importer (Liste de refus, Liste à ne pas supprimer ou Liste de termes suggérés), puis cliquez sur Importer ou Remplacer.

   Le volet Importer s'ouvre.

4. Saisissez le chemin BigQuery de votre emplacement de données ou cliquez sur Parcourir pour sélectionner l'emplacement.

   Le chemin BigQuery doit se trouver dans le même projet et son schéma doit être correct. Pour le vérifier, cliquez sur Parcourir, puis sur le nom de la table pour afficher son contenu dans la console BigQuery.

5. Dans le volet Importer, cliquez sur Importer.

   L'importation commence. Vous pouvez quitter la page sans interrompre l'importation.

cURL

1. Créez un fichier de données pour les paramètres d'entrée de l'importation. Les valeurs de vos paramètres d'entrée varient selon que vous importez depuis Cloud Storage ou BigQuery.

   Utilisez l'objet BigQuerySource pour pointer vers votre ensemble de données BigQuery.

   • dataset-id : ID de l'ensemble de données BigQuery.
   • table-id : ID de la table BigQuery contenant vos données.
   • data-schema : pour la propriété dataSchema, utilisez les valeurs suggestions (par défaut), allowlist et denylist. Utilisez le schéma de saisie semi-automatique pour le commerce.

   {
     "inputConfig":{
       "bigQuerySource": {
         "datasetId":"dataset-id",
         "tableId":"table-id",
         "dataSchema":"data-schema"
       }
     }
   }
   

2. Importez les informations de saisie semi-automatique dans Retail en envoyant une requête POST à la méthode REST CompletionData:import, en fournissant le nom du fichier de données (indiqué sous la forme input.json dans l'exemple ci-dessous).

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" -d @./input.json
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionData:import"
   

   Vous pouvez vérifier l'état de manière automatisée avec l'API. Vous devriez recevoir un objet de réponse ressemblant à ceci :

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "done": false
   }
   

   Le champ de nom est l'ID de l'objet d'opération. Pour demander l'état de cet objet, remplacez le champ de nom par la valeur renvoyée par la méthode d'importation. Une fois l'importation terminée, le champ done renvoie true:

   curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456"
   

   Une fois l'opération terminée, l'objet renvoyé a une valeur done de true et inclut un objet Status semblable à l'exemple suivant :

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
       "createTime": "2020-01-01T03:33:33.000001Z",
       "updateTime": "2020-01-01T03:34:33.000001Z",
       "successCount": "2",
       "failureCount": "1"
     },
     "done": true
     "response": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
     }
   }
   

Format de données pour la saisie semi-automatique

Votre fichier JSON doit ressembler aux exemples suivants. Les sauts de ligne ne sont là que pour des raisons de lisibilité. Vous devez fournir une suggestion entière sur une seule ligne. Chaque suggestion doit figurer sur une ligne distincte.

Champs obligatoires pour la suggestion :

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

ou

{
  "suggestion": "ABC",
  "frequency": "100"
}

Durée de l'importation de données via la saisie semi-automatique

L'exécution d'une importation depuis BigQuery prend généralement de quelques minutes à une heure.

Une fois l'importation de l'ensemble de données terminée, le champ done de l'objet d'opération est défini sur "true". Passé ce délai, l'indexation des données et leur utilisation en production peut prendre un à deux jours supplémentaires.

Maintenez votre ensemble de données de saisie semi-automatique à jour

Si vous prévoyez d'utiliser votre propre ensemble de données importé, il est recommandé de maintenir régulièrement l'ensemble de données importé à jour.

Mise à jour groupée

Vous pouvez utiliser la méthode d'importation pour mettre à jour votre saisie semi-automatique de manière groupée. Pour ce faire, suivez la même procédure que pour l'importation initiale : suivez les étapes de la section Importer des données de saisie semi-automatique. Cette action remplacera l'intégralité de l'ensemble de données importé.

Surveiller l'état d'importation

Pour toujours obtenir des suggestions de haute qualité lorsque vous utilisez la saisie semi-automatique, il est important de maintenir votre ensemble de données à jour. Vous devez surveiller les taux d'erreur d'importation et prendre des mesures, le cas échéant.

Schéma Retail Autocomplete

Lorsque vous importez un ensemble de données de saisie semi-automatique depuis BigQuery, utilisez le schéma Retail ci-dessous pour créer des tables BigQuery avec le format approprié et les charger avec vos données de saisie semi-automatique.

Schéma des suggestions

Cet ensemble de données permet de fournir vos propres expressions de suggestion de saisie semi-automatique avec vos propres scores.

Schéma JSON des suggestions de saisie semi-automatique pour le commerce

JSON

[
  {
    "description": "The suggestion text",
    "mode": "NULLABLE",
    "name": "suggestion",
    "type": "STRING"
  },
  {
    "description": "Global score of this suggestion. Control how this suggestion would be scored / ranked. Only one of this and frequency should be set.",
    "mode": "NULLABLE",
    "name": "globalScore",
    "type": "FLOAT"
  },
  {
    "description": "Frequency of this suggestion. Will be used to rank suggestions when score is not available.",
    "mode": "NULLABLE",
    "name": "frequency",
    "type": "INTEGER"
  },
  {
    "description": "BCP-47 language code of this suggestion.",
    "mode": "NULLABLE",
    "name": "languageCode",
    "type": "STRING"
  },
  {
    "description": "If two suggestions have the same groupID, they will not be returned together. Instead the one ranked higher will be returned. This can be used to deduplicate semantically identical suggestions.",
    "mode": "NULLABLE",
    "name": "groupID",
    "type": "STRING"
  },
  {
    "description": "The score of this suggestion within its group",
    "mode": "NULLABLE",
    "name": "groupScore",
    "type": "FLOAT"
  },
  {
    "description": "Device type for this suggestion.",
    "mode": "NULLABLE",
    "name": "deviceType",
    "type": "STRING"
  },
  {
    "description": "Alternative matching phrases for this suggestion.",
    "mode": "REPEATED",
    "name": "alternativePhrases",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "description": "The name of the custom attribute.",
        "mode": "NULLABLE",
        "name": "key",
        "type": "STRING"
      },
      {
        "fields": [
          {
            "description": "The textual values of this custom attribute.",
            "mode": "REPEATED",
            "name": "text",
            "type": "STRING"
          },
          {
            "description": "The numerical values of this custom attribute.",
            "mode": "REPEATED",
            "name": "numbers",
            "type": "FLOAT"
          }
        ],
        "mode": "NULLABLE",
        "name": "value",
        "type": "RECORD"
      }
    ],
    "description": "A custom attribute that is not explicitly modeled, which can be retrieved together with the suggestion at serving time.",
    "mode": "REPEATED",
    "name": "customAttributes",
    "type": "RECORD"
  }
]

Schéma de la liste de blocage

Cet ensemble de données est utilisé comme liste de blocage pour empêcher la suggestion de certaines expressions.

Schéma JSON de la saisie semi-automatique pour le commerce de détail : JSON

JSON

[
  {
    "description": "The phrase to block from autocomplete suggestions.",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Choose whether to block the exact phrase, or block any suggestions containing this phrase. Supported value \"EXACT_MATCH\", \"CONTAINS\"",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]

Schéma de la liste d'autorisation

Cet ensemble de données permet d'ignorer des processus de post (correction orthographique et filtrage des résultats zéros, par exemple) pour toutes les phrases de cette liste d'autorisation.

JSON : schéma de la liste d'autorisation pour la saisie semi-automatique pour le commerce

JSON

[
  {
    "description": "The phrase to be exempted from autocomplete post processing, e.g. spell correction, filtering",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Whether to match the exact phrase, or any suggestions contain this phrase. Supported values are \"EXACT_MATCH\", \"CONTAINS\".",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]