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 permettant d'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 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 disposez déjà de l'ID de votre 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évisualiser 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 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 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 réduites à 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, que 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) : Un champ de texte pour 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 booster ou d'enterrer des documents. Valeurs :

      • BOOST : nombre à virgule flottante compris entre -1 et 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 promus (ils apparaissent plus haut dans les résultats).
      • CONDITION : expression de filtre de texte pour sélectionner les documents auxquels l'amélioration est appliquée. Le filtre doit renvoyer une valeur booléenne.

      Pour en savoir plus sur l'amélioration de la recherche structurée, consultez Améliorer les résultats de recherche.

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

    • QUERY_EXPANSION_SPEC (facultatif) : Spécification permettant de déterminer dans quelles conditions l'extension des requêtes doit se produire. 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 :

    • DATA_STORE_SPEC : filtre pour un data store spécifique dans lequel effectuer la recherche. Vous pouvez l'utiliser 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 les recherches structurées et non structurées. Le résultat de la recherche guidée contient une liste de paires clé/valeur d'attributs extraites en fonction des documents des 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é de la requête avec le document. Les scores sont répartis dans 11 buckets de 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 après la recherche en fonction du score de pertinence pour supprimer les résultats non pertinents

  • Classement après recherche ou en tant qu'entrée pour d'autres applications

  • Débogage : les scores de pertinence peuvent expliquer 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ées ou non structurées.

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 disposez déjà de l'ID de votre 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.

Le résumé 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 ceux de l'API. Si vous voyez cela, c'est probablement parce que la console utilise un modèle de LLM différent de l'API. Les exemples curl et de code de cette page utilisent le modèle LLM stable.

  • Pour modifier ou afficher le modèle de 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 de 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.