Grounding con la Ricerca Google

Questa pagina spiega come basare le risposte di un modello sulla Ricerca Google, che utilizza dati web disponibili pubblicamente. Inoltre, vengono spiegate le ricerche suggerite, che sono incluse nelle tue risposte.

Grounding con la Ricerca Google

Se vuoi connettere il tuo modello alla conoscenza del mondo, a un'ampia gamma possibile di argomenti o a informazioni aggiornate su internet, utilizza il grounding con la Ricerca Google.

Per scoprire di più sul grounding dei modelli in Vertex AI, consulta la Panoramica del grounding.

Modelli supportati

Questa sezione elenca i modelli che supportano il grounding con la Ricerca.

• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash con audio nativo dell'API Live (anteprima)
• Gemini 2.0 Flash con API Live (anteprima)
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Lingue supportate

Per un elenco delle lingue supportate, consulta Lingue.

Basa il modello sulla Ricerca Google

Segui le istruzioni riportate di seguito per basare un modello su dati web disponibili pubblicamente.

Considerazioni

• Per utilizzare il grounding con la Ricerca Google, devi attivare i suggerimenti della Ricerca Google. Per saperne di più, vedi Utilizzare i suggerimenti della Ricerca Google.

• Per risultati ottimali, utilizza una temperatura di 1.0. Per scoprire di più su come impostare questa configurazione, consulta il corpo della richiesta dell'API Gemini nel riferimento del modello.

• La funzionalità di grounding con la Ricerca Google ha un limite di un milione di query al giorno. Se hai bisogno di ulteriori query, contatta l'Google Cloud assistenza.

I risultati di ricerca possono essere personalizzati per una posizione geografica specifica utilizzando le coordinate di latitudine e longitudine. Per ulteriori informazioni, consulta l'API Grounding.

pip install --upgrade google-genai

# 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,
    GoogleSearch,
    HttpOptions,
    Tool,
)

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

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="When is the next total solar eclipse in the United States?",
    config=GenerateContentConfig(
        tools=[
            # Use Google Search Tool
            Tool(google_search=GoogleSearch())
        ],
    ),
)

print(response.text)
# Example response:
# 'The next total solar eclipse in the United States will occur on ...'

# 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

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithGoogleSearch shows how to generate text using Google Search.
func generateWithGoogleSearch(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "When is the next total solar eclipse in the United States?"},
		},
			Role: "user"},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{}},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The next total solar eclipse in the United States will occur on March 30, 2033, but it will only ...

	return nil
}

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "googleSearch": {}
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

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/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The weather in Chicago this weekend, will be partly cloudy. The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday. There is a slight chance of rain on both days.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "weather in Chicago this weekend"
        ],
        "searchEntryPoint": {
          "renderedContent": "..."
        },
        "groundingChunks": [
          {
            "web": {
              "uri": "https://www.google.com/search?q=weather+in+Chicago,+IL",
              "title": "Weather information for locality: Chicago, administrative_area: IL",
              "domain": "google.com"
            }
          },
          {
            "web": {
              "uri": "...",
              "title": "weatherbug.com",
              "domain": "weatherbug.com"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 85,
              "endIndex": 214,
              "text": "The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday."
            },
            "groundingChunkIndices": [
              0
            ],
            "confidenceScores": [
              0.8662828
            ]
          },
          {
            "segment": {
              "startIndex": 215,
              "endIndex": 261,
              "text": "There is a slight chance of rain on both days."
            },
            "groundingChunkIndices": [
              1,
              0
            ],
            "confidenceScores": [
              0.62836814,
              0.6488607
            ]
          }
        ],
        "retrievalMetadata": {}
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 98,
    "totalTokenCount": 108,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 10
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 98
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash",
  "createTime": "2025-05-19T14:42:55.000643Z",
  "responseId": "b0MraIMFoqnf-Q-D66G4BQ"
}

Comprendere la risposta

Se il prompt del modello si basa correttamente sulla Ricerca Google da Vertex AI Studio o dall'API, le risposte includono metadati con link alle fonti (URL web). 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 della fonte o informazioni incomplete nella risposta del modello.

Supporto per il grounding

È consigliabile visualizzare il supporto per la fondatezza, perché ti aiuta a convalidare le risposte degli editori e aggiunge modi per approfondire l'argomento.

Il supporto di grounding per le risposte provenienti dalle fonti della Ricerca Google deve essere mostrato sia inline che in forma aggregata. Ad esempio, guarda l'immagine che segue per un suggerimento su come farlo.

Utilizzo di opzioni alternative per i motori di ricerca

Quando utilizzi il Grounding con la Ricerca Google, un'Applicazione del Cliente può:

