Flash Géminis 2.0: Tutorial paso a paso con proyecto de demostración

Paso 1: Configurar la clave API para Google AI Studio

Para configurar la clave API, ve a Google AI Studio y haz clic en el botón "Crear clave API". Recuerda copiar la clave y luego pegarla en un archivo llamado .env, con el siguiente formato:

GOOGLE_API_KEY=replace_this_with_api_key

Si ya has trabajado con Google Cloud Platform utilizando la misma cuenta de Google, Google AI Studio te pedirá que elijas uno de tus proyectos para activar la API.

Para seguir este tutorial, el código Python debe estar en la misma carpeta que el archivo .env.

Paso 2: Instalar dependencias de Python

Para este proyecto, utilizaremos los siguientes paquetes:

• google-genai: Una biblioteca Python para integrar los modelos de IA generativa de Google en nuestras aplicaciones.
• pyautogui: Una biblioteca multiplataforma para controlar mediante programación el ratón y el teclado para automatizar tareas. En nuestro caso, lo utilizamos para proporcionar el contenido de la pantalla al modelo de IA.
• python-dotenv: Una biblioteca para gestionar variables de entorno cargándolas desde archivos .env en nuestra aplicación Python.
• sounddevice: Una biblioteca Python para grabar y reproducir sonido utilizando APIs sencillas para la entrada y salida de audio.
• numpy: Una biblioteca fundamental para la computación numérica en Python, que proporciona soporte para matrices, arreglos y una amplia gama de operaciones matemáticas.

Para instalar las dependencias, podemos utilizar pip:

pip install google-genai pyautogui python-dotenv sounddevice numpy

Alternativamente, descargamos el archivo requisitos.txt del repositorio el repositorio de GitHub que he creado para este proyecto y lo utilizamos para crear un entorno Conda:

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

Paso 3: Crea un chatbot de texto con la API GenAI de Google

Empecemos creando una sencilla interfaz de chat de IA de línea de comandos utilizando el modelo Gemini 2 Flash de Google con la biblioteca google.genai. Te recomiendo que consultes la documentación oficial de Géminis 2.0 por si surge algún problema.

El código completo de este ejemplo está disponible en el archivo text.py de mi repositorio de GitHub.

Crear y conectarse al cliente Google GenAI

El primer paso es cargar la clave API de forma segura e inicializar el cliente Google GenAI. El script utiliza dotenv para cargar las variables de entorno desde el archivo .env.

A continuación te explicamos cómo configurar el cliente con las credenciales necesarias:

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

Hacer llamadas asíncronas a la API

Cuando trabajamos con APIs como Google GenAI, a menudo necesitamos gestionar operaciones asíncronas. La programación asíncrona permite que otras operaciones continúen mientras esperas las peticiones de la red, haciendo que tu aplicación responda mejor. Esto es especialmente importante cuando se trata de operaciones de alta latencia, como las peticiones de red.

En Python, la programación asíncrona es posible mediante la biblioteca asyncio y la sintaxis async/await.

Así es como podemos hacer una petición asíncrona a 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())

Esta versión se conecta al modelo de IA y envía un único mensaje "Hola". La respuesta se imprime palabra por palabra en la consola.

Hacerlo interactivo

Para que la aplicación sea interactiva y el usuario pueda chatear con el modelo de IA, añadimos un bucle que permite al usuario enviar varios mensajes. El bucle continúa hasta que el usuario teclea "salir".

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())

Y ya está. Con el script anterior, hemos creado un chatbot de IA de línea de comandos utilizando la API GenAI de Google. Esto es lo que parece:

Paso 4: Añadir modo audio

El modo Audio permite al modelo responder con voz en lugar de texto. Para ajustar el ejemplo anterior al manejo de las respuestas de audio, hacemos lo siguiente

1. Importa sounddevice para reproducir audio y numpy para procesar datos de audio.
2. Cambia la modalidad de respuesta de TEXT a AUDIO:

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

