Inizia a usare Gemini 3

Gemini 3 è la nostra famiglia di modelli più intelligente fino ad oggi, basata su un ragionamento allo stato dell'arte. È progettato per dare vita a qualsiasi idea padroneggiando Agentic Workflows, programmazione autonoma e attività multimodali complesse.

Questa guida fornisce un percorso pratico e consolidato per iniziare a utilizzare Gemini 3 su Gemini Enterprise Agent Platform, evidenziando le funzionalità chiave e le best practice di Gemini 3.

Guida rapida

Prima di iniziare, devi autenticarti in Gemini Enterprise Agent Platform utilizzando una chiave API o le credenziali predefinite dell'applicazione (ADC). Per saperne di più, consulta Metodi di autenticazione.

Installa l'SDK Google Gen AI

Le funzionalità dell'API Gemini 3 richiedono l'SDK Google Gen AI per Python versione 1.51.0 o successive.

pip install --upgrade google-genai

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Gemini Enterprise Agent Platform

Sostituisci il valore GOOGLE_CLOUD_PROJECT con l'ID progetto Google Cloud . Il modello Gemini 3.1 Pro gemini-3.1-pro-preview e il modello Gemini 3 Flash gemini-3-flash-preview sono disponibili solo sugli endpoint globali:

export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

Effettua la tua prima richiesta

Per impostazione predefinita, i modelli Gemini 3 e Gemini 3 Flash utilizzano il ragionamento dinamico per elaborare i prompt. Per risposte più rapide e con una latenza inferiore quando non è richiesto un ragionamento complesso, puoi limitare il thinking_level del modello. La modalità Low thinking è ideale per attività con throughput elevato in cui la velocità è fondamentale.

Per risposte rapide e a bassa latenza:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.6-flash",
   contents="How does AI work?",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.LOW # For fast and low latency response
       )
   ),
)
print(response.text)

Prova attività di ragionamento complesse

Gemini 3 eccelle nel ragionamento avanzato. Per attività complesse come la pianificazione in più passaggi, la generazione di codice verificato o l'utilizzo approfondito degli strumenti, utilizza livelli di pensiero elevati. Utilizza queste configurazioni per le attività che in precedenza richiedevano modelli di ragionamento specializzati.

Per attività più lente e con un ragionamento più approfondito:

from google import genai
from google.genai import types

client = genai.Client()

prompt = """
You are tasked with implementing the classic Thread-Safe Double-Checked Locking (DCL) Singleton pattern in modern C++. This task is non-trivial and requires specialized concurrency knowledge to prevent memory reordering issues.

Write a complete, runnable C++ program named `dcl_singleton.cpp` that defines a class `Singleton` with a private constructor and a static `getInstance()` method.

Your solution MUST adhere to the following strict constraints:
1. The Singleton instance pointer (`static Singleton*`) must be wrapped in `std::atomic` to correctly manage memory visibility across threads.
2. The `getInstance()` method must use `std::memory_order_acquire` when reading the instance pointer in the outer check.
3. The instance creation and write-back must use `std::memory_order_release` when writing to the atomic pointer.
4. A standard `std::mutex` must be used only to protect the critical section (the actual instantiation).
5. The `main` function must demonstrate safe, concurrent access by launching at least three threads, each calling `Singleton::getInstance()`, and printing the address of the returned instance to prove all threads received the same object.
"""

response = client.models.generate_content(
  model="gemini-3.6-flash",
  contents=prompt,
  config=types.GenerateContentConfig(
      thinking_config=types.ThinkingConfig(
          thinking_level=types.ThinkingLevel.HIGH # Dynamic thinking for high reasoning tasks
      )
  ),
)
print(response.text)

Altri livelli di ragionamento

Gemini 3 Flash introduce due nuovi livelli di ragionamento: MINIMAL e MEDIUM per darti un controllo ancora maggiore su come il modello gestisce le attività di ragionamento complesse.

