Melakukan grounding dengan API penelusuran

Anda dapat menghubungkan Gemini ke sumber data eksternal dengan melakukan perujukan menggunakan API penelusuran Anda. Dengan begitu, Anda dapat menggunakan layanan penelusuran apa pun sebagai sumber perujukan untuk Gemini, yang membantu memastikan bahwa respons didasarkan pada informasi terbaru dan paling relevan dari sistem Anda. Hal ini sangat berguna untuk data khusus perusahaan yang tidak tersedia secara publik.

Halaman ini menjelaskan cara mengonfigurasi dan menggunakan perujukan menggunakan API penelusuran apa pun dengan Gemini.

Cara kerja perujukan dengan Search API Anda

Saat Anda melakukan perujukan dengan API penelusuran, Gemini dapat membuat kueri endpoint API eksternal yang Anda berikan. Hal ini memungkinkan Gemini menggunakan fungsi penelusuran kustom Anda sebagai alat untuk meningkatkan kualitas responsnya. Fitur ini memungkinkan interaksi yang lebih dinamis dan sadar konteks, karena model dapat mencari informasi dari sumber data yang Anda tentukan jika diperlukan.

Selama permintaan pembuatan, Gemini dapat melakukan panggilan ke endpoint API eksternal dengan kueri penelusuran. Kemudian, API Anda harus menampilkan cuplikan data yang relevan. Gemini menggunakan cuplikan ini sebagai sumber tepercaya untuk membuat respons yang lebih akurat dan berisi rujukan.

Anda dapat menggabungkan perujukan menggunakan Search API Anda dengan sumber perujukan lain seperti Google Penelusuran. Permintaan pembuatan mendukung hingga 10 sumber perujukan dan kueri multi-alat yang memungkinkan Gemini memanfaatkan berbagai sumber informasi untuk menghasilkan jawaban terbaik.

Model yang didukung

Model berikut mendukung perujukan dengan API Anda:

Untuk mengetahui informasi selengkapnya, lihat Model Gemini.

Sebelum memulai

Untuk menggunakan perujukan dengan Search API Anda, lakukan hal berikut:

  1. Pastikan Vertex AI API diaktifkan di Google Cloud project Anda.
  2. Jika Anda berencana mengikuti panduan penyiapan mendetail untuk membuat endpoint API penelusuran baru, pastikan Anda telah menginstal dan menginisialisasi Google Cloud CLI.

Persyaratan Search API

Untuk menggunakan infrastruktur penelusuran yang ada dengan Gemini, endpoint API Anda harus memenuhi persyaratan berikut:

Skema API

  • Metode HTTP: POST

  • Isi Permintaan (dari Gemini ke API Anda):

    {
  "query": "the user's search query string"
}

  • Isi respons (dari API Anda ke Gemini): Array JSON objek. Setiap objek merepresentasikan hasil penelusuran dan harus berisi kolom cuplikan dan 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"
  }
]

Jika tidak ada hasil yang ditemukan, endpoint API Anda harus menampilkan array kosong.

Autentikasi

Perujukan dengan Search API Anda mendukung penggunaan kunci API, yang mengamankan endpoint API Anda. Gemini mengirimkan kunci API ini sebagai parameter kueri bernama key.

Menggunakan perujukan dengan API penelusuran Anda dengan endpoint yang kompatibel

Jika sudah memiliki endpoint API yang memenuhi persyaratan skema dan autentikasi, Anda dapat mengonfigurasinya secara langsung dalam panggilan Gemini API.

Mengonfigurasi alat externalApi

Saat membuat permintaan ke Gemini API, sertakan parameter alat dengan alat pengambilan yang dikonfigurasi untuk externalApi. Kolom utama mencakup hal berikut:

  • api_spec: "SIMPLE_SEARCH": Ini memberi tahu Gemini untuk menggunakan skema input dan output yang telah ditentukan sebelumnya.
  • endpoint: URL lengkap ke endpoint Gateway API Anda, seperti https://YOUR_GATEWAY_HOSTNAME/v0/search.

  • apiAuth.apiKeyConfig.apiKeyString: Kunci API yang digunakan Gemini untuk mengautentikasi dengan API Anda. Gemini menambahkan kunci ini sebagai ?key=<YOUR_API_KEY> ke URL endpoint.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Region untuk memproses permintaan, seperti us-central1.
  • PROJECT_ID: ID project Google Cloud Anda.
  • MODEL_ID: ID model Gemini yang kompatibel, seperti gemini-2.0-flash-001.
  • USER_PROMPT: Petunjuk teks yang akan disertakan dalam perintah.
  • EXTERNAL_API_ENDPOINT: URL lengkap ke endpoint Gateway API yang diamankan yang dipanggil Gemini, seperti https://YOUR_GATEWAY_HOSTNAME/v0/search. Endpoint ini harus mematuhi skema API yang ditentukan.
  • EXTERNAL_API_KEY: Kunci API yang Anda buat dan konfigurasi untuk API Gateway. Gemini menggunakan kunci ini untuk mengautentikasi dengan endpoint Anda.

Metode HTTP dan URL:

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

Meminta isi JSON:

  {
  "contents": [{
      "role": "user",
      "parts": [{
          "text": "USER_PROMPT"
      }]
  }],
  "tools": [{
      "retrieval": {
        "externalApi": {
          "api_spec": "SIMPLE_SEARCH",
          "endpoint": "EXTERNAL_API_ENDPOINT",
          "apiAuth": {
            "apiKeyConfig": {
              "apiKeyString": "EXTERNAL_API_KEY"
            }
          }
        }
      }
  }]
}

Untuk mengirim permintaan Anda, gunakan salah satu opsi berikut:

