Inizia a utilizzare Gemini 3

Gemini 3 è la nostra famiglia di modelli più intelligente di sempre, basata su un ragionamento all'avanguardia. È progettato per dare vita a qualsiasi idea padroneggiando workflow agentici, programmazione autonoma e attività multimodali complesse.

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

Guida rapida

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

Installare l'SDK Google Gen AI

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

pip install --upgrade google-genai

Imposta le variabili di ambiente per utilizzare l'SDK Gen AI con Vertex AI

Sostituisci il valore GOOGLE_CLOUD_PROJECT con il tuo ID progetto Google Cloud . I modelli Gemini 3 Pro Preview gemini-3-pro-preview e Gemini 3 Flash Preview 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_VERTEXAI=True

Effettua la tua prima richiesta

Per impostazione predefinita, Gemini 3 Pro e Gemini 3 Flash utilizzano il ragionamento dinamico per analizzare i prompt. Per risposte più rapide e a bassa latenza quando non è necessario un ragionamento complesso, puoi vincolare il thinking_level del modello. Il pensiero lento è ideale per attività a velocità effettiva elevata 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-pro-preview",
   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 di 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 che richiedono un ragionamento più complesso:

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-pro-preview",
  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 pensiero

Gemini 3 Flash introduce due nuovi livelli di pensiero: MINIMAL e MEDIUM per darti ancora più controllo sul modo in cui 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, che permette di avere una certa capacità di ragionamento, ma dà comunque la priorità alle operazioni a bassa latenza.

Nuove funzionalità dell'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 nuove funzionalità e i parametri principali disponibili, oltre ai link diretti alla documentazione dettagliata:

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

Livello di pensiero

Il parametro thinking_level ti consente di specificare un budget di pensiero 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, latenza e costi.

  • MINIMAL: (solo Gemini 3 Flash) limita 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 pari a zero per il pensiero, ma richiede comunque firme del pensiero.
  • LOW: limita il modello a utilizzare meno token per il pensiero ed è adatto per attività più semplici in cui non è necessario un ragionamento approfondito. LOW è ideale per attività con velocità effettiva elevata in cui la velocità è essenziale.
  • MEDIUM: (solo Gemini 3 Flash) offre un approccio equilibrato adatto a attività di moderata complessità che traggono vantaggio dal ragionamento ma non richiedono una pianificazione profonda e in più passaggi. Offre una capacità di ragionamento superiore rispetto a LOW, mantenendo una latenza inferiore rispetto a HIGH.
  • HIGH: consente al modello di utilizzare più token per il ragionamento ed è adatto a prompt complessi che richiedono un ragionamento approfondito, come la pianificazione in più passaggi, la generazione di codice verificato o scenari avanzati di chiamata di funzioni. Questo è il livello predefinito per Gemini 3 Pro e Gemini 3 Flash. Utilizza questa configurazione quando sostituisci le attività per le quali potresti aver fatto affidamento in precedenza su modelli di ragionamento specializzati.

Esempio di SDK Gen AI

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3-pro-preview",
   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à OpenAI, i parametri standard vengono mappati automaticamente agli equivalenti di Gemini 3:

  • reasoning_effort maps to thinking_level.
  • none: corrisponde a thinking_level minimal (solo Gemini 3 Flash).
  • medium: corrisponde a thinking_level media per Gemini 3 Flash e thinking_level alta per Gemini 3 Pro.
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-pro-preview",
    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 dell'elaborazione della visione multimodale utilizzando il parametro media_resolution. Risoluzioni più elevate migliorano la capacità del modello di leggere testi piccoli o identificare piccoli dettagli, ma aumentano l'utilizzo di 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 le 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 approssimativi dei token per ogni valore e tipo di media di media_resolution.

