Comece a usar o Gemini 3

O Gemini 3 é a nossa família de modelos mais inteligente até à data, criada com base num raciocínio de última geração. Foi concebido para dar vida a qualquer ideia através do domínio de fluxos de trabalho de agentes, programação autónoma e tarefas multimodais complexas.

Este guia oferece um caminho prático e consolidado para começar a usar o Gemini 3 no Vertex AI, realçando as principais funcionalidades e práticas recomendadas do Gemini 3.

Início rápido

Antes de começar, tem de se autenticar no Vertex AI através de uma chave da API ou das credenciais predefinidas da aplicação (ADC). Consulte os métodos de autenticação para mais informações.

Instale o SDK Google Gen AI

As funcionalidades da API Gemini 3 requerem a versão 1.51.0 ou posterior do SDK de IA gen para Python.

pip install --upgrade google-genai

Defina variáveis de ambiente para usar o SDK de IA gen com a Vertex AI

Substitua o valor GOOGLE_CLOUD_PROJECT pelo seu Google Cloud ID do projeto. O modelo Gemini 3 Pro Preview gemini-3-pro-preview só está disponível nos pontos finais globais:

export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

Faça o seu primeiro pedido

Por predefinição, o Gemini 3 Pro usa o pensamento dinâmico para raciocinar através dos comandos. Para respostas mais rápidas e com menor latência quando não é necessário um raciocínio complexo, pode restringir o thinking_level do modelo. O raciocínio simples é ideal para tarefas de elevado débito em que a velocidade é fundamental, correspondendo aproximadamente ao perfil de latência do Gemini 2.5 Flash, ao mesmo tempo que oferece uma qualidade de resposta superior.

Para respostas rápidas e com baixa latência:

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)

Experimente tarefas de raciocínio complexas

O Gemini 3 destaca-se no raciocínio avançado. Para tarefas complexas, como planeamento de vários passos, geração de código validado ou utilização detalhada de ferramentas, use níveis de raciocínio elevados. Use estas configurações para tarefas que anteriormente requeriam modelos de raciocínio especializados.

Para tarefas mais lentas e de raciocínio complexo:

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)

Novas funcionalidades da API

O Gemini 3 apresenta melhorias poderosas na API e novos parâmetros concebidos para dar aos programadores um controlo detalhado sobre o desempenho (latência, custo), o comportamento do modelo e a fidelidade multimodal.

Esta tabela resume as principais novas funcionalidades e parâmetros disponíveis, bem como links diretos para a respetiva documentação detalhada:

Nova funcionalidade/alteração da API Documentação
Modelo: gemini-3-pro-preview Cartão de modelo Model Garden
Nível de processamento A pensar
Resolução de multimédia Compreensão de imagens Compreensão de vídeos Compreensão de áudio Compreensão de documentos
Assinatura de pensamento Assinaturas de pensamentos
Temperatura Referência da API
Respostas de funções multimodais Chamada de funções: respostas de funções multimodais
Chamada de funções de streaming Chamada de funções: chamada de funções de streaming

Nível de reflexão

O parâmetro thinking_level permite-lhe especificar um orçamento de reflexão para a geração de respostas do modelo. Ao selecionar um de dois estados, pode equilibrar explicitamente as compensações entre a qualidade da resposta e a complexidade do raciocínio, bem como a latência e o custo.

  • Baixo: minimiza a latência e o custo. Ideal para seguir instruções ou conversar.
  • Alto: maximiza a profundidade do raciocínio. Predefinição. Pensamento dinâmico. O modelo pode demorar significativamente mais tempo a alcançar um primeiro token, mas o resultado será mais exaustivamente validado.

Exemplo do SDK de IA gen

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)

Exemplo de compatibilidade com a OpenAI

Para os utilizadores que usam a camada de compatibilidade da OpenAI, os parâmetros padrão são mapeados automaticamente para os equivalentes do Gemini 3:

  • reasoning_effort mapeia para thinking_level.
  • O valor reasoning_effort medium é mapeado para thinking_level.
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)

Resolução de multimédia

O Gemini 3 introduz um controlo detalhado sobre o processamento de visão multimodal através do parâmetro media_resolution. As resoluções mais elevadas melhoram a capacidade do modelo de ler texto pequeno ou identificar detalhes pequenos, mas aumentam a utilização de tokens e a latência. O parâmetro media_resolution determina o número máximo de tokens atribuídos por imagem de entrada, página PDF ou frame de vídeo.

Pode definir a resolução como low, medium ou high por parte de multimédia individual ou globalmente (usando generation_config). Se não for especificado, o modelo usa predefinições ideais com base no tipo de suporte.