curl

Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud CLI init atau gcloud CLI auth login , atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun aktif dengan menjalankan gcloud CLI auth list.

Simpan isi permintaan dalam file bernama request.json, lalu jalankan perintah berikut:

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

Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud CLI init atau gcloud CLI auth login. Anda dapat memeriksa akun aktif dengan menjalankan gcloud CLI auth list.

Simpan isi permintaan dalam file bernama request.json, lalu jalankan perintah berikut:

$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

Anda akan melihat respons JSON seperti berikut:

{
  "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": {
    "..."
  }
}

Menyiapkan endpoint API penelusuran

Jika Anda tidak memiliki endpoint API yang ada dan memenuhi persyaratan, bagian ini akan memandu Anda menyiapkan endpoint menggunakan Cloud Functions dan API Gateway.

Membuat wrapper API eksternal dengan Cloud Functions

Cloud Function dapat bertindak sebagai perantara yang menerima kueri dari Gemini, mengeluarkan kueri yang sesuai ke infrastruktur penelusuran yang ada, seperti database, mesin telusur internal, atau penelusuran vektor, lalu memformat hasilnya dalam skema yang dipahami Gemini.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi Cloud Run Functions.

Contoh penyiapan Cloud Function (Python)

Contoh ini menggunakan daftar produk yang di-hardcode untuk demonstrasi. Anda harus mengganti logika pengambilan data dengan panggilan ke sistem penelusuran Anda yang sebenarnya.

  1. main.py

    import functions_framework
import json
from flask import jsonify

@functions_framework.http
def custom_search_wrapper_minimal(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)

  2. requirements.py

    functions-framework>=3.0.0
Flask>=2.0.0

  3. Deployment: Buka direktori yang berisi main.py dan requirements.txt, lalu jalankan:

    gcloud functions deploy custom_search_wrapper \
  --runtime python311 \
  --trigger-http \
  --entry-point custom_search_wrapper \
  --region YOUR_REGION \
  --allow-unauthenticated \
  --gen2
    • Ganti YOUR_REGION dengan region Google Cloud pilihan Anda, seperti us-central1.
    • --allow-unauthenticated ditentukan karena API Gateway menangani autentikasi.

Mengamankan Cloud Functions dengan API Gateway dan kunci API

API Gateway menyediakan titik entri terkelola yang aman ke Cloud Functions Anda dan memungkinkan Anda menerapkan autentikasi kunci API.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi API Gateway.

  1. Buat spesifikasi OpenAPI (openapi-spec.yaml): File ini menentukan cara API Gateway mengekspos Cloud Functions Anda. Kebijakan ini menetapkan bahwa gateway mengharapkan permintaan POST ke jalur /v0/search dan memerlukan kunci API yang dikirim sebagai parameter kueri bernama 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: query

  2. Deploy API Gateway: Setelah mengganti variabel berikut, jalankan perintah gcloud CLI:

    • YOUR_PROJECT_ID: ID project Google Cloud Anda.
    • YOUR_REGION: Region Google Cloud yang Anda gunakan untuk Cloud Functions, seperti 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

    Setelah deployment, nama host (URL gateway) memiliki format berikut:

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

    Anda dapat menggunakan nama host untuk membuat URL endpoint lengkap untuk Gemini. Contoh:

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

  3. Buat dan batasi Kunci API: Anda harus membuat kunci API yang digunakan Gemini untuk mengakses endpoint API Gateway Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola kunci API.

    Untuk membuat dan membatasi kunci API, lakukan hal berikut:

    1. Di konsol Google Cloud , buka halaman API Gateway / Enable APIs.

      Buka API Gateway API / Enable APIs

    2. Jika API Gateway API belum diaktifkan, klik Launch, lalu klik Enable.

    3. Pilih Credentials.

    4. Klik Buat kredensial, lalu pilih Kunci API.

    5. Klik Show key, lalu salin kunci API yang dibuat. Simpan kunci di lokasi yang aman. Kunci ini digunakan oleh Gemini.

    6. Klik Edit API key, atau klik nama kunci.

    7. Di bagian API restrictions, lakukan tindakan berikut:

      1. Pilih opsi Restrict key.

      2. Pilih layanan terkelola API Gateway Anda. File ini harus diberi nama sesuai dengan API Anda, seperti Custom Search API for Gemini Grounding API.

      3. Jika kunci tidak disertakan atau jika Anda ingin mengelola gateway dengan API menggunakan kunci ini, pastikan API Gateway API (apigateway.googleapis.com) dipilih. Untuk perujukan, kunci memerlukan akses ke layanan API spesifik Anda yang dihosting oleh API Gateway.

    8. Klik Simpan. Endpoint API Gateway Anda diamankan, dan saat menggunakan endpoint API Gateway, Anda harus meneruskan kunci API sebagai parameter kueri. Contoh:

      https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY

Pertimbangan untuk Search API Anda

Tinjau pertimbangan berikut untuk membantu Anda memilih Search API:

  • Kualitas cuplikan: Teks cuplikan yang ditampilkan oleh API Anda sangat penting. Ringkas, tetapi cukup informatif bagi Gemini untuk digunakan sebagai dasar faktual untuk responsnya.
  • Latensi: API penelusuran Anda harus merespons dengan cepat. Latensi tinggi di API Anda akan meningkatkan waktu respons keseluruhan dari Gemini.
  • Penanganan error: Terapkan penanganan error yang andal di Cloud Functions atau Search API Anda. Jika API Anda sering mengalami error atau waktu tunggu habis, hal ini akan berdampak negatif pada kemampuan Gemini untuk menghasilkan respons yang memiliki rujukan.

Langkah berikutnya