Grounding dengan Elasticsearch

Halaman ini menjelaskan cara menggunakan instance Elasticsearch untuk melakukan grounding respons pada data Anda.

Melakukan Grounding Gemini dengan Elasticsearch

Grounding melibatkan penggunaan set data publik dan pribadi untuk memberikan konteks dan fakta guna mendasari respons Model Bahasa Besar (LLM). Dengan melakukan grounding menggunakan Elasticsearch, Anda dapat memanfaatkan indeks Elasticsearch yang ada untuk membantu meningkatkan kualitas dan keandalan output Gemini, mengurangi halusinasi, dan membantu memastikan respons relevan dengan data Anda. Dengan begitu, Anda dapat membangun aplikasi RAG yang canggih seperti:

  • Ringkasan penelusuran generatif
  • Chatbot tanya jawab dengan data perusahaan
  • Agen yang didasarkan pada data Anda

Anda dapat mendasarkan jawaban pada maksimal 10 sumber data sekaligus. Anda dapat menggabungkan grounding dengan Elasticsearch dengan Grounding dengan Google Penelusuran untuk menghubungkan model dengan informasi global, rentang potensi topik yang luas, atau informasi terbaru di internet.

Model yang didukung

Model berikut mendukung grounding dengan Elasticsearch hanya dengan input teks:

Klik untuk meluaskan model yang didukung

Menyiapkan template penelusuran di Elasticsearch

Bagian ini menjelaskan cara menggunakan instance Elasticsearch untuk melakukan grounding pada data yang disimpan dalam instance tersebut.

Praktik terbaik

Untuk mendapatkan respons grounding terbaik, gunakan prinsip berikut saat membuat template penelusuran:

  • Hanya sertakan data yang relevan dan berguna. Misalnya, dalam katalog produk, menentukan URL gambar mungkin tidak membantu LLM menjawab perintah tentang properti produk, kecuali jika perintah tersebut secara khusus meminta URL. Demikian pula, hindari mengeluarkan vektor embedding.

  • Grounding menghapus hasil Elasticsearch dengan relevansi rendah terhadap perintah Anda. Anda harus memberikan jumlah hasil Elasticsearch yang lebih tinggi untuk menangkap semua konteks yang relevan.

  • Data hasil dapat berada dalam satu kolom atau tersebar di beberapa kolom.

Contoh template

Anda dapat menggunakan template penelusuran. Namun, sebaiknya gunakan template penelusuran kNN generik dengan grounding Elasticsearch. Untuk template penelusuran tambahan, lihat repositori GitHub.

Penelusuran semantik dengan Gemini Enterprise Agent Platform ini adalah penelusuran kNN generik.

    PUT _scripts/google-template-knn-multioutput
    {
      "script": {
        "lang": "mustache",
        "source": {
          "_source": {
            "excludes": [ "title_embedding", "description_embedding", "images"]
          },
            "size": "num_hits",
              "knn" : [
              {
                "field": "description_embedding",
                "k": 5,
                "num_candidates": 10,
                "query_vector_builder": {
                  "text_embedding": {
                    "model_id": "googlevertexai_embeddings_004",
                    "model_text": "query"
                  }
                },
                "boost": 0.4
              },
              {
                "field": "title_embedding",
                "k": 5,
                "num_candidates": 10,
                "query_vector_builder": {
                  "text_embedding": {
                    "model_id": "googlevertexai_embeddings_004",
                    "model_text": "query"
                }
              },
              "boost": 0.6
              }
              ]
        }
      }
    }

Membuat respons yang di-grounding dengan Elasticsearch

Bagian ini menjelaskan cara menggunakan Agent Platform API untuk melakukan grounding pada respons LLM Anda.

Prasyarat