Risoluzione dei contenuti multimediali Immagine Video PDF
UNSPECIFIED (valore predefinito) 1120 70 560
LOW 280 70 280 + Testo
MEDIUM 560 70 560 + Text
HIGH 1120 280 1120 + Text
ULTRA_HIGH 2240 N/D N/D
Risoluzione dei contenuti multimediali Token max Indicazioni per l'utilizzo
ultra_high 2240 Attività che richiedono l'analisi di dettagli precisi nelle immagini, come l'elaborazione di fermo immagine 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 il video low è un massimo di 70 token per frame.

Impostazione di media_resolution per singola parte

Puoi impostare media_resolution per ogni parte del contenuto multimediale:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3-pro-preview",
  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-pro-preview",
  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 dei pensieri

Le firme del pensiero sono token criptati che preservano lo stato del ragionamento del modello durante le conversazioni a più turni, in particolare quando si utilizza la chiamata di funzioni.

Quando un modello di pensiero 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 sua catena di pensiero senza problemi una volta fornito il risultato della funzione.

Per ulteriori informazioni, consulta la sezione Firme di pensiero.

Perché le firme del pensiero sono importanti?

Senza le firme del pensiero, il modello "dimentica" i 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 attività in più passaggi in cui l'output di uno strumento informa il ragionamento per il successivo.

Dove vengono restituite le firme dei pensieri?

Gemini 3 Pro e Gemini 3 Flash applicano una convalida più rigorosa e una gestione aggiornata delle firme del 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 del pensiero nelle richieste successive.

  • Le risposte del modello con una chiamata di funzione restituiranno sempre una firma del pensiero, anche quando si utilizza il livello di pensiero MINIMAL.
  • Quando ci sono chiamate di funzione parallele, la prima parte della chiamata di funzione restituita dalla risposta del modello avrà una firma del pensiero.
  • Quando ci sono chiamate di funzioni sequenziali (multistep), ogni chiamata di funzione avrà una firma e i client devono restituire la firma
  • Le risposte del modello senza chiamata di funzione restituiranno una firma di pensiero all'interno dell'ultima parte restituita dal modello.

Come gestire le firme dei pensieri?

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

Gestione 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 della chat o aggiungi la risposta completa del modello, thought_signatures vengono gestiti automaticamente. Non è necessario apportare modifiche al codice.

Esempio di chiamata di funzione manuale

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

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-pro-preview",
   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="tool",
        parts=[
            types.Part.from_function_response(
                name=function_call.name,
                response=function_response_data,
            )
        ],
    )
]

response_2 = client.models.generate_content(
   model="gemini-3-pro-preview",
   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 Gen AI nella chiamata di funzione automatica, le firme del 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-pro-preview",
    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 del pensiero vengono gestite automaticamente aggiungendo la risposta completa del modello nelle richieste di modello sequenziali:

...
# 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": "tool",
        "tool_call_id": tool_call_1.id,
        "content": json.dumps(result_1),
    }
)

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

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

Vedi l'esempio di codice completo.

Gestione manuale

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

Devi obbligatoriamente restituire questa firma esattamente nella parte in cui è stata ricevuta quando invii di nuovo la cronologia della conversazione.

Se non vengono restituite firme corrette, Gemini 3 restituirà un errore 400 "<Function Call> nel blocco di contenuti <index of contents array> non contiene un thought_signature".

Risposte delle funzioni multimodali

La chiamata di funzione multimodale consente agli utenti di ricevere risposte di funzione contenenti oggetti multimodali, migliorando l'utilizzo delle funzionalità di chiamata di funzione del modello. La chiamata di funzione standard supporta solo 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-pro-preview",
    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="tool",
    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-pro-preview",
  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 della chiamata di funzione parziale in streaming per migliorare l'esperienza di streaming durante l'utilizzo dello strumento. 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-pro-preview",
   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, è consigliabile mantenere il parametro temperature sul valore predefinito di 1.0.

Mentre i modelli precedenti spesso traevano vantaggio dalla 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) può comportare un comportamento imprevisto, ad esempio loop o prestazioni ridotte, in particolare in attività matematiche o di ragionamento complesse.

Funzionalità supportate

I modelli Gemini 3 supportano anche le seguenti funzionalità:

