Flash Gemini 2.0: Tutorial passo a passo com projeto de demonstração

Etapa 1: Configurar a chave de API para o Google AI Studio

Para configurar a chave da API, navegue até Google AI Studio e clique no botão "Create API Key" (Criar chave de API). Lembre-se de copiar a chave e colá-la em um arquivo chamado .env, com o seguinte formato:

GOOGLE_API_KEY=replace_this_with_api_key

Se você já tiver trabalhado com o Google Cloud Platform usando a mesma conta do Google, o Google AI Studio solicitará que você escolha um dos seus projetos para ativar a API.

Para que você possa acompanhar este tutorial, o código Python deve estar na mesma pasta que o arquivo .env.

Etapa 2: Instalar as dependências do Python

Para este projeto, usaremos os seguintes pacotes:

• google-genai: Uma biblioteca Python para integrar os modelos de IA generativa do Google em nossos aplicativos.
• pyautogui: Uma biblioteca multiplataforma para controlar programaticamente o mouse e o teclado para automatizar tarefas. No nosso caso, nós o usamos para fornecer o conteúdo da tela ao modelo de IA.
• python-dotenv: Uma biblioteca para gerenciar variáveis de ambiente carregando-as de arquivos .env em nosso aplicativo Python.
• sounddevice: Uma biblioteca Python para gravação e reprodução de som usando APIs simples para entrada e saída de áudio.
• numpy: Uma biblioteca fundamental para computação numérica em Python, que oferece suporte a matrizes, matrizes e uma ampla gama de operações matemáticas.

Para instalar as dependências, podemos usar o pip:

pip install google-genai pyautogui python-dotenv sounddevice numpy

Como alternativa, baixamos o arquivo requirements.txt do do repositório do GitHub que configurei para este projeto e o utilizo para criar um ambiente Conda:

conda create --name gemini python=3.11
conda activate gemini
pip install -r requirements.txt

Etapa 3: Crie um chatbot de texto com a API GenAI do Google

Vamos começar criando uma interface simples de bate-papo com IA de linha de comando usando o modelo Gemini 2 Flash do Google com a biblioteca google.genai. Recomendo que você dê uma olhada na documentação oficial do Gemini 2.0 para o caso de você ter algum problema no caminho.

O código completo para este exemplo está disponível no arquivo text.py do meu repositório no GitHub.

Criando e conectando-se ao cliente do Google GenAI

A primeira etapa é carregar a chave da API com segurança e inicializar o cliente do Google GenAI. O script usa dotenv para carregar variáveis de ambiente do arquivo .env.

Veja como você pode configurar o cliente com as credenciais necessárias:

from google import genai
from dotenv import load_dotenv
import os

# Load environment variables from a .env file
load_dotenv()
client = genai.Client(
    api_key=os.getenv("GOOGLE_API_KEY"),
    http_options={"api_version": "v1alpha"},
)

print("Connected to the AI model!")

Fazer chamadas assíncronas à API

Ao trabalhar com APIs como o Google GenAI, muitas vezes precisamos gerenciar operações assíncronas. A programação assíncrona permite que outras operações continuem enquanto você aguarda as solicitações de rede, tornando seu aplicativo mais responsivo. Isso é particularmente importante ao lidar com operações de alta latência, como solicitações de rede.

No Python, a programação assíncrona é possível usando a biblioteca asyncio e a sintaxe async/await.

Veja como podemos fazer uma solicitação assíncrona ao Google GenAI:

from google import genai
from dotenv import load_dotenv
import os
import asyncio

# Load environment variables from a .env file
load_dotenv()
async def main():
    client = genai.Client(
        api_key=os.getenv("GOOGLE_API_KEY"),
        http_options={"api_version": "v1alpha"},
    )    
    # Define the AI model and configuration
    model_id = "gemini-2.0-flash-exp"
    config = {"response_modalities": ["TEXT"]}
    async with client.aio.live.connect(model=model_id, config=config) as session:
        await session.send("Hello", end_of_turn=True)
        # Process responses from the AI
        async for response in session.receive():
            if not response.server_content.turn_complete:
                for part in response.server_content.model_turn.parts:
                    print(part.text, end="", flush=True)

# Run the main function
asyncio.run(main())

Essa versão se conecta ao modelo de IA e envia uma única mensagem "Hello". A resposta é impressa palavra por palavra no console.

Tornando-o interativo

Para tornar o aplicativo interativo, permitindo que o usuário converse com o modelo de IA, adicionamos um loop que permite que o usuário envie várias mensagens. O loop continua até que o usuário digite "exit".

from google import genai
from dotenv import load_dotenv
import os
import asyncio