Sebelum dapat melakukan grounding respons LLM dengan Elasticsearch, Anda harus menyelesaikan langkah-langkah berikut:

  1. Aktifkan Agent Platform API: Pastikan Agent Platform API diaktifkan untuk project Google Cloud Anda.

  2. Menginstal dan login ke Google Cloud CLI: Instal dan lakukan inisialisasi alat command line gcloud CLI.

  3. Penyiapan Elasticsearch: Gunakan cluster dan indeks Elasticsearch yang ada yang ingin Anda gunakan untuk grounding. Dapatkan informasi berikut dari penyiapan Elasticsearch Anda:

    • Endpoint: URL cluster Elasticsearch Anda.
    • Index Name: Nama indeks yang ingin Anda telusuri, seperti my-data-index.
    • Kunci API: Kunci API yang mengizinkan akses ke cluster Elasticsearch Anda. Kunci API harus diawali dengan awalan ApiKey.

  4. Membuat template penelusuran Elasticsearch: Gunakan sumber data Elasticsearch yang menggunakan template referensi yang menampilkan data hasil untuk grounding.

Membuat respons yang relevan

Konsol

Untuk melakukan grounding dengan Elasticsearch di konsol Google Cloud , lakukan hal berikut:

  1. Buka halaman Agent Studio.

    Buka Agent Studio

  2. Di panel samping, di bagian Model settings, buka bagian Grounding, dan aktifkan tombol Your data.

  3. Di panel konfigurasi, pilih Elasticsearch.

  4. Masukkan endpoint di kolom Elasticsearch endpoint.

  5. Masukkan ApiKey YOUR_API_KEY di kolom Elasticsearch API Key.

  6. Masukkan indeks di kolom Elasticsearch index.

  7. Masukkan template penelusuran di kolom Elasticsearch search template.

  8. Sesuaikan jumlah hit dengan menggeser penggeser Jumlah hit.

  9. Klik Simpan.

  10. Masukkan perintah Anda.

  11. Klik Kirim.

Memahami respons Anda

Jika perintah model Anda berhasil di-grounding ke penyimpanan data Elasticsearch menggunakan Agent Studio atau API, respons model akan menyertakan metadata dengan kutipan dan konten sumber. Jika relevansi sumber rendah atau informasi yang tidak lengkap terjadi dalam respons model, metadata mungkin tidak akan diberikan, dan respons perintah tidak akan di-grounding.

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan Vertex AI: 

# 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,
    Elasticsearch,
    Retrieval,
    Tool,
    HttpOptions,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Replace with your Elasticsearch details
ELASTIC_SEARCH_ENDPOINT = "YOUR_ELASTICSEARCH_ENDPOINT"
ELASTIC_SEARCH_API_KEY = "YOUR_ELASTICSEARCH_API_KEY"
INDEX_NAME = "YOUR_INDEX_NAME"
SEARCH_TEMPLATE_NAME = "YOUR_SEARCH_TEMPLATE_NAME"
NUM_HITS = 5

tool = Tool(
    retrieval=Retrieval(
        external_api=Elasticsearch(
            api_spec="ELASTIC_SEARCH",
            endpoint=ELASTIC_SEARCH_ENDPOINT,
            api_auth={
                "apiKeyConfig": {
                    "apiKeyString": f"ApiKey {ELASTIC_SEARCH_API_KEY}"
                }
            },
            elastic_search_params={
                "index": INDEX_NAME,
                "searchTemplate": SEARCH_TEMPLATE_NAME,
                "numHits": NUM_HITS,
            },
        )
    )
)

response = client.models.generate_content(
    model="gemini-2.5-flash",  # Or another supported model
    contents="What are the main features of product X?", # Your query
    config=GenerateContentConfig(
        tools=[tool],
    ),
)

print(response.text)

REST

