Novità in Gemini 3.5 Flash

Gemini 3.5 Flash è in disponibilità generale (GA), è stabile ed è pronto per l'uso in produzione su larga scala. In quanto modello Flash più intelligente, offre prestazioni di frontiera sostenute nell'esecuzione agentica, nella programmazione e nelle attività a lungo termine su larga scala.

Questa guida contiene una panoramica dei miglioramenti, delle modifiche all'API e delle indicazioni per la migrazione a Gemini 3.5 Flash.

Nuovo modello

Modello ID modello Descrizione
Gemini 3.5 Flash gemini-3.5-flash Il nostro modello più intelligente per prestazioni di frontiera sostenute nelle attività agentiche e di programmazione.

Gemini 3.5 Flash supporta la finestra contestuale da 1 milione di token, un massimo di 65.000 token di output, il ragionamento e lo stesso insieme di strumenti e funzionalità della piattaforma di Gemini 3 Flash. Al momento, l'utilizzo del computer non è supportato.

Per le specifiche complete, consulta la panoramica dei modelli. Per i prezzi, consulta la pagina dei prezzi.

Guida rapida

Tutti gli esempi in questa guida utilizzano l'API Interactions. È supportata anche l'API GenerateContent; si applicano le stesse opzioni di configurazione e gli stessi consigli.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Explain how parallel agentic execution works in three sentences."
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Explain how parallel agentic execution works in three sentences.",
  });
  console.log(interaction.output_text);
}

main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Explain how parallel agentic execution works in three sentences."
  }'

Novità

  • Prestazioni di frontiera sostenute:il nostro modello Flash più intelligente, ottimizzato per le attività agentiche e di programmazione su larga scala.
  • Esecuzione agentica:deployment di sub-agenti, risoluzione dei problemi e loop agentici rapidi su larga scala.
  • Programmazione:cicli di programmazione iterativi, esplorazione rapida e prototipazione per testare percorsi alternativi ed esplorare dinamicamente le soluzioni.
  • Orizzonte lungo:workflow in più passaggi e utilizzo di strumenti su larga scala.
  • Conservazione del ragionamento:il modello mantiene automaticamente il ragionamento intermedio nelle conversazioni in più turni. Non sono necessarie modifiche all'API.
  • Nuovo livello di sforzo predefinito:lo sforzo di ragionamento predefinito è stato modificato da high a medium. Per maggiori dettagli, consulta Nuovo livello di sforzo predefinito.
  • Ragionamento low migliorato:low è ora notevolmente migliorato per le attività di codice e agentiche che richiedono meno passaggi, offrendo una qualità elevata a latenza e costi inferiori.
  • Release GA:modello stabile per l'uso in produzione su larga scala.

Modifiche al comportamento

Nuovo livello di sforzo predefinito: medium

Lo sforzo di ragionamento predefinito è ora medium, modificato da high nell'anteprima di Gemini 3 Flash. medium produce risultati molto buoni in un'ampia gamma di attività, pur essendo più veloce ed economico. Per i problemi complessi, high incoraggia il modello a ragionare in modo più approfondito.

Livello di sforzo Quando utilizzarlo
minimal Ottimizzato per la velocità di risposta. Casi d'uso simili alla chat, risposte rapide basate su fatti, chiamate di strumenti più semplici.
low Attività di codice e agentiche che richiedono una latenza inferiore e meno passaggi. Funziona bene anche per le attività di analisi e scrittura che richiedono un po' di ragionamento.
medium (predefinito) Qualità ottimale per la maggior parte delle attività. Consigliato per casi d'uso di codice e agentici complessi.
high Massimizza la capacità del modello di ragionare e utilizzare gli strumenti. Ideale per ragionamenti complessi, matematica difficile e le attività di codice o agenti più difficili. Consente ragionamenti estesi e chiamate di funzioni.

Per sostituire il valore predefinito, imposta thinking_level nella configurazione:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Prove that the square root of 2 is irrational.",
    generation_config={"thinking_level": "high"},
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Prove that the square root of 2 is irrational.",
    generationConfig: { thinkingLevel: "high" },
  });
  console.log(interaction.output_text);
}

main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Prove that the square root of 2 is irrational.",
    "generation_config": {"thinking_level": "high"}
  }'

Conservazione del ragionamento

Il modello mantiene automaticamente il ragionamento intermedio nelle conversazioni in più turni. Quando è presente nella cronologia delle conversazioni, il contesto di ragionamento viene riportato, il che migliora le prestazioni nelle attività complesse in più passaggi, come il debug iterativo e il refactoring del codice. Non sono necessarie modifiche all'API:

  • API Interazioni: i ragionamenti vengono già conservati automaticamente. Nessuna modifica al comportamento.
  • API GenerateContent: a partire da Gemini 3.5 Flash, il modello utilizza il contesto di ragionamento di tutti i turni precedenti quando le firme di ragionamento sono presenti nella cronologia delle conversazioni. Per attivare questa funzionalità, trasmetti la cronologia delle conversazioni completa e non modificata (incluse le firme di ragionamento) in contents. Gli SDK gestiscono questa operazione automaticamente.

