Anleitung für Funktionsaufrufe

Funktionsaufrufe erleichtern es Ihnen, Ausgaben strukturierter Daten aus generativen Modellen zu erhalten. Sie können diese Ausgaben dann verwenden, um andere APIs aufzurufen und die relevanten Antwortdaten an das Modell zurückzugeben. Mit anderen Worten: Funktionsaufrufe helfen Ihnen, generative Modelle mit externen Systemen zu verbinden, damit die generierten Inhalte aktuelle und genaue Informationen enthalten.

Sie können Gemini-Modellen Beschreibungen von Funktionen zur Verfügung stellen. Dies sind Funktionen, die Sie in der Sprache Ihrer Anwendung schreiben (d. h. es sind keine Google Cloud Functions-Funktionen). Das Modell kann Sie auffordern, eine Funktion aufzurufen und das Ergebnis zurückzugeben, damit das Modell Ihre Abfrage 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 Beleuchtungssteuersystem mit einer Application Programming Interface (API) und möchten es Nutzern ermöglichen, die Beleuchtung über einfache Textanfragen zu steuern. Mit der Funktion für Funktionsaufrufe können Sie Anfragen zur Beleuchtungsänderung von Nutzern interpretieren und in API-Aufrufe umwandeln, um die Beleuchtungswerte festzulegen. Mit diesem hypothetischen Steuersystem für die Beleuchtung können Sie die Helligkeit des Lichts und seine Farbtemperatur steuern, die als zwei separate Parameter definiert werden:

Parameter Typ Erforderlich Beschreibung
brightness number Ja Lichtpegel von 0 bis 100. Null ist deaktiviert und 100 entspricht voller Helligkeit.
colorTemperature String Ja Die Farbtemperatur der Leuchte. Kann daylight, cool oder warm sein.

Der Einfachheit halber hat dieses imaginäre Beleuchtungssystem nur ein Licht, sodass der Nutzer keinen Raum oder Standort angeben muss. Hier ist ein Beispiel für eine JSON-Anfrage, die Sie an die Lighting Control API senden können, um den Helligkeitsgrad mithilfe der Tageslicht-Farbtemperatur auf 50 % zu ändern:

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

In dieser Anleitung erfahren Sie, wie Sie einen Funktionsaufruf für die Gemini API einrichten, um Beleuchtungsanfragen von Nutzern zu interpretieren und sie API-Einstellungen zuzuordnen, um die Helligkeits- und Farbtemperaturwerte einer Lampe zu steuern.

Hinweis: Projekt und API-Schlüssel einrichten

Bevor Sie die Gemini API aufrufen, 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 sein, könnte aber auch Dienste oder APIs außerhalb der Anwendung aufrufen. Die Gemini API ruft diese Funktion nicht direkt auf. Sie können also steuern, wie und wann diese Funktion über Ihren Anwendungscode ausgeführt wird. Zu Demonstrationszwecken wird in dieser Anleitung eine API-Beispielfunktion definiert, die nur die angeforderten Beleuchtungswerte zurückgibt:

