Anleitung für Funktionsaufrufe

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

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.

Maximieren, um zu sehen, wie Sie Ihr Projekt und den API-Schlüssel einrichten

API-Schlüssel abrufen und sichern

Sie benötigen einen API-Schlüssel, um die Gemini API aufzurufen. Wenn Sie noch keinen haben, erstellen Sie einen Schlüssel in Google AI Studio.

API-Schlüssel anfordern

Wir empfehlen dringend, einen API-Schlüssel nicht in Ihr Versionsverwaltungssystem einzuchecken.

Sie sollten Ihren API-Schlüssel in einem Secrets-Speicher wie Secret Manager von Google Cloud speichern.

In dieser Anleitung wird davon ausgegangen, dass Sie auf Ihren API-Schlüssel als Umgebungsvariable zugreifen.

SDK-Paket importieren und API-Schlüssel konfigurieren

Gehen Sie in Ihrer Anwendung so vor:

1. get das Go SDK-Paket in Ihrem Modulverzeichnis:

   go get github.com/google/generative-ai-go
   

2. Importieren Sie das Paket und konfigurieren Sie den Dienst mit Ihrem API-Schlüssel:

   import (
     // import standard libraries
     // Import the GenerativeAI package for Go
     "github.com/google/generative-ai-go/genai"
     "google.golang.org/api/option"
   )
   
   ctx := context.Background()
   // Access your API key as an environment variable
   client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
   if err != nil {
     log.Fatal(err)
   }
   defer client.Close()
   
   // ...
   

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:

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 sollen. Der folgende Code zeigt, wie Sie die Funktion zur Steuerung der Beleuchtung deklarieren:

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 Ihren Funktionsdeklarationen beim Initialisieren des Modellobjekts. Sie deklarieren Funktionen 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-1.5-flash")

// Specify the function declaration.
model.Tools = []*genai.Tool{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()) 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)
}