Anleitung für Funktionsaufrufe

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

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.

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:

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.

dart pub add google_generative_ai

flutter pub add google_generative_ai

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 API-Beispielfunktion definiert, die gibt nur die angeforderten Beleuchtungswerte zurück:

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

Funktionsdeklarationen erstellen

Erstellen Sie die Funktionsdeklaration, die Sie an das generative Modell übergeben. Wenn Sie eine Funktion für die Verwendung durch das Modell deklarieren, 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 und wie für die Parameter im Funktionsaufruf. Im folgenden Code wird gezeigt, wie die Funktion zur Beleuchtungssteuerung deklariert wird:

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      'brightness',
      'colorTemperature'
    ]));

Funktionen während der Modellinitialisierung deklarieren

Wenn Sie Funktionsaufrufe mit einem Modell verwenden möchten, müssen Sie Ihre Funktionsdeklarationen angeben, wenn Sie das Modellobjekt initialisieren. Funktionen werden deklariert, indem Sie den Parameter tools des Modells festlegen. Das Dart-SDK unterstützt auch Dabei werden die Funktionen als Argumente für generateContent oder generateContentStream APIs

final model = GenerativeModel(
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [lightControlTool])
  ],
);

Funktionsaufruf generieren

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

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'setLightValues' => await setLightValues(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}