Gemini 2.0 Flash : Tutoriel étape par étape avec projet de démonstration

Étape 1 : Configurer la clé API pour Google AI Studio

Pour configurer la clé API, accédez à Google AI Studio et cliquez sur le bouton "Créer une clé API". N'oubliez pas de copier la clé et de la coller dans un fichier nommé .env, avec le format suivant :

GOOGLE_API_KEY=replace_this_with_api_key

Si vous avez déjà travaillé avec Google Cloud Platform en utilisant le même compte Google, Google AI Studio vous invitera à choisir l'un de vos projets pour activer l'API.

Pour suivre ce tutoriel, le code Python doit se trouver dans le même dossier que le fichier .env.

Étape 2 : Installer les dépendances de Python

Pour ce projet, nous utiliserons les paquets suivants :

• google-genai: Une bibliothèque Python pour intégrer les modèles d'IA générative de Google dans nos applications.
• pyautogui: Une bibliothèque multiplateforme pour le contrôle programmatique de la souris et du clavier afin d'automatiser des tâches. Dans notre cas, nous l'utilisons pour fournir le contenu de l'écran au modèle d'IA.
• python-dotenv: Une bibliothèque pour gérer les variables d'environnement en les chargeant dans notre application Python à partir de fichiers .env.
• sounddevice: Une bibliothèque Python pour l'enregistrement et la lecture de sons utilisant des API simples pour l'entrée et la sortie audio.
• numpy: Une bibliothèque fondamentale pour le calcul numérique en Python, fournissant un support pour les tableaux, les matrices, et une large gamme d'opérations mathématiques.

Pour installer les dépendances, nous pouvons utiliser pip :

pip install google-genai pyautogui python-dotenv sounddevice numpy

Alternativement, nous téléchargeons le fichier requirements.txt du dépôt le dépôt GitHub que j'ai mis en place pour ce projet et l'utiliser pour créer un environnement Conda :

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

Étape 3 : Créez un chatbot textuel avec l'API Google GenAI

Commençons par créer une simple interface de chat IA en ligne de commande en utilisant le modèle Gemini 2 Flash de Google avec la bibliothèque google.genai. Je vous recommande de consulter la documentation officielle de Gemini 2.0 en cas de problèmes en cours de route.

Le code complet de cet exemple est disponible dans le fichier text.py de mon dépôt GitHub.

Création et connexion au client Google GenAI

La première étape consiste à charger la clé API de manière sécurisée et à initialiser le client Google GenAI. Le script utilise dotenv pour charger les variables d'environnement à partir du fichier .env.

Voici comment configurer le client avec les informations d'identification nécessaires :

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

Effectuer des appels d'API asynchrones

Lorsque nous travaillons avec des API telles que Google GenAI, nous devons souvent gérer des opérations asynchrones. La programmation asynchrone permet de poursuivre d'autres opérations en attendant les demandes du réseau, ce qui rend votre application plus réactive. Ceci est particulièrement important lorsqu'il s'agit d'opérations à forte latence telles que les demandes de réseau.

En Python, la programmation asynchrone est rendue possible grâce à la bibliothèque asyncio et à la syntaxe async/await.

Voici comment nous pouvons faire une demande asynchrone à 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())

Cette version se connecte au modèle d'IA et envoie un seul message "Hello". La réponse est imprimée mot par mot sur la console.

Rendre le site interactif

Pour rendre l'application interactive et permettre à l'utilisateur de discuter avec le modèle d'IA, nous ajoutons une boucle qui permet à l'utilisateur d'envoyer plusieurs messages. La boucle se poursuit jusqu'à ce que l'utilisateur tape "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())

Et c'est tout ! Avec le script ci-dessus, nous avons créé un chatbot IA en ligne de commande en utilisant l'API GenAI de Google. Voici à quoi cela ressemble :

Étape 4 : Ajouter un mode audio

Le mode audio permet au modèle de répondre par la voix au lieu du texte. Pour adapter l'exemple précédent au traitement des réponses audio, nous procédons comme suit

1. Importez sounddevice pour la lecture audio et numpy pour le traitement des données audio.
2. Changez la modalité de réponse de TEXT à AUDIO:

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

3. Initialiser un flux audio avant de se connecter au client :

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

