Samouczek wywoływania funkcji

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

Wywołania funkcji ułatwiają uzyskiwanie danych wyjściowych uporządkowanych danych z modeli generatywnych. Następnie możesz używać tych danych wyjściowych do wywoływania innych interfejsów API i zwracania odpowiednich danych odpowiedzi do modelu. Inaczej mówiąc, wywołanie funkcji pomaga połączyć modele generatywne z systemami zewnętrznymi, aby generowane treści zawierały najbardziej aktualne i dokładne informacje.

Modele Gemini możesz przesłać z opisami funkcji. Są to funkcje, które piszesz w języku aplikacji (czyli nie są to funkcje Google Cloud). Model może poprosić o wywołanie funkcji i odesłanie wyniku, aby ułatwić mu obsługę zapytania.

Więcej informacji znajdziesz we wprowadzeniu do wywoływania funkcji.

Przykładowy interfejs API do sterowania oświetleniem

Załóżmy, że masz podstawowy system sterowania oświetleniem z interfejsem programowania aplikacji (API) i chcesz umożliwić użytkownikom sterowanie oświetleniem za pomocą prostych żądań tekstowych. Możesz użyć funkcji wywołań funkcji, aby zinterpretować prośby użytkowników o zmianę oświetlenia i przełożyć je na wywołania interfejsu API w celu ustawienia wartości oświetlenia. Ten hipotetyczny system sterowania oświetleniem umożliwia kontrolowanie jasności światła oraz temperatury barwowej za pomocą 2 osobnych parametrów:

Dla uproszczenia ten wymyślony system oświetleniowy ma tylko 1 światło, więc użytkownik nie musi określać pomieszczenia ani lokalizacji. Oto przykładowe żądanie JSON, które możesz wysłać do interfejsu API sterowania oświetleniem, aby zmienić poziom jasności na 50% z użyciem temperatury barwowej światła dziennego:

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

Ten samouczek pokazuje, jak skonfigurować wywołanie funkcji dla interfejsu Gemini API, aby zinterpretować żądania dotyczące oświetlenia i mapować je na ustawienia interfejsu API w celu sterowania wartościami jasności i temperatury kolorów.

Zanim zaczniesz: skonfiguruj projekt i klucz interfejsu API

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

// Access your API key as a Build Configuration variable
val apiKey = BuildConfig.apiKey

Zdefiniuj funkcję interfejsu API

utworzyć funkcję, która wysyła żądanie do interfejsu API; Ta funkcja powinna być zdefiniowana w kodzie aplikacji, ale może wywoływać usługi lub interfejsy API poza nią. Interfejs Gemini API nie wywołuje tej funkcji bezpośrednio, więc możesz kontrolować, jak i kiedy ta funkcja jest wykonywana za pomocą kodu aplikacji. Dla celów demonstracyjnych ten samouczek definiuje przykładową funkcję interfejsu API, która zwraca żądane wartości oświetlenia:

suspend fun setLightValues(
    brightness: Int,
    colorTemp: String
): JSONObject {
    // This mock API returns the requested lighting values
    return JSONObject().apply {
        put("brightness", brightness)
        put("colorTemperature", colorTemp)
    }
}

Utwórz deklaracje funkcji

Utwórz deklarację funkcji, którą przekażesz do modelu generatywnego. Deklarując funkcję do użycia przez model, podaj jak najwięcej szczegółów w opisach funkcji i parametrów. Na podstawie tych informacji model generatywny określa, którą funkcję wybrać i jak podać wartości dla parametrów w wywołaniu funkcji. Ten kod pokazuje, jak zadeklarować funkcję sterowania oświetleniem:

val lightControlTool = defineFunction(
  name = "setLightValues",
  description = "Set the brightness and color temperature of a room light.",
  Schema.int("brightness", "Light level from 0 to 100. Zero is off and 100" +
    " is full brightness."),
  Schema.str("colorTemperature", "Color temperature of the light fixture" +
    " which can be `daylight`, `cool` or `warm`.")
) { brightness, colorTemp ->
    // Call the function you declared above
    setLightValues(brightness.toInt(), colorTemp)
}

Deklarowanie funkcji podczas inicjowania modelu

Jeśli chcesz używać wywołań funkcji z modelem, musisz podczas inicjowania obiektu modelu przesłać deklaracje funkcji. Aby zadeklarować funkcje, ustaw parametr tools modelu:

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",

    // Access your API key as a Build Configuration variable
    apiKey = BuildConfig.apiKey,

    // Specify the function declaration.
    tools = listOf(Tool(listOf(lightControlTool)))
)

Wygeneruj wywołanie funkcji

Po zainicjowaniu modelu z deklaracjami funkcji możesz wyświetlić prompt za pomocą zdefiniowanej funkcji. Wywoływać funkcji należy używać za pomocą promptów na czacie (sendMessage()), ponieważ wywołanie funkcji zwykle korzysta z kontekstu poprzednich promptów i odpowiedzi.

val chat = generativeModel.startChat()

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

// Send the message to the generative model
var response = chat.sendMessage(prompt)

// Check if the model responded with a function call
response.functionCall?.let { functionCall ->
  // Try to retrieve the stored lambda from the model's tools and
  // throw an exception if the returned function was not declared
  val matchedFunction = generativeModel.tools?.flatMap { it.functionDeclarations }
      ?.first { it.name == functionCall.name }
      ?: throw InvalidStateException("Function not found: ${functionCall.name}")

  // Call the lambda retrieved above
  val apiResponse: JSONObject = matchedFunction.execute(functionCall)

  // Send the API response back to the generative model
  // so that it generates a text response that can be displayed to the user
  response = chat.sendMessage(
    content(role = "function") {
        part(FunctionResponsePart(functionCall.name, apiResponse))
    }
  )
}

// Whenever the model responds with text, show it in the UI
response.text?.let { modelResponse ->
    println(modelResponse)
}