Eseguire la migrazione agli ultimi modelli Gemini

Questa guida spiega come aggiornare l'applicazione all'ultima versione di Gemini. Questa guida presuppone che la tua applicazione utilizzi già una versione precedente di Gemini. Per scoprire come iniziare a utilizzare Gemini in Gemini Enterprise Agent Platform, consulta la guida rapida all'API Gemini in Gemini Enterprise Agent Platform.

Questa guida non spiega come passare dall'SDK Agent Platform all'SDK Google Gen AI attuale. Per queste informazioni, consulta la nostra guida alla migrazione dell'SDK Agent Platform.

Quali modifiche devo aspettarmi?

L'aggiornamento della maggior parte delle applicazioni di AI generativa all'ultima versione di Gemini richiede poche modifiche al codice o ai prompt. Tuttavia, alcune applicazioni potrebbero richiedere aggiustamenti immediati. È difficile prevedere queste modifiche senza prima testare i prompt con la nuova versione. Prima di eseguire la migrazione completa, ti consigliamo di eseguire test approfonditi. Per suggerimenti su come creare prompt efficaci, consulta le nostre indicazioni sulla strategia per i prompt. Utilizza il nostro elenco di controllo per la salute dei prompt per trovare e risolvere i problemi relativi ai prompt.

Aggiornamento dei report sul conteggio dei token

Potresti notare un aumento previsto del numero di token segnalati, poiché la nostra infrastruttura aggiornata ora acquisisce con precisione tutti i componenti delle richieste, inclusi metadati complessi come schemi di risposta e chiamate di funzioni, che in precedenza venivano conteggiati in modo errato dal sistema legacy.

Devi apportare modifiche significative al codice solo per determinati cambiamenti che causano interruzioni o per utilizzare le nuove funzionalità di Gemini.

A quale modello Gemini devo eseguire la migrazione?

Il modello Gemini che utilizzi dipende dalle esigenze della tua applicazione:

Funzionalità 2.5 Pro 2.5 Flash 2.5 Flash-Lite 3 Flash 3.1 Pro 3.1 Flash-Lite 3.5 Flash
Fase di lancio GA GA GA Anteprima Anteprima GA GA
Modalità di input
Testo, Codice, Immagini, Audio, Video
Testo, Codice, Immagini, Audio, Video
Testo, Codice, Immagini, Audio, Video
Testo, Codice, Immagini, Audio, Video, PDF
Testo, Codice, Immagini, Audio, Video, PDF
Testo, Codice, Immagini, Audio, Video, PDF
Testo, Codice, Immagini, Audio, Video, PDF
Modalità di output
Testo
Testo
Testo
Testo
Testo
Testo
Testo
Finestra contestuale, limite totale di token 1.048.576 1.048.576 1.048.576 1.048.576 1.048.576 1.048.576 1.048.576
Lunghezza del contesto di output 65.535 (valore predefinito) 65.535 (valore predefinito) 65.535 (valore predefinito) 65.536 65.536 65.535 (valore predefinito) 65.535 (valore predefinito)
Grounding con la Ricerca Google
Chiamata di funzione
Esecuzione di codice
Memorizzazione nella cache del contesto implicito
Memorizzazione nella cache del contesto esplicito
Previsioni in batch
API Gemini Live
Perfezionamento
Latenza
SDK consigliato SDK Gen AI SDK Gen AI SDK Gen AI SDK Gen AI SDK Gen AI SDK Gen AI SDK Gen AI
Unità di prezzo Token Token Token Token Token Token Token
Data di ritiro Non prima del 16 ottobre 2026 Non prima del 16 ottobre 2026 Non prima del 16 ottobre 2026

Prima di iniziare la migrazione

Prima di iniziare la procedura di migrazione, tieni presente quanto segue:

InfoSec, governance e approvazioni normative

Ottieni le approvazioni dai team di sicurezza delle informazioni (InfoSec), gestione dei rischi e conformità in anticipo. Copri eventuali regole specifiche relative a rischi e conformità, soprattutto in settori regolamentati come quello sanitario e finanziario.

