Anleitung für Funktionsaufrufe

Funktionsaufrufe erleichtern Ihnen, Ausgaben für strukturierte Daten generativen Modellen. 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 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. Dies sind Funktionen, die Sie in der Sprache Ihrer App schreiben (d. h. sie sind 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 von 0 bis 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 imaginäre Beleuchtungssystem nur eine Leuchte, sodass die Nutzenden muss kein Raum oder Standort angeben. Hier ist ein Beispiel für eine JSON-Anfrage, können Sie an die Lighting Control API senden, um die Helligkeit auf 50 % zu ändern. mithilfe der Tageslicht-Farbtemperatur:

{
  "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.

Hinweis: 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, 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. 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 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()) verwenden, da Funktionsaufrufe im Allgemeinen vom Kontext früherer Prompts und Antworten profitieren.

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. Sie können den enable_automatic_function_calling verwenden, damit das SDK die Funktion automatisch aufruft.

# 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. In diesem Abschnitt wird ein Beispiel für die Verwendung paralleler Funktionsaufrufe gezeigt.

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 entspricht einem einzelnen Funktionsaufruf, der vom Modell angefordert wurde. 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 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 wir uns 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"
   }
 }]

Dies gibt die Liste der genai.protos.Tool-Objekte zurück, die an die der API erstellen. Wenn das gedruckte Format nicht vertraut ist, protobuf-Klassen. Jedes genai.protos.Tool (in diesem Fall 1) enthält eine Liste von genai.protos.FunctionDeclarations, die eine Funktion und ihre Argumente beschreiben.

Hier ist eine Deklaration für dieselbe Multiplikationsfunktion, die mit den genai.protos-Klassen geschrieben wurde. 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 beiden Fällen übergeben Sie eine Darstellung eines genai.protos.Tool oder eine 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
]

Funktion selbst ausführen:

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}))]))