4. Accédez aux données audio de la partie réponse et ajoutez-les au flux audio de la lecture :

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)

Le fichier audio.py dans le le référentiel contient le script complet avec ces changements. Le script contient des commentaires sur les lignes qui ont été modifiées.

Étape 5 : Ajouter l'exécution de code avec des outils

L'une des grandes caractéristiques des modèles d'IA modernes est leur capacité à appeler de manière autonome des fonctions personnalisées dans notre code, et Gemini 2 ne fait pas exception à la règle.

Pour ce faire, nous indiquons au modèle les fonctions qui peuvent être appelées en les enregistrant en tant qu'outils. Ensuite, en analysant l'invite, les noms de fonction et les descriptions, le modèle décidera s'il veut faire un appel de fonction. Lorsqu'il décide de le faire, il envoie une réponse spéciale contenant le nom de la fonction qu'il souhaite appeler et les arguments.

Pour définir un outil, il faut

1. Écrivez une fonction Python avec le même nom et les mêmes arguments que ceux définis dans le schéma.
2. Créez le schéma de la fonction, qui est un dictionnaire contenant des métadonnées sur la fonction, telles que son nom, une description textuelle et une spécification des arguments.
3. Fournir le schéma fonctionnel au modèle d'IA.
4. Exécutez la fonction lorsque le modèle le demande.

Pour illustrer cela, définissons un outil capable de lire un fichier, ce qui permet au modèle de répondre à des questions sur les fichiers de notre machine locale.

Définition de la fonction

Cette partie n'est que du code Python ordinaire. Le modèle s'attend à ce que la réponse soit un dictionnaire avec une clé ”result” si la fonction a réussi et ”error” dans le cas contraire.

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

Spécifier le schéma

Voici comment nous pouvons définir un schéma pour cette fonction :

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

Nous proposons quatre champs :

• ”name”: Le nom de la fonction.
• ”description”: Une description textuelle. Le modèle s'en sert pour décider d'appeler ou non la fonction.
• ”properties”: Description des arguments de la fonction.
• ”output”: Description de la sortie de la fonction.

Vérifiez la documentation officielle pour plus d'informations sur les schémas de fonctions.

Fournir la fonction au modèle

Pour que le modèle connaisse notre fonction, nous fournissons le schéma de la fonction dans la configuration du modèle :

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

Traitement de la demande d'appel de fonction à partir du modèle

Lorsque le modèle décide d'effectuer un appel de fonction, il ajoute une adresse tool_call à l'adresse response. Elle contient le nom de la fonction et les arguments. Il peut contenir plusieurs demandes d'appel, nous devons donc itérer sur chacune d'entre elles, appeler les fonctions correspondantes et renvoyer le résultat au modèle :

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

L'implémentation complète de cet exemple est fournie dans le fichier tool.py dans le le référentiel contenant le script complet avec ces changements appliqués. Les définitions des fonctions et des schémas se trouvent dans le fichier tool_spec.py .

Accès au web

À l'aide d'outils, nous pouvons également donner au modèle la possibilité d'accéder au web en ajoutant l'outil de recherche Google :

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

Cet outil est intégré et, pour cette raison, nous n'avons pas besoin de fournir une fonction.

Exécution du code

Une autre fonction intégrée est l'exécution du code. L'exécution de code permet au modèle d'écrire et d'exécuter du code Python pour répondre à des questions complexes, impliquant généralement des mathématiques. Par exemple, avec cet outil, si nous lui demandons de calculer la somme des 10 premiers nombres premiers, il écrira d'abord le code Python pour effectuer ce calcul, l'exécutera, puis fournira la réponse.

Pour activer l'outil, nous procédons comme suit :

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

Voici un exemple du comportement du modèle lors de l'exécution du code :

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

Étape 6 : Créer un assistant visuel

Dans cette dernière section, nous explorons les capacités visuelles de Gemini 2. L'objectif est de créer un assistant IA capable de comprendre le contenu de notre écran et de répondre aux questions qui s'y rapportent. Cela peut être utile, par exemple, lorsque nous lui demandons d'expliquer une erreur que nous voyons dans notre terminal ou de fournir des informations sur un élément affiché à l'écran.

