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 nutzen. Dadurch wird sichergestellt, dass Antworten auf den neuesten und relevantesten Informationen aus Ihren Systemen basieren. Das ist besonders nützlich für unternehmensspezifische Daten, die nicht öffentlich verfügbar sind.
Auf dieser Seite wird erläutert, wie Sie die Fundierung mit einer beliebigen Such-API mit Gemini konfigurieren und verwenden.
Funktionsweise der Fundierung mit Ihrer Such-API
Wenn Sie die Fundierung mit Ihrer Such-API verwenden, kann Gemini einen von Ihnen bereitgestellten externen API-Endpunkt abfragen. So kann Gemini Ihre benutzerdefinierte Suchfunktion als Tool verwenden, um seine Antworten zu verbessern. Das ermöglicht dynamischere und kontextbezogenere Interaktionen, da das Modell bei Bedarf Informationen aus den von Ihnen angegebenen Datenquellen abrufen kann.
Bei einer Generierungsanfrage kann Gemini einen Aufruf an den externen API-Endpunkt mit einer Suchanfrage senden. Ihre API sollte dann relevante Datenausschnitte zurückgeben. Gemini verwendet diese Ausschnitte als zuverlässige Quelle, 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 Abfragen mit mehreren Tools, bei denen Gemini verschiedene Informationsquellen nutzen kann, um die bestmögliche Antwort zu generieren.
Unterstützte Modelle
In diesem Abschnitt sind die Modelle aufgeführt, die die Fundierung mit Ihrer Such-API unterstützen.
Klicken Sie hier, um die unterstützten Modelle zu maximieren
Hinweis
So verwenden Sie die Fundierung mit Ihrer Such-API:
- Achten Sie darauf, dass die Agent Platform API aktiviert ist in Ihrem Google Cloud Projekt.
- Wenn Sie der detaillierten Einrichtungsanleitung zum Erstellen eines neuen Such-API-Endpunkt folgen möchten, müssen Sie die Google Cloud CLI installiert und initialisierthaben.
Anforderungen an die Such-API
Wenn Sie Ihre vorhandene Suchinfrastruktur mit Gemini verwenden möchten, muss Ihr API-Endpunkt die folgenden Anforderungen erfüllen:
API-Schema
- 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 Ihrer Such-API unterstützt die Verwendung des API-Schlüssels, der Ihren API-Endpunkt schützt. 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.
Tool externalApi 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. Wichtige Felder sind:
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, mit dem sich Gemini bei Ihrer API authentifiziert. 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 diese Werte in den folgenden Anfragedaten:
- LOCATION: Die Region, in der die Anfrage verarbeitet werden soll. Wenn Sie den globalen Endpunkt verwenden möchten, lassen Sie den Standort aus dem Endpunktnamen weg 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" } } } } }] }Verwenden Sie eine der folgenden Optionen, um Ihre Anfrage zu senden:
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. Dazu führen Sie gcloud CLI init oder gcloud CLI auth login aus. 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 vorhandenen API-Endpunkt haben, der die Anforderungen erfüllt, erfahren Sie in diesem Abschnitt, wie Sie einen mit Cloud Functions und API Gateway einrichten.
Wrapper für externe API mit Cloud Functions erstellen
Eine Cloud Functions-Funktion kann als Vermittler fungieren, der Anfragen von Gemini empfängt, entsprechende Anfragen an Ihre vorhandene Suchinfrastruktur sendet, z. B. an eine Datenbank, eine interne Suchmaschine oder eine Vektorsuche, und die Ergebnisse dann im 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 zur Demonstration eine fest codierte Produktliste verwendet. Sie müssen die Logik zum Abrufen von Daten durch Aufrufe an Ihr tatsächliches Suchsystem 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 zu dem 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 gewünschte Google Cloud Region, z. B.
us-central1. --allow-unauthenticatedwird angegeben, da API Gateway die Authentifizierung übernimmt.
- Ersetzen Sie YOUR_REGION durch die gewünschte 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. Es wird angegeben, 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: Nachdem Sie die folgenden Variablen ersetzt haben, führen Sie die gcloud CLI-Befehle aus:
- YOUR_PROJECT_ID: Ihre Google Cloud Projekt-ID
- 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 zugreifen kann. Weitere Informationen finden Sie unter API-Schlüssel verwalten.
So erstellen und beschränken Sie einen API-Schlüssel:
Wechseln Sie in der Google Cloud Console zur Seite API Gateway / APIs aktivieren.
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 Ihren verwalteten API Gateway-Dienst aus. Er 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, achten Sie darauf, dass die API Gateway API (
apigateway.googleapis.com) ausgewählt ist. 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 Abfrageparameter übergeben. Beispiel:
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY
Überlegungen zu Ihrer Such-API
Beachten Sie die folgenden Überlegungen, um die richtige Such-API auszuwählen:
- Qualität des Snippets: Der von Ihrer API zurückgegebene Snippet-Text ist entscheidend. Er sollte kurz, aber informativ genug sein, damit Gemini ihn als faktische Grundlage für seine Antwort verwenden kann.
- Latenz: Ihre Such-API sollte schnell reagieren. Eine hohe Latenz in Ihrer API erhöht die Gesamtantwortzeit von Gemini.
- Fehlerbehandlung: Implementieren Sie eine robuste Fehlerbehandlung in Ihren Cloud Functions-Funktionen oder Ihrer Such-API. Wenn Ihre API häufig Fehler verursacht oder eine Zeitüberschreitung auftritt, wirkt sich das negativ auf die Fähigkeit von Gemini aus, fundierte Antworten zu generieren.