Disponibilità della posizione

I modelli e le funzionalità di AI generativa di Google e dei partner sulla piattaforma Gemini Enterprise Agent sono disponibili tramite endpoint regionali specifici e un endpoint globale. Gli endpoint globali coprono il mondo intero e offrono una migliore disponibilità e affidabilità rispetto alle singole regioni.

La disponibilità degli endpoint regionali varia in base al modello. Per informazioni dettagliate su ciascun modello, consulta la nostra guida alle sedi.

Differenze di prezzo basate sulla modalità e sulla tokenizzazione

I prezzi variano a seconda del modello Gemini. La nostra pagina dei prezzi elenca i costi per tutte le modalità (testo, codice, immagini, voce e così via) per modello.

Fine-tuning supervisionato

Gli ultimi modelli Gemini offrono una migliore qualità dell'output. Ciò può significare che la tua applicazione non ha più bisogno di un modello ottimizzato. Se la tua applicazione utilizza il fine-tuning supervisionato con un modello Gemini precedente, testa prima la tua applicazione con il modello più recente senza fine-tuning e valuta i risultati.

Se scegli di utilizzare il fine-tuning supervisionato, non puoi spostare il modello ottimizzato esistente dalle versioni precedenti di Gemini. Devi eseguire un nuovo job di ottimizzazione per la nuova versione di Gemini.

Quando ottimizzi un nuovo modello Gemini, inizia con le impostazioni di ottimizzazione predefinite. Non riutilizzare i valori degli iperparametri delle versioni precedenti di Gemini, perché il servizio di ottimizzazione è ottimizzato per le versioni più recenti. Il riutilizzo di impostazioni precedenti è improbabile che produca risultati ottimali.

Test di regressione

Quando esegui l'upgrade all'ultima versione di Gemini, devi eseguire tre tipi principali di test di regressione:

  1. Test di regressione del codice:test di regressione dal punto di vista dell'ingegneria del software e delle operazioni di sviluppo (DevOps). Questo tipo di test di regressione è sempre richiesto.

  2. Test di regressione del rendimento del modello:test di regressione dal punto di vista della data science o del machine learning. Ciò significa garantire che la nuova versione del modello Gemini fornisca output che almeno mantengano lo stesso livello di qualità della versione precedente.

    I test di regressione delle prestazioni del modello sono valutazioni del modello eseguite quando un sistema o il suo modello sottostante cambia. ovvero:

    • Test delle prestazioni offline: test che verificano la qualità degli output del modello in un ambiente di sperimentazione dedicato in base a varie metriche di qualità dell'output del modello.
    • Test delle prestazioni del modello online: test che verificano la qualità degli output del modello in un deployment online live in base al feedback degli utenti implicito o esplicito.
  3. Test di carico: questi test verificano il modo in cui l'applicazione gestisce molte richieste contemporaneamente. Il test di carico è obbligatorio per le applicazioni che utilizzano il Throughput riservato.

Come eseguire la migrazione all'ultima versione

Le sezioni seguenti descrivono i passaggi per eseguire la migrazione all'ultima versione di Gemini. Per risultati ottimali, completa questi passaggi nell'ordine indicato.

1. Requisiti di valutazione e test del modello di documento

  1. Preparati a ripetere tutte le valutazioni pertinenti che hai eseguito quando hai creato l'applicazione, oltre a quelle eseguite da allora.
  2. Se le valutazioni attuali non coprono o misurano completamente tutte le attività eseguite dalla tua applicazione, progetta e prepara altre valutazioni. Per iniziare, puoi utilizzare il nostro playbook di valutazione e le nostre ricette di valutazione.
  3. Se la tua applicazione prevede RAG, l'utilizzo di strumenti, flussi di lavoro complessi degli agenti o catene di prompt, assicurati che i dati di valutazione esistenti consentano di valutare ogni componente in modo indipendente. In caso contrario, raccogli esempi di input-output per ogni componente.
  4. Se la tua applicazione è critica o fa parte di un sistema in tempo reale più ampio rivolto agli utenti, includi la valutazione online.

