Anleitung für Funktionsaufrufe

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

Mit Funktionsaufrufen können Sie einfacher strukturierte Datenausgaben aus generativen Modellen erhalten. Sie können diese Ausgaben dann verwenden, um andere APIs aufzurufen und die relevanten Antwortdaten an das Modell zurückzugeben. Mithilfe von Funktionsaufrufen können Sie also generative Modelle mit externen Systemen verbinden, damit die generierten Inhalte die neuesten und genauesten Informationen enthalten.

Sie können Gemini-Modellen Funktionsbeschreibungen zur Verfügung stellen. Das sind Funktionen, die Sie in der Sprache Ihrer App schreiben. Es handelt sich also nicht um Google Cloud Functions. Das Modell fordert Sie möglicherweise auf, eine Funktion aufzurufen und das Ergebnis zurückzugeben, damit das Modell Ihre Anfrage verarbeiten kann.

Weitere Informationen finden Sie unter Einführung in Funktionsaufrufe.

Beispiel-API für die Beleuchtungssteuerung

Angenommen, Sie haben ein einfaches Beleuchtungssystem mit einer API (Application Programming Interface) und möchten Nutzern ermöglichen, die Beleuchtung über einfache Textanfragen zu steuern. Mit der Funktion „Funktionsaufruf“ können Sie Anfragen von Nutzern zur Beleuchtungsänderung interpretieren und in API-Aufrufe umwandeln, um die Beleuchtungswerte festzulegen. 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önnen, um die Beleuchtungsstärke mit der Tageslicht-Farbtemperatur auf 50 % zu ändern:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

In dieser Anleitung zeigen wir Ihnen, wie Sie einen Funktionsaufruf für die Gemini API einrichten, um die Beleuchtungsanfragen von Nutzern zu interpretieren und ihnen API-Einstellungen zuzuordnen, um die Helligkeit und Farbtemperatur eines Leuchtmittels zu steuern.

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 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:

func setLightValues(brightness int, colorTemp string) map[string]any {
    // This mock API returns the requested lighting values
    return map[string]any{
        "brightness":       brightness,
        "colorTemperature": colorTemp}
}

Funktionsdeklaration 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. Anhand dieser Informationen bestimmt das generative Modell, welche Funktion ausgewählt werden soll und wie Werte für die Parameter im Funktionsaufruf angegeben werden. Im folgenden Code wird gezeigt, wie die Funktion zur Beleuchtungssteuerung deklariert wird:

lightControlTool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{{
        Name:        "controlLight",
        Description: "Set the brightness and color temperature of a room light.",
        Parameters: &genai.Schema{
            Type: genai.TypeObject,
            Properties: map[string]*genai.Schema{
                "brightness": {
                    Type:        genai.TypeString,
                    Description: "Light level from 0 to 100. Zero is off and"+
                        " 100 is full brightness.",
                },
                "colorTemperature": {
                    Type:        genai.TypeString,
                    Description: "Color temperature of the light fixture which" +
                        " can be `daylight`, `cool` or `warm`.",
                },
            },
            Required: []string{"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:

// ...

lightControlTool := &genai.Tool{
    // ...
}

// Use a model that supports function calling, like a Gemini 1.5 model
model := client.GenerativeModel("gemini-2.0-flash")

// Specify the function declaration.
model.Tools = []*genai.Tool{lightControlTool}

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.

// Start new chat session.
session := model.StartChat()

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

// Send the message to the generative model.
resp, err := session.SendMessage(ctx, genai.Text(prompt))
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Check that you got the expected function call back.
part := resp.Candidates[0].Content.Parts[0]
funcall, ok := part.(genai.FunctionCall)
if !ok {
    log.Fatalf("Expected type FunctionCall, got %T", part)
}
if g, e := funcall.Name, lightControlTool.FunctionDeclarations[0].Name; g != e {
    log.Fatalf("Expected FunctionCall.Name %q, got %q", e, g)
}
fmt.Printf("Received function call response:\n%q\n\n", part)

apiResult := map[string]any{
    "brightness":  "30",
    "colorTemperature":  "warm" }

// Send the hypothetical API result back to the generative model.
fmt.Printf("Sending API result:\n%q\n\n", apiResult)
resp, err = session.SendMessage(ctx, genai.FunctionResponse{
    Name:     lightControlTool.FunctionDeclarations[0].Name,
    Response: apiResult,
})
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Show the model's response, which is expected to be text.
for _, part := range resp.Candidates[0].Content.Parts {
    fmt.Printf("%v\n", part)
}

Zusätzliche Optionen

Modus für Funktionsaufrufe

Mit dem Parameter mode für den Funktionsaufruf können Sie das Ausführungsverhalten des Features ändern. Es stehen drei Modi zur Verfügung:

• AUTO: Das Standardverhalten des Modells. Das Modell entscheidet, ob ein Funktionsaufruf oder eine Antwort in natürlicher Sprache vorhergesagt werden soll.
• ANY: Das Modell ist darauf beschränkt, immer einen Funktionsaufruf vorherzusagen. Wenn allowed_function_names nicht angegeben ist, wählt das Modell eine der verfügbaren Funktionsdeklarationen aus. Wenn allowed_function_names angegeben wird, wählt das Modell eine der zulässigen Funktionen aus.
• NONE: Das Modell sagt keinen Funktionsaufruf voraus. In diesem Fall verhält sich das Modell so, als würden Sie keine Funktionsdeklarationen übergeben.

Sie können auch eine Reihe von allowed_function_names übergeben, die die Funktionen einschränken, die vom Modell aufgerufen werden. Sie sollten allowed_function_names nur angeben, wenn der Modus ANY ist. Funktionsnamen müssen mit den Namen der Funktionsdeklarationen übereinstimmen. Wenn der Modus auf ANY und allowed_function_names festgelegt ist, prognostiziert das Modell einen Funktionsaufruf aus den angegebenen Funktionsnamen.

Sie können den Funktionsaufrufmodus angeben, indem Sie beim Initialisieren des generativen Modells einen ToolConfig-Parameter festlegen.

// ...

// Setting a function calling mode is only available in Gemini 1.5 Pro.
model := client.GenerativeModel("gemini-1.5-pro-latest")

model.Tools = []*genai.Tool{lightControlTool}

model.ToolConfig = &genai.ToolConfig{
    FunctionCallingConfig: &genai.FunctionCallingConfig{
        // Possible values: FunctionCallingAuto, FunctionCallingAny, FunctionCallingNone.
        // Only call functions; model won't generate text.
        Mode: genai.FunctionCallingAny,
        // This must only be set when the Mode is FunctionCallingAny.
        AllowedFunctionNames: []string{"exchangeRate"},
    },
}

Der Funktionsaufrufmodus kann direkt nach dem Festlegen der ToolConfig des Modells aktualisiert werden.

// Required a text response, model won't generate function calls.
model.ToolConfig.FunctionCallingConfig.Mode = genai.FunctionCallingNone
// Must not be set, unless Mode is FunctionCallingAny.
model.ToolConfig.FunctionCallingConfig.AllowedFunctionNames = nil