MINIMAL offre opzioni di budget di pensiero quasi pari a zero per le attività ottimizzate per il throughput, anziché per il ragionamento. MEDIUM consente un equilibrio tra velocità e ragionamento, offrendo alcune capacità di ragionamento, ma dando comunque priorità alle operazioni a bassa latenza.

Nuove funzionalità API

Gemini 3 introduce potenti miglioramenti dell'API e nuovi parametri progettati per offrire agli sviluppatori un controllo granulare su prestazioni (latenza, costo), comportamento del modello e fedeltà multimodale.

Questa tabella riassume le principali nuove funzionalità e i parametri disponibili, insieme ai link diretti alla documentazione dettagliata:

Nuova funzionalità/Modifica dell'API Documentazione
Modello: gemini-3.1-pro-preview Scheda del modello
Gemini Enterprise Agent Platform Model Garden
Livello di pensiero Ragionamento
Risoluzione dei contenuti multimediali Comprensione delle immagini
Comprensione dei video
Comprensione dell'audio
Comprensione dei documenti
Firma del pensiero Firme del pensiero
Temperatura Riferimento API
Risposte di funzioni multimodali Chiamata di funzione: risposte di funzioni multimodali
Chiamata di funzione in streaming Chiamata di funzione: chiamata di funzione in streaming

Livello di pensiero

Il parametro thinking_level consente di specificare un budget di ragionamento per la generazione della risposta del modello. Selezionando uno dei due stati, puoi bilanciare esplicitamente i compromessi tra qualità della risposta e complessità del ragionamento, nonché tra latenza e costo.

  • MINIMAL: (solo Gemini 3 Flash e Gemini 3.1 Flash-Lite) Vincola il modello a utilizzare il minor numero possibile di token per il ragionamento ed è ideale per attività a bassa complessità che non trarrebbero vantaggio da un ragionamento approfondito. MINIMAL è il più vicino possibile a un budget di pensiero pari a zero, ma richiede comunque firme di pensiero.
  • LOW: limita il modello a utilizzare meno token per il ragionamento ed è adatto per attività più semplici in cui non è richiesto un ragionamento approfondito. LOW è ideale per attività con throughput elevato in cui la velocità è essenziale.
  • MEDIUM: (solo Gemini 3 Flash, Gemini 3.1 Pro e Gemini 3.1 Flash-Lite) Offre un approccio equilibrato adatto ad attività di complessità moderata che traggono vantaggio dal ragionamento, ma che non richiedono una pianificazione approfondita in più passaggi. Offre maggiori capacità di ragionamento rispetto a LOW, mantenendo al contempo una latenza inferiore rispetto a HIGH.
  • HIGH: consente al modello di utilizzare più token per il ragionamento ed è adatto per prompt complessi che richiedono un ragionamento approfondito, come la pianificazione in più passaggi, la generazione di codice verificato o scenari di chiamata di funzione avanzati. Questo è il livello predefinito per i modelli Gemini 3 e Gemini 3 Flash. Utilizza questa configurazione quando sostituisci attività per le quali in precedenza avresti potuto fare affidamento su modelli di ragionamento specializzati.

Esempio di SDK Google Gen AI

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.6-flash",
   contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH # Default, dynamic thinking
       )
   ),
)
print(response.text)

Esempio di compatibilità con OpenAI

Per gli utenti che utilizzano il livello di compatibilità con OpenAI, i parametri standard vengono mappati automaticamente agli equivalenti di Gemini 3:

  • reasoning_effort corrisponde a thinking_level.
  • none: corrisponde a thinking_level (solo Gemini 3 Flash).
  • medium: corrisponde alla soglia thinking_level per tutti i modelli Gemini 3.
import openai
from google.auth import default
from google.auth.transport.requests import Request

credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])

client = openai.OpenAI(
    base_url=f"https://aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/global/endpoints/openapi",
    api_key=credentials.token,
)