2. Eseguire upgrade del codice ed eseguire test

L'upgrade del codice richiede tre modifiche principali:

Le sezioni seguenti esaminano queste modifiche in modo più dettagliato.

Eseguire l'upgrade all'SDK Google Gen AI

Se la tua applicazione Gemini 1.x utilizza l'SDK Vertex AI, passa all'SDK Gen AI. Consulta la nostra guida alla migrazione dell'SDK Vertex AI per i dettagli, inclusi esempi di codice per effettuare chiamate simili con l'SDK Gen AI. Le release dell'SDK Vertex AI successive a giugno 2026 non supportano Gemini e le nuove funzionalità di Gemini sono disponibili solo nell'SDK Gen AI.

Ti consigliamo vivamente di eseguire l'aggiornamento alla versione google-genai dell'SDK 2.0.0 o successiva per usufruire di tutte le nuove funzionalità di Gemini 3.5 Flash e dei modelli successivi.

Se non hai mai utilizzato l'SDK Gen AI, consulta il notebook Guida introduttiva a Google AI generativa utilizzando l'SDK Gen AI.

Modificare le chiamate Gemini

Aggiorna il codice di previsione per utilizzare uno degli ultimi modelli Gemini. Come minimo, ciò significa modificare il nome dell'endpoint del modello.

Le modifiche esatte al codice variano in base a come hai creato l'applicazione, in particolare se hai utilizzato l'SDK Gen AI o l'SDK Vertex AI.

Dopo aver apportato modifiche al codice, esegui test di regressione del codice e altri test del software per assicurarti che il codice funzioni come previsto. Questo passaggio verifica se il codice funziona, ma non la qualità delle risposte del modello.

Correggere le modifiche al codice che causano errori

  • Recupero dinamico: passa all'utilizzo del grounding con la Ricerca Google. Questa funzionalità richiede l'SDK Gen AI e non è supportata dall'SDK Vertex AI.
  • Filtri dei contenuti: prendi nota delle impostazioni predefinite dei filtri dei contenuti. Modifica il codice se si basa su un valore predefinito che è stato modificato.
  • Parametro di campionamento dei token Top-K: I modelli successivi a gemini-1.0-pro-vision non supportano la modifica del parametro Top-K.
  • Ragionamento: Gemini 3 Pro e i modelli successivi utilizzano il parametro thinking_level anziché thinking_budget. Per saperne di più, consulta Control model thinking.
  • Firme del pensiero: per Gemini 3 Pro e modelli successivi, se in un turno è prevista una firma del pensiero, ma non viene fornita, il modello restituisce un errore anziché un avviso. Vedi Firme dei pensieri.
  • Risoluzione e tokenizzazione dei contenuti multimediali: Gemini 3 Pro e i modelli successivi utilizzano una lunghezza della sequenza variabile per la tokenizzazione dei contenuti multimediali anziché la panoramica e scansione e hanno nuove risoluzioni e costi dei token predefiniti per immagini, PDF e video. Vedi Comprensione delle immagini e Comprensione dei video.
  • Metadati di utilizzo: per Gemini 3 Pro e modelli successivi, i conteggi dei token PDF in usage_metadata vengono riportati nella modalità IMAGE anziché in DOCUMENT.
  • Segmentazione dell'immagine: la segmentazione dell'immagine non è supportata da Gemini 3 Pro e modelli successivi.
  • Risposte delle funzioni multimodali: per Gemini 3 Pro e modelli successivi, puoi includere dati di immagini e PDF nelle risposte delle funzioni. Vedi Risposte delle funzioni multimodali.
  • Elaborazione dei PDF: per Gemini 3 Pro e modelli successivi, l'OCR non viene utilizzato per impostazione predefinita durante l'elaborazione dei PDF scansionati.

