Novità di Gemini 3.5 Flash

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 di frontiera sostenute nell'esecuzione agentica, nella programmazione e nelle attività a lungo termine su scala.

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

Nuovo modello

Gemini 3.5 Flash supporta la finestra contestuale da 1 milione di token, 65.000 token di output massimi, il ragionamento e lo stesso insieme di strumenti e funzionalità della piattaforma di Gemini 3 Flash. L'opzione Uso del computer non è attualmente supportata.

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

Guida rapida

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

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how parallel agentic execution works in three sentences.",
)
print(response.text)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how parallel agentic execution works in three sentences.",
  });
  console.log(response.text);
}

main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Explain how parallel agentic execution works in three sentences."}]
    }]
  }'

Novità

• Prestazioni di frontiera sostenute: il nostro modello Flash più intelligente, ottimizzato per attività agentiche e di programmazione su larga scala.
• Esecuzione autonoma:deployment di sub-agenti, risoluzione dei problemi e cicli autonomi 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 degli strumenti su larga scala.
• Conservazione del pensiero:il modello mantiene automaticamente il ragionamento intermedio nelle conversazioni multiturno. Non sono necessarie modifiche all'API.
• Nuovo livello di impegno predefinito: l'impegno di pensiero predefinito è cambiato da high a medium. Per informazioni dettagliate, consulta Nuovo livello di impegno predefinito.
• Miglioramento del ragionamento di low: low è stato notevolmente migliorato per il codice e le attività di tipo agente 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 impegno predefinito: medium

Lo sforzo di pensiero predefinito ora è medium, modificato rispetto a high in Gemini 3 Flash Preview. medium offre risultati molto buoni in un'ampia gamma di attività ed è più veloce ed economico. Per problemi complessi, high incoraggia il modello a ragionare in modo più approfondito.

Per eseguire l'override del valore predefinito, imposta thinking_level nella configurazione:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Prove that the square root of 2 is irrational.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    ),
)

print(response.text)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Prove that the square root of 2 is irrational.",
    config: {
      thinkingConfig: {
        thinkingLevel: "HIGH",
      },
    },
  });
  console.log(response.text);
}

main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Prove that the square root of 2 is irrational."}]
    }],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "HIGH"
      }
    }
  }'

Conservazione dei pensieri

Il modello mantiene automaticamente il ragionamento intermedio nelle conversazioni multi-turno. Se presente nella cronologia della conversazione, il contesto del ragionamento viene riportato, il che migliora le prestazioni in attività complesse in più passaggi come il debug iterativo e il refactoring del codice. Nessuna modifica all'API necessaria:

• API Interactions: i pensieri vengono già conservati automaticamente. Nessun cambiamento nel 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 del pensiero sono presenti nella cronologia della conversazione. Per attivare questa funzionalità, trasmetti la cronologia completa e non modificata della conversazione (incluse le firme dei pensieri) in contents. Gli SDK gestiscono automaticamente questa operazione.

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.

• 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 al posto di thinking_budget.
• Corrispondenza della risposta alla chiamata di funzione: id, name e il conteggio delle risposte devono corrispondere alle chiamate precedenti.
• Risposte di funzione multimodali: includi contenuti multimodali all'interno della risposta di funzione, non all'esterno.
• Istruzioni inline nelle risposte delle funzioni: aggiungile al testo della risposta della funzione, non come parti separate.
• Ridurre le chiamate agli strumenti non necessarie: utilizza livelli di pensiero inferiori o sperimenta con le istruzioni di sistema per ridurre le chiamate agli strumenti nei flussi di lavoro degli agenti.

Per informazioni su come aggiornare il codice, consulta le sezioni seguenti.

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)
config = types.GenerateContentConfig(
    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)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="medium")
)

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

Chiamata di funzione: corrispondenza esatta della risposta

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

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

// ✅ Include matching id and name in the function response
const functionResponsePart = {
  functionResponse: {
    name: toolCall.name,
    response: { result: result },
    id: toolCall.id,
  },
};

const finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    { role: "user", parts: [functionResponsePart] },
  ],
  config: config,
});

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "..."}]},
      {"role": "model", "parts": [{"functionCall": {"name": "my_function", "args": {...}}}]},
      {"role": "user", "parts": [{"functionResponse": {"name": "my_function", "id": "call_id", "response": {"result": "..."}}}]}
    ]
  }'