# Load environment variables from a .env file
load_dotenv()
async def main():
    client = genai.Client(
        api_key=os.getenv("GOOGLE_API_KEY"),
        http_options={"api_version": "v1alpha"},
    )
    # Define the AI model and configuration
    model_id = "gemini-2.0-flash-exp"
    config = {"response_modalities": ["TEXT"]}
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("> ")
            print()
            # Exit the loop if the user types "exit"
            if message == "exit":
                print("Exiting...")
                break
            # Send the user's message to the AI model, marking the end of the turn
            await session.send(message, end_of_turn=True)
            # Receive responses asynchronously and process each response
            async for response in session.receive():
                if not response.server_content.turn_complete:
                    for part in response.server_content.model_turn.parts:
                        print(part.text, end="", flush=True)
            print()

# Run the main function
asyncio.run(main())

E é isso! Com o script acima, criamos um chatbot de IA de linha de comando usando a API GenAI do Google. Aqui está o que você vê:

Etapa 4: Adicionar modo de áudio

O modo de áudio permite que o modelo responda com voz em vez de texto. Para ajustar o exemplo anterior para lidar com as respostas de áudio, você deve

1. Importe sounddevice para reprodução de áudio e numpy para processar dados de áudio.
2. Altere a modalidade de resposta de TEXT para AUDIO:

	config = {"response_modalities": ["AUDIO"]} 

3. Inicialize um fluxo de áudio antes de se conectar ao cliente:

	with sd.OutputStream(
	samplerate=24000, 
	channels=1, 
	dtype="int16",
) as audio_stream:

4. Acesse os dados de áudio da parte da resposta e adicione-os ao fluxo de áudio da reprodução:

for part in response.server_content.model_turn.parts:
    # Get the audio data from the response part and add it to the steam
    inline_data = part.inline_data
    audio_data = np.frombuffer(inline_data.data, dtype="int16")
    audio_stream.write(audio_data)

O arquivo audio.py no repositório no repositório contém o script completo com essas alterações aplicadas. O script contém comentários sobre as linhas que foram alteradas.

Etapa 5: Adicionar execução de código com ferramentas

Um dos grandes recursos dos modelos modernos de IA é a capacidade de chamar de forma autônoma funções personalizadas em nosso código, e o Gemini 2 não é exceção.

A maneira como isso funciona é informar ao modelo quais funções estão disponíveis para serem chamadas, registrando-as como ferramentas. Em seguida, ao analisar o prompt, os nomes e as descrições das funções, o modelo decidirá se deseja fazer uma chamada de função. Quando você decidir fazer isso, ele enviará uma resposta especial com o nome da função que deseja chamar e os argumentos.

Para definir uma ferramenta, precisamos:

1. Escreva uma função Python com o mesmo nome e argumentos definidos no esquema.
2. Crie o esquema de função, que é um dicionário com metadados sobre a função, como seu nome, uma descrição textual e uma especificação dos argumentos.
3. Forneça o esquema de funções para o modelo de IA.
4. Execute a função quando o modelo a solicitar.

Para ilustrar isso, vamos definir uma ferramenta que possa ler um arquivo, permitindo que o modelo responda a perguntas sobre arquivos em nosso computador local.

Definição da função

Essa parte é apenas um código Python comum. O modelo espera que a resposta seja um dicionário com uma chave ”result” se a função for bem-sucedida e ”error” caso contrário.

def load_file_content(filename):
    try:
      with open(filename, "rt") as f:
          return {
              "result": f.read()
          }
    except Exception as e:
      return {
          "error": "Could not load file content",
      }

Especificando o esquema

Veja como podemos definir um esquema para essa função:

load_file_content_schema = {
    "name": "load_file_content",
    "description": "Load the content of a file",
    "parameters": {
        "type": "object",
        "properties": {
            "filename": {
                "type": "string",
                "description": "The name of the file",
            },
        },
        "required": ["filename"],
    },
    "output": {
        "type": "string",
        "description": "The text content of the file",
    },
}

Fornecemos quatro campos:

• ”name”: O nome da função.
• ”description”: Uma descrição textual. Isso é usado pelo modelo para decidir se você deve chamar a função.
• ”properties”: Descrição dos argumentos da função.
• ”output”: Descrição da saída da função.

Verificar a documentação oficial para obter mais informações sobre esquemas de funções.

Fornecimento da função ao modelo

Para que o modelo saiba sobre nossa função, fornecemos o esquema de função na configuração do modelo:

config = {
       "tools": [{"function_declarations": [load_file_content_schema]}], 
       "response_modalities": ["TEXT"]
}

