Vous pouvez connecter Gemini à vos sources de données externes en ancrant vos données avec votre API Search. Cela vous permet d'utiliser n'importe quel service de recherche comme source d'ancrage pour Gemini, ce qui permet de s'assurer que les réponses sont basées sur les informations les plus récentes et les plus pertinentes de vos systèmes. Cela est particulièrement utile pour les données spécifiques à l'entreprise qui ne sont pas disponibles publiquement.
Cette page explique comment configurer et utiliser l'ancrage avec n'importe quelle API Search avec Gemini.
Fonctionnement de l'ancrage avec votre API de recherche
Lorsque vous ancrez avec votre API de recherche, Gemini peut interroger un point de terminaison d'API externe que vous fournissez. Cela permet à Gemini d'utiliser votre fonctionnalité de recherche personnalisée comme outil pour améliorer ses réponses. Il permet des interactions plus dynamiques et contextuelles, car le modèle peut rechercher des informations à partir des sources de données que vous avez spécifiées, si nécessaire.
Lors d'une demande de génération, Gemini peut appeler le point de terminaison de l'API externe avec une requête de recherche. Votre API doit ensuite renvoyer des extraits de données pertinents. Gemini utilise ces extraits comme source de vérité pour générer une réponse plus précise et ancrée.
Vous pouvez combiner l'ancrage à l'aide de votre API Search avec d'autres sources d'ancrage, comme la recherche Google. Une demande de génération accepte jusqu'à 10 sources d'ancrage et des requêtes multi-outils où Gemini peut tirer parti de différentes sources d'informations pour générer la meilleure réponse possible.
Modèles compatibles
Les modèles suivants sont compatibles avec l'ancrage avec votre API :
Pour en savoir plus, consultez Modèles Gemini.
Avant de commencer
Pour utiliser l'ancrage avec votre API Search, procédez comme suit :
- Assurez-vous que l'API Vertex AI est activée dans votre projet Google Cloud.
- Si vous prévoyez de suivre le guide de configuration détaillé pour créer un point de terminaison de l'API Search, assurez-vous d'avoir installé et initialisé Google Cloud CLI.
Exigences de l'API Search
Pour utiliser votre infrastructure de recherche existante avec Gemini, votre point de terminaison d'API doit répondre aux exigences suivantes :
Schéma de l'API
- Méthode HTTP :
POST Corps de la requête (de Gemini à votre API) :
{ "query": "the user's search query string" }Corps de la réponse (de votre API à Gemini) : tableau JSON d'objets. Chaque objet représente un résultat de recherche et doit contenir les champs "snippet" et "uri".
[ { "snippet": "A text snippet containing the answer or relevant information.", "uri": "A URI/URL linking to the source of the information, or a relevant identifier." }, { "snippet": "Another piece of information.", "uri": "https://example.com/another-source" } ]
Si aucun résultat n'est trouvé, votre point de terminaison d'API doit renvoyer un tableau vide.
Authentification
L'ancrage avec votre API Search est compatible avec l'utilisation de la clé API, qui sécurise votre point de terminaison d'API. Gemini envoie cette clé API en tant que paramètre de requête nommé key.
Utiliser l'ancrage avec votre API Search et un point de terminaison compatible
Si vous disposez déjà d'un point de terminaison d'API qui répond aux exigences de schéma et d'authentification, vous pouvez le configurer directement dans vos appels à l'API Gemini.
Configurer l'outil externalApi
Lorsque vous envoyez une requête à l'API Gemini, incluez le paramètre "tools" avec un outil de récupération configuré pour externalApi. Voici les principaux champs :
api_spec: "SIMPLE_SEARCH": indique à Gemini d'utiliser le schéma d'entrée et de sortie prédéfini.endpoint: URL complète de votre point de terminaison API Gateway, telle quehttps://YOUR_GATEWAY_HOSTNAME/v0/search.apiAuth.apiKeyConfig.apiKeyString: clé API utilisée par Gemini pour s'authentifier auprès de votre API. L'application Gemini ajoute cette clé en tant que?key=<YOUR_API_KEY>à l'URL du point de terminaison.
REST
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- LOCATION : région dans laquelle traiter la requête, par exemple
us-central1. - PROJECT_ID : ID de votre projet Google Cloud .
- MODEL_ID : ID d'un modèle Gemini compatible, tel que
gemini-2.0-flash-001. - USER_PROMPT : instructions textuelles à inclure dans la requête.
- EXTERNAL_API_ENDPOINT : URL complète du point de terminaison sécurisé d'API Gateway que Gemini appelle, par exemple
https://YOUR_GATEWAY_HOSTNAME/v0/search. Ce point de terminaison doit respecter le schéma d'API spécifié. - EXTERNAL_API_KEY : clé API que vous avez générée et configurée pour votre API Gateway. Gemini utilise cette clé pour s'authentifier auprès de votre point de terminaison.
Méthode HTTP et URL :
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
Corps JSON de la requête :
{
"contents": [{
"role": "user",
"parts": [{
"text": "USER_PROMPT"
}]
}],
"tools": [{
"retrieval": {
"externalApi": {
"api_spec": "SIMPLE_SEARCH",
"endpoint": "EXTERNAL_API_ENDPOINT",
"apiAuth": {
"apiKeyConfig": {
"apiKeyString": "EXTERNAL_API_KEY"
}
}
}
}
}]
}
Pour envoyer votre demande, utilisez l'une des options suivantes :
curl
La commande suivante suppose que vous vous êtes connecté à la gcloud CLI avec votre compte utilisateur en exécutant gcloud CLI init ou gcloud CLI auth login , ou en utilisant Cloud Shell, qui vous connecte automatiquement à la gcloud CLI. Vous pouvez exécuter gcloud CLI auth list pour vérifier le compte actuellement actif.
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"
Powershell
La commande suivante suppose que vous vous êtes connecté à la gcloud CLI avec votre compte utilisateur en exécutant gcloud CLI init ou gcloud CLI auth login. Vous pouvez exécuter gcloud CLI auth list pour vérifier le compte actuellement actif.
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON de ce type :
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "You can make an appointment on the website https://dmv.gov/"
}
]
},
"finishReason": "STOP",
"safetyRatings": [
"..."
],
"groundingMetadata": {
"retrievalQueries": [
"How to make appointment to renew driving license?"
],
"groundingChunks": [
{
"retrievedContext": {
"uri": "https://...",
"snippet": "Snippet text about driving license renewal"
}
}
],
"groundingSupport": [
{
"segment": {
"startIndex": 25,
"endIndex": 147
},
"segment_text": "ipsum lorem ...",
"supportChunkIndices": [1, 2],
"confidenceScore": [0.9541752, 0.97726375]
},
{
"segment": {
"startIndex": 294,
"endIndex": 439
},
"segment_text": "ipsum lorem ...",
"supportChunkIndices": [1],
"confidenceScore": [0.9541752, 0.9325467]
}
]
}
}
],
"usageMetadata": {
"..."
}
}
Configurer un point de terminaison de l'API Search
Si vous ne disposez pas d'un point de terminaison d'API existant qui répond aux exigences, cette section vous explique comment en configurer un à l'aide de Cloud Functions et d'API Gateway.
Créer votre wrapper d'API externe avec Cloud Functions
Une fonction Cloud peut servir d'intermédiaire qui reçoit les requêtes de Gemini, émet les requêtes appropriées à votre infrastructure de recherche existante (comme une base de données, un moteur de recherche interne ou une recherche vectorielle), puis met en forme les résultats dans le schéma que Gemini comprend.
Pour en savoir plus, consultez la documentation sur Cloud Run Functions.
Exemple de configuration de fonction Cloud (Python)
Cet exemple utilise une liste de produits codée en dur à des fins de démonstration. Vous devrez remplacer la logique de récupération des données par des appels à votre système de recherche.
main.pyimport functions_framework import json from flask import jsonify @functions_framework.http def custom_search_wrapper(request): """ HTTP Cloud Function to provide a minimal, fixed response for Gemini grounding. """ if request.method != 'POST': return 'Only POST requests are accepted', 405 request_json = request.get_json(silent=True) if not request_json or 'query' not in request_json: return jsonify({"error": "Invalid request. JSON body with 'query' field is required."}), 400 user_query = request_json['query'] print(f"Received query: '{user_query}'. Responding with fixed data.") # --- FIXED RESPONSE --- # This is a hardcoded response. In a real scenario, you would # use the 'user_query' to fetch relevant data. fixed_results = [ { "snippet": "This is a fixed snippet from your custom Search API. The original query was: " + user_query, "uri": "https://example.com/docs/fixed-test-data" }, { "snippet": "Another piece of fixed information to demonstrate the list format.", "uri": "https://example.com/another-fixed-source" } ] # --- END OF FIXED RESPONSE --- return jsonify(fixed_results)requirements.pyfunctions-framework>=3.0.0 Flask>=2.0.0Déploiement : accédez au répertoire contenant
main.pyetrequirements.txt, puis exécutez la commande suivante :gcloud functions deploy custom_search_wrapper \ --runtime python311 \ --trigger-http \ --entry-point custom_search_wrapper \ --region YOUR_REGION \ --allow-unauthenticated \ --gen2- Remplacez YOUR_REGION par la région Google Cloud de votre choix, par exemple
us-central1. --allow-unauthenticatedest spécifié, car API Gateway gère l'authentification.
- Remplacez YOUR_REGION par la région Google Cloud de votre choix, par exemple
Sécuriser les fonctions Cloud avec API Gateway et une clé API
API Gateway fournit un point d'entrée sécurisé et géré pour vos fonctions Cloud Functions, et vous permet d'appliquer l'authentification par clé API.
Pour en savoir plus, consultez la documentation API Gateway.
Créez une spécification OpenAPI (
openapi-spec.yaml) : ce fichier définit la façon dont API Gateway expose vos fonctions Cloud Functions. Il spécifie que la passerelle attend une requêtePOSTsur le chemin d'accès/v0/searchet nécessite une clé API envoyée en tant que paramètre de requête nommékey.swagger: '2.0' info: title: Custom Search API for Gemini Grounding description: Wraps an internal search function, secured by API Key for Gemini. version: 1.0.0 schemes: - https produces: - application/json consumes: - application/json paths: /v0/search: # TODO: This will be part of API endpoint URL change if necessary post: summary: Custom search endpoint for Gemini operationId: customSearchForGemini # TODO: Change if needed x-google-backend: address: YOUR_CLOUD_FUNCTION_TRIGGER_URL # TODO: Replace with your Cloud Function trigger URL parameters: - name: body in: body required: true schema: type: object properties: query: type: string security: - api_key_query: [] responses: '200': description: Search results schema: type: array items: type: object properties: snippet: type: string uri: type: string '400': description: Invalid request '401': description: Unauthorized (Missing or invalid API key) '500': description: Internal server error securityDefinitions: api_key_query: type: apiKey name: key # Gemini will send its API key using this query parameter name in: queryDéployez API Gateway : après avoir remplacé les variables suivantes, exécutez les commandes gcloud CLI :
- YOUR_PROJECT_ID : ID de votre projet Google Cloud .
- YOUR_REGION : région Google Cloud que vous avez utilisée pour vos fonctions Cloud, par exemple
us-central1.
# 1. Create an API gcloud api-gateway apis create custom-search-gemini-api --project=YOUR_PROJECT_ID # 2. Create an API Config from your OpenAPI spec gcloud api-gateway api-configs create v1 \ --api=custom-search-gemini-api \ --openapi-spec=openapi-spec.yaml \ --project=YOUR_PROJECT_ID \ --display-name="Version 1" # 3. Create a Gateway gcloud api-gateway gateways create custom-search-gateway \ --api=custom-search-gemini-api \ --api-config=v1 \ --location=YOUR_REGION \ --project=YOUR_PROJECT_IDAprès le déploiement, le nom d'hôte (URL de la passerelle) se présente au format suivant :
https://custom-search-gateway-UNIQUE_ID.nw.gateway.devVous pouvez utiliser le nom d'hôte pour construire l'URL complète du point de terminaison pour Gemini. Exemple :
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/searchCréez et limitez une clé API : vous devez créer une clé API que Gemini utilise pour accéder à votre point de terminaison API Gateway. Pour en savoir plus, consultez Gérer les clés API.
Pour créer et restreindre une clé API :
Dans la console Google Cloud , accédez à la page API Gateway / Activer les API.
Si l'API Gateway n'est pas activée, cliquez sur Lancer, puis sur Activer.
Sélectionnez Identifiants.
Cliquez sur Créer des identifiants, puis sélectionnez Clé API.
Cliquez sur Afficher la clé, puis copiez la clé API générée. Stockez la clé dans un emplacement sécurisé. Cette clé est utilisée par Gemini.
Cliquez sur Modifier la clé API ou sur le nom de la clé.
Dans la section Restrictions relatives aux API, procédez comme suit :
Sélectionnez l'option Restreindre la clé.
Sélectionnez votre service géré API Gateway. Il doit porter le nom de votre API, par exemple
Custom Search API for Gemini Grounding API.Si la clé n'est pas incluse ou si vous prévoyez de gérer la passerelle avec l'API à l'aide de cette clé, assurez-vous que l'API API Gateway (
apigateway.googleapis.com) est sélectionnée. Pour l'ancrage, la clé doit avoir accès à votre service d'API spécifique hébergé par API Gateway.
Cliquez sur Enregistrer. Votre point de terminaison API Gateway est sécurisé. Lorsque vous l'utilisez, vous devez transmettre la clé API en tant que paramètre de requête. Exemple :
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY
Points à prendre en compte pour votre API Search
Tenez compte des points suivants pour choisir votre API Search :
- Qualité de l'extrait : le texte de l'extrait renvoyé par votre API est essentiel. Elle doit être concise, mais suffisamment informative pour que Gemini puisse l'utiliser comme base factuelle pour sa réponse.
- Latence : votre API de recherche doit répondre rapidement. Une latence élevée dans votre API augmente le temps de réponse global de Gemini.
- Gestion des erreurs : implémentez une gestion des erreurs robuste dans vos fonctions Cloud Functions ou votre API Search. Si votre API génère fréquemment des erreurs ou expire, cela a un impact négatif sur la capacité de Gemini à générer des réponses ancrées.