Per questo passaggio, concentrati solo sulle modifiche al codice. Potresti dover apportare altre modifiche in un secondo momento, ma attendi di iniziare la valutazione. Dopo le valutazioni, prendi in considerazione questi aggiustamenti in base ai risultati della valutazione:

  • Se passi al recupero dinamico, potresti dover modificare le istruzioni di sistema per controllare quando viene utilizzata la Ricerca Google (ad esempio, "Only generate queries for the Google Search tool if the user asks about sports. Don't generate queries for any other topic."). Tuttavia, prima di modificare i prompt, attendi di aver effettuato la valutazione.
  • Se hai utilizzato il parametro Top-K, regola gli altri parametri di campionamento dei token, come Top-P, per ottenere risultati simili.

3. Eseguire valutazioni offline

Ripeti le valutazioni che hai eseguito quando hai sviluppato e lanciato per la prima volta la tua applicazione, le valutazioni offline eseguite da allora e le valutazioni aggiuntive che hai identificato nel passaggio 1. Se ritieni ancora che la tua valutazione non copra completamente l'ambito della tua applicazione, esegui ulteriori valutazioni.

Se non disponi di un modo automatizzato per eseguire valutazioni offline, valuta la possibilità di utilizzare Gen AI evaluation service.

Se la tua applicazione utilizza il fine-tuning, esegui la valutazione offline prima di ottimizzare nuovamente il modello con l'ultima versione di Gemini. I modelli più recenti offrono una qualità dell'output migliorata, il che può significare che la tua applicazione non ha più bisogno di un modello ottimizzato.

4. Valuta i risultati della valutazione e ottimizza i prompt e gli iperparametri

Se la valutazione offline mostra che la tua applicazione ha un rendimento inferiore, migliorala finché il suo rendimento non corrisponda a quello del modello precedente. Per farlo:

5. Esegui test di carico

Se la tua applicazione richiede una determinata velocità effettiva minima, esegui test di carico per assicurarti che l'ultima versione dell'applicazione soddisfi i requisiti di velocità effettiva.

Il test di carico deve essere eseguito prima della valutazione online, perché quest'ultima comporta l'esposizione del modello al traffico in tempo reale. Utilizza gli strumenti e la strumentazione di test del carico esistenti per questo passaggio.

Se la tua applicazione soddisfa già le esigenze di velocità effettiva, valuta la possibilità di utilizzare la velocità effettiva di cui è stato eseguito il provisioning. Avrai bisogno di Throughput riservato a breve termine aggiuntivo per coprire il test di carico mentre l'ordine di Throughput riservato attuale gestisce il traffico di produzione.

6. (Facoltativo) Esegui valutazioni online

Passa alla valutazione online solo se la valutazione offline mostra un'elevata qualità dell'output di Gemini e la tua applicazione richiede una valutazione online.

La valutazione online è un tipo specifico di test online. Prova a utilizzare gli strumenti e i metodi esistenti della tua organizzazione per la valutazione online. Ad esempio:

  • Se la tua organizzazione esegue regolarmente test A/B, esegui un test per confrontare la versione attuale della tua applicazione con l'ultima versione di Gemini.
  • Se la tua organizzazione utilizza regolarmente implementazioni canary, utilizzale con i modelli più recenti e misura le variazioni nel comportamento degli utenti.

Puoi anche eseguire la valutazione online aggiungendo nuove funzionalità di feedback e misurazione alla tua applicazione. Applicazioni diverse richiedono metodi di feedback diversi. Ad esempio:

  • Aggiunta di pulsanti Mi piace e Non mi piace accanto agli output del modello e confronto dei tassi tra un modello precedente e gli ultimi modelli Gemini.
  • Mostrare agli utenti gli output del modello precedente e dei modelli più recenti uno accanto all'altro e chiedere loro di scegliere il preferito.
  • Monitoraggio della frequenza con cui gli utenti ignorano o modificano manualmente gli output del modello precedente rispetto ai modelli più recenti.

Questi metodi di feedback spesso richiedono l'esecuzione dell'ultima versione di Gemini insieme alla versione esistente. Questo deployment parallelo è talvolta chiamato "modalità shadow" o "deployment blu/verde".

Se i risultati della valutazione online differiscono notevolmente da quelli della valutazione offline, la valutazione offline non acquisisce gli aspetti chiave dell'ambiente live o dell'esperienza utente. Applica i risultati della valutazione online per creare una nuova valutazione offline che colmi la lacuna, quindi torna al passaggio 3.