Best practice per la creazione di prompt

Gemini 3 è un modello di ragionamento che cambia il modo in cui devi creare i prompt.

  • Istruzioni precise: sii conciso nei prompt di input. Gemini 3 risponde al meglio a istruzioni dirette e chiare. Potrebbe analizzare in modo eccessivo tecniche di prompt engineering verbose o eccessivamente complesse utilizzate per i modelli precedenti.
  • Livello di dettaglio dell'output: per impostazione predefinita, Gemini 3 è meno dettagliato e preferisce fornire risposte dirette ed efficienti. Se il tuo caso d'uso richiede una persona più colloquiale o "loquace", devi indirizzare esplicitamente il modello nel prompt (ad esempio, "Spiega questo come un assistente amichevole e loquace").
  • Fondatezza:per i casi d'uso di fondatezza, 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 Ricerca Google: quando utilizzi lo strumento Ricerca Google, Gemini 3 Flash a volte può confondere la data / ora corrente con gli eventi del 2024. Ciò può comportare la formulazione di query di ricerca per l'anno sbagliato. 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 se gli viene comunicato esplicitamente il suo knowledge cutoff. Questo accade quando lo strumento Ricerca Google è disattivato e la query richiede esplicitamente che il modello sia in grado di identificare i dati di interruzione nella conoscenza parametrica. Consiglio: 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. L'alta risoluzione consente al modello di acquisire i dettagli di un'immagine e potrebbe utilizzare più token per frame, mentre la risoluzione inferiore consente di ottimizzare costi e latenza per le immagini con meno dettagli visivi.
  • Miglioramento dell'analisi video: utilizza una frequenza di campionamento di fotogrammi al secondo (FPS) più elevata per i video che richiedono un'analisi temporale granulare, ad esempio la comprensione di azioni rapide o il monitoraggio di movimenti ad alta velocità.

Considerazioni sulla migrazione

Tieni in considerazione le seguenti funzionalità e limitazioni durante la migrazione:

  • Livello di pensiero: 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 qualità della risposta, complessità del ragionamento, latenza e costo.
  • Impostazioni di temperatura:se il codice esistente imposta esplicitamente temperature (soprattutto su valori bassi per output deterministici), è consigliabile rimuovere questo parametro e utilizzare il valore predefinito di Gemini 3 1.0 per evitare potenziali problemi di loop o un peggioramento delle prestazioni per attività complesse.
  • Firme del pensiero: per i modelli Gemini 3, se in un turno è prevista una firma del 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 della sequenza variabile per la tokenizzazione dei contenuti multimediali anziché Pan e Scan e hanno nuove risoluzioni e costi dei token predefiniti 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 consumati finali. L'utilizzo accurato per la fatturazione è disponibile solo dopo l'esecuzione all'interno di usage_metadata della risposta.
  • Utilizzo dei token: la migrazione alle impostazioni predefinite 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 ti affidi a un comportamento specifico per l'analisi dei documenti densi, prova la nuova impostazione media_resolution: "high" per garantire una precisione continua. Per i modelli Gemini 3, i conteggi dei token PDF in usage_metadata vengono riportati nella modalità IMMAGINE anziché DOCUMENTO.
  • Segmentazione dell'immagine: la segmentazione dell'immagine non è supportata dai modelli Gemini 3. Per i workload che richiedono la segmentazione integrata delle immagini, è consigliabile continuare a utilizzare Gemini 2.5 Flash con il pensiero disattivato.
  • Risposte di funzione multimodali: per i modelli Gemini 3, puoi includere dati di immagini e PDF nelle risposte di funzione.

Domande frequenti

  1. Qual è la data limite per le conoscenze di Gemini 3 Pro? Gemini 3 ha un limite di conoscenza di gennaio 2025.

  2. Quale regione è gemini-3-pro-preview disponibile su Google Cloud? Globale.

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

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

  5. gemini-3-pro-preview supporta l'API Gemini Live? No.

Passaggi successivi