3. Inicializa un flujo de audio antes de conectarte al cliente:

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

4. Accede a los datos de audio de la parte de respuesta y añádelos al flujo de audio de la reproducción:

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)

El archivo audio.py en el repositorio contiene el script completo con estos cambios aplicados. El guión contiene comentarios sobre las líneas que han cambiado.

Paso 5: Añade ejecución de código con herramientas

Una de las grandes características de los modelos de IA modernos es su capacidad para llamar de forma autónoma a funciones personalizadas de nuestro código, y Géminis 2 no es una excepción.

La forma en que funciona es que le decimos al modelo qué funciones están disponibles para ser llamadas registrándolas como herramientas. Después, analizando la indicación, los nombres de las funciones y las descripciones, el modelo decidirá si quiere hacer una llamada a una función. Cuando decida hacerlo, enviará una respuesta especial con el nombre de la función a la que quiere llamar y los argumentos.

Para definir una herramienta, necesitamos

1. Escribe una función Python con el mismo nombre y argumentos que los definidos en el esquema.
2. Crea el esquema de la función, que es un diccionario con metadatos sobre la función, como su nombre, una descripción textual y una especificación de los argumentos.
3. Proporciona el esquema de funciones al modelo de IA.
4. Ejecuta la función cuando el modelo lo solicite.

Para ilustrarlo, definamos una herramienta que pueda leer un archivo, permitiendo que el modelo responda a preguntas sobre archivos de nuestra máquina local.

Definir la función

Esta parte es sólo código Python normal. El modelo espera que la respuesta sea un diccionario con una clave ”result” si la función ha tenido éxito y ”error” en caso contrario.

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

Especificar el esquema

Así es como podemos definir un esquema para esta función:

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

Proporcionamos cuatro campos:

• ”name”: El nombre de la función.
• ”description”: Una descripción textual. El modelo lo utiliza para decidir si llama a la función.
• ”properties”: Descripción de los argumentos de la función.
• ”output”: Descripción de la salida de la función.

Consulta la documentación oficial para obtener más información sobre los esquemas de funciones.

Proporcionar la función al modelo

Para que el modelo conozca nuestra función, proporcionamos el esquema de la función en la configuración del modelo:

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

Procesar la solicitud de llamada a función del modelo

Cuando el modelo decida realizar una llamada a una función, añadirá una tool_call a la response. Contendrá el nombre de la función y los argumentos. Podría contener varias peticiones de llamada, por lo que necesitamos iterar sobre todas ellas, llamar a las funciones correspondientes y devolver el resultado al 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)

La implementación completa de este ejemplo se proporciona en el archivo tool.py en el repositorio que contiene el script completo con estos cambios aplicados. Las definiciones de funciones y esquemas están en el archivo tool_spec.py .

Acceso web

Utilizando herramientas, también podemos dar al modelo la capacidad de acceder a la web añadiendo la herramienta de búsqueda de Google:

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

Esta herramienta está incorporada, y por eso no necesitamos proporcionar una función.

Ejecución del código

Otra función incorporada es la ejecución de código. La ejecución de código permite al modelo escribir y ejecutar código Python para responder a preguntas complejas, normalmente matemáticas. Por ejemplo, con esta herramienta, si le pedimos que calcule la suma de los 10 primeros números primos, primero escribirá código Python para calcularlo, lo ejecutará y luego nos dará la respuesta.

Para activar la herramienta, hacemos lo siguiente

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

Aquí tienes un ejemplo del comportamiento del modelo con la ejecución de 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.

Paso 6: Construye un Asistente Visual

En esta última sección, exploramos las capacidades visuales de Gemini 2. El objetivo es crear un asistente de IA que pueda entender el contenido de nuestra pantalla y responder a preguntas sobre él. Esto puede ser útil, por ejemplo, cuando le pedimos que nos explique un error que vemos en nuestro terminal o que nos proporcione información sobre algo que aparece actualmente en la pantalla.

