Grounding dengan Elasticsearch

Konsol

Untuk melakukan perujukan dengan Elasticsearch di konsol Cloud de Confiance , lakukan hal berikut:

1. Buka halaman Agent Studio.

   Buka Agent Studio

2. Di panel samping, di bagian Setelan model, buka bagian Perujukan, lalu aktifkan tombol Data Anda.

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 mendasarkan pada penyimpanan data Elasticsearch menggunakan Agent 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 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 mengirimkan perintah teks dan mendasarkannya pada 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.

Kirim 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 Cloud de Confiance by S3NS Anda. 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 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 memiliki rujukan. Alasan tersebut mencakup relevansi sumber yang rendah atau informasi yang tidak lengkap dalam respons model.

Berikut adalah perincian data output:

• Peran: Menunjukkan pengirim jawaban berbasis informasi. Karena responsnya selalu berisi teks yang di-grounding, perannya selalu model.
• Teks: Jawaban yang relevan yang dihasilkan oleh LLM.
• Metadata perujukan: Informasi tentang sumber perujukan, yang berisi elemen berikut:
  • Potongan perujukan: Daftar hasil dari indeks Elasticsearch Anda yang mendukung jawaban.
  • Perujukan mendukung: 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 serta versi yang lebih baru.