Processar a solicitação de chamada de função do modelo

Quando o modelo decidir executar uma chamada de função, ele adicionará um tool_call ao response. Isso conterá o nome da função e os argumentos. Ele pode conter várias solicitações de chamada, portanto, precisamos iterar sobre todas elas, chamar as funções correspondentes e enviar o resultado de volta ao modelo:

# A dictionary mapping the function names to the actual functions
FUNCTIONS = {"load_file_content": load_file_content}
if response.tool_call is not None:
    for fc in tool_call.function_calls:
        f = FUNCTIONS.get(fc.name)
        tool_response = types.LiveClientToolResponse(
            function_responses=[
                types.FunctionResponse(
                    name=fc.name,
                    id=fc.id,
                    response=f(**fc.args),
                )
            ]
        )
    await session.send(tool_response)

A implementação completa desse exemplo é fornecida no arquivo tool.py no no repositório que contém o script completo com essas alterações aplicadas. As definições de função e esquema estão no arquivo no arquivo tool_spec.py .

Acesso à Web

Usando ferramentas, também podemos dar ao modelo a capacidade de acessar a Web, adicionando a ferramenta de pesquisa do Google:

search_tool = {"google_search": {}}
config = {
    "tools": [search_tool],
    "response_modalities": ["TEXT"],
}

Essa ferramenta é incorporada e, por esse motivo, não precisamos fornecer uma função.

Execução do código

Outra função incorporada é a execução de código. A execução de código permite que o modelo escreva e execute código Python para responder a perguntas complexas, geralmente envolvendo matemática. Por exemplo, com essa ferramenta, se pedirmos que ela calcule a soma dos 10 primeiros números primos, ela primeiro escreverá o código Python para calcular isso, executará e, em seguida, fornecerá a resposta.

Para ativar a ferramenta, você deve fazer isso:

code_execution_tool = {"code_execution": {}}
config = {
    "tools": [code_execution_tool],
    "response_modalities": ["TEXT"],
}

Aqui está um exemplo do comportamento do modelo com a execução do código:

​​> add the first 10 prime numbers
Okay, I understand. You want me to add the first 10 prime numbers.
Here's my plan:
1. **Identify the first 10 prime numbers:** I will use a python code to find prime numbers.
2. **Sum the prime numbers:** I will also sum them using python.
3. **Report the result**
The first 10 prime numbers are 2, 3, 5, 7, 11, 13, 17, 19, 23, and 29.  Their sum is 129.

Etapa 6: Criar um assistente visual

Nesta última seção, exploramos os recursos visuais da Gemini 2. O objetivo é criar um assistente de IA que possa entender o conteúdo em nossa tela e responder a perguntas sobre ele. Isso pode ser útil, por exemplo, quando pedimos que ele explique um erro que vemos em nosso terminal ou forneça informações sobre algo que está sendo exibido na tela.

Nos exemplos anteriores, usamos a programação assíncrona para nos conectarmos ao modelo de IA e enviar dados para frente e para trás enquanto processávamos as respostas em tempo real. Infelizmente, a versão atual do SDK ainda não oferece suporte à comunicação em tempo real com imagens. Em vez disso, fornecemos dados de imagem por meio de um fluxo de trabalho de solicitação-resposta. Observe que isso não é uma limitação do Gemini 2.0 em si, mas que a API beta atual ainda não oferece suporte a isso.

Envio de uma solicitação síncrona para o Google GenAI

Vamos começar aprendendo como enviar uma solicitação com dados de imagem para a API GenAI do Google. Veja como podemos enviar uma solicitação síncrona:

from google import genai
from dotenv import load_dotenv
import os

load_dotenv()

client = genai.Client(
    api_key=os.getenv("GOOGLE_API_KEY"),
    http_options={"api_version": "v1alpha"},
)

response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["Hello"],
)

print(response.text)

A principal diferença neste exemplo é que usamos client.models.generate_content para enviar uma solicitação à API. Essa é uma solicitação síncrona, o que significa que ela não oferece uma experiência de conversa em tempo real.

Envio de uma imagem

Você pode enviar uma imagem carregando-a e adicionando-a à lista de conteúdo. Usamos o pacote PIL para criar uma função chamada load_and_resize_image() que carrega e redimensiona a imagem.

from PIL import Image

def load_and_resize_image(image_path):
    with Image.open(image_path) as img:
        aspect_ratio = img.height / img.width
        new_height = int(img.width * aspect_ratio)
        return img.resize((img.width, new_height), Image.Resampling.LANCZOS)    

image = load_and_resize_image("example_image.jpeg")

response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["Describe the image", image],
)

print(response.text)

Criando o assistente visual de IA

