Anleitung für Funktionsaufrufe

<ph type="x-smartling-placeholder"></ph> Python Node.js Los Dart (Flutter) Android Swift Web

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 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. 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, damit das Modell Ihre Abfrage verarbeiten kann.

Falls Sie dies noch nicht getan haben, sollten Sie sich die Einführung in Funktionsaufrufe mehr.

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 umwandeln, um die Lichtverhältnisse Werte. Mit diesem hypothetischen Lichtsteuerungssystem kannst du Helligkeit des Lichts und seine Farbtemperatur, definiert als zwei separate Parameter:

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, müssen Sie Ihr Projekt einrichten und konfigurieren Ihren API-Schlüssel.

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 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 müssen also kann steuern, wie und wann diese Funktion über Ihre Anwendung ausgeführt wird Code. Zu Demonstrationszwecken wird in dieser Anleitung eine API-Beispielfunktion definiert, die gibt nur die angeforderten Beleuchtungswerte zurück:

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. Wann? eine Funktion zur Verwendung durch das Modell deklarieren, sollten Sie so viele Details wie möglich in den Funktions- und Parameterbeschreibungen. Das generative Modell bestimmt anhand dieser Informationen, welche Funktion ausgewählt und wie für die Parameter im Funktionsaufruf. Der folgende Code zeigt, wie Sie die Funktion zur Steuerung der Beleuchtung deklarieren:

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 Ihren Funktionsdeklarationen beim Initialisieren des Modellobjekts. 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. Sie sollten Funktionsaufrufe mit Chat-Prompts (sendMessage()), da Funktionsaufrufe im Allgemeinen im Kontext früherer Prompts und Antworten.

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)