Novità di Gemini 3.5 Flash

3.6 Flash & 3.5 Flash-Lite Questa pagina

Gemini 3.5 Flash è in disponibilità generale (GA), stabile e pronto per l'uso in produzione su larga scala. In quanto modello Flash più intelligente, offre prestazioni all'avanguardia sostenute in attività agentiche, di programmazione e di lunga durata su larga scala.

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

Nuovo modello

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 set di strumenti e funzionalità della piattaforma di Gemini 3 Flash, incluso l'utilizzo del computer (anteprima).

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 suggerimenti.

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)

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();

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

Novità

• Prestazioni all'avanguardia sostenute: il nostro modello Flash più intelligente, ottimizzato per 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 programmazione 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.

Scegliere il modello Flash giusto

Gemini 3.5 Flash è il nostro modello Flash più intelligente e potente. Tuttavia, casi d'uso diversi possono avere requisiti di costo e latenza diversi.

• Gemini 3.1 Flash-Lite: per attività a basso costo, ad alto volume che non richiedono la profondità di ragionamento avanzata di 3.5 Flash, ti consigliamo di utilizzare Gemini 3.1 Flash-Lite. È un modello stabile a lungo termine ottimizzato per l'efficienza. Per maggiori dettagli, consulta la guida per gli sviluppatori di Flash-Lite.
• Gemini 3 Flash (anteprima): anche se ti consigliamo di eseguire la migrazione a 3.5 Flash per la stabilità GA e il ragionamento migliorato, Gemini 3 Flash (anteprima) rimane disponibile per gli sviluppatori che vogliono continuare a testare il modello di anteprima.

Modifiche al comportamento

Nuovo livello di sforzo predefinito: medium

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

Per sostituire il valore predefinito, imposta thinking_level nella configurazione:

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)

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();

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

La tabella seguente mostra i livelli di ragionamento supportati per modello:

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 abilitare questa funzionalità, trasmetti la cronologia delle conversazioni completa, 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 seguenti 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 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 (valore predefinito) e high.

Chiamata di funzione: corrispondenza rigorosa delle risposte

L'API Interactions genera già errori in caso di risposte di funzioni non corrispondenti. L'API GenerateContent non genera ancora errori, 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:

# ✅ 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)}],
    }],
)

// ✅ 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) }],
  }],
});

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -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 generare output di qualità inferiore. Segui invece il suggerimento 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.

# ✅ 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,
                },
            ],
        }
    ],
)

// ✅ 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 generare output di qualità inferiore. Aggiungi invece eventuali istruzioni aggiuntive alla fine del testo della risposta della funzione, separate da due nuove righe.

# ✅ 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}],
    }],
)

// ✅ 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 }],
  }],
});

Ridurre le 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 v2.0.0 o versioni 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 da Gemini 3 Flash (anteprima)

• Aggiorna il 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). Se il tuo caso d'uso è molto sensibile ai costi, valuta la possibilità di eseguire la migrazione a Gemini 3.1 Flash-Lite invece. Per maggiori dettagli, consulta la pagina dei prezzi.
• Rimuovi temperature, top_p, top_k dalla configurazione (non più consigliata).
• 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 → 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 è supportato.

Eseguire la migrazione da Gemini 2.5

Tutte le azioni precedenti, più:

• Semplifica i prompt. Se hai utilizzato la tecnica di prompt engineering della catena di ragionamento per forzare il ragionamento, prova thinking_level: "medium" o "high" con prompt più semplici invece.
• Testa i workload 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 precisione continua. La migrazione ai valori predefiniti 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 URL, l'esecuzione del codice e le funzioni personalizzate possono essere utilizzati nella stessa richiesta.
• Se utilizzi le risposte di funzioni multimodali, sposta i contenuti multimodali all'interno delle parti della risposta della funzione, non accanto.
• Se utilizzi le 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 workload di segmentazione, continua a utilizzare Gemini 2.5 Flash con il ragionamento disattivato.
• Rimuovi candidate_count dalla configurazione (non supportata in Gemini 3.x)

Funzionalità della famiglia Gemini 3

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

