Gemini 2.0 Flash: Stapsgewijze tutorial met demoproject

Stap 1: Stel de API-sleutel in voor Google AI Studio

Ga om de API-sleutel in te stellen naar Google AI Studio en klik op de knop “Create API Key”. Kopieer de sleutel en plak hem vervolgens in een bestand met de naam .env, in het volgende formaat:

GOOGLE_API_KEY=replace_this_with_api_key

Als je al met Google Cloud Platform hebt gewerkt met dezelfde Google-account, vraagt Google AI Studio je om een van je projecten te kiezen om de API te activeren.

Om deze tutorial te volgen, moet de Python-code in dezelfde map staan als het .env-bestand.

Stap 2: Installeer Python-afhankelijkheden

Voor dit project gebruiken we de volgende packages:

• google-genai: Een Python-bibliotheek om Google’s generatieve AI-modellen in onze applicaties te integreren.
• pyautogui: Een cross-platform bibliotheek om muis en toetsenbord programmatisch te bedienen voor automatisering. In ons geval gebruiken we het om de scherminhoud aan het AI-model te leveren.
• python-dotenv: Een bibliotheek om omgevingsvariabelen te beheren door ze uit .env-bestanden in onze Python-app te laden.
• sounddevice: Een Python-bibliotheek voor het opnemen en afspelen van geluid met eenvoudige API’s voor audio-in- en -uitvoer.
• numpy: Een basisbibliotheek voor numerieke berekeningen in Python, met ondersteuning voor arrays, matrices en een breed scala aan wiskundige operaties.

Om de afhankelijkheden te installeren, kunnen we pip gebruiken:

pip install google-genai pyautogui python-dotenv sounddevice numpy

requirements.txt-bestand ook downloaden uit de GitHub-repository die ik voor dit project heb opgezet en gebruiken om een Conda-omgeving te maken:

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

Stap 3: Maak een tekst-chatbot met de Google GenAI API

Laten we beginnen met een eenvoudige AI-chatinterface voor de command line met Google’s Gemini 2 Flash-model via de google.genai-bibliotheek. Ik raad aan om de officiële documentatie van Gemini 2.0 te raadplegen als je onderweg ergens tegenaan loopt.

De volledige code voor dit voorbeeld staat in het bestand text.py in mijn GitHub-repository.

De Google GenAI-client aanmaken en verbinden

De eerste stap is de API-sleutel veilig laden en de Google GenAI-client initialiseren. Het script gebruikt dotenv om omgevingsvariabelen uit het .env-bestand te laden.

Zo stel je de client in met de benodigde inloggegevens:

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

Asynchrone API-aanroepen doen

Bij het werken met API’s zoals Google GenAI moeten we vaak asynchrone operaties beheren. Asynchroon programmeren laat andere bewerkingen doorgaan terwijl je op netwerkverzoeken wacht, waardoor je applicatie responsiever wordt. Dit is vooral belangrijk bij operaties met hoge latency, zoals netwerkverkeer.

In Python wordt asynchroon programmeren mogelijk gemaakt met de asyncio-bibliotheek en de async/await-syntaxis.

Zo doen we een asynchroon verzoek naar 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())

Deze versie maakt verbinding met het AI-model en stuurt één “Hello”-bericht. Het antwoord wordt woord voor woord in de console geprint.

Interactief maken

Om de applicatie interactief te maken, zodat je heen en weer kunt chatten met het AI-model, voegen we een lus toe waarmee je meerdere berichten kunt sturen. De lus gaat door totdat je "exit" typt.

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

En dat is het! Met het bovenstaande script hebben we een AI-chatbot voor de command line gemaakt met de Google GenAI API. Zo ziet het eruit:

Stap 4: Voeg audiomodus toe

Met audiomodus kan het model met stem reageren in plaats van tekst. Om het vorige voorbeeld aan te passen voor audio-antwoorden, doen we het volgende:

1. Importeer sounddevice voor audio-weergave en numpy om audiogegevens te verwerken.
2. Verander de response modality van TEXT naar AUDIO:

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

3. Initialiseer een audiostream voordat je verbinding maakt met de client:

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

4. Haal de audiogegevens uit het response-onderdeel en voeg ze toe aan de audiostream voor weergave:

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)

Het bestand audio.py in de repository bevat het volledige script met deze aanpassingen. In het script staan opmerkingen bij de regels die veranderd zijn.

Stap 5: Voeg code-executie toe met tools

Een van de sterke punten van moderne AI-modellen is dat ze autonoom aangepaste functies in onze code kunnen aanroepen, en Gemini 2 vormt daarop geen uitzondering.

Dit werkt zo: we vertellen het model welke functies kunnen worden aangeroepen door ze als tools te registreren. Vervolgens beslist het model, op basis van de prompt, functienamen en beschrijvingen, of het een functie wil aanroepen. Als het dat doet, stuurt het een speciaal antwoord met de naam van de functie en de argumenten die het wil gebruiken.

Om een tool te definiëren, moeten we:

1. Een Python-functie schrijven met dezelfde naam en argumenten als in het schema gedefinieerd.
2. Het functieschema maken, een dictionary met metadata over de functie, zoals de naam, een tekstuele beschrijving en een specificatie van de argumenten.
3. Het functieschema aan het AI-model aanbieden.
4. De functie uitvoeren wanneer het model erom vraagt.

Ter illustratie definiëren we een tool die een bestand kan lezen, zodat het model vragen kan beantwoorden over bestanden op onze lokale machine.

De functie definiëren

Dit deel is gewone Python-code. Het model verwacht dat het antwoord een dictionary is met een ”result”-sleutel als de functie is geslaagd en ”error” anders.

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

Het schema specificeren

Zo definiëren we een schema voor deze functie:

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

We geven vier velden op:

• ”name”: De naam van de functie.
• ”description”: Een tekstuele beschrijving. Het model gebruikt dit om te bepalen of het de functie moet aanroepen.
• ”properties”: Beschrijving van de functie-argumenten.
• ”output”: Beschrijving van de uitvoer van de functie.

Bekijk de officiële documentatie voor meer informatie over functieschema’s.

De functie aan het model aanbieden

Om het model op de hoogte te brengen van onze functie, geven we het functieschema mee in de modelconfiguratie:

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

Het functieaanroepverzoek van het model verwerken

Wanneer het model beslist een functie aan te roepen, voegt het een tool_call toe aan de response. Deze bevat de functienaam en de argumenten. Er kunnen meerdere aanroepverzoeken zijn, dus we moeten erover itereren, de bijbehorende functies aanroepen en het resultaat terugsturen naar het model:

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

De volledige implementatie van dit voorbeeld staat in het bestand tool.py in de repository met het volledige script met deze aanpassingen. De functie- en schema-definities staan in het bestand tool_spec.py.

Webtoegang

Met tools kunnen we het model ook webtoegang geven door de Google-zoektool toe te voegen:

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

Deze tool is ingebouwd, en daarom hoeven we geen functie aan te leveren.

Code-executie

Een andere ingebouwde functie is code-executie. Hiermee kan het model Python-code schrijven en uitvoeren om complexe vragen te beantwoorden, meestal met wiskunde. Als we het bijvoorbeeld vragen de som van de eerste 10 priemgetallen te berekenen, schrijft het eerst Python-code om dit te berekenen, voert die uit en geeft vervolgens het antwoord.

Om de tool te activeren, doen we dit:

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

Hier is een voorbeeld van het gedrag van het model met code-executie:

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

Stap 6: Bouw een visuele assistent

In dit laatste deel verkennen we de visuele capaciteiten van Gemini 2. Het doel is een AI-assistent te maken die de inhoud op ons scherm begrijpt en er vragen over kan beantwoorden. Dit is bijvoorbeeld handig als we het vragen om een fout in onze terminal uit te leggen of informatie te geven over iets dat momenteel op het scherm staat.

