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 per fondare le risposte del modello linguistico 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 della ricerca generativa
• Chatbot di domande e risposte con dati aziendali
• Agenti basati sui tuoi dati

Puoi basare una risposta su un massimo di 10 origini dati contemporaneamente. Puoi combinare il grounding con Elasticsearch con il grounding con la Ricerca Google per collegare il modello alla conoscenza 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

• Gemini Nano Banana 2.1
• Gemini 3.8 Live
• Gemini 3.8 Flash
• Gemini 3.7 Flash
• Gemini 3.6 Flash
• Gemini 3.5 Flash-Lite
• Gemini 3.5 Flash
• Gemini 3.1 Pro anteprima
• Gemini 3.1 Flash-Lite
• Gemini 3.1 Flash Image
• Gemini 3 Pro Image
• Gemini 3 Flash (anteprima)
• Gemini 2.5 Pro
• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash con audio nativo dell'API Gemini Live
• Gemini 2.5 Flash

Configurare un modello 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 base, utilizza questi principi quando crei un modello di ricerca:

• Includi solo dati pertinenti e utili. Ad esempio, in un catalogo di prodotti, specificare un URL 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 restituire i vector embedding.

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

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

Modelli di esempio

Puoi utilizzare i 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
              }
              ]
        }
      }
    }

Generare risposte fondate con Elasticsearch

Questa sezione spiega come utilizzare l'API Agent Platform per basare le risposte del modello LLM su dati reali.

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 Elasticsearch esistente e l'indice che vuoi utilizzare per il grounding. Ottieni le seguenti informazioni dalla configurazione di Elasticsearch:

   • Endpoint: l'URL del 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 modello di ricerca Elasticsearch: utilizza un'origine dati Elasticsearch che utilizza un modello di riferimento che restituisce dati dei risultati per il grounding.

Generare risposte fondate

Console

Per eseguire il grounding con Elasticsearch nella console Google Cloud :

1. Vai alla pagina Agent Studio.

   Vai ad Agent Studio

2. Nel riquadro laterale, in Impostazioni modello, vai alla sezione Grounding e attiva il pulsante di attivazione/disattivazione 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 modello 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.

Comprendere 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 nella risposta del modello si verifica 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 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 utilizzare come base.
• ELASTIC_SEARCH_ENDPOINT: il percorso assoluto dell'endpoint per la risorsa Elasticsearch da utilizzare.
• ELASTIC_SEARCH_API_KEY: la chiave API per l'endpoint dati Elasticsearch.
• INDEX_NAME: il nome dell'indice Elasticsearch utilizzato per la base.
• 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 API, come le istruzioni di sistema e le chat multi-turno, 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 POST API ed esegui 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: il tuo ID progetto Google Cloud . Per saperne di più sugli ID progetto, consulta la pagina Creare e gestire progetti.
• MODEL_ID: l'ID modello 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],
            },
          ],
        },
      }
    ],
  }

Comprendere la risposta

La risposta di entrambe le API include il testo generato dall'LLM, chiamato candidato. Se il prompt del modello si basa correttamente sull'origine dati Elasticsearch, le risposte includono metadati di base, 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 del 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 una suddivisione dei dati di output:

• Ruolo: indica il mittente della risposta basata su fonti. Poiché la risposta contiene sempre testo basato su dati reali, il ruolo è sempre model.
• Testo: la risposta fondata generata dall'LLM.
• Metadati di grounding: informazioni sull'origine del grounding, che contiene i seguenti elementi:
  • Chunk di grounding: un elenco di risultati dell'indice Elasticsearch che supportano la risposta.
  • Fonti di supporto: informazioni su un'affermazione specifica all'interno della risposta che possono essere utilizzate per mostrare le citazioni:
  • Segmento: la parte della risposta del modello che è supportata da un blocco di grounding.
  • Indice del chunk di grounding: l'indice dei chunk di grounding nell'elenco dei chunk di grounding che corrisponde a questa richiesta.
  • Punteggi di affidabilità: un numero compreso tra 0 e 1 che indica quanto l'affermazione sia basata sul set di chunk di grounding fornito. Non disponibile per Gemini 2.5 Pro e Gemini 2.5 Flash e versioni successive.

Passaggi successivi

• Per scoprire come inviare richieste di prompt della chat, consulta la sezione Chat in più turni.
• Per scoprire le best practice per l'AI responsabile e i filtri di sicurezza della piattaforma di agenti, consulta Best practice per la sicurezza.