Risposte della funzione multimodale

Spesso vediamo clienti fornire immagini al di fuori della risposta della funzione. Ciò può portare a un comportamento imprevisto del modello (ad es. perdita di pensieri) e a risultati di qualità inferiore. Segui invece il consiglio riportato nella documentazione dell'API Multimodal Function Responses e includi contenuti multimodali nelle parti della risposta della funzione che invii al modello. Il modello può elaborare questi contenuti multimodali al turno successivo per produrre una risposta più informata.

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

// ✅ Include multimodal content in the function response
const finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    {
      role: "user",
      parts: [{
        functionResponse: {
          name: toolCall.name,
          id: toolCall.id,
          response: {
            result: "instrument.jpg",
            image: base64ImageData,
          },
        },
      }],
    },
  ],
  config: config,
});

Istruzioni incorporate nelle risposte delle funzioni

Spesso i clienti forniscono istruzioni aggiuntive insieme alle risposte delle funzioni come Parts successivi. Ciò può portare a un comportamento imprevisto del modello (ad es. perdita di pensieri) e a risultati di qualità inferiore. Aggiungi invece eventuali istruzioni extra alla fine del testo di 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_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

// ✅ 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 finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    {
      role: "user",
      parts: [{
        functionResponse: {
          name: toolCall.name,
          id: toolCall.id,
          response: { result: resultText },
        },
      }],
    },
  ],
  config: config,
});

Riduzione delle chiamate agli strumenti non necessarie

Se riscontri un uso eccessivo delle chiamate di strumenti, due tecniche aiutano a ridurle al minimo:

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

2. Aggiungi un'istruzione di sistema:se l'utilizzo eccessivo persiste dopo aver modificato il livello di pensiero, valuta la possibilità di utilizzare un prompt che limiti l'utilizzo dello strumento. Ad esempio:

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

Elenco di controllo per la migrazione

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 di Gemini 3 Flash (anteprima). Per informazioni dettagliate, 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 corrispondenti a tutte le parti di FunctionResponse.
• Testa i tuoi prompt. Sforzo predefinito modificato da high → medium; verifica qualità, velocità e costi.
• La conservazione dei pensieri è ora attiva per impostazione predefinita. Il contesto del ragionamento viene riportato nei turni successivi, il che migliora le prestazioni, ma può aumentare l'utilizzo dei token.
• Riduci le chiamate agli strumenti non necessarie: inizia riducendo il livello di pensiero (medium, low o minimal); aggiungi un'istruzione di sistema per limitare l'utilizzo degli strumenti se l'uso 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.

Esegui la migrazione da Gemini 2.5

Tutte le azioni precedenti, più:

• Semplifica i prompt. Se hai utilizzato l'ingegneria dei prompt a catena di pensiero per forzare il ragionamento, prova thinking_level: "medium" o "high" con prompt più semplici.
• Testa i carichi di lavoro PDF e multimediali. Se ti sei affidato 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 diminuirlo per i video. Se le richieste superano la finestra contestuale, riduci esplicitamente il valore di media_resolution. Per ulteriori dettagli, consulta la documentazione sulla risoluzione dei contenuti multimediali.
• 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 di 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 la funzionalità di ragionamento disattivata oppure 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 mantenute:

• Thinking: contesto di ragionamento criptato e conservato tra le chiamate API. Automatico nell'API Interactions; implicito in GenerateContent.
• Output strutturati con strumenti: combina la modalità JSON con strumenti integrati (Ricerca, contesto URL, esecuzione di codice, chiamata di funzioni).
• Risposte multimodali delle funzioni: restituisci immagini, audio e altri contenuti multimediali nei risultati della chiamata di funzione.
• Esecuzione di codice con immagini: esegui codice che elabora e genera immagini.
• Utilizzo combinato degli strumenti: utilizza gli strumenti integrati e le chiamate di funzione personalizzate nella stessa richiesta.

Passaggi successivi

• Scopri di più sulla famiglia Gemini 3 nella Guida per gli sviluppatori di Gemini 3
• Scopri di più sulle strategie di progettazione dei prompt nella guida all'ingegneria dei prompt.
• Inizia a usare il Gemini 3 Cookbook
• Scopri di più sull'ottimizzazione e sull'inferenza dell'API Gemini