Diese Seite wurde von der Cloud Translation API übersetzt.

Fundierung mit Ihrer Such-API

Sie können Gemini mit Ihren externen Datenquellen verbinden, indem Sie die Fundierung mit Ihrer Such-API vornehmen. 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. 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.

So funktioniert die Fundierung mit Ihrer Such-API

Wenn Sie die Fundierung mit Ihrer Such-API vornehmen, kann Gemini einen externen API-Endpunkt abfragen, den Sie bereitstellen. 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.

Während einer Generierungsanfrage kann Gemini den externen API-Endpunkt mit einer Suchanfrage aufrufen. Ihre API sollte dann relevante Datenausschnitte zurückgeben. Gemini verwendet diese Snippets als Quelle, um eine genauere und fundiertere Antwort zu generieren.

Sie können die Fundierung über Ihre Such-API mit anderen Fundierungsquellen wie der Google Suche kombinieren. Eine Anfrage zur Generierung unterstützt bis zu 10 Fundierungsquellen und Anfragen mit mehreren Tools, bei denen Gemini verschiedene Informationsquellen nutzen kann, um die bestmögliche Antwort zu generieren.

Unterstützte Modelle

Die folgenden Modelle unterstützen Grounding mit Ihrer API:

Weitere Informationen finden Sie unter Gemini-Modelle.

Hinweise

So verwenden Sie die Fundierung mit Ihrer Search API:

Achten Sie darauf, dass die Vertex AI API in Ihrem Google Cloud-Projekt aktiviert ist.
Wenn Sie der detaillierten Einrichtungsanleitung zum Erstellen eines neuen Search API-Endpunkt folgen möchten, muss die Google Cloud CLI installiert und initialisiert sein.

Anforderungen für die Search API

Damit Sie Ihre vorhandene Suchinfrastruktur mit Gemini verwenden können, 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, wodurch Ihr API-Endpunkt geschützt wird. Gemini sendet diesen API-Schlüssel als Abfrageparameter mit dem Namen key.

Fundierung mit Ihrer Search API mit einem kompatiblen Endpunkt verwenden

Wenn Sie bereits einen API-Endpunkt haben, der den Schema- und Authentifizierungsanforderungen entspricht, 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 ein, das für externalApi konfiguriert ist. Zu den wichtigsten Feldern gehören:

api_spec: "SIMPLE_SEARCH": Damit wird Gemini angewiesen, das vordefinierte Ein- 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 zur Authentifizierung bei Ihrer API verwendet. Gemini hängt diesen Schlüssel als ?key=<YOUR_API_KEY> an die Endpunkt-URL an.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

LOCATION: Die Region, in der die Anfrage verarbeitet werden soll, z. B. us-central1.
PROJECT_ID: Ihre Google Cloud Projekt-ID.
MODEL_ID: Die Modell-ID eines kompatiblen Gemini-Modells, z. B. gemini-2.0-flash-001.
USER_PROMPT: Die Textanleitung, die in den Prompt eingefügt werden soll.
EXTERNAL_API_ENDPOINT: Die vollständige URL zu Ihrem gesicherten API Gateway-Endpunkt, der von Gemini aufgerufen wird, 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 zur Authentifizierung bei Ihrem Endpunkt.

HTTP-Methode und URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

