Grounding con Elasticsearch

Console

Per eseguire il grounding con Elasticsearch nella console Google Cloud :

1. Vai a Vertex AI Studio alla pagina Crea prompt.

   Vai a Crea prompt

2. Nel riquadro Impostazioni, per basare i dati su fatti reali, fai clic sul pulsante di attivazione/disattivazione Basamento: i tuoi dati.

3. Nel riquadro Personalizza grounding, seleziona Elasticsearch.

4. Inserisci l'endpoint nel campo Endpoint Elasticsearch.

5. Inserisci la chiave API 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. Modifica 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 Vertex AI 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 della fonte o informazioni incomplete, i metadati potrebbero non essere forniti e la risposta al prompt non sarà basata su dati reali.

REST

Questa sezione spiega come utilizzare l'API Vertex AI per basare le risposte del tuo LLM su dati reali.

Prerequisiti

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

1. Attiva l'API Vertex AI: assicurati che l'API Vertex AI 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 e un indice esistenti 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 i dati dei risultati per il grounding.

Accesso API

Utilizza le seguenti istruzioni per basare Gemini sulla tua origine dati Elasticsearch utilizzando l'API Vertex AI.

Prepara una richiesta di generazione fondata

Per inviare un prompt di testo e basarlo su Elasticsearch, invia una richiesta POST all'API Vertex AI. Come minimo, devi fornire il corpo della richiesta. Assicurati di effettuare le seguenti sostituzioni:

• QUERY: il prompt di testo da utilizzare come base.
• ELASTIC_SEARCH_ENDPOINT: il percorso dell'endpoint assoluto 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 modello di ricerca Elasticsearch utilizzato per il grounding.
• NUM_HITS: il numero di risultati restituiti dall'origine dati Elasticsearch e utilizzati per il grounding.

Corpo JSON della richiesta:

    {
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "text": "QUERY"
            }
          ]
        }
      ],
      "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 ulteriori informazioni su altri campi dell'API, come le istruzioni di sistema e le chat multi-turno, 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 esegui le seguenti sostituzioni:

• LOCATION: la regione in cui elaborare la richiesta. Per ulteriori informazioni sulle località disponibili, consulta AI generativa su Vertex AI.
• 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 dati reali. Poiché la risposta contiene sempre testo basato su dati reali, il ruolo è sempre model.
• Testo: la risposta basata su grounding 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 chunk di grounding.
  • Indice del blocco di grounding: l'indice dei blocchi di grounding nell'elenco dei blocchi di grounding che corrisponde a questa rivendicazione.
  • 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.