Anleitung für Funktionsaufrufe

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

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.

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:

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.

enum APIKey {
  // Fetch the API key from `GenerativeAI-Info.plist`
  static var `default`: String {
    guard let filePath = Bundle.main.path(forResource: "GenerativeAI-Info", ofType: "plist")
    else {
      fatalError("Couldn't find file 'GenerativeAI-Info.plist'.")
    }
    let plist = NSDictionary(contentsOfFile: filePath)
    guard let value = plist?.object(forKey: "API_KEY") as? String else {
      fatalError("Couldn't find key 'API_KEY' in 'GenerativeAI-Info.plist'.")
    }
    if value.starts(with: "_") {
      fatalError(
        "Follow the instructions at https://ai.google.dev/tutorials/setup to get an API key."
      )
    }
    return value
  }
}

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:

func setLightValues(brightness: String,
                    colorTemp: String) -> JSONObject {
  // This mock API returns the requested lighting values
  return [
    "brightness": .string(brightness),
    "colorTemperature": .string(colorTemp)
  ]
}

Funktionsdeklarationen erstellen

Erstellen Sie die Funktionsdeklaration, die Sie an das generative Modell übergeben. Wenn Sie eine Funktion zur Verwendung durch das Modell deklarieren, sollten Sie in den Funktions- und Parameterbeschreibungen so viele Details wie möglich angeben. Das generative Modell verwendet diese Informationen, um zu bestimmen, welche Funktion ausgewählt werden soll und wie Werte für die Parameter im Funktionsaufruf bereitgestellt werden. Der folgende Code zeigt, wie die Funktion für die Beleuchtungssteuerung deklariert wird:

let controlLightFunctionDeclaration = FunctionDeclaration(
  name: "controlLight",
  description: "Set the brightness and color temperature of a room light.",
  parameters: [
    "brightness": Schema(
      type: .string,
      description: "Light level from 0 to 100. Zero is off and 100 is full brightness."
    ),
    "colorTemperature": Schema(
      type: .string,
      description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`."
    ),
  ],
  requiredParameters: ["brightness", "colorTemperature"]
)

Funktionen während der Modellinitialisierung deklarieren

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

// Use a model that supports function calling, like a Gemini 1.5 model
let generativeModel = GenerativeModel(
  name: "gemini-1.5-flash",
  apiKey: apiKey,
  // Specify the function declaration.
  tools: [Tool(functionDeclarations: [controlLightFunctionDeclaration])]
)

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.

let chat = generativeModel.startChat()

let prompt = "Dim the lights so the room feels cozy and warm."

// Send the message to the generative model
let response1 = try await chat.sendMessage(prompt)

// Check if the model responded with a function call
guard let functionCall = response1.functionCalls.first else {
  fatalError("Model did not respond with a function call.")
}
// Print an error if the returned function was not declared
guard functionCall.name == "controlLight" else {
  fatalError("Unexpected function called: \(functionCall.name)")
}
// Verify that the names and types of the parameters match the declaration
guard case let .string(brightness) = functionCall.args["brightness"] else {
  fatalError("Missing argument: brightness")
}
guard case let .string(colorTemp) = functionCall.args["colorTemperature"] else {
  fatalError("Missing argument: colorTemperature")
}

// Call the hypothetical API
let apiResponse = setLightValues(brightness: brightness, colorTemperature: colorTemp)

// Send the API response back to the model so it can generate a text response that can be
// displayed to the user.
let response = try await chat.sendMessage([ModelContent(
  role: "function",
  parts: [.functionResponse(FunctionResponse(
    name: functionCall.name,
    response: apiResponse
  ))]
)])

// Log the text response.
guard let modelResponse = response.text else {
  fatalError("Model did not respond with text.")
}
print(modelResponse)