Se utilizzi il throughput di cui è stato eseguito il provisioning, potresti dover acquistare un throughput di cui è stato eseguito il provisioning a breve termine aggiuntivo per continuare a soddisfare i requisiti di throughput per gli utenti nella valutazione online.

7. Distribuzione in produzione

Una volta che la valutazione mostra che l'ultimo modello Gemini funziona bene o meglio di un modello precedente, sostituisci la versione dell'applicazione esistente con la nuova versione. Segui le procedure standard della tua organizzazione per l'implementazione della produzione.

Se utilizzi il throughput riservato, modifica l'ordine del throughput riservato con il modello Gemini che preferisci. Se stai implementando la tua applicazione in modo incrementale, utilizza la capacità di trasmissione di cui è stato eseguito il provisioning a breve termine per soddisfare le esigenze di capacità di trasmissione per due diversi modelli Gemini.

Aggiornamenti dei parametri e best practice in Gemini 3.x

Quanto segue si applica a tutti i modelli Gemini 3.x, incluso Gemini 3.5 Flash. Sono stati introdotti con Gemini 3 e sono elencati qui come promemoria.

Parametri di campionamento (deprecati)

temperature, top_p e top_k non sono più consigliati per tutti i modelli Gemini 3.x. Il modello gestisce il proprio campionamento per ottenere risultati ottimali. Rimuovi questi parametri da tutte le richieste.

Per massimizzare il determinismo, ti consigliamo di definire un'istruzione di sistema con regole esplicite per il tuo caso d'uso specifico.

thinking_budget (deprecato)

Il parametro numerico non elaborato thinking_budget non è più consigliato per tutti i modelli Gemini 3.x. Utilizza invece l'enumerazione di stringhe thinking_level.

Chiamata di funzione: corrispondenza esatta della risposta

L'API non genera ancora errori, ma le risposte non corrispondenti fanno sì che il modello restituisca risposte vuote con finish_reason: STOP nella maggior parte dei casi. Segui sempre queste convenzioni:

  • Includi id: ogni FunctionResponse deve includere id dell'FunctionCall corrispondente.
  • Corrispondenza name: il valore name nella risposta deve corrispondere al valore name nella chiamata.
  • Conteggi delle corrispondenze: restituisce esattamente un FunctionResponse per ogni FunctionCall ricevuto.

Risposte della funzione multimodale

Quando fornisci contenuti multimodali (come immagini) in risposta a una chiamata di funzione, includi i contenuti all'interno delle parti della risposta della funzione, non all'esterno. In questo modo si evita un comportamento imprevisto del modello, come la fuoriuscita di pensieri.

Istruzioni in linea con la risposta della funzione

Se devi fornire istruzioni per la piattaforma insieme alle risposte della funzione, aggiungile alla fine del testo della risposta della funzione separate da due nuove righe, anziché come parti separate.

Riduzione delle chiamate agli strumenti non necessarie

Se riscontri un utilizzo eccessivo delle chiamate di strumenti: 1. Riduci il livello di pensiero (medium, low o minimal). 2. Aggiungi un'istruzione di sistema per limitare l'utilizzo dello strumento (ad es. "You have a limited action budget of <n> tool calls. Use them efficiently.").

Elenco di controllo per la migrazione

