Grounding con Agent Search

Questa pagina spiega come basare le risposte utilizzando i dati di Ricerca agente.

Grounding di Gemini con i tuoi dati

Se vuoi eseguire la Retrieval-Augmented Generation (RAG), collega il modello ai dati del tuo sito web o ai tuoi set di documenti, quindi utilizza il grounding con Agent Search.

Il grounding sui tuoi dati supporta un massimo di 10 origini dati di Agent Search e può essere combinato con il grounding con la Ricerca Google.

Modelli supportati

In questa sezione sono elencati i modelli che supportano il grounding con i tuoi dati.

Fai clic per espandere i modelli supportati

Prerequisiti

Prima di poter basare l'output del modello sui tuoi dati, procedi nel seguente modo:

  1. Nella console Google Cloud , vai alla pagina IAM e cerca l'autorizzazione discoveryengine.servingConfigs.search, necessaria per il funzionamento del servizio di grounding.

    Vai a IAM

    Per ottenere le autorizzazioni necessarie per utilizzare il grounding con la ricerca dell'agente, chiedi all'amministratore di concederti i seguenti ruoli IAM:

    • Per leggere tutte le risorse di Discovery Engine: Discovery Engine Viewer (roles/discoveryengine.viewer).

    • Per leggere e scrivere tutte le risorse Discovery Engine e creare un'istanza di ricerca dell'agente: Discovery Engine Editor (roles/discoveryengine.editor).

    Per saperne di più su IAM, consulta Ruoli e autorizzazioni IAM.

  2. Abilita AI Applications e attiva l'API.

  3. Crea un'origine dati di AI Applications e un'applicazione.

    Per saperne di più, consulta l'Introduzione alla ricerca degli agenti.

Attivare AI Applications

Per utilizzare Agent Search per basare le risposte, devi attivare il servizio Agent Search seguendo questi passaggi:

  1. Nella Google Cloud console, vai alla pagina AI Applications.

    Vai ad AI Applications

  2. (Facoltativo) Esamina i termini per l'utilizzo dei dati.

AI Applications è disponibile nella località global o nelle multiregioni eu e us. Per saperne di più, consulta Località delle applicazioni AI.

Crea un datastore in AI Applications

Per creare un datastore in AI Applications, puoi scegliere di utilizzare come base i dati o i documenti del sito web.

Sito web

  1. Apri la pagina Crea datastore dalla console Google Cloud .

  2. Nella casella Contenuto del sito web, fai clic su Seleziona.
    Viene visualizzato il riquadro Specifica i siti web per il datastore.

  3. Se l'opzione Indicizzazione avanzata dei siti web non è selezionata, seleziona la casella di controllo Indicizzazione avanzata dei siti web per attivarla. Viene visualizzato il riquadro
    Configura il datastore.

  4. Nella sezione Specifica i pattern URL da indicizzare, segui questi passaggi:

    • Aggiungi gli URL per i Siti da includere.
    • (Facoltativo) Aggiungi gli URL dei siti da escludere.

  5. Fai clic su Continua.

  6. Nel riquadro Configura il datastore:

    1. Seleziona un valore dall'elenco Località del datastore.
    2. Inserisci un nome nel campo Nome del tuo datastore. L'ID viene generato. Utilizza questo ID quando generi le risposte con grounding con il tuo datastore. Per saperne di più, consulta Genera risposte con fati di fatto con il datastore.
    3. Fai clic su Crea.

Documenti

  1. Apri la pagina Crea datastore dalla console Google Cloud .

  2. Nella casella Cloud Storage, fai clic su Seleziona.
    Viene visualizzato il riquadro Importa dati da Cloud Storage.

  3. Nella sezione Documenti non strutturati (PDF, HTML, TXT e altro), seleziona Documenti non strutturati (PDF, HTML, TXT e altro).

  4. Seleziona un'opzione per Frequenza della sincronizzazione.

  5. Seleziona un'opzione Seleziona una cartella o un file da importare e inserisci il percorso nel campo.

  6. Fai clic su Continua.
    Viene visualizzato il riquadro Configura il datastore.

  7. Nel riquadro Configura il datastore:

    1. Seleziona un valore dall'elenco Località del datastore.
    2. Inserisci un nome nel campo Nome del tuo datastore. L'ID viene generato.
    3. Per selezionare le opzioni di analisi e suddivisione in blocchi per i tuoi documenti, espandi la sezione Opzioni di elaborazione documenti. Per saperne di più sui diversi parser, consulta Analizza i documenti.
    4. Fai clic su Crea.

  8. Fai clic su Crea.