JSON-Text anfordern:

  {
  "contents": [{
      "role": "user",
      "parts": [{
          "text": "USER_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, haben Sie folgende Möglichkeiten:

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 den folgenden Befehl aus: gcloud CLI auth list.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und 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 haben Sie „gcloud CLI init“ oder „gcloud CLI auth login“ ausgeführt. Sie können das aktive Konto mit dem Befehl „gcloud CLI auth list“ prüfen.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und 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 Content

Sie 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, wird in diesem Abschnitt beschrieben, wie Sie einen mit Cloud Functions und API Gateway einrichten.

Externen API-Wrapper mit Cloud Functions erstellen

Eine Cloud Function kann als Vermittler fungieren, der Anfragen von Gemini empfängt, entsprechende Anfragen an Ihre vorhandene Suchinfrastruktur wie eine Datenbank, interne Suchmaschine oder 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 eine fest codierte Produktliste zur Demonstration verwendet. Sie müssen die Logik zum Abrufen von Daten durch Aufrufe Ihres tatsächlichen Suchsystems ersetzen.

main.py

import 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.py

functions-framework>=3.0.0
Flask>=2.0.0

Bereitstellung: Wechseln Sie zum Verzeichnis mit main.py und requirements.txt 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-unauthenticated wird angegeben, da die Authentifizierung von API Gateway übernommen wird.
Wichtig :Die Trigger-URL nach der Bereitstellung hat das Format https://....run.app. Verwenden Sie dieses Format für die API Gateway-Konfiguration im nächsten Schritt.

Cloud Functions mit API Gateway und einem API-Schlüssel sichern

API Gateway bietet einen sicheren, verwalteten Einstiegspunkt für Ihre Cloud Functions und ermöglicht die Erzwingung der API-Schlüsselauthentifizierung.

Weitere Informationen finden Sie in der API Gateway-Dokumentation.

OpenAPI-Spezifikation erstellen (openapi-spec.yaml): In dieser Datei wird definiert, wie API Gateway Ihre Cloud Functions-Funktionen bereitstellt. Sie gibt an, dass das Gateway eine POST-Anfrage an den Pfad /v0/search erwartet und einen API-Schlüssel erfordert, der als Abfrageparameter mit dem Namen key gesendet 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: query

API Gateway bereitstellen: Führen Sie die gcloud CLI-Befehle aus, nachdem Sie die folgenden Variablen ersetzt haben:

YOUR_PROJECT_ID: Ihre Google Cloud -Projekt-ID.
YOUR_REGION: Die Google Cloud Region, die Sie für Ihre Cloud Functions 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_ID

Nach der Bereitstellung hat der Hostname (Gateway-URL) folgendes Format:

https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev

Sie 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/search

API-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:
1. Rufen Sie in der Google Cloud Console die Seite API Gateway / APIs aktivieren auf.
  Zur API Gateway API / APIs aktivieren
2. Wenn die API Gateway API nicht aktiviert ist, klicken Sie auf Starten und dann auf Aktivieren.
3. Wählen Sie Anmeldedaten aus.
4. Klicken Sie auf Anmeldedaten erstellen und wählen Sie API-Schlüssel aus.
5. 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.
6. Klicken Sie auf API-Schlüssel bearbeiten oder auf den Namen des Schlüssels.
7. Führen Sie im Abschnitt API-Einschränkungen folgende Schritte aus:
  1. Wählen Sie die Option Schlüssel einschränken aus.
  2. Wählen Sie Ihren verwalteten API Gateway-Dienst aus. Sie muss nach Ihrer API benannt werden, z. B. Custom Search API for Gemini Grounding API.
  3. 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 muss der Schlüssel Zugriff auf Ihren spezifischen API-Dienst haben, der von API Gateway gehostet wird.
  Hinweis :In der Regel wird für die Verwaltung ein separater Schlüssel oder ein separates Dienstkonto verwendet.
8. 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 zur Search API

Die folgenden Überlegungen können Ihnen bei der Auswahl der Such-API helfen:

Snippet-Qualität: Der von Ihrer API zurückgegebene Snippet-Text ist entscheidend. Sie sollte kurz, aber informativ genug sein, damit Gemini sie als sachliche Grundlage für die Antwort verwenden kann.
Latenz: Ihre Such-API sollte schnell reagieren. Eine hohe Latenz in Ihrer API erhöht die gesamte Reaktionszeit von Gemini.
Fehlerbehandlung: Implementieren Sie eine robuste Fehlerbehandlung in Ihren Cloud Functions oder Ihrer Search API. Wenn bei Ihrer API häufig Fehler auftreten oder Zeitüberschreitungen erfolgen, wirkt sich das negativ auf die Fähigkeit von Gemini aus, fundierte Antworten zu generieren.

Nächste Schritte

Fundierung mit der Google Suche.