Grounding con Elasticsearch

Questa pagina spiega come utilizzare l'istanza Elasticsearch per basare le risposte sui tuoi dati.

Grounding di Gemini con Elasticsearch

Il grounding prevede l'utilizzo di set di dati pubblici e privati per fornire contesto e fatti su cui basare le risposte dei modelli linguistici di grandi dimensioni (LLM). Eseguendo il grounding con Elasticsearch, puoi sfruttare gli indici Elasticsearch esistenti per migliorare la qualità e l'affidabilità dell'output di Gemini, riducendo le allucinazioni e contribuendo a garantire che le risposte siano pertinenti ai tuoi dati. In questo modo puoi creare potenti applicazioni RAG, come:

  • Riepiloghi di ricerca generativi
  • Chatbot di domande e risposte con dati aziendali
  • Agenti basati sui tuoi dati

Puoi basare una risposta su un massimo di 10 origini dati alla volta. Puoi combinare il grounding con Elasticsearch con il grounding con la Ricerca Google per collegare il modello alle conoscenze del mondo, a un'ampia gamma possibile di argomenti o a informazioni aggiornate su internet.

Modelli supportati

I seguenti modelli supportano il grounding con Elasticsearch solo con input di testo:

Fai clic per espandere i modelli supportati

Configura un template di ricerca in Elasticsearch

Questa sezione spiega come utilizzare l'istanza Elasticsearch per eseguire il grounding dei dati archiviati nell'istanza.

Best practice

Per ottenere le migliori risposte di grounding, utilizza questi principi durante la creazione di un modello di ricerca:

  • Includi solo dati pertinenti e utili. Ad esempio, in un catalogo dei prodotti, specificare l'URL di un'immagine potrebbe non aiutare l'LLM a rispondere ai prompt sulle proprietà del prodotto, a meno che il prompt non richieda specificamente un URL. Allo stesso modo, evita di generare vector embedding.

  • Il grounding rimuove i risultati di Elasticsearch con bassa pertinenza rispetto ai prompt. Devi fornire un numero maggiore di risultati di Elasticsearch per acquisire tutto il contesto pertinente.

  • I dati dei risultati possono trovarsi in un unico campo o essere distribuiti su più campi.

Modelli di esempio

Puoi utilizzare i tuoi modelli di ricerca. Tuttavia, ti consigliamo di utilizzare il modello di ricerca kNN generico con il grounding di Elasticsearch. Per altri modelli di ricerca, consulta il repository GitHub.

Questa ricerca semantica con Gemini Enterprise Agent Platform è una ricerca kNN generica.

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

Genera risposte fondate con Elasticsearch

Questa sezione spiega come utilizzare l'API Agent Platform per eseguire il grounding delle risposte del LLM.

Prerequisiti

Prima di poter basare le risposte LLM su Elasticsearch, devi completare quanto segue:

  1. Attiva l'API Agent Platform: assicurati che l'API Agent Platform sia abilitata per il tuo progetto Google Cloud .

  2. Installa e accedi a Google Cloud CLI: installa e inizializza lo strumento a riga di comando gcloud CLI.

  3. Configurazione di Elasticsearch: utilizza un cluster e un indice Elasticsearch esistenti che vuoi utilizzare per il grounding. Ottieni le seguenti informazioni dalla configurazione di Elasticsearch:

    • Endpoint: l'URL del tuo cluster Elasticsearch.
    • Nome indice: il nome dell'indice in cui vuoi eseguire la ricerca, ad esempio my-data-index.
    • Chiave API: una chiave API che consente l'accesso al tuo cluster Elasticsearch. La chiave API deve iniziare con il prefisso ApiKey.

  4. Crea un template di ricerca Elasticsearch: utilizza un'origine dati Elasticsearch che utilizza un template di riferimento che restituisce i dati dei risultati per il grounding.

Genera risposte fondate

Console

