Anleitung für Funktionsaufrufe

Mithilfe von Funktionsaufrufen können Sie einfacher strukturierte Datenausgaben aus generativen Modellen abrufen. Sie können diese Ausgaben dann verwenden, um andere APIs aufzurufen und die relevanten Antwortdaten an das Modell zu senden. Mit anderen Worten, Funktionsaufrufe helfen generative Modelle mit externen Systemen verbinden, damit die generierten Inhalte aktuelle und korrekte Informationen enthält.

Sie können Gemini-Modellen Beschreibungen von Funktionen 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 bearbeiten 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

Stellen Sie sich vor, Sie hätten eine einfache Lichtsteuerung mit einer Anwendungsprogrammierung. und es den Nutzern ermöglichen möchten, die Beleuchtung über Textanfragen. Mit der Funktion „Funktionsaufruf“ können Sie die Beleuchtung interpretieren und in API-Aufrufe umsetzen, um die Lichtverhältnisse Werte. Mit diesem hypothetischen Beleuchtungssystem können Sie die Helligkeit des Lichts und seine Farbtemperatur steuern, die als zwei separate Parameter definiert sind:

Parameter Typ Erforderlich Beschreibung
brightness Zahl Ja Lichtpegel zwischen 0 und 100. „0“ steht für „Aus“ und „100“ für die volle Helligkeit.
colorTemperature String Ja Die Farbtemperatur der Leuchte. Kann daylight, cool oder warm sein.

Der Einfachheit halber hat dieses fiktive 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 erfahren Sie, wie Sie einen Funktionsaufruf für die Gemini API einrichten, um Beleuchtungsanfragen der Nutzer interpretieren und API-Einstellungen zuordnen, um ein die Helligkeits- und Farbtemperaturwerte.

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 definiert werden, innerhalb des Codes Ihrer Anwendung, könnte aber auch Dienste oder APIs außerhalb von Ihre Anwendung. 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, 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 vom Modell in einem Funktionsaufruf verwendet werden soll, sollten Sie die Funktions- und Parameterbeschreibungen so detailliert wie möglich gestalten. Das generative Modell bestimmt anhand dieser Informationen, auszuwählende Funktion und wie Werte für die Parameter in der Funktion bereitgestellt werden anrufen.

Funktionen während der Modellinitialisierung deklarieren

Wenn Sie Funktionsaufrufe mit einem Modell verwenden möchten, müssen Sie Ihre Funktionen deklarieren, wenn Sie das Modellobjekt initialisieren. Sie deklarieren Funktionen, indem Sie Parameter tools des Modells verwenden:

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

Funktionsaufruf generieren

Nachdem Sie das Modell mit Ihren Funktionsdeklarationen initialisiert haben, können Sie es mit der definierten Funktion auffordern. Sie sollten Funktionsaufrufe mit Chat-Prompts (sendMessage()), da Funktionsaufrufe im Allgemeinen im Kontext früherer Prompts und Antworten.

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

Das ChatSession-Objekt des Python SDK vereinfacht die Verwaltung von Chatsitzungen, da es den Unterhaltungsverlauf für Sie übernimmt. Du kannst enable_automatic_function_calling verwenden, um das SDK zu erhalten wird die Funktion automatisch aufgerufen.

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

Paralleler Funktionsaufruf

Zusätzlich zu den oben beschriebenen grundlegenden Funktionsaufrufen können Sie auch mehrere Funktionen in einer einzigen Runde 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 das Modell jetzt mit einer Anweisung auf, die alle angegebenen Tools verwenden kann.

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

# 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 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 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 _tools-Attribut des Modells an. Dort sehen Sie, wie die Funktionen beschrieben werden, 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. Wenn Ihnen das gedruckte Format nicht bekannt 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.

Hier ist eine Deklaration für dieselbe Multiplikationsfunktion, geschrieben unter Verwendung des genai.protos Klassen. Beachten Sie, dass diese Klassen nur die Funktion für der API ist keine Implementierung enthalten. Es funktioniert also nicht, mit automatischen Funktionsaufrufen. Funktionen benötigen jedoch nicht immer Implementierung.

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 eine genai.protos.FunctionCall zurückgibt, die 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}))]))