• Offrire opzioni di motori di ricerca alternativi.
• Impostare altri motori di ricerca come opzione predefinita.
• Mostrare i propri suggerimenti di ricerca o risultati di ricerca o quelli di terze parti, a condizione che: tutti i risultati non Google vengano visualizzati separatamente dai risultati fondati e dai suggerimenti di ricerca di Google e mostrati in modo da non confondere gli utenti o suggerire che provengano da Google.

Vantaggi

I seguenti prompt e flussi di lavoro complessi che richiedono pianificazione, ragionamento e pensiero possono essere eseguiti quando utilizzi la Ricerca Google come strumento:

• Puoi basarti su informazioni aggiornate e accurate per assicurarti che le risposte siano pertinenti.
• Puoi recuperare artefatti dal web per eseguire l'analisi.
• Puoi trovare immagini, video o altri contenuti multimediali pertinenti per aiutarti nel ragionamento multimodale o nella generazione di attività.
• Puoi eseguire attività di programmazione, risoluzione dei problemi tecnici e altre attività specializzate.
• Puoi trovare informazioni specifiche per regione o contribuire a tradurre i contenuti in modo accurato.
• Puoi trovare siti web pertinenti da esplorare.

Utilizzare i suggerimenti di Ricerca Google

Quando utilizzi il grounding con la Ricerca Google e ricevi suggerimenti di ricerca nella risposta, devi visualizzarli in produzione e nelle tue applicazioni.

Per ulteriori informazioni sul grounding con la Ricerca Google, vedi Grounding con la Ricerca Google.

In particolare, devi mostrare le query di ricerca incluse nei metadati della risposta basata su dati reali. La risposta include:

• "content": risposta generata tramite LLM.
• "webSearchQueries": le query da utilizzare per i suggerimenti di ricerca.

Ad esempio, nel seguente snippet di codice, Gemini risponde a un prompt basato sulla ricerca, che chiede informazioni su un tipo di pianta tropicale.

"predictions": [
  {
    "content": "Monstera is a type of vine that thrives in bright indirect light…",
    "groundingMetadata": {
      "webSearchQueries": ["What's a monstera?"],
    }
  }
]

Puoi prendere questo output e visualizzarlo utilizzando i suggerimenti di ricerca.

Requisiti per i suggerimenti di ricerca

Di seguito sono riportati i requisiti per i suggerimenti:

Requisiti di visualizzazione

Di seguito sono riportati i requisiti di visualizzazione:

• Mostra il suggerimento di ricerca esattamente come fornito e non apportare modifiche a colori, caratteri o aspetto. Assicurati che il suggerimento di ricerca venga visualizzato come specificato nei seguenti mockup, ad esempio la modalità Chiaro e la modalità Buio:

• Ogni volta che viene mostrata una risposta basata su fonti, il suggerimento di ricerca corrispondente deve rimanere visibile.
• Per il branding, devi seguire rigorosamente le linee guida di Google per l'utilizzo da parte di terze parti degli elementi distintivi del brand Google, disponibili nel Centro risorse per il brand.
• Quando utilizzi il grounding con la Ricerca, vengono visualizzati i chip dei suggerimenti di ricerca. Il campo che contiene i chip di suggerimento deve avere la stessa larghezza della risposta fondata dell'LLM.

Comportamento con un tocco

Quando un utente tocca il chip, viene indirizzato direttamente a una pagina dei risultati di ricerca (SRP) per il termine di ricerca visualizzato nel chip. La pagina dei risultati di ricerca può aprirsi all'interno del browser dell'applicazione o in un'applicazione browser separata. È importante non ridurre a icona, rimuovere o ostacolare in alcun modo la visualizzazione della pagina dei risultati di ricerca. Il seguente mockup animato illustra l'interazione tocca e vai alla pagina dei risultati di ricerca.

Codice per implementare un suggerimento di ricerca

Quando utilizzi l'API per basare una risposta sulla ricerca, la risposta del modello fornisce uno stile HTML e CSS conforme nel campo renderedContent, che implementi per visualizzare i suggerimenti di ricerca nella tua applicazione.

Passaggi successivi

• Per scoprire di più sul grounding, consulta la panoramica sul grounding.
• Per scoprire come inviare richieste di prompt di chat, consulta la sezione Chat in più turni.
• Per scoprire di più sulle best practice per l'AI responsabile e sui filtri di sicurezza di Vertex AI, consulta Best practice per la sicurezza.
• Scopri come inviare richieste di prompt di chat.
• Scopri di più sulle best practice per l'AI responsabile e sui filtri di sicurezza di Vertex AI.