Vous pouvez connecter Gemini à vos sources de données externes en utilisant l'ancrage avec votre API de recherche. 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. Cette fonctionnalité est particulièrement utile pour les données spécifiques à l'entreprise qui ne sont pas accessibles au public.
Cette page explique comment configurer et utiliser l'ancrage à l'aide d'une API de recherche avec Gemini.
Fonctionnement de l'ancrage avec votre API de recherche
Lorsque vous utilisez l'ancrage 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. Les interactions sont plus dynamiques et plus contextuelles, car le modèle peut rechercher des informations dans les sources de données que vous avez spécifiées en cas de besoin.
Lors d'une requête 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 plus ancrée.
Vous pouvez combiner l'ancrage à l'aide de votre API de recherche avec d'autres sources d'ancrage, comme la recherche Google. Une requête de génération accepte jusqu'à 10 sources d'ancrage et des requêtes multi-outils dans lesquelles Gemini peut tirer parti de différentes sources d'informations pour générer la meilleure réponse possible.
Modèles compatibles
Cette section liste les modèles compatibles avec l'ancrage avec votre API de recherche.
Cliquer pour développer les modèles compatibles
Avant de commencer
Pour utiliser l'ancrage avec votre API de recherche, procédez comme suit :
- Assurez-vous que l'API Agent Platform est activée dans votre Google Cloud projet.
- Si vous prévoyez de suivre le guide de configuration détaillé pour créer un nouveau point de terminaison d'API de recherche, assurez-vous que Google Cloud CLI est installé et initialisé.
Conditions applicables à l'API de recherche
Pour utiliser votre infrastructure de recherche existante avec Gemini, votre point de terminaison de l'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 de recherche 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 de recherche avec un point de terminaison compatible
Si vous disposez déjà d'un point de terminaison de l'API qui répond aux exigences de schéma et d'authentification, vous pouvez le configurer directement dans vos appels d'API Gemini.
Configurer l'outil externalApi
Lorsque vous effectuez une requête auprès de l'API Gemini, incluez le paramètre "tools" avec un outil de récupération configuré pour externalApi. Les champs clés incluent les éléments suivants :
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, par exemplehttps://YOUR_GATEWAY_HOSTNAME/v0/search.apiAuth.apiKeyConfig.apiKeyString: clé API que Gemini utilise pour s'authentifier auprès de votre API. Gemini ajoute cette clé en tant que?key=<YOUR_API_KEY>à l' URL du point de terminaison.
Python
Installer
pip install --upgrade google-genai
Pour en savoir plus, consultez la documentation de référence du SDK.
Définissez des variables d'environnement pour utiliser le SDK Gen AI avec Vertex AI :
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
from google import genai
from google.genai.types import (
GenerateContentConfig,
ExternalApi,
Retrieval,
Tool,
HttpOptions,
)
client = genai.Client(http_options=HttpOptions(api_version="v1"))
# Replace with your API details
EXTERNAL_API_ENDPOINT = "YOUR_EXTERNAL_API_ENDPOINT" # e.g., https://YOUR_GATEWAY_HOSTNAME/v0/search
EXTERNAL_API_KEY = "YOUR_EXTERNAL_API_KEY"
tool = Tool(
retrieval=Retrieval(
external_api=ExternalApi(
api_spec="SIMPLE_SEARCH",
endpoint=EXTERNAL_API_ENDPOINT,
api_auth={
"apiKeyConfig": {
"apiKeyString": EXTERNAL_API_KEY
}
}
)
)
)
response = client.models.generate_content(
model="gemini-2.5-flash", # Or another supported model
contents="What can you tell me about product Y based on my API?", # Your query
config=GenerateContentConfig(
tools=[tool],
),
)
print(response.text)
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. Pour utiliser le point de terminaison global, excluez l'emplacement du nom du point de terminaison et configurez l'emplacement de la ressource sur
global. - PROJECT_ID : ID de votre Google Cloud projet.
- MODEL_ID : ID d'un modèle Gemini compatible, tel
que
gemini-2.5-flash. - PROMPT : instructions textuelles à inclure dans le prompt.
- EXTERNAL_API_ENDPOINT : URL complète de votre point de terminaison API Gateway sécurisé 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContentCorps JSON de la requête :
{ "contents": [{ "role": "user", "parts": [{ "text": "PROMPT" }] }], "tools": [{ "retrieval": { "externalApi": { "api_spec": "SIMPLE_SEARCH", "endpoint": "EXTERNAL_API_ENDPOINT", "apiAuth": { "apiKeyConfig": { "apiKeyString": "EXTERNAL_API_KEY" } } } } }] }Pour envoyer votre requête, utilisez l'une des options suivantes :
curl
La commande suivante suppose que vous vous êtes connecté à 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 à 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é à 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 ContentVous 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 de recherche
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 vers votre infrastructure de recherche existante (par exemple, 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 les fonctions Cloud Run.
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 réel.
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 de votre choix Google Cloud , par exemple
us-central1. --allow-unauthenticatedest spécifié, car API Gateway gère l'authentification.
- Remplacez YOUR_REGION par la région de votre choix Google Cloud , par exemple
Sécuriser Cloud Functions avec API Gateway et une clé API
API Gateway fournit un point d'entrée sécurisé et géré pour vos Cloud Functions et vous permet d'appliquer l'authentification par clé API.
Pour en savoir plus, consultez la documentation sur API Gateway.
Créer une spécification OpenAPI (
openapi-spec.yaml) : ce fichier définit la manière dont API Gateway expose vos 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éployer API Gateway : après avoir remplacé les variables suivantes, exécutez les commandes gcloud CLI :
- YOUR_PROJECT_ID: ID du projet Google Cloud .
- YOUR_REGION: région que vous
avez utilisée pour vos Cloud Functions, par exemple
us-central1. Google Cloud
# 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) est au format suivant :
https://custom-search-gateway-UNIQUE_ID.nw.gateway.devVous pouvez utiliser le nom d'hôte pour créer l'URL complète du point de terminaison pour Gemini. Exemple :
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/searchCréer et limiter 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 la section Gérer les clés API.
Pour créer et limiter une clé API, procédez comme suit :
Dans la Google Cloud console, accédez à la page API Gateway / Activer les API.
Si l'API Gateway API 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 Gateway API (
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
Considérations concernant votre API de recherche
Tenez compte des considérations suivantes pour vous aider à choisir votre API de recherche :
- Qualité des extraits : le texte des extraits renvoyé par votre API est essentiel. Il doit être concis, mais suffisamment informatif 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 gestion des exceptions robuste dans vos Cloud Functions ou votre API de recherche. 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.