• Ragionamento: contesto di ragionamento criptato conservato nelle chiamate API. Automatico nell'API Interactions; implicito in GenerateContent.
• Output strutturati con gli strumenti: combina la modalità JSON con gli strumenti integrati (Ricerca, contesto URL, esecuzione del codice, chiamata di funzione).
• Risposte di funzioni multimodali: restituisci immagini, audio e altri contenuti multimediali nei risultati delle chiamate di funzioni.
• Esecuzione del codice con le immagini: esegui il codice che elabora e genera immagini.
• Utilizzo combinato degli strumenti: utilizza gli strumenti integrati e la chiamata di funzione personalizzata nella stessa richiesta.
• Risoluzione dei contenuti multimediali: controllo granulare dell'allocazione dei token per gli input di immagini, video e PDF. I modelli Gemini 3 supportano le impostazioni di risoluzione per elemento di contenuto (low, medium, high, ultra_high) per i prompt a fedeltà mista.
• Firme di ragionamento: rappresentazioni criptate del ragionamento interno del modello. Obbligatorio per la chiamata di funzione multi-turno in modalità stateless; gestito automaticamente dall'API Interactions e dagli SDK ufficiali.

Best practice per i prompt

I modelli Gemini 3.x sono modelli di ragionamento, il che modifica il modo in cui devi creare i prompt.

• Istruzioni precise: crea prompt concisi. Gemini 3.x risponde al meglio a istruzioni dirette e chiare. Le tecniche di prompt engineering dettagliate o complesse progettate per i modelli precedenti potrebbero causare un'analisi eccessiva del modello.
• Dettaglio dell'output: per impostazione predefinita, Gemini 3 e 3.1 sono meno dettagliati e preferiscono risposte dirette ed efficienti. Se il tuo caso d'uso richiede un tono colloquiale, guida esplicitamente il modello nel prompt (ad esempio, "Spiega questo come un assistente amichevole e loquace").
• Gestione del contesto: quando lavori con set di dati di grandi dimensioni (ad esempio libri interi, codebase o video lunghi), inserisci le istruzioni o le domande specifiche alla fine del prompt, dopo il contesto dei dati. Ancora il ragionamento del modello iniziando la domanda con una frase come "In base alle informazioni precedenti...".

Scopri di più sulle strategie di progettazione dei prompt nella guida al prompt engineering.

Limitazioni

• La segmentazione delle immagini non è supportata in Gemini 3.x. Per i workload di segmentazione, continua a utilizzare Gemini 2.5 Flash con il ragionamento disattivato.

Domande frequenti

1. Qual è il knowledge cutoff per Gemini 3.5 Flash? Gemini 3.5 Flash ha un knowledge cutoff di gennaio 2025. Per informazioni più recenti, utilizza lo strumento di grounding della Ricerca tool.

2. Quali sono i limiti della finestra contestuale? Gemini 3.5 Flash supporta una finestra contestuale di input da 1 milione di token e fino a 65.000 token di output.

3. Il mio vecchio codice thinking_budget funzionerà ancora? Sì, thinking_budget è ancora supportato per la compatibilità con le versioni precedenti, ma ti consigliamo di eseguire la migrazione a thinking_level per prestazioni più prevedibili. Non utilizzare entrambi nella stessa richiesta.

4. Gemini 3.5 Flash supporta l'API Batch? Sì. Per maggiori dettagli, consulta la guida all' API Batch.

5. La memorizzazione nella cache del contesto è supportata? Sì, la memorizzazione nella cache del contesto è supportata.

6. Quali strumenti sono supportati? Gemini 3.5 Flash supporta la Ricerca Google, il grounding con Google Maps, la ricerca di file, l'esecuzione del codice, il contesto URL e la chiamata di funzione standard, incluso l'utilizzo combinato degli strumenti e l'utilizzo del computer.

Passaggi successivi

• Scopri di più sulle strategie di progettazione dei prompt nella guida al prompt engineering.
• Inizia a utilizzare il ricettario di Gemini 3
• Scopri di più sull'ottimizzazione e sull'inferenza dell'API Gemini