Per eseguire il grounding con Elasticsearch nella console Google Cloud , segui questi passaggi:

  1. Vai alla pagina Agent Studio.

    Vai ad Agent Studio

  2. Nel riquadro laterale, in Impostazioni modello, vai alla sezione Grounding e attiva l'opzione I tuoi dati.

  3. Nel riquadro di configurazione, seleziona Elasticsearch.

  4. Inserisci l'endpoint nel campo Endpoint Elasticsearch.

  5. Inserisci ApiKey YOUR_API_KEY nel campo Chiave API Elasticsearch.

  6. Inserisci l'indice nel campo Indice Elasticsearch.

  7. Inserisci il template di ricerca nel campo Template di ricerca Elasticsearch.

  8. Regola il numero di hit spostando il cursore Numero di hit.

  9. Fai clic su Salva.

  10. Inserisci il prompt.

  11. Fai clic su Invia.

Comprendi la risposta

Se il prompt del modello si basa correttamente sui datastore Elasticsearch utilizzando Agent Studio o l'API, le risposte del modello includono metadati con citazioni e contenuti di origine. Se la risposta del modello presenta una bassa pertinenza della fonte o informazioni incomplete, i metadati potrebbero non essere forniti e la risposta al prompt non sarà basata su dati reali.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con 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

Per inviare un prompt testuale e fare il grounding con Elasticsearch, invia una richiesta POST all'API Agent Platform. Come minimo, devi fornire il corpo della richiesta. Assicurati di effettuare le seguenti sostituzioni:

  • PROMPT: il prompt testuale da fare il grounding.
  • ELASTIC_SEARCH_ENDPOINT: il percorso assoluto dell'endpoint per la risorsa Elasticsearch da utilizzare.
  • ELASTIC_SEARCH_API_KEY: la chiave API per l'endpoint dei dati Elasticsearch.
  • INDEX_NAME: Il nome dell'indice Elasticsearch utilizzato per la messa a terra.
  • SEARCH_TEMPLATE_NAME: il template di ricerca Elasticsearch utilizzato per il grounding.

  • NUM_HITS: il numero di risultati restituiti dall'origine dati Elasticsearch e utilizzati per il grounding.

    Metodo HTTP e URL:

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

    Corpo JSON della richiesta:

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

Per saperne di più su altri campi dell'API, come le istruzioni di sistema e le chat a più turni, consulta la Guida per principianti all'AI generativa.

Invia la richiesta API

Puoi salvare il corpo della richiesta in un file denominato request.json. Quindi esegui la richiesta API POST e apporta le seguenti sostituzioni:

  • LOCATION: la regione in cui elaborare la richiesta. Per utilizzare l'endpoint globale, escludi la località dal nome dell'endpoint e configura la località della risorsa su global.
  • PROJECT_ID: l'ID progetto Google Cloud . Per saperne di più sugli ID progetto, consulta Creazione e gestione dei progetti.
  • MODEL_ID: l'ID del modello multimodale.
  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"

Dovresti ricevere una risposta JSON simile alla seguente:

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

Comprendi la risposta

La risposta di entrambe le API include il testo generato dall'LLM, chiamato candidato. Se il prompt del modello viene sottoposto correttamente al grounding nell'origine dati Elasticsearch, le risposte includono i metadati di grounding, che identificano le parti della risposta derivate dai dati Elasticsearch. Tuttavia, esistono diversi motivi per cui questi metadati potrebbero non essere forniti e la risposta al prompt non sarà basata su dati reali. Questi motivi includono una bassa pertinenza delle fonti o informazioni incomplete nella risposta del modello.

Di seguito è riportata un'analisi dettagliata dei dati di output:

  • Ruolo: indica il mittente della risposta con grounding. Poiché la risposta contiene sempre testo con dati di fatto, il ruolo è sempre model.
  • Testo: la risposta fondata generata dall'LLM.
  • Metadati di grounding: informazioni sulla fonte di grounding, che contiene i seguenti elementi:
    • Chunk di grounding: un elenco di risultati dell'indice Elasticsearch che supportano la risposta.
    • Supporti di grounding: informazioni su un'affermazione specifica all'interno della risposta che possono essere utilizzate per mostrare le citazioni:
    • Segmento: la parte della risposta del modello supportata da un chunk di grounding.
    • Indice del chunk di grounding: l'indice dei chunk di grounding nell'elenco dei chunk di grounding corrispondente a questa dichiarazione.
    • Punteggi di affidabilità: un numero compreso tra 0 e 1 che indica il livello di grounding dell'affermazione nell'insieme di chunk di grounding fornito. Non disponibile per Gemini 2.5 Pro, Gemini 2.5 Flash e versioni successive.

Passaggi successivi