Samouczek wywoływania funkcji

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

Wywoływanie funkcji ułatwia uzyskiwanie uporządkowanych danych wyjściowych z modeli generatywnych. Następnie możesz używać tych danych do wywoływania innych interfejsów API i zwracania odpowiednich danych odpowiedzi do modelu. Innymi słowy, wywoływanie funkcji pomaga Ci łączyć modele generatywne z systemami zewnętrznymi, aby generowane treści zawierały jak najbardziej aktualne i dokładne informacje.

Możesz przekazywać modelom Gemini opisy funkcji. Są to funkcje zapisane w języku aplikacji (czyli nie są to funkcje Google Cloud Functions). Model może poprosić o wywołanie funkcji i odesłanie wyniku, aby pomóc w obróbce zapytania.

Jeśli jeszcze tego nie zrobiłeś, zapoznaj się z artykułem Wprowadzenie do wywoływania funkcji, aby dowiedzieć się więcej.

Przykład interfejsu API do sterowania oświetleniem

Wyobraź sobie, że masz podstawowy system sterowania oświetleniem z interfejsem programowania aplikacji (API) i chcesz umożliwić użytkownikom sterowanie światłami za pomocą prostych żądań tekstowych. Za pomocą funkcji wywoływania funkcji możesz interpretować żądania zmiany oświetlenia od użytkowników i przekształcać je w wywołania interfejsu API, aby ustawiać wartości oświetlenia. Ten hipotetyczny system sterowania oświetleniem umożliwia kontrolowanie jasności światła i jego temperatury barwowej, zdefiniowanych jako dwa oddzielne parametry:

W ramach uproszczenia tego wyimaginowanego systemu oświetlenia ma on tylko jedną lampę, więc użytkownik nie musi określać pokoju ani lokalizacji. Oto przykładowy plik JSON, który możesz wysłać do interfejsu Lighting Control API, aby zmienić poziom światła na 50% przy użyciu temperatury barwowej światła dziennego:

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

W tym samouczku pokazujemy, jak skonfigurować wywołanie funkcji dla interfejsu Gemini API, aby interpretować żądania dotyczące oświetlenia użytkowników i mapować je na ustawienia interfejsu API w celu sterowania wartościami jasności i temperatury barwowej światła.

Zanim zaczniesz: skonfiguruj projekt i klucz interfejsu API

Zanim wywołasz interfejs Gemini API, musisz skonfigurować projekt i klucz interfejsu API.

Definiowanie funkcji interfejsu API

Utwórz funkcję, która wysyła żądanie do interfejsu API. Funkcję tę należy zdefiniować w kodzie aplikacji, ale może ona wywoływać usługi lub interfejsy API spoza aplikacji. Interfejs Gemini API nie wywołuje tej funkcji bezpośrednio, więc możesz kontrolować, jak i kiedy jest ona wykonywana za pomocą kodu aplikacji. Na potrzeby tego samouczka zdefiniowaliśmy w nim fikcyjną funkcję interfejsu API, która zwraca tylko żądane wartości oświetlenia:

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

Tworzenie deklaracji funkcji

Utwórz deklarację funkcji, którą przekażesz do modelu generatywnego. Podczas deklarowania funkcji do użycia przez model należy podać jak najwięcej szczegółów w opisie funkcji i parametrów. Model generatywny używa tych informacji, aby określić, którą funkcję wybrać i jak podać wartości parametrów w wywołaniu funkcji. Poniższy kod pokazuje, jak zadeklarować funkcję sterowania oświetleniem:

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"},
        },
    }},
}

Deklarowanie funkcji podczas inicjowania modelu

Jeśli chcesz używać wywołań funkcji w przypadku modelu, podczas inicjowania obiektu modelu musisz podać deklaracje funkcji. Funkcje deklarujesz, ustawiając parametr Tools modelu:

// ...

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}

Generowanie wywołania funkcji

Po zainicjowaniu modelu za pomocą deklaracji funkcji możesz wywołać model za pomocą zdefiniowanej funkcji. Do wywoływania funkcji należy używać promptów czatu (SendMessage()), ponieważ wywoływanie funkcji zwykle korzysta z kontekstu poprzednich promptów i odpowiedzi.

// 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)
}