prompt = """
Write a bash script that takes a matrix represented as a string with
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

response = client.chat.completions.create(
    model="gemini-3.6-flash",
    reasoning_effort="medium", # Map to thinking_level high.
    messages=[{"role": "user", "content": prompt}],
)

print(response.choices[0].message.content)

Risoluzione dei contenuti multimediali

Gemini 3 introduce un controllo granulare sull'elaborazione della visione multimodale utilizzando il parametro media_resolution. Le risoluzioni più elevate migliorano la capacità del modello di leggere testi di piccole dimensioni o identificare piccoli dettagli, ma aumentano l'utilizzo dei token e la latenza. Il parametro media_resolution determina il numero massimo di token allocati per immagine di input, pagina PDF o frame video.

Puoi impostare la risoluzione su low, medium o high a livello globale (utilizzando generation_config) o per singole parti multimediali. La risoluzione ultra_high può essere impostata solo per singole parti multimediali. Se non specificato, il modello utilizza i valori predefiniti ottimali in base al tipo di media.

Conteggi dei token

Questa tabella riassume i conteggi dei token approssimativi per ogni valore media_resolution e tipo di media.

Risoluzione dei contenuti multimediali Immagine Video PDF
UNSPECIFIED (valore predefinito) 1120 70 560
LOW 280 70 280 + testo
MEDIUM 560 70 560 + testo
HIGH 1120 280 1120 + testo
ULTRA_HIGH 2240 N/D N/D
Risoluzione dei contenuti multimediali Token massimi Indicazioni per l'utilizzo
ultra_high 2240 Attività che richiedono l'analisi di dettagli precisi nelle immagini, come l'elaborazione di fotogrammi di registrazioni dello schermo o foto ad alta risoluzione.
high 1120 Attività di analisi delle immagini per garantire la massima qualità.
medium 560
low Immagine: 280 Video: 70 Sufficiente per la maggior parte delle attività. Nota: per i video, low è un massimo di 70 token per frame.

Impostazione di media_resolution per singola parte

Puoi impostare media_resolution per singola parte multimediale:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.6-flash",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH # High resolution
          ),
      ),
      Part(
          file_data=types.FileData(
             file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
            mime_type="video/mp4",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW # Low resolution
          ),
      ),
      "When does the image appear in the video? What is the context?",
  ],
)
print(response.text)

Impostazione di media_resolution a livello globale

Puoi anche impostare media_resolution a livello globale (utilizzando GenerateContentConfig):

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.6-flash",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
      ),
      "What is in the image?",
  ],
  config=types.GenerateContentConfig(
      media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW, # Global setting
  ),
)
print(response.text)

Firme del pensiero

Le firme dei pensieri sono token criptati che preservano lo stato di ragionamento del modello durante le conversazioni multi-turno, in particolare quando si utilizza la chiamata di funzione.

Quando un modello di ragionamento decide di chiamare uno strumento esterno, mette in pausa il suo processo di ragionamento interno. La firma del pensiero funge da "stato di salvataggio", consentendo al modello di riprendere la catena di pensiero senza problemi una volta fornito il risultato della funzione.

Per saperne di più, consulta Firme dei pensieri.

Perché le firme dei pensieri sono importanti?

Senza le firme di pensiero, il modello "dimentica" i suoi passaggi di ragionamento specifici durante la fase di esecuzione dello strumento. La restituzione della firma garantisce:

  • Continuità del contesto: il modello conserva il motivo per cui è stato chiamato lo strumento.
  • Ragionamento complesso: consente di eseguire attività in più passaggi in cui l'output di uno strumento fornisce informazioni per il ragionamento dello strumento successivo.

Dove vengono restituite le firme del pensiero?

I modelli Gemini 3 e Gemini 3 Flash applicano una convalida più rigorosa e una gestione aggiornata delle firme di pensiero, introdotte originariamente in Gemini 2.5. Per garantire che il modello mantenga il contesto in più turni di una conversazione, devi restituire le firme di pensiero nelle richieste successive.

  • Le risposte del modello con una chiamata di funzione restituiranno sempre una firma del ragionamento, anche quando si utilizza il livello di ragionamento MINIMAL.
  • Quando sono presenti chiamate di funzione parallele, la prima parte della chiamata di funzione restituita dalla risposta del modello avrà una firma del pensiero.
  • Quando sono presenti chiamate di funzione sequenziali (in più passaggi), ogni chiamata di funzione avrà una firma e i client dovranno restituirla.
  • Le risposte del modello senza una chiamata di funzione restituiranno una firma del ragionamento all'interno dell'ultima parte restituita dal modello.

Come gestire le firme del pensiero?

Esistono due modi principali per gestire le firme dei pensieri: automaticamente utilizzando gli SDK Google Gen AI o l'API OpenAI oppure manualmente se interagisci direttamente con l'API.

Elaborazione automatica (consigliata)

Se utilizzi gli SDK Google Gen AI (Python, Node.js, Go, Java) o l'API OpenAI Chat Completions e utilizzi le funzionalità standard della cronologia chat o aggiungi la risposta completa del modello, i thought_signatures vengono gestiti automaticamente. Non è necessario apportare modifiche al codice.

Esempio di chiamata di funzione manuale

Quando utilizzi l'SDK Google Gen AI, le firme di pensiero vengono gestite automaticamente aggiungendo la risposta completa del modello nelle richieste sequenziali del modello:

from google import genai
from google.genai import types

client = genai.Client()

# 1. Define your tool
get_weather_declaration = types.FunctionDeclaration(
   name="get_weather",
   description="Gets the current weather temperature for a given location.",
   parameters={
       "type": "object",
       "properties": {"location": {"type": "string"}},
       "required": ["location"],
   },
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])

# 2. Send a message that triggers the tool
prompt = "What's the weather like in London?"
response = client.models.generate_content(
   model="gemini-3.6-flash",
   contents=prompt,
   config=types.GenerateContentConfig(
       tools=[get_weather_tool],
       thinking_config=types.ThinkingConfig(include_thoughts=True)
   ),
)

# 4. Handle the function call
function_call = response.function_calls[0]
location = function_call.args["location"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {location}")
function_response_data = {
   "location": location,
   "temperature": "30C",
}

# 5. Send the tool's result back
# Append this turn's messages to history for a final response.
# The `content` object automatically attaches the required thought_signature behind the scenes.
history = [
    types.Content(role="user", parts=[types.Part(text=prompt)]),
    response.candidates[0].content, # Signature preserved here
    types.Content(
        role="user",
        parts=[
            types.Part.from_function_response(
                name=function_call.name,
                response=function_response_data,
            )
        ],
    )
]

response_2 = client.models.generate_content(
   model="gemini-3.6-flash",
   contents=history,
   config=types.GenerateContentConfig(
        tools=[get_weather_tool],
        thinking_config=types.ThinkingConfig(include_thoughts=True)
   ),
)

# 6. Get the final, natural-language answer
print(f"\nFinal model response: {response_2.text}")
Esempio di chiamata di funzione automatica

Quando utilizzi l'SDK Google Gen AI nella chiamata di funzione automatica, le firme di pensiero vengono gestite automaticamente:


from google import genai
from google.genai import types

def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, for example San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="What's the temperature in Boston?",
    config=types.GenerateContentConfig(
            tools=[get_current_temperature],
    )
)

print(response.text) # The SDK handles the function call and thought signature, and returns the final text
Esempio di compatibilità con OpenAI

Quando utilizzi l'API OpenAI Chat Completions, le firme dei pensieri vengono gestite automaticamente aggiungendo la risposta completa del modello alle richieste sequenziali del modello:

...
# Append user prompt and assistant response including thought signatures
messages.append(response1.choices[0].message)

# Execute the tool
tool_call_1 = response1.choices[0].message.tool_calls[0]
result_1 = get_current_temperature(**json.loads(tool_call_1.function.arguments))

# Append tool response to messages
messages.append(
    {
        "role": "user",
        "tool_call_id": tool_call_1.id,
        "content": json.dumps(result_1),
    }
)

response2 = client.chat.completions.create(
    model="gemini-3.6-flash",
    messages=messages,
    tools=tools,
    extra_body={
        "extra_body": {
            "google": {
                "thinking_config": {
                    "include_thoughts": True,
                },
            },
        },
    },
)

print(response2.choices[0].message.tool_calls)

Guarda l'esempio di codice completo.

Movimentazione manuale

Se interagisci direttamente con l'API o gestisci payload JSON non elaborati, devi gestire correttamente l'elemento thought_signature incluso nel turno del modello.

Devi restituire questa firma esattamente nella parte in cui è stata ricevuta quando invii la cronologia delle conversazioni.

Se non vengono restituite le firme corrette, Gemini 3 restituirà un errore 400 "<Function Call> nel blocco di contenuti <indice dell'array di contenuti> manca un thought_signature".

Risposte di funzioni multimodali

La chiamata di funzione multimodale consente agli utenti di avere risposte di funzione contenenti oggetti multimodali, consentendo un migliore utilizzo delle funzionalità di chiamata di funzione del modello. La chiamata di funzione standard supporta solo le risposte di funzione basate su testo:

from google import genai
from google.genai import types

client = genai.Client()

# This is a manual, two turn multimodal function calling workflow:

# 1. Define the function tool
get_image_declaration = types.FunctionDeclaration(
   name="get_image",
   description="Retrieves the image file reference for a specific order item.",
   parameters={
       "type": "object",
       "properties": {
            "item_name": {
                "type": "string",
                "description": "The name or description of the item ordered (e.g., 'green shirt')."
            }
       },
       "required": ["item_name"],
   },
)
tool_config = types.Tool(function_declarations=[get_image_declaration])

# 2. Send a message that triggers the tool
prompt = "Show me the green shirt I ordered last month."
response_1 = client.models.generate_content(
    model="gemini-3.6-flash",
    contents=[prompt],
    config=types.GenerateContentConfig(
        tools=[tool_config],
    )
)

# 3. Handle the function call
function_call = response_1.function_calls[0]
requested_item = function_call.args["item_name"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {requested_item}")

function_response_data = {
  "image_ref": {"$ref": "dress.jpg"},
}

function_response_multimodal_data = types.FunctionResponsePart(
   file_data=types.FunctionResponseFileData(
      mime_type="image/png",
      display_name="dress.jpg",
      file_uri="gs://cloud-samples-data/generative-ai/image/dress.jpg",
   )
)

# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
history = [
  types.Content(role="user", parts=[types.Part(text=prompt)]),
  response_1.candidates[0].content,
  types.Content(
    role="user",
    parts=[
        types.Part.from_function_response(
            name=function_call.name,
            response=function_response_data,
            parts=[function_response_multimodal_data]
        )
    ],
  )
]

response_2 = client.models.generate_content(
  model="gemini-3.6-flash",
  contents=history,
  config=types.GenerateContentConfig(
      tools=[tool_config],
      thinking_config=types.ThinkingConfig(include_thoughts=True)
  ),
)

print(f"\nFinal model response: {response_2.text}")

Chiamata di funzione in streaming

Puoi utilizzare gli argomenti di chiamata di funzione parziale in streaming per migliorare l'esperienza di streaming sull'utilizzo degli strumenti. Questa funzionalità può essere attivata impostando esplicitamente stream_function_call_arguments su true:

from google import genai
from google.genai import types

client = genai.Client()

get_weather_declaration = types.FunctionDeclaration(
  name="get_weather",
  description="Gets the current weather temperature for a given location.",
  parameters={
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
  },
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])


for chunk in client.models.generate_content_stream(
   model="gemini-3.6-flash",
   contents="What's the weather in London and New York?",
   config=types.GenerateContentConfig(
       tools=[get_weather_tool],
       tool_config = types.ToolConfig(
           function_calling_config=types.FunctionCallingConfig(
               mode=types.FunctionCallingConfigMode.AUTO,
               stream_function_call_arguments=True,
           )
       ),
   ),
):
   function_call = chunk.function_calls[0]
   if function_call and function_call.name:
       print(f"{function_call.name}")
       print(f"will_continue={function_call.will_continue}")

Esempio di risposta del modello:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "willContinue": true
            }
          }
        ]
      }
    }
  ]
}

Temperatura

  • Range for Gemini 3: 0.0 - 2.0 (default: 1.0)

Per Gemini 3, è vivamente consigliato mantenere il parametro temperature al valore predefinito 1.0.

Mentre i modelli precedenti spesso beneficiavano della regolazione della temperatura per controllare la creatività rispetto al determinismo, le capacità di ragionamento di Gemini 3 sono ottimizzate per l'impostazione predefinita.

La modifica della temperatura (impostandola su un valore inferiore a 1.0) potrebbe causare un comportamento imprevisto, come loop o un peggioramento delle prestazioni, in particolare in attività matematiche o di ragionamento complesse.

Funzionalità supportate

I modelli Gemini 3 supportano anche le seguenti funzionalità:

Best practice per i prompt

Gemini 3 è un modello di ragionamento, il che cambia il modo in cui dovresti scrivere i prompt.

  • Istruzioni precise: sii conciso nei prompt di input. Gemini 3 risponde meglio a istruzioni dirette e chiare. Potrebbe analizzare in modo eccessivo tecniche di prompt engineering prolisse o eccessivamente complesse utilizzate per i modelli precedenti.
  • Preferenze di lettura dell'output: per impostazione predefinita, Gemini 3 è meno prolisso e preferisce fornire risposte dirette ed efficienti. Se il tuo caso d'uso richiede un tono più colloquiale o "chiacchierone", devi indirizzare esplicitamente il modello nel prompt (ad esempio, "Spiega questo concetto come un assistente amichevole e loquace").
  • Grounding: per i casi d'uso di grounding, ti consigliamo di utilizzare le seguenti istruzioni per gli sviluppatori: You are a strictly grounded assistant limited to the information provided in the User Context. In your answers, rely **only** on the facts that are directly mentioned in that context. You must **not** access or utilize your own knowledge or common sense to answer. Do not assume or infer from the provided facts; simply report them exactly as they appear. Your answer must be factual and fully truthful to the provided text, leaving absolutely no room for speculation or interpretation. Treat the provided context as the absolute limit of truth; any facts or details that are not directly mentioned in the context must be considered **completely untruthful** and **completely unsupported**. If the exact answer is not explicitly written in the context, you must state that the information is not available.
  • Utilizzo dello strumento della Ricerca Google: quando utilizzi lo strumento della Ricerca Google, Gemini 3 Flash a volte può confondere la data/l'ora corrente con gli eventi del 2024. Ciò può comportare la formulazione di query di ricerca per l'anno sbagliato da parte del modello. Per assicurarti che il modello utilizzi il periodo di tempo corretto, rafforza esplicitamente la data corrente in system instructions: For time-sensitive user queries that require up-to-date information, you MUST follow the provided current time (date and year) when formulating search queries in tool calls. Remember it is 2025 this year.
  • knowledge cutoff: per alcune query, Gemini 3 Flash trae vantaggio dal fatto che gli venga comunicato esplicitamente il suo knowledge cutoff. Questo accade quando lo strumento della Ricerca Google è disattivato e la query richiede esplicitamente che il modello sia in grado di identificare la data limite nella conoscenza parametrica. Suggerimento: aggiungi la seguente clausola a system instructions: Your knowledge cutoff date is January 2025.
  • Utilizzo di media_resolution: utilizza il parametro media_resolution per controllare il numero massimo di token utilizzati dal modello per rappresentare un'immagine o i frame nei video. La risoluzione elevata consente al modello di acquisire i dettagli di un'immagine e può utilizzare più token per frame, mentre la risoluzione più bassa consente di ottimizzare i costi e la latenza per le immagini con meno dettagli visivi.
  • Miglioramento dell'analisi video: utilizza una frequenza di campionamento di frame al secondo (FPS) più elevata per i video che richiedono un'analisi temporale granulare, come la comprensione di azioni rapide o il rilevamento del movimento ad alta velocità.

Considerazioni sulla migrazione

Durante la migrazione, tieni presente le seguenti funzionalità e i seguenti vincoli:

  • Livello di ragionamento: i modelli Gemini 3 utilizzano il parametro thinking_level per controllare la quantità di ragionamento interno eseguito dal modello (basso o alto) e per bilanciare la qualità della risposta, la complessità del ragionamento, la latenza e il costo.
  • Impostazioni della temperatura: se il codice esistente imposta esplicitamente temperature (soprattutto su valori bassi per output deterministici), ti consigliamo di rimuovere questo parametro e utilizzare il valore predefinito di Gemini 3 1.0 per evitare potenziali problemi di loop o un peggioramento delle prestazioni su attività complesse.
  • Firme di pensiero: per i modelli Gemini 3, se in un turno è prevista una firma di pensiero, ma non viene fornita, il modello restituisce un errore anziché un avviso.
  • Risoluzione e tokenizzazione dei contenuti multimediali: i modelli Gemini 3 utilizzano una lunghezza di sequenza variabile per la tokenizzazione dei contenuti multimediali anziché Pan and Scan e hanno nuove risoluzioni predefinite e costi dei token per immagini, PDF e video.
  • Conteggio dei token per l'input multimodale: i conteggi dei token per gli input multimodali (immagini, video, audio) sono una stima basata sul media_resolution scelto. Pertanto, il risultato della chiamata API count_tokens potrebbe non corrispondere ai token utilizzati finali. L'utilizzo preciso per la fatturazione è disponibile solo dopo l'esecuzione all'interno di usage_metadata della risposta.
  • Consumo di token: la migrazione ai valori predefiniti di Gemini 3 potrebbe aumentare l'utilizzo dei token per immagini e PDF, ma diminuire l'utilizzo dei token per i video. Se le richieste ora superano la finestra contestuale a causa di risoluzioni predefinite più elevate, è consigliabile ridurre esplicitamente la risoluzione dei contenuti multimediali.
  • Comprensione di PDF e documenti: la risoluzione OCR predefinita per i PDF è cambiata. Se hai fatto affidamento su un comportamento specifico per l'analisi di documenti densi, testa la nuova impostazione media_resolution: "high" per garantire un'accuratezza continua. Per i modelli Gemini 3, i conteggi dei token PDF in usage_metadata vengono riportati nella modalità IMMAGINE anziché DOCUMENTO.
  • Segmentazione delle immagini: la segmentazione delle immagini non è supportata dai modelli Gemini 3. Per i workload che richiedono la segmentazione delle immagini integrata, si consiglia di continuare a utilizzare Gemini 2.5 Flash con il ragionamento disattivato.
  • Risposte di funzioni multimodali: per i modelli Gemini 3, puoi includere dati di immagini e PDF nelle risposte delle funzioni.

Domande frequenti

  1. In quale regione è disponibile gemini-3.1-pro-preview su Google Cloud? Global.

  2. Quali sono i limiti della finestra contestuale? I modelli Gemini 3 supportano una finestra contestuale di input di 1 milione di token e fino a 64.000 token di output.

  3. gemini-3.1-pro-preview supporta l'output di immagini? No.

  4. gemini-3.1-pro-preview supporta l'API Gemini Live? No.

Passaggi successivi