Anleitung für Funktionsaufrufe

Python Node.js Go Dart (Flutter) Android Swift Web REST

Mit Funktionsaufrufen können Sie einfacher strukturierte Datenausgaben aus generativen Modellen erhalten. Sie können diese Ausgaben dann verwenden, um andere APIs aufzurufen und die relevanten Antwortdaten an das Modell zurückzugeben. Mithilfe von Funktionsaufrufen können Sie also generative Modelle mit externen Systemen verbinden, damit die generierten Inhalte die aktuellsten und genauesten Informationen enthalten.

Sie können Gemini-Modellen Funktionsbeschreibungen zur Verfügung stellen. Das sind Funktionen, die Sie in der Sprache Ihrer App schreiben (d. h. keine Google Cloud Functions). Das Modell fordert Sie möglicherweise auf, eine Funktion aufzurufen und das Ergebnis zurückzugeben, damit das Modell Ihre Anfrage verarbeiten kann.

Weitere Informationen finden Sie unter Einführung in Funktionsaufrufe. Sie können diese Funktion auch in Google Colab ausprobieren oder sich den Beispielcode im Repository Gemini API Cookbook ansehen.

Beispiel-API für die Beleuchtungssteuerung

Angenommen, Sie haben ein einfaches Beleuchtungssystem mit einer API (Application Programming Interface) und möchten Nutzern ermöglichen, die Beleuchtung über einfache Textanfragen zu steuern. Mit der Funktion „Funktionsaufruf“ können Sie Anfragen von Nutzern zur Beleuchtungsänderung interpretieren und in API-Aufrufe umwandeln, um die Beleuchtungswerte festzulegen. Mit diesem hypothetischen Beleuchtungssystem können Sie die Helligkeit des Lichts und seine Farbtemperatur steuern, die als zwei separate Parameter definiert sind:

Der Einfachheit halber hat dieses imaginäre Beleuchtungssystem nur eine Lampe, sodass der Nutzer keinen Raum oder Standort angeben muss. Hier ist eine Beispiel-JSON-Anfrage, die Sie an die API zur Beleuchtungssteuerung senden könnten, um die Beleuchtungsstärke mit der Tageslicht-Farbtemperatur auf 50 % zu ändern:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

In dieser Anleitung zeigen wir Ihnen, wie Sie einen Funktionsaufruf für die Gemini API einrichten, um die Beleuchtungsanfragen von Nutzern zu interpretieren und ihnen API-Einstellungen zuzuordnen, um die Helligkeit und Farbtemperatur eines Leuchtmittels zu steuern.

Bevor Sie beginnen: Projekt und API-Schlüssel einrichten

Bevor Sie die Gemini API aufrufen können, müssen Sie Ihr Projekt einrichten und Ihren API-Schlüssel konfigurieren.

API-Funktion definieren

Erstellen Sie eine Funktion, die eine API-Anfrage stellt. Diese Funktion sollte im Code Ihrer Anwendung definiert werden, kann aber Dienste oder APIs außerhalb Ihrer Anwendung aufrufen. Die Gemini API ruft diese Funktion nicht direkt auf. Sie können also über Ihren Anwendungscode steuern, wie und wann diese Funktion ausgeführt wird. Zu Demonstrationszwecken wird in dieser Anleitung eine Mock-API-Funktion definiert, die nur die angeforderten Beleuchtungswerte zurückgibt:

def set_light_values(brightness: int, color_temp: str) -> dict[str, int | str]:
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {
        "brightness": brightness,
        "colorTemperature": color_temp
    }

Wenn Sie eine Funktion erstellen, die vom Modell in einem Funktionsaufruf verwendet werden soll, sollten Sie die Funktions- und Parameterbeschreibungen so detailliert wie möglich ausarbeiten. Anhand dieser Informationen bestimmt das generative Modell, welche Funktion ausgewählt werden soll und wie Werte für die Parameter im Funktionsaufruf angegeben werden.

Funktionen während der Modellinitialisierung deklarieren

Wenn Sie den Funktionsaufruf verwenden möchten, definieren Sie die Funktionen als Tools in GenerateContentConfig zusammen mit anderen generierungsbezogenen Einstellungen wie Temperatur- oder Stopp-Tokens.

from google.genai import types

config = types.GenerateContentConfig(tools=[set_light_values])

Dies kann auch als Python-Wörterbuch definiert werden.

config = {
    'tools': [set_light_values],
}

Funktionsaufruf generieren

Nachdem Sie die Funktionsdeklarationen definiert haben, können Sie das Modell auffordern, die Funktion zu verwenden. Sie können Inhalte direkt oder über die Chatoberfläche generieren.

from google import genai

client = genai.Client()

# Generate directly with generate_content.
response = client.models.generate_content(
    model='gemini-2.0-flash',
    config=config,
    contents='Turn the lights down to a romantic level'
)
print(response.text)

# Use the chat interface.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Turn the lights down to a romantic level')
print(response.text)

Im Python SDK werden Funktionen automatisch aufgerufen. Wenn Sie jeden Funktionsaufruf verarbeiten oder zwischen den Aufrufen eine andere Logik ausführen möchten, können Sie die Funktion über das Flag in der Generierungskonfiguration deaktivieren.