Aggiornamenti dei parametri e best practice in Gemini 3.x

Le seguenti indicazioni si applicano a tutti i modelli Gemini 3.x, incluso Gemini 3.5 Flash.

  • temperature, top_p, top_k: ti consigliamo vivamente di non modificare i valori predefiniti. Le funzionalità di ragionamento di Gemini 3 sono ottimizzate per le impostazioni predefinite.
  • Utilizza thinking_level anziché thinking_budget.
  • Corrispondenza delle risposte di chiamata di funzione: id, name e il numero di risposte devono corrispondere alle chiamate precedenti.
  • Risposte di funzioni multimodali: includi i contenuti multimodali all'interno della risposta della funzione, non all'esterno.
  • Istruzioni in linea nelle risposte delle funzioni: aggiungile al testo della risposta della funzione, non come parti separate.
  • Riduci le chiamate di strumenti non necessarie: utilizza livelli di ragionamento inferiori o sperimenta con le istruzioni di sistema per ridurre le chiamate di strumenti nei workflow agentici.

Consulta le sezioni riportate di seguito per scoprire come aggiornare il codice.

Parametri di campionamento (non più consigliati)

temperature, top_p e top_k non sono più consigliati per tutti i modelli Gemini 3.x. Le funzionalità di ragionamento di Gemini 3 sono ottimizzate per le impostazioni predefinite. Rimuovi questi parametri da tutte le richieste.

# ⚠️ Remove these parameters (not recommended)
generation_config = {
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 40,
}

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

thinking_budget (non più consigliato)

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.

# ⚠️ Before (not recommended)
generation_config = {
    "thinking": {"thinking_budget": 7500},
}

# ✅ After
generation_config = {
    "thinking": {"thinking_level": "medium"},
}

Valori disponibili: minimal, low, medium (predefinito) e high.

Chiamata di funzione: corrispondenza rigorosa delle risposte

L'API Interactions genera già un errore in caso di risposte di funzioni non corrispondenti. L'API GenerateContent non genera ancora un errore, ma nella maggior parte dei casi le risposte non corrispondenti fanno sì che il modello restituisca risposte vuote con finish_reason: STOP. Segui sempre queste convenzioni:

Requisito Dettagli
Includi id Ogni FunctionResponse deve includere l'id della FunctionCall corrispondente
Corrispondenza di name name nella risposta deve corrispondere a name nella chiamata
Corrispondenza dei conteggi Restituisci esattamente una FunctionResponse per ogni FunctionCall ricevuta

Python

# ✅ Include matching call_id and name in the function_result
final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    tools=[my_tool],
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [{"type": "text", "text": json.dumps(result)}],
    }],
)

JavaScript

// ✅ Include matching call_id and name in the function_result
const finalInteraction = await client.interactions.create({
  model: "gemini-3.5-flash",
  previousInteractionId: interaction.id,
  tools: [myTool],
  input: [{
    type: "function_result",
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: "text", text: JSON.stringify(result) }],
  }],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "previous_interaction_id": "<INTERACTION_ID>",
    "tools": [...],
    "input": [{
      "type": "function_result",
      "name": "my_function",
      "call_id": "<CALL_ID>",
      "result": [{"type": "text", "text": "..."}]
    }]
  }'

Risposte di funzioni multimodali

Spesso i clienti forniscono immagini al di fuori della risposta della funzione. Ciò può comportare un comportamento imprevisto del modello (ad es. perdita di ragionamento) e produrre output di qualità inferiore. Segui invece il consiglio riportato nella documentazione dell'API Risposte di funzioni multimodali e includi i contenuti multimodali nelle parti della risposta della funzione che invii al modello. Il modello può elaborare questi contenuti multimodali nel turno successivo per produrre una risposta più informata.

Python

# ✅ Include multimodal content in the function response
final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": tool_call.name,
            "call_id": tool_call.id,
            "result": [
                {"type": "text", "text": "instrument.jpg"},
                {
                    "type": "image",
                    "mime_type": "image/jpeg",
                    "data": base64_image_data,
                },
            ],
        }
    ],
)

JavaScript

// ✅ Include multimodal content in the function response
const finalInteraction = await client.interactions.create({
  model: "gemini-3.5-flash",
  previousInteractionId: interaction.id,
  input: [{
    type: "function_result",
    name: toolCall.name,
    call_id: toolCall.id,
    result: [
      { type: "text", text: "instrument.jpg" },
      {
        type: "image",
        mime_type: "image/jpeg",
        data: base64ImageData,
      },
    ],
  }],
});

Istruzioni in linea nelle risposte delle funzioni

Spesso i clienti forniscono istruzioni aggiuntive insieme alle risposte delle funzioni come Parts successive. Ciò può comportare un comportamento imprevisto del modello (ad es. perdita di ragionamento) e produrre output di qualità inferiore. Aggiungi invece eventuali istruzioni aggiuntive alla fine del testo della risposta della funzione, separate da due nuove righe.

