Utilizzo di Grounding con Google Search nell'API Gemini

Cosa è il Grounding?

Il "grounding" nei modelli di intelligenza artificiale si riferisce al processo di "ancorare" le risposte del modello a fonti di informazioni verificabili ed esterne. In pratica, significa che invece di basarsi esclusivamente sulla conoscenza interna (che potrebbe essere limitata o non aggiornata), il modello consulta fonti esterne per fornire risposte più accurate, fattuali e aggiornate.

Il grounding risolve diversi problemi tipici dei modelli AI:
• Informazioni obsolete: I modelli AI hanno una data di cut-off della conoscenza, mentre il grounding permette di accedere a informazioni recenti
• Allucinazioni: Riduce significativamente la tendenza dei modelli a generare informazioni non accurate o inventate
• Verificabilità: Fornisce fonti che l'utente può consultare per verificare l'accuratezza delle risposte

Grounding con Google Search nell'API Gemini

La funzionalità Grounding con Google Search nell'API Gemini e AI Studio sfrutta la potenza del motore di ricerca Google per migliorare l'accuratezza e l'attualità delle risposte del modello. Oltre a risposte più fattuali, quando Grounding con Google Search è abilitato, l'API Gemini restituisce fonti di riferimento (link di supporto in linea) e Suggerimenti di Ricerca Google insieme al contenuto della risposta. I Suggerimenti di Ricerca indirizzano gli utenti ai risultati di ricerca corrispondenti alla risposta fornita.

Per vedere da vicino un esempio concreto consideriamo il mondo delle designazioni arbitrali nelle partite di calcio. Questa guida mostrerà nel dettaglio i principi di tale tecnica.

Prima di iniziare

Prima di chiamare l'API Gemini, assicurati di avere installato PHP 7.4 o superiore, e di avere una chiave API Gemini configurata e pronta per l'uso.

Configurare Grounding con Google Search

A partire da Gemini 2.0, Google Search è disponibile come strumento. Ciò significa che il modello può decidere quando utilizzare Google Search. L'esempio seguente mostra come configurare la Ricerca come strumento in PHP 7.4 per ottenere informazioni sugli arbitri di una partita di calcio specifica.

<?php
// Configura la tua chiave API Gemini
$apiKey = 'LA_TUA_CHIAVE_API';

// Funzione per chiamare l'API Gemini con Google Search
function interrogaGeminiConSearch($domanda, $apiKey) {
    // Prepara l'URL dell'API
    $url = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=" . $apiKey;
    
    // Prepara i dati della richiesta
    $datiRichiesta = [
        'contents' => [
            [
                'parts' => [
                    ['text' => $domanda]
                ]
            ]
        ],
        'tools' => [
            [
                'google_search' => new stdClass() // Oggetto vuoto per rispettare il formato JSON
            ]
        ]
    ];
    
    // Inizializza cURL
    $ch = curl_init($url);
    
    // Imposta le opzioni cURL
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($datiRichiesta));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    
    // Esegui la richiesta
    $risposta = curl_exec($ch);
    
    // Verifica errori
    if (curl_errno($ch)) {
        echo 'Errore cURL: ' . curl_error($ch);
        return null;
    }
    
    // Chiudi la sessione cURL
    curl_close($ch);
    
    // Decodifica la risposta JSON
    return json_decode($risposta, true);
}

// Esempio di utilizzo per ottenere informazioni sugli arbitri di una partita
$partita = "Juventus Milan Serie A 12 maggio 2025"; // Modifica con la partita di cui vuoi conoscere gli arbitri
$domanda = "Chi sono gli arbitri della partita di calcio $partita?";

$risultato = interrogaGeminiConSearch($domanda, $apiKey);

// Visualizza il risultato
if ($risultato) {
    echo "<h2>Informazioni sugli arbitri:</h2>";
    
    // Estrai il testo della risposta (la struttura potrebbe variare, adatta in base alla risposta effettiva)
    if (isset($risultato['candidates'][0]['content']['parts'][0]['text'])) {
        echo "<div class='risposta'>";
        echo $risultato['candidates'][0]['content']['parts'][0]['text'];
        echo "</div>";
    }
    
    // Estrai e visualizza le fonti di grounding se presenti
    if (isset($risultato['candidates'][0]['groundingAnnotations'])) {
        echo "<h3>Fonti:</h3>";
        echo "<ul>";
        foreach ($risultato['candidates'][0]['groundingAnnotations'] as $fonte) {
            if (isset($fonte['entity']['webSearchUrl'])) {
                echo "<li><a href='" . $fonte['entity']['webSearchUrl'] . "'>" . $fonte['entity']['title'] . "</a></li>";
            }
        }
        echo "</ul>";
    }
} else {
    echo "Nessun risultato ottenuto dall'API";
}
?>

Funzionalità aggiuntive

La funzionalità Search-as-a-tool permette anche ricerche multi-turno. La combinazione di Search con function calling non è ancora supportata. Search come strumento consente prompt e flussi di lavoro complessi che richiedono pianificazione, ragionamento e riflessione per:

• Trovare informazioni accurate sugli arbitri designati per una partita specifica
• Verificare dettagli sulle decisioni arbitrali controverse in partite passate
• Ottenere statistiche sugli arbitri e il loro storico con determinate squadre
• Consultare le normative arbitrali più recenti
• Trovare informazioni specifiche per regione o campionato
• Tradurre accuratamente contenuti relativi alle designazioni arbitrali

Grounding con Google Search funziona con tutte le lingue disponibili quando si effettuano prompt testuali. Nel piano a pagamento dell'API Gemini Developer, puoi ottenere 1.500 query Grounding con Google Search al giorno gratuitamente, con query aggiuntive fatturate alla tariffa standard di $35 per 1.000 query (cf. prezzi).
Gemini 2.0 rappresenta un passo significativo nell’evoluzione dei modelli multimodali, grazie all’integrazione del grounding che consente una comprensione più ancorata alla realtà e contestualmente più affidabile. Questa capacità di collegare le informazioni generate dal modello a fonti concrete o a elementi del mondo reale apre nuove prospettive per applicazioni in ambiti come l’educazione, la ricerca, l’assistenza e l’automazione. Tuttavia, rimane fondamentale continuare a monitorare e valutare criticamente l’uso di queste tecnologie per garantirne un impiego etico, trasparente e realmente utile.