Tokens
Imagem Vídeo PDF
MEDIA_RESOLUTION_UNSPECIFIED (PREDEFINIÇÃO) 1120 70 560
MEDIA_RESOLUTION_LOW 280 70 280
MEDIA_RESOLUTION_MEDIUM 560 70 560
MEDIA_RESOLUTION_HIGH 1120 280 1120
Resolução de multimédia Máximo de tokens Orientações de utilização
high 1120 Tarefas de análise de imagens para garantir a máxima qualidade.
medium 560
low Imagem: 280 Vídeo: 70 Suficiente para a maioria das tarefas. Nota: para vídeo, o número máximo de low é de 70 tokens por frame.

Definir media_resolution por peça individual

Pode definir media_resolution por parte de conteúdo multimédia individual:

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)

A definir media_resolution globalmente

Também pode definir media_resolution globalmente (usando 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)

Assinaturas de pensamentos

As assinaturas de pensamento são tokens encriptados que preservam o estado de raciocínio do modelo durante conversas com várias interações, especificamente quando se usa a chamada de funções.

Quando um modelo de pensamento decide chamar uma ferramenta externa, pausa o seu processo de raciocínio interno. A assinatura de pensamento funciona como um "estado de gravação", permitindo que o modelo retome a sua cadeia de pensamento de forma integrada assim que fornecer o resultado da função.

Para mais informações, consulte o artigo Assinaturas de pensamento.

Por que motivo as assinaturas de pensamento são importantes?

Sem assinaturas de pensamento, o modelo "esquece-se" dos passos de raciocínio específicos durante a fase de execução da ferramenta. A devolução da assinatura garante:

  • Continuidade do contexto: o modelo preserva o motivo pelo qual a ferramenta foi chamada.
  • Raciocínio complexo: permite tarefas com vários passos em que o resultado de uma ferramenta informa o raciocínio para a seguinte.

Onde são devolvidas as assinaturas de pensamentos?

O Gemini 3 Pro aplica uma validação mais rigorosa e um processamento atualizado nas assinaturas de reflexão, que foram originalmente introduzidas no Gemini 2.5. Para garantir que o modelo mantém o contexto em vários turnos de uma conversa, tem de devolver as assinaturas de reflexão nos pedidos subsequentes.

  • As respostas do modelo com uma chamada de função devolvem sempre uma assinatura de pensamento.
  • Quando existem chamadas de funções paralelas, a primeira parte da chamada de função devolvida pela resposta do modelo tem uma assinatura de pensamento.
  • Quando existem chamadas de funções sequenciais (vários passos), cada chamada de função tem uma assinatura e espera-se que os clientes devolvam a assinatura
  • As respostas do modelo sem uma chamada de função devolvem uma assinatura de pensamento na última parte devolvida pelo modelo.

Como processar assinaturas de pensamentos?

Existem duas formas principais de processar assinaturas de pensamento: automaticamente através dos SDKs de IA gen ou da API OpenAI, ou manualmente se estiver a interagir diretamente com a API.

Se estiver a usar os SDKs de IA gen da Google (Python, Node.js, Go e Java) ou a API OpenAI Chat Completions, e a usar as funcionalidades padrão do histórico do chat ou a anexar a resposta completa do modelo, thought_signatures são processados automaticamente. Não tem de alterar o código.

Exemplo de chamadas de funções manuais

Quando usa o SDK de IA gen., as assinaturas de raciocínio são processadas automaticamente anexando a resposta completa do modelo em pedidos sequenciais do modelo:

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}")
Exemplo de chamadas de funções automáticas

Quando usa o SDK de IA gen na chamada de funções automática, as assinaturas de pensamento são processadas 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
Exemplo de compatibilidade com a OpenAI

Quando usa a API OpenAI Chat Completions, as assinaturas de pensamento são processadas automaticamente anexando a resposta completa do modelo a pedidos de modelos sequenciais:

...
# 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)

Veja o exemplo de código completo.

Manuseamento manual

Se estiver a interagir diretamente com a API ou a gerir payloads JSON não processados, tem de processar corretamente o thought_signature incluído no turno do modelo.

Tem de devolver esta assinatura na parte exata em que foi recebida quando enviar o histórico da conversa de volta.

Se não forem devolvidas assinaturas adequadas, o Gemini 3 devolve um erro 400 "<Function Call> no bloco de conteúdo <index of contents array> está a faltar um thought_signature".

Respostas de funções multimodais

A Chamada de funções multimodal permite que os utilizadores tenham respostas de funções que contenham objetos multimodais, o que permite uma melhor utilização das capacidades de Chamada de funções do modelo. A chamada de funções padrão só suporta respostas de funções baseadas em texto:

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}")

Chamada de funções de streaming

Pode usar argumentos de chamadas de funções parciais de streaming para melhorar a experiência de streaming na utilização de ferramentas. Pode ativar esta funcionalidade definindo explicitamente stream_function_call_arguments como 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}")

