Melakukan grounding dengan API penelusuran

Panduan ini menunjukkan cara menghubungkan Gemini ke sumber data eksternal Anda dengan melakukan perujukan menggunakan API penelusuran Anda.

Halaman ini membahas beberapa topik berikut:

Diagram berikut merangkum alur kerja untuk menyiapkan endpoint API penelusuran baru:

Cara kerja perujukan dengan Search API Anda

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

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

Anda dapat menggabungkan perujukan menggunakan API penelusuran Anda dengan sumber perujukan lainnya seperti Google Penelusuran. Permintaan pembuatan mendukung hingga 10 sumber perujukan dan kueri multi-alat yang memungkinkan Gemini menggunakan berbagai sumber informasi untuk menghasilkan jawaban yang lebih komprehensif.

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. Aktifkan Vertex AI API di project Google Cloud Anda.
  2. Jika Anda berencana mengikuti panduan penyiapan mendetail untuk membuat endpoint Search API 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 mewakili hasil penelusuran dan harus berisi kolom snippet 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 API penelusuran Anda mendukung penggunaan kunci API untuk mengamankan endpoint Anda. Gemini mengirimkan kunci API ini sebagai parameter kueri bernama key.

Pilih metode perujukan Anda

Sebelum memulai, tentukan apakah akan menggunakan endpoint API yang sudah ada atau menyiapkan endpoint baru. Tabel berikut membandingkan kedua pendekatan ini.

Opsi Deskripsi Kelebihan Kekurangan Kasus Penggunaan
Menggunakan endpoint yang kompatibel Gunakan langsung API yang ada yang memenuhi skema dan metode autentikasi yang diperlukan. Penyiapan lebih cepat; memanfaatkan infrastruktur yang ada. Memerlukan API Anda untuk mematuhi skema tertentu. Anda sudah memiliki layanan penelusuran dengan API yang kompatibel.
Menyiapkan endpoint baru Buat endpoint API baru menggunakan layanan seperti Cloud Functions dan API Gateway untuk bertindak sebagai wrapper bagi sumber data Anda. Sangat fleksibel; dapat menyesuaikan sumber data apa pun untuk memenuhi persyaratan. Penyiapan yang lebih kompleks yang melibatkan beberapa layanan Google Cloud. Sumber data Anda tidak memiliki API yang kompatibel, atau Anda perlu membuat antarmuka penelusuran baru dari awal.

Menggunakan 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 tools dengan alat pengambilan yang dikonfigurasi untuk externalApi. Konfigurasi ini mencakup kolom kunci 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.

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 melakukan autentikasi dengan endpoint Anda.

Untuk mendasari model Anda, kirim permintaan POST ke metode generateContent.

REST

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"
            }
          }
        }
      }
  }]
}

Respons mencakup metadata perujukan dengan detail tentang konteks yang diambil:

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

curl

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

Simpan isi permintaan dari tab REST 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 init atau gcloud auth login. Anda dapat memeriksa akun aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dari tab REST 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

Menyiapkan endpoint API penelusuran baru

Jika Anda tidak memiliki endpoint API yang kompatibel, 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 diperlukan Gemini.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi Cloud Functions.

Contoh penyiapan Cloud Function (Python)

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

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)

requirements.txt

functions-framework>=3.0.0
Flask>=2.0.0

Deployment

Buka direktori yang berisi main.py dan requirements.txt, lalu jalankan perintah berikut:

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 yang Anda pilih, seperti us-central1.
  • --allow-unauthenticated ditentukan karena API Gateway menangani autentikasi.

Setelah deployment, catat URL pemicu. Anda akan menggunakan URL ini di langkah berikutnya.

Mengamankan Cloud Function dengan API Gateway dan kunci API

API Gateway menyediakan titik entri terkelola yang aman ke Cloud Functions dan memungkinkan Anda menerapkan autentikasi kunci API. Untuk mengetahui informasi selengkapnya, lihat dokumentasi API Gateway.

1. Membuat spesifikasi OpenAPI

Buat file bernama openapi-spec.yaml. File ini menentukan cara API Gateway mengekspos Cloud Functions Anda. Kebijakan ini menentukan 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

Ganti YOUR_CLOUD_FUNCTION_TRIGGER_URL dengan URL pemicu yang Anda catat saat men-deploy Cloud Functions.

2. Men-deploy Gateway API

Jalankan perintah gcloud CLI berikut setelah mengganti variabel:

  • YOUR_PROJECT_ID: ID project Google Cloud Anda.
  • YOUR_REGION: Google Cloud region 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 gateway memiliki format https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev. Gunakan nama host ini untuk membuat URL endpoint lengkap untuk Gemini, misalnya: https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search.

3. Membuat dan membatasi kunci API

Anda harus membuat kunci API yang digunakan Gemini untuk mengakses endpoint API Gateway Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola kunci API.

  1. Di Google Cloud konsol, buka halaman API & Layanan > Kredensial.

    Buka API Gateway API / Enable APIs

  2. Klik Buat kredensial, lalu pilih Kunci API.

  3. Salin kunci API yang dibuat dan simpan di lokasi yang aman. Kunci ini digunakan oleh Gemini.

  4. Klik Edit API key.

  5. Di bagian API restrictions, lakukan tindakan berikut:

    1. Pilih opsi Restrict key.
    2. Dari dropdown, pilih layanan terkelola API Gateway Anda. File ini harus diberi nama sesuai dengan API Anda, seperti Custom Search API for Gemini Grounding API.

  6. Klik Simpan.

Endpoint Gateway API Anda kini diamankan. Saat menggunakan endpoint, teruskan kunci API sebagai parameter kueri. Misalnya: 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 mendesain API penelusuran:

  • Kualitas cuplikan: Teks cuplikan yang ditampilkan oleh API Anda sangat penting. Harus ringkas, tetapi cukup informatif bagi Gemini untuk digunakan sebagai dasar faktual 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