En los ejemplos anteriores, utilizamos programación asíncrona para conectar con el modelo de IA y enviar datos de un lado a otro mientras procesábamos las respuestas en tiempo real. Lamentablemente, la versión actual del SDK aún no admite la comunicación en tiempo real con imágenes. En su lugar, proporcionamos datos de imagen mediante un flujo de trabajo de solicitud-respuesta. Ten en cuenta que esto no es una limitación de Géminis 2.0 en sí, sino que la actual API beta aún no lo admite.

Envío de una solicitud sincrónica a Google GenAI

Empecemos por aprender a enviar una solicitud con datos de imagen a la API GenAI de Google. Así es como podemos enviar una petición 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)

La principal diferencia en este ejemplo es que utilizamos client.models.generate_content para enviar una solicitud a la API. Se trata de una solicitud sincrónica, lo que significa que no proporciona una experiencia de conversación en tiempo real.

Enviar una imagen

Podemos enviar una imagen cargándola y añadiéndola a la lista de contenidos. Utilizamos el paquete PIL para crear una función llamada load_and_resize_image() que carga y redimensiona la imagen.

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)

Creación del asistente visual de IA

El asistente visual de IA procesa una indicación textual junto con una captura de pantalla para ayudarnos a responder preguntas sobre lo que hay en la pantalla. He experimentado mucho con esto, y el modelo puede comprender el contenido de la pantalla incluso cuando hay varias ventanas abiertas.

La forma más sencilla de proporcionar al modelo el contenido de la pantalla es haciendo una captura de pantalla. Para ello, utilizamos el paquete pyautogui, una biblioteca multiplataforma para controlar mediante programación el ratón y el teclado para automatizar tareas. En nuestro caso, lo utilizaremos sólo para hacer capturas de pantalla, aunque podríamos ampliar su funcionalidad para que la IA realice tareas en nuestro ordenador de forma autónoma.

Aquí tienes una función para hacer una captura de pantalla:

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 hacerlo interactivo, repetimos los siguientes pasos hasta que el usuario decida salir de la aplicación:

1. Pide al usuario que introduzca una pregunta.
2. Haz una captura de pantalla y envíasela al modelo de IA junto con la indicación.
3. Muestra el resultado al usuario.

Debemos tener en cuenta una cosa con este planteamiento. La aplicación se ejecutará en el terminal, que también se muestra en la pantalla. Por lo tanto, es mejor indicar al modelo que ignore la ventana del terminal. Esto puede hacerse añadiendo un system_instruction a la configuración:

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

Poniéndolo todo junto, aquí está nuestro asistente visual de IA. El archivo con el código completo también está disponible como archivo vision.py en el repositorio.

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()

La versión actual es un poco tosca, ya que requiere que el terminal esté abierto encima de la vista actual para que podamos activarlo. Un siguiente paso natural sería ejecutarlo en segundo plano y utilizar entrada y salida de voz en lugar de texto.

Conclusión

Hemos aprendido a utilizar el modelo Gemini 2.0 Flash para diversas aplicaciones, como desarrollar chatbots capaces de entablar conversaciones en tiempo real con texto y voz, permitir que el modelo de IA realice acciones mediante llamadas a funciones y un asistente visual capaz de analizar el contenido de la pantalla de nuestro ordenador.

Si quieres profundizar más, Google proporciona dos ejemplos que muestran la capacidad del modelo para detectar objetos en una imagen proporcionando sus cuadros delimitadores con etiquetas. Este ejemplo se centra en la comprensión espacial 2D pidiendo al modelo que identifique y etiquete magdalenas en un dibujo. Gemini también puede comprender el contexto 3D de una imagen, como se muestra aquí.

En general, Géminis 2.0 es bastante prometedora, a pesar de que la versión actual de la API aún no nos permite utilizarla en todo su potencial. Me entusiasma la idea de utilizar plenamente las capacidades multimodales en tiempo real en un futuro próximo.