Grounding con Agent Search

Questa pagina spiega come basare le risposte sui tuoi dati di Ricerca agente.

Basare Gemini sui 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 Grounding con Ricerca agente.

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

Modelli supportati

Questa sezione elenca i modelli che supportano il grounding con i tuoi dati.

Prerequisiti

Prima di poter basare l'output del modello sui tuoi dati:

  1. Nella Google Cloud console, 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 Ricerca 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 di Discovery Engine e creare un'istanza di Ricerca agente: Discovery Engine Editor (roles/discoveryengine.editor).

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

  2. Attiva AI Applications e l'API.

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

    Per saperne di più, consulta Introduzione a Ricerca agente.

Attivare AI Applications

Per utilizzare Ricerca agente per basare le risposte, devi attivare il servizio Ricerca agente seguendo questi passaggi:

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

    Vai a AI Applications

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

AI Applications è disponibile nella località global o nelle multi-regioni eu e us. Per saperne di più, consulta Località di AI Applications.

Creare un datastore in AI Applications

Per creare un datastore in AI Applications, puoi scegliere di basare i risultati sui dati del sito web o sui documenti.

Sito web

  1. Apri la pagina Crea dati store dalla Google Cloud console.

  2. Nella casella Contenuti 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.
    Configura il datastore viene visualizzato il riquadro.

  4. Nella sezione Specifica i pattern URL da indicizzare, esegui le seguenti operazioni:

    • Aggiungi gli URL per i siti da includere.
    • (Facoltativo) Aggiungi gli URL per i 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 basate sul datastore. Per saperne di più, consulta Generare risposte basate sul datastore con il tuo datastore.
    3. Fai clic su Crea.

Documenti

  1. Apri la pagina Crea dati store dalla Google Cloud console.

  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 Frequenza di sincronizzazione.

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

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

  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 dei documenti, espandi la sezione Opzioni di elaborazione dei documenti. Per saperne di più sui diversi parser, consulta Analizzare i documenti.
    4. Fai clic su Crea.

  8. Fai clic su Crea.

Generare risposte basate sul datastore

Segui queste istruzioni per basare un modello sui tuoi dati. È supportato un massimo di 10 datastore.

Se non conosci l'ID del datastore:

  1. Nella Google Cloud console, 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 AI Applications utilizzando Vertex AI Studio nella Google Cloud console:

  1. Nella Google Cloud console, vai alla pagina Vertex AI Studio.

    Vai a Vertex AI Studio

  2. Per attivare il grounding:
    1. Nel menu di navigazione, fai clic su + Nuovo e Chat.
    2. Espandi il riquadro Impostazioni modello e seleziona il modello.
    3. (Facoltativo) Se l'opzione Output strutturato o Grounding: Google è attiva, disattivala.
    4. Fai clic sul pulsante di attivazione/disattivazione Grounding: i tuoi dati. Viene visualizzato il riquadro Personalizza grounding.
      1. Seleziona un'opzione di origine del grounding dalla tabella seguente:
        2. Opzione di grounding Descrizione Input
        Vertex AI RAG Engine Basa i risultati sui tuoi dati e sui componenti fai da te. Se non hai un corpus, devi crearne uno. In caso contrario, inserisci il corpus.
        Ricerca agente Basa i risultati sui tuoi dati con un Google-motore di ricerca gestito. Inserisci il percorso nel campo Percorso datastore Vertex AI.
        Elasticsearch Basa i risultati su 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 Modello di ricerca Elasticsearch.
      2. Fai clic su Salva.
  3. Inserisci il prompt nella casella di testo e fai clic su Invia. Le risposte ai prompt sono basate su AI Applications.

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 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_VERTEXAI=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 Vertex AI 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 di testo utilizzando l'API Vertex AI, 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 modello 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": {
    "..."
  }
}

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, le risposte includono metadati di grounding, che identificano le parti della risposta derivate dai tuoi dati. Tuttavia, esistono diversi motivi per cui questi metadati potrebbero non essere forniti e la risposta al prompt non verrà basata. 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. Poiché la risposta contiene sempre testo basato, il ruolo è sempre model.
  • Testo: la risposta basata 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 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 dei blocchi di grounding: l'indice dei blocchi di grounding nell' elenco dei blocchi di grounding che corrisponde a questa affermazione.
    • Punteggi di attendibilità: un numero compreso tra 0 e 1 che indica quanto l'affermazione è basata sul set di blocchi di grounding fornito. Non disponibile per Gemini 2.5 e versioni successive.

Passaggi successivi