Grounding con Elasticsearch

Console

Per basare le risposte sui dati con Elasticsearch nella Cloud de Confiance console, procedi nel seguente modo:

1. Vai alla pagina Agent Studio.

   Vai a Agent Studio

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

8. Regola il numero di risultati scorrendo il cursore Numero di risultati.

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 di 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 verificano una bassa pertinenza dell'origine o informazioni incomplete, i metadati potrebbero non essere forniti e la risposta del prompt non sarà basata sui dati.

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 dell'endpoint assoluto per la risorsa Elasticsearch da utilizzare.
• ELASTIC_SEARCH_API_KEY: la chiave API per l'endpoint dei dati di Elasticsearch.
• INDEX_NAME: il nome dell'indice Elasticsearch utilizzato per il grounding.
• SEARCH_TEMPLATE_NAME: il modello 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 a più turni, consulta la Guida introduttiva 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 ed effettua 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' Cloud de Confiance by S3NS ID progetto. 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 grounding, che identificano le parti della risposta derivate dai dati di Elasticsearch. Tuttavia, esistono diversi motivi per cui questi metadati potrebbero non essere forniti e la risposta del prompt non sarà basata sui dati. Questi motivi includono una bassa pertinenza dell'origine o informazioni incomplete nella risposta del modello.

Di seguito è riportata una suddivisione dei dati di output:

• Ruolo: indica il mittente della risposta basata sui dati. Poiché la risposta contiene sempre testo basato sui dati, il ruolo è sempre model.
• Testo: la risposta basata sui dati generata dall'LLM.
• Metadati di grounding: informazioni sull'origine del grounding, che contiene i seguenti elementi:
  • Blocchi 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 può essere utilizzata per mostrare le citazioni:
  • Segmento: la parte della risposta del modello supportata da un blocco di grounding.
  • Indice del blocco di grounding: l'indice dei blocchi di grounding nell' elenco dei blocchi di grounding che corrisponde a questa affermazione.
  • Punteggi di affidabilità: un numero compreso tra 0 e 1 che indica quanto sia basata sui dati l'affermazione nel set di blocchi di grounding fornito. Non disponibile per Gemini 2.5 Pro e Gemini 2.5 Flash e versioni successive.