def set_light_values(brightness, color_temp):
    """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 in einem Funktionsaufruf vom Modell verwendet werden soll, sollten Sie in den Funktions- und Parameterbeschreibungen so viele Details wie möglich angeben. Das generative Modell bestimmt anhand dieser Informationen, welche Funktion ausgewählt werden soll und wie Werte für die Parameter im Funktionsaufruf bereitgestellt werden.

Funktionen während der Modellinitialisierung deklarieren

Wenn Sie Funktionsaufrufe mit einem Modell verwenden möchten, müssen Sie Ihre Funktionen beim Initialisieren des Modellobjekts deklarieren. Sie deklarieren Funktionen, indem Sie den Parameter tools des Modells festlegen:

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                              tools=[set_light_values])

Funktionsaufruf generieren

Sobald Sie das Modell mit Ihren Funktionsdeklarationen initialisiert haben, können Sie das Modell mit der definierten Funktion aufrufen. Sie sollten Funktionsaufrufe mit Chat-Prompts (sendMessage()) verwenden, da Funktionsaufrufe im Allgemeinen davon profitieren, den Kontext früherer Prompts und Antworten zu haben.

chat = model.start_chat()
response = chat.send_message('Dim the lights so the room feels cozy and warm.')
response.text

Das Objekt ChatSession des Python SDK vereinfacht die Verwaltung von Chatsitzungen, da es den Unterhaltungsverlauf für Sie verarbeitet. Sie können enable_automatic_function_calling verwenden, damit das SDK automatisch

# Create a chat session that automatically makes suggested function calls
chat = model.start_chat(enable_automatic_function_calling=True)

Parallele Funktionsaufrufe

Zusätzlich zu den oben beschriebenen grundlegenden Funktionsaufrufen können Sie auch mehrere Funktionen in einem einzigen Vorgang aufrufen. Dieser Abschnitt zeigt ein Beispiel für die Verwendung paralleler Funktionsaufrufe.

Definieren Sie die Tools.

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, bpm: int) -> 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.
      bpm: The beats per minute of the music.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}, {bpm=}")
    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 nun das Modell mit einer Anweisung auf, die alle angegebenen Tools verwenden könnte.

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

model = genai.GenerativeModel(model_name="gemini-1.5-flash", tools=house_fns)

# Call the API.
chat = model.start_chat()
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call.
for part in response.parts:
    if fn := part.function_call:
        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, bpm=120.0)
dim_lights(brightness=0.3)

Jedes der gedruckten Ergebnisse steht für einen einzelnen Funktionsaufruf, den das Modell angefordert hat. Um die Ergebnisse zurückzusenden, geben Sie die Antworten in der angeforderten Reihenfolge ein.

# Simulate the responses from the specified tools.
responses = {
    "power_disco_ball": True,
    "start_music": "Never gonna give you up.",
    "dim_lights": True,
}

# Build the response parts.
response_parts = [
    genai.protos.Part(function_response=genai.protos.FunctionResponse(name=fn, response={"result": val}))
    for fn, val in responses.items()
]

response = chat.send_message(response_parts)
print(response.text)

Let's get this party started! I've turned on the disco ball, started playing some upbeat music, and dimmed the lights. 🎶✨  Get ready to dance! 🕺💃

Datentypzuordnung des Funktionsaufrufs

Die automatische Extraktion des Schemas aus Python-Funktionen funktioniert nicht in allen Fällen. Beispielsweise können keine Fälle verarbeitet werden, in denen die Felder eines verschachtelten Wörterbuchobjekts beschrieben werden, aber die API unterstützt dies. Die API kann folgende Typen beschreiben:

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

Die Clientbibliothek google.ai.generativelanguage bietet Zugriff auf Low-Level-Typen, mit denen Sie die volle Kontrolle haben.

Sehen Sie sich zuerst das Attribut _tools des Modells an, um zu sehen, wie es die Funktionen beschreibt, die Sie an das Modell übergeben haben:

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

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                             tools=[multiply])

model._tools.to_proto()

[function_declarations {
   name: "multiply"
   description: "returns a * b."
   parameters {
     type_: OBJECT
     properties {
       key: "b"
       value {
         type_: NUMBER
       }
     }
     properties {
       key: "a"
       value {
         type_: NUMBER
       }
     }
     required: "a"
     required: "b"
   }
 }]

Dadurch wird die Liste der genai.protos.Tool-Objekte zurückgegeben, die an die API gesendet werden würden. Wenn das gedruckte Format nicht vertraut ist, liegt das daran, dass es sich um Google-protobuf-Klassen handelt. Jede genai.protos.Tool (in diesem Fall 1) enthält eine Liste von genai.protos.FunctionDeclarations, die eine Funktion und ihre Argumente beschreibt.

Hier ist eine Deklaration für dieselbe Multiplikationsfunktion, die mit den Klassen genai.protos geschrieben wurde. Diese Klassen beschreiben nur die Funktion für die API. Sie enthalten keine Implementierung dieser Funktion. Diese Funktion funktioniert also nicht bei automatischen Funktionsaufrufen. Funktionen müssen jedoch nicht immer implementiert werden.

calculator = genai.protos.Tool(
    function_declarations=[
      genai.protos.FunctionDeclaration(
        name='multiply',
        description="Returns the product of two numbers.",
        parameters=genai.protos.Schema(
            type=genai.protos.Type.OBJECT,
            properties={
                'a':genai.protos.Schema(type=genai.protos.Type.NUMBER),
                'b':genai.protos.Schema(type=genai.protos.Type.NUMBER)
            },
            required=['a','b']
        )
      )
    ])

Entsprechend können Sie dies als JSON-kompatibles Objekt beschreiben:

calculator = {'function_declarations': [
      {'name': 'multiply',
       'description': 'Returns the product of two numbers.',
       'parameters': {'type_': 'OBJECT',
       'properties': {
         'a': {'type_': 'NUMBER'},
         'b': {'type_': 'NUMBER'} },
       'required': ['a', 'b']} }]}

genai.protos.Tool(calculator)

function_declarations {
  name: "multiply"
  description: "Returns the product of two numbers."
  parameters {
    type_: OBJECT
    properties {
      key: "b"
      value {
        type_: NUMBER
      }
    }
    properties {
      key: "a"
      value {
        type_: NUMBER
      }
    }
    required: "a"
    required: "b"
  }
}

In jedem Fall übergeben Sie eine Darstellung einer genai.protos.Tool oder einer Liste von Tools an

model = genai.GenerativeModel('gemini-1.5-flash', tools=calculator)
chat = model.start_chat()

response = chat.send_message(
    f"What's 234551 X 325552 ?",
)

Wie bevor das Modell einen genai.protos.FunctionCall zurückgibt, der die multiply-Funktion des Rechners aufruft:

response.candidates

[index: 0
content {
  parts {
    function_call {
      name: "multiply"
      args {
        fields {
          key: "b"
          value {
            number_value: 325552
          }
        }
        fields {
          key: "a"
          value {
            number_value: 234551
          }
        }
      }
    }
  }
  role: "model"
}
finish_reason: STOP
]

Führen Sie die Funktion selbst aus:

fc = response.candidates[0].content.parts[0].function_call
assert fc.name == 'multiply'

result = fc.args['a'] * fc.args['b']
result

76358547152.0

Senden Sie das Ergebnis an das Modell, um die Unterhaltung fortzusetzen:

response = chat.send_message(
    genai.protos.Content(
    parts=[genai.protos.Part(
        function_response = genai.protos.FunctionResponse(
          name='multiply',
          response={'result': result}))]))