Untuk mengirim perintah teks dan melakukan grounding dengan Elasticsearch, kirim permintaan POST ke Agent Platform API. Setidaknya, Anda harus memberikan isi permintaan. Pastikan untuk melakukan penggantian berikut:

  • PROMPT: Perintah teks yang akan di-grounding.
  • ELASTIC_SEARCH_ENDPOINT: Jalur endpoint absolut untuk resource Elasticsearch yang akan digunakan.
  • ELASTIC_SEARCH_API_KEY: Kunci API untuk endpoint data Elasticsearch.
  • INDEX_NAME: Nama indeks Elasticsearch yang digunakan untuk grounding.
  • SEARCH_TEMPLATE_NAME: Template penelusuran Elasticsearch yang digunakan untuk grounding.

  • NUM_HITS: Jumlah hasil yang ditampilkan dari sumber data Elasticsearch dan digunakan untuk grounding.

    Metode HTTP dan URL:

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

    Meminta isi JSON:

      {
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "PROMPT"
          }
        ]
      }
    ],
    "tools": [{
      "retrieval": {
        "externalApi": {
          "api_spec": "ELASTIC_SEARCH",
          "endpoint": "ELASTIC_SEARCH_ENDPOINT",
          "apiAuth": {
            "apiKeyConfig": {
              "apiKeyString": "ApiKey ELASTIC_SEARCH_API_KEY"
            }
          },
          "elasticSearchParams": {
            "index": "INDEX_NAME",
            "searchTemplate": "SEARCH_TEMPLATE_NAME",
            "numHits": "NUM_HITS",
          }
        }
      }
    }]
  }

Untuk mengetahui informasi selengkapnya tentang kolom API lainnya seperti petunjuk sistem dan percakapan multi-turn, lihat Panduan pemula AI generatif.

Mengirim permintaan API

Anda dapat menyimpan isi permintaan dalam file bernama request.json. Kemudian, jalankan permintaan POST API, dan lakukan penggantian berikut:

  • LOCATION: Region untuk memproses permintaan. Untuk menggunakan endpoint global, kecualikan lokasi dari nama endpoint, dan konfigurasikan lokasi resource ke global.
  • PROJECT_ID: Project ID Google Cloud Anda. Untuk mengetahui informasi selengkapnya tentang project ID, lihat Membuat dan mengelola project.
  • MODEL_ID: ID model dari model multimodal.
  curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
      -d @request.json \
  "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

Anda akan melihat respons JSON seperti berikut:

  {
    "candidates": [
      {
        "content": {
          "role": "model",
          "parts": [
            {
              "text": "Based on the information ..."
            }
          ]
        },
        "finishReason": "STOP",
        "safetyRatings": [ "..." ],
        "groundingMetadata": {
          "groundingChunks": [
            {
              "retrievedContext": {
                "text": "ipsum lorem ..."
              }
            },
            {...},
            {...},
          ],
          "groundingSupports": [
            {
              "segment": {
                "startIndex": 25,
                "endIndex": 147,
                "text": "ipsum lorem ..."
              },
              "groundingChunkIndices": [1,2],
              "confidenceScores": [0.6626542, 0.82018316],
            },
          ],
        },
      }
    ],
  }

Memahami respons Anda

Respons dari kedua API tersebut mencakup teks yang dihasilkan LLM, yang disebut kandidat. Jika perintah model Anda berhasil di-grounding ke sumber data Elasticsearch, responsnya akan menyertakan metadata grounding, yang mengidentifikasi bagian respons yang berasal dari data Elasticsearch Anda. Namun, ada beberapa alasan mengapa metadata ini mungkin tidak diberikan, dan respons perintah tidak akan di-grounding. Alasan ini mencakup relevansi sumber yang rendah atau informasi yang tidak lengkap dalam respons model.

Berikut adalah perincian data output:

  • Role: Menunjukkan pengirim jawaban yang di-grounding. Karena responsnya selalu berisi teks yang di-grounding, perannya selalu model.
  • Text: Jawaban yang di-grounding dan dihasilkan oleh LLM.
  • Metadata grounding: Informasi tentang sumber grounding, yang berisi elemen berikut:
    • Grounding chunks: Daftar hasil dari indeks Elasticsearch Anda yang mendukung jawaban.
    • Dukungan grounding: Informasi tentang klaim tertentu dalam jawaban yang dapat digunakan untuk menampilkan kutipan:
    • Segmen: Bagian dari jawaban model yang didukung oleh grup grounding.
    • Indeks potongan grounding: Indeks potongan grounding dalam daftar potongan grounding yang sesuai dengan klaim ini.
    • Skor keyakinan: Angka dari 0 hingga 1 yang menunjukkan seberapa kuat klaim tersebut didasarkan pada set potongan rujukan yang disediakan. Tidak tersedia untuk Gemini 2.5 Pro dan Gemini 2.5 Flash dan yang lebih baru.

Langkah berikutnya