Grounding dengan Elasticsearch

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

Mendasarkan Gemini dengan Elasticsearch

Mendasarkan melibatkan penggunaan set data publik dan pribadi untuk memberikan konteks dan fakta guna mendasarkan respons Model Bahasa Besar (LLM) . Dengan mendasarkan 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. Hal ini memungkinkan Anda membuat 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 pendasaran dengan Elasticsearch dengan Grounding with Google Search untuk menghubungkan model dengan informasi global, berbagai topik yang memungkinkan, atau informasi terbaru di internet.

Model yang didukung

Model berikut mendukung pendasaran 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 mendasarkan data yang disimpan di instance.

Praktik terbaik

Untuk mendapatkan respons pendasaran terbaik, gunakan prinsip-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 secara khusus meminta URL. Demikian pula, hindari menampilkan vektor embedding.

  • Pendasaran menghapus hasil Elasticsearch dengan relevansi rendah terhadap perintah Anda. Anda harus memberikan hasil Elasticsearch yang lebih banyak 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 pendasaran Elasticsearch. Untuk template penelusuran tambahan, lihat repositori GitHub.

Penelusuran semantik dengan Platform Agen Gemini Enterprise 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 didasarkan dengan Elasticsearch

Bagian ini menjelaskan cara menggunakan Agent Platform API untuk mendasarkan respons LLM Anda.

Prasyarat

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

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

  2. Menginstal dan login ke Google Cloud CLI 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 pendasaran. Dapatkan informasi berikut dari penyiapan Elasticsearch Anda:

    • Endpoint: URL cluster Elasticsearch Anda.
    • Nama Indeks: Nama indeks yang ingin Anda telusuri seperti my-data-index.
    • Kunci API: Kunci API yang memungkinkan akses ke cluster Elasticsearch Anda. Kunci API harus dimulai dengan awalan ApiKey.

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

Membuat respons yang didasarkan

Konsol

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

  1. Buka Vertex AI Studio ke halaman Create prompt.

    Buka Create prompt

  2. Di panel Settings, untuk mendasarkan data Anda, klik tombol Grounding: Your data.

  3. Di panel Customize Grounding, 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 Number of hits.

  9. Klik Save.

  10. Masukkan perintah Anda.

  11. Klik Submit.

Memahami respons Anda

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

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan 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 mendasarkannya dengan Elasticsearch, kirim permintaan POST ke Agent Platform API. Minimal, Anda harus memberikan isi permintaan. Pastikan untuk melakukan penggantian berikut:

  • PROMPT: Perintah teks yang akan didasarkan.
  • 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 pendasaran.
  • SEARCH_TEMPLATE_NAME: Template penelusuran Elasticsearch yang digunakan untuk pendasaran.

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

    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 chat 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 konfigurasi lokasi resource ke global.
  • PROJECT_ID: Project ID Anda Google Cloud . Untuk mengetahui informasi selengkapnya tentang project ID, lihat Membuat dan mengelola project.
  • MODEL_ID: ID 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 menyertakan teks yang dibuat LLM, yang disebut kandidat. Jika perintah model Anda berhasil didasarkan ke sumber data Elasticsearch, respons akan menyertakan metadata pendasaran, yang mengidentifikasi bagian respons yang berasal dari data Elasticsearch Anda. Namun, ada beberapa alasan metadata ini mungkin tidak diberikan, dan respons perintah tidak akan didasarkan. Alasan ini mencakup relevansi sumber rendah atau informasi tidak lengkap dalam respons model.

Berikut adalah rincian data output:

  • Peran: Menunjukkan pengirim jawaban yang didasarkan. Karena respons selalu berisi teks yang didasarkan, peran selalu model.
  • Teks: Jawaban yang didasarkan yang dibuat oleh LLM.
  • Metadata pendasaran: Informasi tentang sumber pendasaran, yang berisi elemen berikut:
    • Grounding chunks: Daftar hasil dari indeks Elasticsearch Anda yang mendukung jawaban.
    • Dukungan dasar: Informasi tentang klaim tertentu dalam jawaban yang dapat digunakan untuk menampilkan kutipan:
    • Segmen: Bagian jawaban model yang dibuktikan oleh potongan pendasaran.
    • Indeks potongan pendasaran: Indeks potongan pendasaran dalam daftar potongan pendasaran yang sesuai dengan klaim ini.
    • Skor kepercayaan: Angka dari 0 hingga 1 yang menunjukkan seberapa didasarkan klaim dalam kumpulan potongan pendasaran yang diberikan. Tidak tersedia untuk Gemini 2.5 Pro dan Gemini 2.5 Flash serta yang lebih baru.

Langkah berikutnya

  • Untuk mempelajari cara mengirim permintaan perintah chat, lihat Chat multi-turn.
  • Untuk mempelajari praktik terbaik responsible AI dan filter keamanan Agent Platform, lihat Praktik terbaik keamanan.