Obtenir des résultats de recherche (ancienne version)

Cette page explique comment obtenir des résultats de recherche à l'aide de l'API.

Vous pouvez effectuer des appels d'API et les intégrer à votre serveur ou à votre application. Cette page inclut des exemples de code expliquant comment 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 obtenir des résultats de recherche à l'aide de l'API.

REST

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

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

    1. Dans la Google Cloud console, accédez à la Gemini Enterprise page.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et obtenez son ID dans la colonne ID.

  2. Affichez un aperçu des 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 : par l'ID de l'application que vous souhaitez interroger.
    • QUERY : par le texte de la requête à rechercher.
    • USER_PSEUDO_ID: par une chaîne encodée en UTF-8, qui sert d'identifiant pseudonymisé unique permettant de suivre les utilisateurs. Sa longueur maximale est de 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 à un site Web ou s'en déconnecte.
      • 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 dégrader 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 userPseudoId.

    • PAGE_SIZE: par le 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 forcées à la valeur maximale.

    • OFFSET : facultatif. Index de début 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 15 résultats doivent être renvoyés, 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 données.

    • BOOST_SPEC : facultatif. Spécification permettant de mettre en avant ou de masquer 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 boosting est appliqué. Le filtre doit renvoyer une valeur booléenne.

      Pour en savoir plus sur le boosting pour la recherche structurée, consultez Mettre en avant les résultats de recherche.

    • FACET_SPEC : facultatif. Spécification d'attribut permettant d'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. Permet d'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 :

    • 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 connectée à plusieurs datastores. Pour en savoir plus, consultez DataStoreSpec.

    • Afficher les résultats de 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 émettant 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é de la requête avec le document. Les scores sont répartis dans 11 buckets compris dans la plage : 0, 0.1, 0.2, … à 1.0. Plus le score est élevé, plus le document est pertinent.

Tenez compte des scores de pertinence des documents pour les cas d'utilisation suivants :

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

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

  • Débogage : les scores de pertinence peuvent fournir des informations sur la raison pour laquelle 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, use the engines.servingConfigs.search method as follows:

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

    1. Dans la Google Cloud console, accédez à la Gemini Enterprise page.

      Accédez à "Applications".

    2. Sur la page Applications, recherchez le nom de votre application et obtenez son ID dans la colonne ID.

  2. Exécutez la commande curl suivante pour que les scores soient 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 : par l'ID de l'application que vous souhaitez interroger.
    • QUERY : par le texte de la requête à rechercher.

La synthèse de recherche diffère 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 les résultats de l'API. Si cela se produit, la raison probable est que la console utilise un modèle LLM différent de celui de l'API. Les exemples de code et de 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 résumé et Spécifier le modèle de réponse.