Python

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    tools=[my_tool],
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [{"type": "text", "text": result_text}],
    }],
)

JavaScript

// ✅ Append inline instructions to the end of the function response separated by two newlines
const resultText = `${JSON.stringify(result)}\n\n<your inline instructions>`;

const finalInteraction = await client.interactions.create({
  model: "gemini-3.5-flash",
  previousInteractionId: interaction.id,
  tools: [myTool],
  input: [{
    type: "function_result",
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: "text", text: resultText }],
  }],
});

Riduzione delle chiamate di strumenti non necessarie

Se riscontri un utilizzo eccessivo delle chiamate di strumenti, due tecniche possono aiutarti a ridurle al minimo:

  1. Inizia riducendo il livello di ragionamento (medium, low o minimal): i livelli di ragionamento più elevati incoraggiano il modello a utilizzare più strumenti per esplorare e verificare, quindi la riduzione del livello può ridurre le chiamate di strumenti.

  2. Aggiungi un'istruzione di sistema:se l'utilizzo eccessivo persiste dopo aver regolato il livello di ragionamento, valuta la possibilità di utilizzare un prompt che limiti l'utilizzo degli strumenti. Ad esempio:

    You have a limited action budget of <n> tool calls. Use them efficiently.

Elenco di controllo per la migrazione

Ti consigliamo vivamente di eseguire l'aggiornamento all'google-genai SDK versione 2.0.0 o successive. Questa versione introduce modifiche che causano interruzioni all'API Interactions. Per maggiori dettagli, consulta la guida alla migrazione delle modifiche che causano interruzioni.

Eseguire la migrazione dall'anteprima di Gemini 3 Flash

  • Aggiorna il nome del modello: gemini-3-flash-preview → gemini-3.5-flash
  • Esamina i prezzi. Gemini 3.5 Flash è più costoso dell'anteprima di Gemini 3 Flash. Per maggiori dettagli, consulta la pagina dei prezzi.
  • Rimuovi temperature, top_p, top_k dalla configurazione (non più consigliato).
  • Sostituisci thinking_budget con thinking_level.
  • Aggiungi id e name corrispondente a tutte le parti FunctionResponse.
  • Testa i prompt. Lo sforzo predefinito è stato modificato da high a medium; verifica la qualità, la velocità e il costo.
  • La conservazione del ragionamento è ora attiva per impostazione predefinita. Il contesto di ragionamento viene riportato nei turni, il che migliora le prestazioni, ma potrebbe aumentare l'utilizzo dei token.
  • Riduci le chiamate di strumenti non necessarie: inizia riducendo il livello di ragionamento (medium, low o minimal); aggiungi un'istruzione di sistema per limitare l'utilizzo degli strumenti se l'utilizzo eccessivo persiste.
  • L'utilizzo del computer non è supportato in Gemini 3.5 Flash al momento. Per i carichi di lavoro di utilizzo del computer, continua a utilizzare l'anteprima di Gemini 3 Flash.

Eseguire la migrazione da Gemini 2.5

Tutte le azioni precedenti, più:

  • Semplifica i prompt. Se hai utilizzato la progettazione di prompt di tipo "chain-of-thought" per forzare il ragionamento, prova a utilizzare thinking_level: "medium" o "high" con prompt più semplici invece.
  • Testa i carichi di lavoro di PDF e contenuti multimediali. Se ti affidi a un comportamento specifico per l'analisi di documenti densi, testa l'impostazione media_resolution_high per garantire la continuità dell'accuratezza. La migrazione alle impostazioni predefinite di Gemini 3 potrebbe anche aumentare l'utilizzo dei token per i PDF, ma ridurlo per i video; se le richieste superano la finestra contestuale, riduci esplicitamente media_resolution. Per maggiori dettagli, consulta la documentazione sulla risoluzione dei contenuti multimediali per dettagli.
  • Sfrutta l'utilizzo combinato degli strumenti. La Ricerca Google, il contesto dell'URL, l'esecuzione del codice e le funzioni personalizzate possono essere utilizzati nella stessa richiesta.
  • Se utilizzi risposte di funzioni multimodali, sposta i contenuti multimodali all'interno delle parti della risposta della funzione, non accanto.
  • Se utilizzi istruzioni in linea con le risposte delle funzioni, aggiungile al testo della risposta della funzione, separate da due nuove righe, non come parti separate.
  • La segmentazione delle immagini non è supportata in Gemini 3.x. Per i carichi di lavoro di segmentazione , continua a utilizzare Gemini 2.5 Flash con il ragionamento disattivato o Gemini Robotics-ER 1.6.

Funzionalità della famiglia Gemini 3

Gemini 3.5 Flash eredita tutte le funzionalità della famiglia Gemini 3, ad eccezione dell'utilizzo del computer. Funzionalità introdotte in Gemini 3 che vengono riportate:

Passaggi successivi