O assistente visual de IA processa um prompt textual junto com uma captura de tela para nos ajudar a responder perguntas sobre o que está na tela. Fiz muitos experimentos com isso e o modelo consegue entender o conteúdo da tela mesmo quando várias janelas estão abertas.

A maneira mais simples de fornecer ao modelo o conteúdo da tela é fazer uma captura de tela. Para isso, usamos o pacote pyautogui, uma biblioteca multiplataforma para controlar programaticamente o mouse e o teclado para automatizar tarefas. No nosso caso, vamos usá-lo apenas para fazer capturas de tela, embora possamos estender sua funcionalidade para permitir que a IA execute tarefas em nosso computador de forma autônoma.

Aqui está uma função para fazer uma captura de tela:

def capture_screen():
    timestamp = time.strftime("%Y%m%d-%H%M%S")
    filename = f"screenshot_{timestamp}.jpeg"
    screenshot = pyautogui.screenshot()
    screenshot = screenshot.convert("RGB")
    screenshot.save(filename, format="JPEG")
    return filename

Para torná-lo interativo, repetimos as etapas a seguir até que o usuário decida sair do aplicativo:

1. Peça ao usuário para inserir um prompt.
2. Faça uma captura de tela e envie-a para o modelo de IA junto com o prompt.
3. Exibir o resultado para o usuário.

Você precisa ter uma coisa em mente com essa abordagem. O aplicativo será executado no terminal, que também é exibido na tela. Portanto, é melhor instruir o modelo a ignorar a janela do terminal. Isso pode ser feito adicionando um system_instruction à configuração:

client.models.generate_content(
        model="gemini-2.0-flash-exp",
        contents=[prompt, screen],
        config=types.GenerateContentConfig(
            system_instruction="Ignore the terminal window in the image when analyzing the image",
        ),
)

Juntando tudo isso, aqui está o nosso assistente visual de IA. O arquivo com o código completo também está disponível como o arquivo vision.py no no repositório.

from google import genai
from google.genai import types
from PIL import Image
import pyautogui
import time
import os
from dotenv import load_dotenv
load_dotenv()

# Initialize the GenAI client
client = genai.Client(
    api_key=os.getenv("GOOGLE_API_KEY"),
    http_options={"api_version": "v1alpha"},
)
def capture_screen():
    timestamp = time.strftime("%Y%m%d-%H%M%S")
    filename = f"screenshot_{timestamp}.jpeg"
    screenshot = pyautogui.screenshot()
    screenshot = screenshot.convert("RGB")
    screenshot.save(filename, format="JPEG")
    return filename

def load_and_resize_image(image_path):
    with Image.open(image_path) as img:
        aspect_ratio = img.height / img.width
        new_height = int(img.width * aspect_ratio)
        return img.resize((img.width, new_height), Image.Resampling.LANCZOS)    

def get_genai_response(prompt):
    print("Analyzing screen...")
    screen = load_and_resize_image(capture_screen())
    response = client.models.generate_content(
        model="gemini-2.0-flash-exp",
        contents=[prompt, screen],
        config=types.GenerateContentConfig(
            system_instruction="Ignore the terminal window in the image when analyzing the image",
        ),
    )
    return response.text

def main():
    while True:
        prompt = input("> ")
        print()
        if prompt == "exit":
            break
        answer = get_genai_response(prompt)
        print(answer)
        print()

if __name__ == "__main__":
    main()

A versão atual é um pouco desajeitada, exigindo que o terminal esteja aberto na parte superior da exibição atual para que você possa acioná-la. Uma próxima etapa natural seria executá-lo em segundo plano e usar entrada e saída de voz em vez de texto.

Conclusão

Aprendemos a usar o modelo Gemini 2.0 Flash para várias aplicações, como o desenvolvimento de chatbots que podem participar de conversas em tempo real com texto e voz, permitindo que o modelo de IA execute ações usando chamadas de função e um assistente visual capaz de analisar o conteúdo da tela do nosso computador.

Se você quiser explorar mais, o Google fornece dois exemplos que demonstram a capacidade do modelo de detectar objetos em uma imagem, fornecendo rótulos às suas caixas delimitadoras. Este exemplo concentra-se na compreensão espacial 2D, pedindo ao modelo que identifique e rotule os cupcakes em uma imagem. O Gemini também pode entender o contexto 3D de uma imagem, como você pode ver aqui.

De modo geral, o Gemini 2.0 é bastante promissor, apesar do fato de que a versão atual da API ainda não nos permite usá-lo em todo o seu potencial. Estou animado para usar totalmente os recursos multimodais em tempo real em um futuro próximo.