Sie können Gemini mit Ihren externen Datenquellen verbinden, indem Sie die Fundierung mit Ihrer Such-API verwenden. So können Sie jeden Suchdienst als Fundierungsquelle für Gemini verwenden. Dadurch wird sichergestellt, dass die Antworten auf den neuesten und relevantesten Informationen aus Ihren Systemen basieren. Dies ist besonders nützlich für unternehmensspezifische Daten, die nicht öffentlich verfügbar sind.
Auf dieser Seite wird beschrieben, wie Sie die Fundierung mit einer beliebigen Such-API mit Gemini konfigurieren und verwenden.
So funktioniert die Fundierung mit Ihrer Such-API
Wenn Sie die Fundierung mit Ihrer Such-API durchführen, kann Gemini einen von Ihnen bereitgestellten externen API-Endpunkt abfragen. So kann Gemini Ihre benutzerdefinierte Suchfunktion als Tool verwenden, um die Antworten zu verbessern. Sie ermöglicht dynamischere und kontextbezogene Interaktionen, da das Modell bei Bedarf Informationen aus den von Ihnen angegebenen Datenquellen abrufen kann.
Während einer Generierungsanfrage kann Gemini den externen API-Endpunkt mit einer Suchanfrage aufrufen. Ihre API sollte dann relevante Daten-Snippets zurückgeben. Gemini verwendet diese Snippets als Source of Truth, um eine genauere und fundiertere Antwort zu generieren.
Sie können die Fundierung mit Ihrer Such-API mit anderen Fundierungsquellen wie der Google Suche kombinieren. Eine Generierungsanfrage unterstützt bis zu 10 Fundierungsquellen und Multi-Tool-Abfragen, bei denen Gemini verschiedene Informationsquellen nutzen kann, um die bestmögliche Antwort zu generieren.
Unterstützte Modelle
In diesem Abschnitt werden die Modelle aufgeführt, die die Fundierung mit Ihrer Such-API unterstützen.
Klicken, um unterstützte Modelle einzublenden
- Gemini Robotics ER 2
- Gemini Nano Banana 2.1
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Live
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
- Gemini 3.1 Flash Image
- Gemini 3 Pro Image
- Gemini 3 Flash
- Gemini 2.5 Pro
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash mit nativen Audiofunktionen der Gemini Live API
- Gemini 2.5 Flash
Hinweis
So verwenden Sie die Fundierung mit Ihrer Such-API:
- Achten Sie darauf, dass die Agent Platform API in Ihrem Google Cloud -Projekt aktiviert ist.
- Wenn Sie der detaillierten Einrichtungsanleitung zum Erstellen eines neuen Such-API-Endpunkt folgen möchten, muss die Google Cloud CLI installiert und initialisiert sein.
Anforderungen an die Search API
Wenn Sie Ihre vorhandene Suchinfrastruktur mit Gemini verwenden möchten, muss Ihr API-Endpunkt die folgenden Anforderungen erfüllen:
API-Schemas
- HTTP-Methode:
POST Anfragetext (von Gemini an Ihre API):
{ "query": "the user's search query string" }Antworttext (von Ihrer API an Gemini): Ein JSON-Array von Objekten. Jedes Objekt stellt ein Suchergebnis dar und muss die Felder „snippet“ und „uri“ enthalten.
[ { "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" } ]
Wenn keine Ergebnisse gefunden werden, sollte Ihr API-Endpunkt ein leeres Array zurückgeben.
Authentifizierung
Die Fundierung mit der Search API unterstützt die Verwendung des API-Schlüssels, der Ihren API-Endpunkt sichert. Gemini sendet diesen API-Schlüssel als Abfrageparameter mit dem Namen key.
Fundierung mit Ihrer Such-API mit einem kompatiblen Endpunkt verwenden
Wenn Sie bereits einen API-Endpunkt haben, der die Schema- und Authentifizierungsanforderungen erfüllt, können Sie ihn direkt in Ihren Gemini API-Aufrufen konfigurieren.
externalApi-Tool konfigurieren
Wenn Sie eine Anfrage an die Gemini API senden, fügen Sie den Parameter „tools“ mit einem Abruftool hinzu, das für externalApi konfiguriert ist. Zu den wichtigsten Feldern gehören:
api_spec: "SIMPLE_SEARCH": Damit wird Gemini angewiesen, das vordefinierte Eingabe- und Ausgabeschema zu verwenden.endpoint: Die vollständige URL zu Ihrem API Gateway-Endpunkt, z. B.https://YOUR_GATEWAY_HOSTNAME/v0/search.apiAuth.apiKeyConfig.apiKeyString: Der API-Schlüssel, den Gemini für die Authentifizierung bei Ihrer API verwendet. Gemini hängt diesen Schlüssel als?key=<YOUR_API_KEY>an die Endpunkt-URL an.
Python
Installieren
pip install --upgrade google-genai
Weitere Informationen finden Sie in der SDK-Referenzdokumentation.
Legen Sie Umgebungsvariablen fest, um das Google Gen AI SDK mit Vertex AI zu verwenden:
# 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
Ersetzen Sie folgende Werte in den Anfragedaten:
- LOCATION: Die Region, in der die Anfrage verarbeitet werden soll. Wenn Sie den globalen Endpunkt verwenden möchten, schließen Sie den Standort aus dem Endpunktnamen aus und konfigurieren Sie den Standort der Ressource auf
global. - PROJECT_ID: Ihre Google Cloud Projekt-ID
- MODEL_ID: Die Modell-ID eines kompatiblen Gemini-Modells, z. B.
gemini-2.5-flash. - PROMPT: Die Textanleitung, die in den Prompt eingefügt werden soll.
- EXTERNAL_API_ENDPOINT: Die vollständige URL zu Ihrem gesicherten API Gateway-Endpunkt, den Gemini aufruft, z. B.
https://YOUR_GATEWAY_HOSTNAME/v0/search. Dieser Endpunkt muss dem angegebenen API-Schema entsprechen. EXTERNAL_API_KEY: Der API-Schlüssel, den Sie für Ihr API-Gateway generiert und konfiguriert haben. Gemini verwendet diesen Schlüssel, um sich bei Ihrem Endpunkt zu authentifizieren.
HTTP-Methode und URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContentJSON-Text der Anfrage:
{ "contents": [{ "role": "user", "parts": [{ "text": "PROMPT" }] }], "tools": [{ "retrieval": { "externalApi": { "api_spec": "SIMPLE_SEARCH", "endpoint": "EXTERNAL_API_ENDPOINT", "apiAuth": { "apiKeyConfig": { "apiKeyString": "EXTERNAL_API_KEY" } } } } }] }Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:
curl
Der folgende Befehl setzt voraus , dass Sie sich mit Ihrem Nutzerkonto in der gcloud CLI angemeldet haben. Dazu haben Sie „gcloud CLI init“ oder „gcloud CLI auth login“ ausgeführt oder die Cloud Shell genutzt, die Sie automatisch in der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie „gcloud CLI auth list“ aus.
Speichern Sie den Anfragetext in einer Datei mit dem Namen
request.jsonund führen Sie den folgenden Befehl aus: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
Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud CLI angemeldet haben, indem Sie „gcloud CLI init“ oder „gcloud CLI auth login“ ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie „gcloud CLI auth list“ aus.
Speichern Sie den Anfragetext in einer Datei mit dem Namen
request.jsonund führen Sie den folgenden Befehl aus:$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 ContentSie sollten eine JSON-Antwort ähnlich wie diese erhalten:
{ "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": { "..." } }
Such-API-Endpunkt einrichten
Wenn Sie keinen API-Endpunkt haben, der die Anforderungen erfüllt, finden Sie in diesem Abschnitt eine Anleitung zum Einrichten eines Endpunkts mit Cloud Functions und API Gateway.
Externen API-Wrapper mit Cloud Functions erstellen
Eine Cloud Functions-Funktion kann als Vermittler fungieren, der Abfragen von Gemini empfängt, entsprechende Abfragen an Ihre vorhandene Suchinfrastruktur wie eine Datenbank, eine interne Suchmaschine oder eine Vektorsuche sendet und die Ergebnisse dann in dem Schema formatiert, das Gemini versteht.
Weitere Informationen finden Sie in der Dokumentation zu Cloud Run-Funktionen.
Beispiel für die Einrichtung einer Cloud Functions-Funktion (Python)
In diesem Beispiel wird zu Demonstrationszwecken eine hartcodierte Produktliste verwendet. Sie müssen die Logik für den Datenabruf durch Aufrufe Ihres tatsächlichen Suchsystems ersetzen.
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.0Bereitstellung: Wechseln Sie zum Verzeichnis, das
main.pyundrequirements.txtenthält, und führen Sie Folgendes aus:gcloud functions deploy custom_search_wrapper \ --runtime python311 \ --trigger-http \ --entry-point custom_search_wrapper \ --region YOUR_REGION \ --allow-unauthenticated \ --gen2- Ersetzen Sie YOUR_REGION durch die von Ihnen ausgewählte Google Cloud Region, z. B.
us-central1. --allow-unauthenticatedwird angegeben, da API Gateway die Authentifizierung übernimmt.
- Ersetzen Sie YOUR_REGION durch die von Ihnen ausgewählte Google Cloud Region, z. B.
Cloud Functions-Funktionen mit API Gateway und einem API-Schlüssel sichern
API Gateway bietet einen sicheren, verwalteten Einstiegspunkt für Ihre Cloud Functions-Funktionen und ermöglicht die Erzwingung der API-Schlüsselauthentifizierung.
Weitere Informationen finden Sie in der API Gateway-Dokumentation.
OpenAPI-Spezifikation (
openapi-spec.yaml) erstellen: In dieser Datei wird definiert, wie API Gateway Ihre Cloud Functions-Funktionen bereitstellt. Sie gibt an, dass das Gateway einePOST-Anfrage an den Pfad/v0/searcherwartet und einen API-Schlüssel erfordert, der als Abfrageparameter mit dem Namenkeygesendet wird.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: queryAPI Gateway bereitstellen: Ersetzen Sie die folgenden Variablen und führen Sie dann die gcloud CLI-Befehle aus:
- YOUR_PROJECT_ID: Ihre Projekt-ID in Google Cloud .
- YOUR_REGION: Die Google Cloud Region, die Sie für Ihre Cloud Functions-Funktionen verwendet haben, z. B.
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_IDNach der Bereitstellung hat der Hostname (Gateway-URL) das folgende Format:
https://custom-search-gateway-UNIQUE_ID.nw.gateway.devSie können den Hostnamen verwenden, um die vollständige Endpunkt-URL für Gemini zu erstellen. Beispiel:
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/searchAPI-Schlüssel erstellen und einschränken: Sie müssen einen API-Schlüssel erstellen, mit dem Gemini auf Ihren API Gateway-Endpunkt zugreift. Weitere Informationen finden Sie unter API-Schlüssel verwalten.
So erstellen und beschränken Sie einen API-Schlüssel:
Rufen Sie in der Google Cloud Console die Seite API Gateway / APIs aktivieren auf.
Wenn die API Gateway API nicht aktiviert ist, klicken Sie auf Starten und dann auf Aktivieren.
Wählen Sie Anmeldedaten aus.
Klicken Sie auf Anmeldedaten erstellen und wählen Sie API-Schlüssel aus.
Klicken Sie auf Schlüssel anzeigen und kopieren Sie den generierten API-Schlüssel. Bewahren Sie den Schlüssel an einem sicheren Ort auf. Dieser Schlüssel wird von Gemini verwendet.
Klicken Sie auf API-Schlüssel bearbeiten oder auf den Namen des Schlüssels.
Führen Sie im Abschnitt API-Einschränkungen folgende Schritte aus:
Wählen Sie die Option Schlüssel einschränken aus.
Wählen Sie den verwalteten API Gateway-Dienst aus. Sie muss nach Ihrer API benannt sein, z. B.
Custom Search API for Gemini Grounding API.Wenn der Schlüssel nicht enthalten ist oder Sie das Gateway mit der API über diesen Schlüssel verwalten möchten, muss die API Gateway API (
apigateway.googleapis.com) ausgewählt sein. Für die Fundierung benötigt der Schlüssel Zugriff auf Ihren spezifischen API-Dienst, der von API Gateway gehostet wird.
Klicken Sie auf Speichern. Ihr API Gateway-Endpunkt ist gesichert. Wenn Sie den API Gateway-Endpunkt verwenden, müssen Sie den API-Schlüssel als Suchparameter übergeben. Beispiel:
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY
Überlegungen zu Ihrer Such-API
Berücksichtigen Sie die folgenden Punkte, um die richtige Such-API auszuwählen:
- Snippet-Qualität: Der von Ihrer API zurückgegebene Snippet-Text ist entscheidend. Sie sollte prägnant, aber informativ genug sein, damit Gemini sie als sachliche Grundlage für die Antwort verwenden kann.
- Latenz: Ihre Such-API sollte schnell antworten. Eine hohe Latenz in Ihrer API erhöht die Gesamtreaktionszeit von Gemini.
- Fehlerbehandlung: Implementieren Sie eine robuste Fehlerbehandlung in Ihren Cloud Functions-Funktionen oder der Search API. Wenn Ihre API häufig Fehler oder Zeitüberschreitungen verursacht, wirkt sich das negativ auf die Fähigkeit von Gemini aus, fundierte Antworten zu generieren.