Dans les exemples précédents, nous avons utilisé la programmation asynchrone pour nous connecter au modèle d'IA et envoyer des données dans les deux sens tout en traitant les réponses en temps réel. Malheureusement, la version actuelle du SDK ne prend pas encore en charge la communication en temps réel avec les images. Au lieu de cela, nous fournissons des données d'image par le biais d'un flux de travail demande-réponse. Notez qu'il ne s'agit pas d'une limitation de Gemini 2.0 lui-même - c'est simplement que l'API bêta actuelle ne le prend pas encore en charge.

Envoi d'une requête synchrone à Google GenAI

Commençons par apprendre à envoyer une requête contenant des données d'image à l'API GenAI de Google. Voici comment nous pouvons envoyer une requête synchrone :

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 principale différence dans cet exemple est que nous utilisons client.models.generate_content pour envoyer une requête à l'API. Il s'agit d'une demande synchrone, ce qui signifie qu'elle n'offre pas une expérience de conversation en temps réel.

Envoi d'une image

Nous pouvons envoyer une image en la chargeant et en l'ajoutant à la liste de contenu. Nous utilisons le paquet PIL pour créer une fonction appelée load_and_resize_image() qui charge et redimensionne l'image.

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)

Créer l'assistant visuel de l'IA

L'assistant visuel de l'IA traite une invite textuelle ainsi qu'une capture d'écran pour nous aider à répondre à des questions sur ce qui est affiché à l'écran. J'ai fait de nombreuses expériences à ce sujet et le modèle peut comprendre le contenu de l'écran même lorsque plusieurs fenêtres sont ouvertes.

La manière la plus simple de fournir au modèle le contenu de l'écran est de faire une capture d'écran. Pour ce faire, nous utilisons le paquetage pyautogui, une bibliothèque multiplateforme pour le contrôle programmatique de la souris et du clavier afin d'automatiser des tâches. Dans notre cas, nous l'utiliserons uniquement pour prendre des captures d'écran, mais nous pourrions étendre ses fonctionnalités pour permettre à l'IA d'effectuer des tâches sur notre ordinateur de manière autonome.

Voici une fonction permettant de faire une capture d'écran :

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

Pour la rendre interactive, nous répétons les étapes suivantes jusqu'à ce que l'utilisateur décide de quitter l'application :

1. Demandez à l'utilisateur de saisir une invite.
2. Faites une capture d'écran et envoyez-la au modèle d'IA en même temps que l'invite.
3. Affichez le résultat à l'utilisateur.

Il faut garder une chose à l'esprit dans cette approche. L'application s'exécute dans le terminal, qui est également affiché à l'écran. Il est donc préférable de demander au modèle d'ignorer la fenêtre du terminal. Pour ce faire, il suffit d'ajouter une adresse system_instruction à la configuration :

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

Pour résumer, voici notre assistant visuel d'IA. Le fichier contenant le code complet est également disponible en tant que fichier vision.py dans le le dépôt.

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 version actuelle est un peu maladroite, car elle exige que le terminal soit ouvert au-dessus de la vue actuelle pour que nous puissions le déclencher. L'étape suivante consisterait naturellement à l'exécuter en arrière-plan et à utiliser la saisie et la sortie vocales au lieu du texte.

Conclusion

Nous avons appris à utiliser le modèle Gemini 2.0 Flash pour diverses applications, telles que le développement de chatbots capables d'engager des conversations en temps réel avec du texte et de la voix, permettant au modèle d'IA d'effectuer des actions à l'aide d'appels de fonction et d'un assistant visuel capable d'analyser le contenu de notre écran d'ordinateur.

Si vous souhaitez aller plus loin, Google fournit deux exemples illustrant la capacité du modèle à détecter des objets dans une image en fournissant des étiquettes pour leurs contours. Cet exemple met l'accent sur la compréhension de l'espace en 2D en demandant au modèle d'identifier et d'étiqueter des petits gâteaux sur une image. Les Gémeaux peuvent également comprendre le contexte 3D d'une image, comme le montre l'exemple suivant ici.

Dans l'ensemble, Gemini 2.0 est très prometteur, même si la version actuelle de l'API ne nous permet pas encore de l'utiliser à son plein potentiel. Je suis impatient d'utiliser pleinement les capacités multimodales en temps réel dans un avenir proche.