Da Gemini 3 Flash (anteprima)

  • Aggiornamento del nome del modello: gemini-3-flash-preview → gemini-3.5-flash.
  • Esamina i prezzi. Gemini 3.5 Flash è più costoso di Gemini 3 Flash (anteprima).
  • Rimuovi temperature, top_p, top_k dalla configurazione.
  • Sostituisci thinking_budget con thinking_level.
  • Aggiungi id e name corrispondenti a tutte le parti di FunctionResponse.
  • Testa i tuoi prompt. Impegno predefinito cambiato da high → medium.
  • La conservazione dei pensieri è ora attiva per impostazione predefinita. Il contesto del ragionamento viene riportato nei turni successivi.
  • Riduci le chiamate inutili agli strumenti modificando il livello di pensiero o aggiungendo istruzioni di sistema.
  • L'utilizzo del computer non è supportato in Gemini 3.5 Flash al momento.
  • Mitigare la piaggeria: se gemini-3.5-flash inizia a mostrare segni di piaggeria, puoi provare a mitigare questo comportamento tramite le istruzioni di sistema aggiungendo quanto segue: - Keep your responses concise. - Provide a summary of your work when you end your turn. Ground your response in the work you did. Keep your tone professional and avoid overconfident language, bragging, or overclaiming success. - AVOID using superlatives such as "perfectly", "flawlessly", "100% correct", "Summary of Accomplishments" etc. to summarize your work for the user. Be humble. - AVOID over-the-top politeness or complimenting the user excessively. - Format your responses in github-style markdown.

Da Gemini 2.5

  • Testa i carichi di lavoro PDF e di documenti. Il consumo di token per i PDF potrebbe aumentare.
  • Semplifica i prompt. Prova thinking_level: "medium" o "high" con prompt più semplici anziché prompt complessi di ragionamento a catena.
  • Sfrutta l'utilizzo combinato degli strumenti (Ricerca, contesto URL, esecuzione del codice, funzioni).
  • Sposta i contenuti multimodali all'interno delle parti di risposta della funzione.
  • Aggiungi istruzioni in linea al testo della risposta della funzione.

Miglioramento delle prestazioni del modello

Durante la migrazione, applica questi suggerimenti per ottenere prestazioni ottimali dal modello Gemini che hai scelto:

  • Per tutti i modelli Gemini 3, i parametri di campionamento (temperature, top_p e top_k) sono ritirati. Il modello gestisce il proprio campionamento per ottenere risultati ottimali. Google consiglia di rimuovere questi parametri da tutte le richieste.
  • Controlla le istruzioni di sistema, i prompt e gli esempi di few-shot learning per eventuali incongruenze, contraddizioni o istruzioni ed esempi irrilevanti.
  • Prova un modello più potente. Ad esempio, se hai valutato Gemini 2.0 Flash-Lite, prova Gemini 2.0 Flash.
  • Esamina i risultati della valutazione automatica per assicurarti che corrispondano al giudizio umano, soprattutto i risultati che utilizzano un modello di valutazione. Assicurati che le istruzioni del modello di giudice siano chiare, coerenti e non ambigue.
  • Per migliorare le istruzioni del modello di valutazione, testale con più persone che lavorano in isolamento. Se gli esseri umani interpretano le istruzioni in modo diverso e forniscono giudizi diversi, le istruzioni del modello di giudizio non sono chiare.
  • Ottimizza il modello.
  • Esamina gli output di valutazione per individuare i pattern che mostrano tipi specifici di errori. Il raggruppamento degli errori per modello, tipo o categoria fornisce dati di valutazione più mirati, semplificando la modifica dei prompt per correggere questi errori.
  • Assicurati di valutare i diversi componenti dell'AI generativa in modo indipendente.
  • Prova a modificare i parametri di campionamento dei token.

Assistenza

Se hai bisogno di assistenza, Google Cloud offre pacchetti di assistenza per soddisfare le tue esigenze, come servizi di copertura 24/7, assistenza telefonica e consulenza con un responsabile dell'assistenza tecnica. Per maggiori informazioni, consulta Google Cloud Assistenza.

Passaggi successivi

Guida

Scopri le nozioni di base sull'utilizzo dell'SDK Google Gen AI per inviare query ai modelli Gemini con Agent Platform.

Panoramica

Elenco dei modelli Google disponibili in Agent Platform, come Gemini, Gemma e Veo.

Panoramica

Elenco dei modelli sviluppati dai partner di Google disponibili in Agent Platform, come Claude e Mistral.

Panoramica

Panoramica su come utilizzare modelli aperti come Gemma, Llama, DeepSeek e altri in Agent Platform.

Risorsa

Domande frequenti sull'utilizzo di Gemini con Agent Platform.