Genera risposte fondate con il tuo datastore

Utilizza le seguenti istruzioni per basare un modello sui tuoi dati. È supportato un massimo di 10 datastore.

Se non conosci l'ID del datastore, segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina AI Applications e nel menu di navigazione fai clic su Datastore.

    Vai alla pagina Datastore

  2. Fai clic sul nome del tuo datastore.

  3. Nella pagina Dati del datastore, recupera l'ID del datastore.

Console

Per basare l'output del modello su Ricerca agente utilizzando Agent Studio nella consoleGoogle Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Agent Studio.

    Vai ad Agent Studio

  2. Per attivare il grounding, segui questi passaggi:
    1. Nel riquadro laterale, in Impostazioni del modello, seleziona il modello.
    2. Vai alla sezione Grounding e attiva l'opzione I tuoi dati. Viene visualizzato il riquadro di configurazione.
      1. Seleziona un'opzione per l'origine di grounding dalla tabella seguente:
        2. Opzione di grounding Descrizione Input
        RAG Engine Esegue il grounding utilizzando i tuoi dati e componenti fai da te. Se non hai un corpus, devi crearne uno. In caso contrario, inserisci il tuo corpus.
        Agent Search Esegue il grounding utilizzando i tuoi dati con un motore di ricerca gestito da Google. Inserisci il percorso nel campo Percorso del datastore Gemini Enterprise Agent Platform.
        Elasticsearch Esegue il grounding utilizzando Elasticsearch. Inserisci le seguenti informazioni:
        1. Inserisci un valore nel campo Endpoint Elasticsearch.
        2. Inserisci un valore nel campo Chiave API Elasticsearch.
        3. Inserisci un valore nel campo Indice Elasticsearch.
        4. Inserisci un valore nel campo Template di ricerca Elasticsearch.
      2. Fai clic su Salva.
  3. Inserisci il prompt nel campo e fai clic su Invia. Le risposte ai prompt si basano sulla ricerca dell'agente.

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,
    VertexAISearch,
    Retrieval,
    Tool,
    HttpOptions,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Replace with your Agent Search data store details
DATASTORE_PATH = "projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATASTORE_ID"

tool = Tool(
    retrieval=Retrieval(
        vertex_ai_search=VertexAISearch(
            datastore=DATASTORE_PATH
        )
    )
)

response = client.models.generate_content(
    model="gemini-2.5-flash",  # Or another supported model
    contents="What information can you find about topic X in the provided documents?", # Your query
    config=GenerateContentConfig(
        tools=[tool],
    ),
)

print(response.text)

REST

Per testare un prompt testuale utilizzando l'API Agent Platform, invia una richiesta POST all'endpoint del modello del publisher.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • LOCATION: la regione in cui elaborare la richiesta. Per utilizzare l'endpoint global, escludi la località dal nome dell'endpoint e configura la località della risorsa su global.
  • PROJECT_ID: il tuo ID progetto. .
  • MODEL_ID: l'ID del modello multimodale.
  • PROMPT: il prompt da inviare al modello.

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": {
      "vertexAiSearch": {
        "datastore": projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATASTORE_ID
      }
    }
  }],
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "You can make an appointment on the website https://dmv.gov/"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        "..."
      ],
      "groundingMetadata": {
        "retrievalQueries": [
          "How to make appointment to renew driving license?"
        ],
        "groundingChunks": [
          {
            "retrievedContext": {
              "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AXiHM.....QTN92V5ePQ==",
              "title": "dmv"
            }
          }
        ],
        "groundingSupport": [
          {
            "segment": {
              "startIndex": 25,
              "endIndex": 147
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1, 2],
            "confidenceScore": [0.9541752, 0.97726375]
          },
          {
            "segment": {
              "startIndex": 294,
              "endIndex": 439
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1],
            "confidenceScore": [0.9541752, 0.9325467]
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "..."
  }
}

Comprendi la risposta

La risposta di entrambe le API include il testo generato dall'LLM, chiamato candidato. Se il prompt del modello viene basato correttamente sull'origine dati, le risposte includono i metadati di grounding, che identificano le parti della risposta derivate dai dati. 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 del tuo indice 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 e versioni successive.

Passaggi successivi