Exemplo de resposta do modelo:

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

Temperatura

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

Para o Gemini 3, é vivamente recomendável manter o parâmetro temperature no valor predefinido de 1.0.

Embora os modelos anteriores beneficiassem frequentemente do ajuste da temperatura para controlar a criatividade em comparação com o determinismo, as capacidades de raciocínio do Gemini 3 estão otimizadas para a definição predefinida.

Alterar a temperatura (definindo-a para menos de 1.0) pode levar a um comportamento inesperado, como repetições ou desempenho degradado, particularmente em tarefas matemáticas ou de raciocínio complexas.

Funcionalidades suportadas

O Gemini 3 Pro também suporta as seguintes funcionalidades:

Práticas recomendadas de pedidos

O Gemini 3 é um modelo de raciocínio, o que altera a forma como deve dar comandos.

  • Instruções precisas: seja conciso nos seus comandos de entrada. O Gemini 3 responde melhor a instruções diretas e claras. Pode analisar em excesso técnicas de engenharia de comandos detalhadas ou excessivamente complexas usadas para modelos mais antigos.
  • Nível de detalhe do resultado: por predefinição, o Gemini 3 é menos detalhado e prefere fornecer respostas diretas e eficientes. Se o seu exemplo de utilização exigir uma personalidade mais conversacional ou "faladora", tem de direcionar explicitamente o modelo no comando (por exemplo, "Explica isto como um assistente amigável e falador").

Considerações sobre a migração

Considere as seguintes funcionalidades e restrições ao fazer a migração:

  • Nível de raciocínio: o Gemini 3 Pro e os modelos posteriores usam o parâmetro thinking_level para controlar a quantidade de raciocínio interno que o modelo realiza (baixo ou alto) e para equilibrar a qualidade da resposta, a complexidade do raciocínio, a latência e o custo.
  • Definições de temperatura: se o seu código existente definir explicitamente temperature (especialmente para valores baixos para resultados determinísticos), é recomendado remover este parâmetro e usar a predefinição do Gemini 3 de 1.0 para evitar potenciais problemas de repetição ou degradação do desempenho em tarefas complexas.
  • Assinaturas de reflexão: para o Gemini 3 Pro e modelos posteriores, se for esperada uma assinatura de reflexão num turno, mas não for fornecida, o modelo devolve um erro em vez de um aviso.
  • Resolução de multimédia e tokenização: os modelos Gemini 3 Pro e posteriores usam um comprimento de sequência variável para a tokenização de multimédia em vez de Pan and Scan, e têm novas resoluções predefinidas e custos de tokens para imagens, PDFs e vídeos.
  • Contagem de tokens para entrada multimodal: as contagens de tokens para entradas multimodais (imagens, vídeo e áudio) são uma estimativa baseada no media_resolution escolhido. Como tal, o resultado da chamada da API count_tokens pode não corresponder aos tokens consumidos finais. A utilização precisa para faturação só está disponível após a execução no usage_metadata da resposta.
  • Consumo de tokens: a migração para as predefinições do Gemini 3 Pro pode aumentar a utilização de tokens para imagens e PDFs, mas diminuir a utilização de tokens para vídeo. Se os pedidos excederem agora a capacidade de resposta devido às resoluções predefinidas mais elevadas, é recomendável reduzir explicitamente a resolução dos conteúdos multimédia.
  • PDF e interpretação de documentos: a resolução de OCR predefinida para PDFs foi alterada. Se usou um comportamento específico para a análise de documentos densos, teste a nova definição media_resolution: "high" para garantir a precisão contínua. Para o Gemini 3 Pro e modelos posteriores, as contagens de tokens de PDF em usage_metadata são comunicadas na modalidade IMAGE em vez de DOCUMENT.
  • Segmentação de imagens: a segmentação de imagens não é suportada pelo Gemini 3 Pro e modelos posteriores. Para cargas de trabalho que requerem segmentação de imagens integrada, recomendamos que continue a usar o Gemini 2.5 Flash com o modo de raciocínio desativado.
  • Respostas de funções multimodais: para os modelos Gemini 3 Pro e posteriores, pode incluir dados de imagens e PDFs nas respostas de funções.

Perguntas frequentes

  1. Qual é o limite de conhecimento do Gemini 3 Pro? O Gemini 3 tem um limite de conhecimento de janeiro de 2025.

  2. Que região está gemini-3-pro-preview disponível no Google Cloud? Análise global.

  3. Quais são os limites da capacidade de resposta? O Gemini 3 Pro suporta uma capacidade de resposta de entrada de 1 milhão de tokens e até 64 mil tokens de saída.

  4. O gemini-3-pro-preview suporta a saída de imagens? Não.

  5. O gemini-3-pro-preview suporta a API Gemini Live? Não.

O que se segue?