Obtenir des résultats de recherche

Cette page explique comment prévisualiser les résultats de recherche à l'aide de la console Google Cloud et comment obtenir des résultats de recherche à l'aide de l'API.

De plus, au lieu d'utiliser l'interface utilisateur de l'application Web, vous pouvez effectuer des appels d'API et les intégrer à votre serveur ou à votre application. Cette page inclut des exemples de code pour effectuer des requêtes de recherche à l'aide des bibliothèques clientes gRPC avec un compte de service.

Obtenir des résultats de recherche

Vous pouvez prévisualiser les résultats de recherche depuis la console  Google Cloud ou les obtenir à l'aide de l'API.

Console

Pour prévisualiser les résultats de recherche d'une application avec des données structurées ou non structurées à l'aide de la console Google Cloud , procédez comme suit :

  1. Ouvrez la page Aperçu dans la console.
  2. Saisissez une requête de recherche.
    1. Si vous avez activé la saisie semi-automatique à l'étape 1, une liste de suggestions s'affiche sous la barre de recherche à mesure que vous saisissez du texte.
  3. (Facultatif) Si vous avez associé plusieurs data stores à votre application, mais que vous ne souhaitez obtenir des résultats que d'un data store spécifique, sélectionnez-le.
  4. Cliquez sur Entrée pour envoyer la requête.
    1. Une liste de résultats de recherche s'affiche sous la barre de recherche.
    2. Si aucun mappage d'attribut n'est défini sur la page Configurations, chaque résultat de recherche s'affiche sous la forme d'une liste de noms et de valeurs d'attributs bruts.
    3. Si des mappages d'attributs ont été enregistrés sur la page Configurations, les résultats de recherche affichent les mêmes images que celles de l'aperçu de la page Configurations.
  5. Si des facettes ont été spécifiées sur la page Configurations, elles s'affichent de la même manière.
  6. Cliquez sur la flèche sous la liste des résultats pour charger la page suivante.

REST

Pour utiliser l'API afin d'obtenir des résultats de recherche pour une application basée sur des données structurées ou non structurées, utilisez la méthode engines.servingConfigs.search :

  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 Gemini Enterprise.

      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. Prévisualisez les résultats de recherche.

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
-d '{
"query": "QUERY",
"userPseudoId": "USER_PSEUDO_ID",
"pageSize": "PAGE_SIZE",
"offset": "OFFSET",
"orderBy": "ORDER_BY",
"filter": "FILTER",
"boostSpec": "BOOST_SPEC",
"facetSpec": "FACET_SPEC",
"queryExpansionSpec": "QUERY_EXPANSION_SPEC",
"spellCorrectionSpec": "SPELL_CORRECTION_SPEC",
"contentSearchSpec": "CONTENT_SEARCH_SPEC",
"dataStoreSpecs": [{"DATA_STORE_SPEC"}],
}'

    Remplacez les éléments suivants :

    • PROJECT_ID : par l'ID du projet.
    • APP_ID : ID de l'application que vous souhaitez interroger.
    • QUERY : texte de la requête à rechercher.
    • USER_PSEUDO_ID : chaîne encodée en UTF-8, qui sert d'identifiant pseudonymisé unique pour suivre les utilisateurs. Il peut comporter jusqu'à 128 caractères. Google vous recommande vivement d'utiliser ce champ, car il améliore les performances du modèle et la qualité de la personnalisation. Vous pouvez utiliser un cookie HTTP pour ce champ, qui identifie de manière unique un visiteur sur un seul appareil. Voici quelques points importants à prendre en compte :

      • Cet identifiant ne change pas lorsque le visiteur se connecte ou se déconnecte d'un site Web.
      • Ce champ ne doit pas être défini sur le même identifiant pour plusieurs utilisateurs. Sinon, l'utilisation du même ID utilisateur pour plusieurs utilisateurs peut combiner les historiques d'événements de différents utilisateurs et nuire à la qualité du modèle.
      • Ce champ ne doit pas inclure d'informations permettant d'identifier personnellement l'utilisateur.
      • Pour une requête de recherche ou de navigation donnée, ce champ doit correspondre au champ userPseudoId correspondant dans les événements utilisateur.

      Pour en savoir plus, consultez les sections sur userPseudoId

    • PAGE_SIZE : nombre de résultats renvoyés par la recherche. La taille de page maximale autorisée dépend du type de données. Les tailles de page supérieures à la valeur maximale sont ramenées à la valeur maximale.

    • OFFSET (facultatif) : Index de départ des résultats. La valeur par défaut est 0.

      Par exemple, si le décalage est de 2, la taille de la page est de 10 et qu'il y a 15 résultats à renvoyer, les résultats 2 à 11 sont renvoyés sur la première page.

    • ORDER_BY (facultatif) : Ordre dans lequel les résultats sont organisés.

    • FILTER (facultatif) : Champ de texte permettant de filtrer votre recherche à l'aide d'une expression de filtre. La valeur par défaut est une chaîne vide, ce qui signifie qu'aucun filtre n'est appliqué.

      Exemple : color: ANY("red", "blue") AND score: IN(*, 100.0e)

      Pour en savoir plus, consultez Filtrer la recherche de données structurées ou non structurées.

    • BOOST_SPEC (facultatif) : Spécification permettant de mettre en avant ou d'enterrer des documents. Valeurs :

      • BOOST : 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).
      • CONDITION : expression de filtre de texte permettant de sélectionner les documents auxquels le boost est appliqué. Le filtre doit renvoyer une valeur booléenne.

      Pour en savoir plus sur l'optimisation de la recherche structurée, consultez Optimiser les résultats de recherche.

    • FACET_SPEC (facultatif) : Spécification d'attributs pour effectuer une recherche par attributs.

    • QUERY_EXPANSION_SPEC (facultatif) : Spécification permettant de déterminer dans quelles conditions l'expansion de requête doit avoir lieu. La valeur par défaut est DISABLED.

    • SPELL_CORRECTION_SPEC (facultatif) : Spécification permettant de déterminer dans quelles conditions la correction orthographique doit avoir lieu. La valeur par défaut est AUTO.

    • CONTENT_SEARCH_SPEC (facultatif) : Pour obtenir des extraits, des réponses extractives, des segments extractifs et des résumés de recherche. Pour les données non structurées uniquement. Pour en savoir plus, consultez les pages suivantes :

    • DATA_STORE_SPEC : filtres pour un data store spécifique dans lequel effectuer la recherche. Vous pouvez utiliser cette option si votre application de recherche est associée à plusieurs data stores. Pour en savoir plus, consultez DataStoreSpec.

    • Afficher les résultats de la recherche guidée dans la réponse à la recherche :

      Les résultats de recherche guidée sont renvoyés avec les réponses de recherche pour la recherche structurée et non structurée. Le résultat de recherche guidée contient une liste de paires clé/valeur d'attributs extraites en fonction des documents de résultats de recherche. Cela permet aux utilisateurs d'affiner leurs résultats de recherche en utilisant certaines clés et valeurs d'attributs comme filtres.

      Dans cet exemple de réponse, la couleur verte a été utilisée pour affiner les résultats de recherche en envoyant une nouvelle requête de recherche avec le champ de filtre spécifié comme _gs.color: ANY("green") :

      {
"guidedSearchResult": {
  "refinementAttributes": [
    {
      "attributeKey": "_gs.color",
      "attributeValue": "green"
    },
    {
      "attributeKey": "_gs.category",
      "attributeValue": "shoe"
    }
  ]
}
}