from google.genai import types

# Use strong types.
config = types.GenerateContentConfig(
    tools=[set_light_values],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

# Use a dictionary.
config = {
    'tools': [set_light_values],
    'automatic_function_calling': {'disable': True},
}

Paralleler Funktionsaufruf

Zusätzlich zu den oben beschriebenen grundlegenden Funktionsaufrufen können Sie auch mehrere Funktionen in einer einzigen Runde aufrufen. In diesem Abschnitt wird ein Beispiel für die Verwendung paralleler Funktionsaufrufe gezeigt.

Tools definieren

def power_disco_ball(power: bool) -> bool:
    """Powers the spinning disco ball."""
    print(f"Disco ball is {'spinning!' if power else 'stopped.'}")
    return True


def start_music(energetic: bool, loud: bool) -> str:
    """Play some music matching the specified parameters.

    Args:
      energetic: Whether the music is energetic or not.
      loud: Whether the music is loud or not.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}")
    return "Never gonna give you up."


def dim_lights(brightness: float) -> bool:
    """Dim the lights.

    Args:
      brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
    """
    print(f"Lights are now set to {brightness:.0%}")
    return True

Rufen Sie das Modell jetzt mit einer Anweisung auf, die alle angegebenen Tools verwenden kann. In diesem Beispiel wird eine tool_config verwendet. Weitere Informationen finden Sie unter Funktionsaufrufe konfigurieren.

# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]

config = {
    # Set the available functions.
    'tools': house_fns,
    # Disable AFC so you can inspect the results first.
    'automatic_function_calling': {'disable': True},
    # Force the model to act (call 'any' function), instead of chatting.
    'tool_config': {
        'function_calling_config': {
            'mode': 'any'
        }
    }
}

# Call the API.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Turn this place into a party!')

# Print out each of the function calls requested from this single call.
for fn in response.function_calls:
  args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
  print(f"{fn.name}({args})")

power_disco_ball(power=True)
start_music(energetic=True, loud=True)
dim_lights(brightness=0.3)

Jedes der gedruckten Ergebnisse entspricht einem einzelnen Funktionsaufruf, der vom Modell angefordert wurde. Wenn Sie die Ergebnisse zurücksenden, geben Sie die Antworten in der Reihenfolge an, in der sie angefordert wurden.

Am einfachsten ist es, automatic_function_calling aktiviert zu lassen, damit das SDK die Funktionsaufrufe und die Antwortweitergabe automatisch verarbeitet.

config = {
    'tools': house_fns,
}

# Call the API.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Do everything you need to this place into party!')

print(response.text)

Disco ball is spinning!
Starting music! energetic=True loud=True
Lights are now set to 50%
Alright, I've turned on the disco ball, started playing "Never gonna give you up.", and dimmed the lights. Let's get this party started!

Datentypzuordnung für Funktionsaufrufe

Die automatische Schemaextraktion aus Python-Funktionen funktioniert nicht in allen Fällen. Beispiel: Es werden keine Fälle verarbeitet, in denen Sie die Felder eines verschachtelten Dictionary-Objekts beschreiben, obwohl die API dies unterstützt. Die API kann jeden der folgenden Typen beschreiben:

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

Wenn Sie sehen möchten, wie das abgeleitete Schema aussieht, können Sie es mit from_callable konvertieren:

from pprint import pprint

def multiply(a: float, b: float):
    """Returns a * b."""
    return a * b

fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)

# to_json_dict() provides a clean JSON representation.
pprint(fn_decl.to_json_dict())

{'description': 'Returns a * b.',
 'name': 'multiply',
 'parameters': {'properties': {'a': {'type': 'NUMBER'},
                               'b': {'type': 'NUMBER'}},
                'type': 'OBJECT'}}

Diese JSON-Felder werden den entsprechenden Feldern im Pydantic-Schema zugeordnet und können als Tool umschlossen werden.

config = types.GenerateContentConfig(
    tools=[types.Tool(function_declarations=[fn_decl])]
)

Hier ist eine Deklaration für dieselbe multiply-Funktion, die mit den genai.types-Klassen geschrieben wurde. Diese Klassen beschreiben nur die Funktion für die API, sie enthalten keine Implementierung. Daher funktioniert dieser Ansatz nicht mit dem automatischen Funktionsaufruf. Sie können damit jedoch Funktionen definieren, die keine konkreten Python-Funktionen sind (z. B. um einen Remote-HTTP-Aufruf einzubinden) und Sie haben mehr Kontrolle über Funktionsaufrufe (z. B. um function_calling_config so zu ändern, dass sie einem Statusgraphen folgen).

tool = types.Tool(function_declarations=[
    types.FunctionDeclaration(
        name="multiply",
        description="Returns a * b.",
        parameters=types.Schema(
            properties={
                'a': types.Schema(type='NUMBER'),
                'b': types.Schema(type='NUMBER'),
            },
            type='OBJECT',
        ),
    )
])
assert tool.function_declarations[0] == fn_decl