Grounding dengan Elasticsearch

Konsol

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

1. Buka Vertex AI Studio ke halaman Create prompt.

   Buka Buat perintah

2. Di panel Setelan, untuk mendasarkan data Anda, klik tombol Pendasaran: Data Anda.

3. Di panel Sesuaikan Perujukan, 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 melakukan perujukan ke datastore 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 di-grounding.

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_VERTEXAI=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 menyandarkannya dengan Elasticsearch, kirim permintaan POST ke Vertex AI API. Minimal, Anda harus memberikan isi permintaan. Pastikan untuk melakukan penggantian berikut:

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

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

  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-giliran, 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 konfigurasi lokasi resource ke global.
• PROJECT_ID: ID project Google Cloud Anda. Untuk mengetahui informasi selengkapnya tentang ID project, 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 mendasarkan pada sumber data Elasticsearch, respons akan menyertakan metadata perujukan, 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 respons selalu berisi teks yang dirujuk, peran selalu model.
• Teks: Jawaban yang dirujuk 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.
  • Dukungan perujukan: Informasi tentang klaim tertentu dalam jawaban yang dapat digunakan untuk menampilkan kutipan:
  • Segmen: Bagian jawaban model yang didukung oleh potongan perujukan.
  • Indeks potongan perujukan: Indeks potongan perujukan dalam daftar potongan perujukan yang sesuai dengan klaim ini.
  • Skor keyakinan: Angka dari 0 hingga 1 yang menunjukkan seberapa kuat klaim tersebut didasarkan pada kumpulan perujukan yang disediakan. Tidak tersedia untuk Gemini 2.5 Pro dan Gemini 2.5 Flash serta versi yang lebih baru.