In de vorige voorbeelden gebruikten we asynchroon programmeren om verbinding te maken met het AI-model en data heen en weer te sturen terwijl we reacties in realtime verwerkten. Helaas ondersteunt de huidige versie van de SDK nog geen realtime communicatie met afbeeldingen. In plaats daarvan leveren we beelddata via een request-responseworkflow. Let op: dit is geen beperking van Gemini 2.0 zelf—het is alleen zo dat de huidige bèta-API dit nog niet ondersteunt.

Een synchrone aanvraag naar Google GenAI sturen

Laten we beginnen met hoe je een verzoek met beelddata naar de Google GenAI API stuurt. Zo versturen we een synchrone aanvraag:

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)

Het belangrijkste verschil in dit voorbeeld is dat we client.models.generate_content gebruiken om een verzoek naar de API te sturen. Dit is een synchrone aanvraag, wat betekent dat je geen realtime gespreksbeleving krijgt.

Een afbeelding versturen

We kunnen een afbeelding versturen door die te laden en toe te voegen aan de contents-lijst. We gebruiken het PIL-pakket om een functie load_and_resize_image() te maken die de afbeelding laadt en schaalt.

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)

De visuele AI-assistent maken

De visuele AI-assistent verwerkt een tekstuele prompt samen met een screenshot om ons te helpen vragen te beantwoorden over wat er op het scherm staat. Ik heb hier uitgebreid mee geëxperimenteerd en het model begrijpt de scherminhoud ook wanneer meerdere vensters openstaan.

De eenvoudigste manier om het model scherminhoud te geven is door een screenshot te maken. Hiervoor gebruiken we het pakket pyautogui, een cross-platform bibliotheek om muis en toetsenbord programmatisch te bedienen voor automatisering. In ons geval gebruiken we het alleen om screenshots te maken, al zouden we de functionaliteit kunnen uitbreiden zodat de AI zelfstandig taken op onze computer uitvoert.

Hier is een functie om een screenshot te maken:

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

Om het interactief te maken herhalen we het volgende totdat de gebruiker de applicatie afsluit:

1. Vraag de gebruiker om een prompt in te voeren.
2. Maak een screenshot en stuur het samen met de prompt naar het AI-model.
3. Toon het resultaat aan de gebruiker.

Bij deze aanpak is er één ding om rekening mee te houden. De applicatie draait in de terminal, die ook op het scherm te zien is. Daarom is het beter om het model te instrueren het terminalvenster te negeren. Dit kan door een system_instruction toe te voegen aan de configuratie:

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

Alles bij elkaar is dit onze visuele AI-assistent. Het bestand met de volledige code is ook beschikbaar als vision.py in de repository.

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

De huidige versie is wat omslachtig, omdat de terminal bovenaan het huidige venster moet staan om hem te kunnen activeren. Een logische volgende stap is hem op de achtergrond te laten draaien en spraak in- en uitvoer te gebruiken in plaats van tekst.

Conclusie

We hebben geleerd hoe je het Gemini 2.0 Flash-model gebruikt voor verschillende toepassingen, zoals chatbots die in realtime met tekst en stem kunnen communiceren, het AI-model acties laten uitvoeren via functieaanroepen en een visuele assistent die de inhoud van ons computerscherm kan analyseren.

Als je verder wilt verkennen, biedt Google twee voorbeelden die laten zien hoe het model objecten in een afbeelding kan detecteren door hun begrenzingsvakken met labels te geven. Dit voorbeeld richt zich op 2D-ruimtelijk begrip door het model te vragen cupcakes in een foto te identificeren en te labelen. Gemini kan ook de 3D-context van een afbeelding begrijpen, zoals hier wordt getoond.

Al met al is Gemini 2.0 veelbelovend, ook al laat de huidige API-versie ons het nog niet op volle kracht gebruiken. Ik kan niet wachten om in de nabije toekomst de multimodale realtime-mogelijkheden volledig te benutten.