Obtenir des scores de pertinence des documents avec les résultats de recherche

Les scores de pertinence des documents sont basés sur la similarité entre la requête et le document. Les scores sont répartis dans 11 buckets, de 0 à 1 (0, 0,1, 0,2, etc.). Plus le score est élevé, plus le document est pertinent.

Voici quelques exemples de cas d'utilisation des scores de pertinence des documents :

  • Filtrage post-recherche basé sur le score de pertinence pour supprimer les résultats non pertinents

  • Classement post-recherche ou en tant qu'entrée pour d'autres applications

  • Débogage : les scores de pertinence peuvent vous aider à comprendre pourquoi certains résultats de recherche sont renvoyés.

Pour chaque résultat de recherche, un score de pertinence peut être renvoyé :

  "results": [
    {
      "id": "DOCUMENT_ID",
      "document": {
      ...
      },
      "modelScores": {
        "relevance_score": {
          "values": [
            DOCUMENT-RELEVANCE-SCORE
          ]
        }
      }
    },
    ...

Consultez également l'exemple de commande dans la procédure ci-dessous.

Avant de commencer : Assurez-vous que l'application de recherche est associée à un data store structuré ou non structuré.

REST

Pour demander que les scores de pertinence des documents soient renvoyés avec les résultats de recherche, utilisez la méthode engines.servingConfigs.search comme suit :

  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 Gemini Enterprise.

      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 la commande curl suivante pour obtenir les scores renvoyés avec les résultats de recherche.

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
-d '{
     "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search",
     "query": "QUERY",
     "relevanceScoreSpec": {
       "returnRelevanceScore": true
     }
}'
    • PROJECT_ID : par l'ID du projet.
    • APP_ID : ID de l'application que vous souhaitez interroger.
    • QUERY : texte de la requête à rechercher.

La synthèse de recherche varie selon le modèle

Si vous générez des résumés de recherche pour vos requêtes, vous remarquerez peut-être que les résumés diffèrent entre les résultats de la console et ceux de l'API. Si vous voyez ce message, la raison probable est que la console utilise un modèle LLM différent de celui de l'API. Les exemples de code et curl de cette page utilisent le modèle LLM stable.

  • Pour modifier ou afficher le modèle LLM utilisé sur la page Aperçu de l'UI, accédez à la page Configurations > onglet UI de votre application.

  • Pour les appels de méthode, le modèle stable est le modèle par défaut. Pour utiliser un modèle LLM autre que le modèle stable, consultez Spécifier le modèle de synthèse et Spécifier le modèle de réponse.