Samouczek wywoływania funkcji

Python Node.js Przejdź Dart (migotanie) Android Swift Internet REST

Wywołanie funkcji ułatwia pobieranie danych wyjściowych z uporządkowanych danych 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łanie funkcji pomaga Łączysz modele generatywne z systemami zewnętrznymi, aby wygenerowane treści zawiera najbardziej aktualne i dokładne informacje.

Możesz przekazywać modelom Gemini opisy funkcji. Są to funkcje napisane 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.

Zapoznaj się z Wprowadzenie do wywoływania funkcji więcej.

Przykładowy interfejs API do sterowania oświetleniem

Wyobraź sobie, że masz podstawowy system sterowania oświetleniem i programowanie interfejsu (API) i chcesz umożliwić użytkownikom sterowanie oświetleniem za pomocą prostego żądań tekstowych. Możesz skorzystać z funkcji wywoływania funkcji, aby interpretować oświetlenie zmieniać żądania użytkowników i przekształcać je w wywołania interfejsu API w celu ustawienia oświetlenia . Ten hipotetyczny system sterowania oświetleniem umożliwia kontrolowanie jasności światła i jego temperatury barwowej, zdefiniowanych jako dwa oddzielne parametry:

Dla uproszczenia ten wymyślony system oświetleniowy ma tylko jedno światło, dzięki czemu użytkownik nie musi określać pomieszczenia ani lokalizacji. Oto przykład żądania JSON, które możesz wysłać do interfejsu Lighting Control API, aby zmienić poziom światła do 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 Gemini API, musisz skonfigurować projekt klucz interfejsu API.

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

Definiowanie funkcji interfejsu API

utworzyć funkcję, która wysyła żądanie do interfejsu API; Tę funkcję należy zdefiniować w kodzie aplikacji, ale może wywoływać usługi lub interfejsy API poza Twojej 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. Dla celów demonstracyjnych w tym samouczku zdefiniowano imitację funkcji interfejsu API, która po prostu 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. Kiedy zadeklarujesz funkcję do użytku przez model, podaj jak najwięcej szczegółów w opisach funkcji i parametrów. Model generatywny wykorzystuje te informacje do określenia, którą funkcję wybrać i jak udostępnić parametrów w wywołaniu funkcji. Poniższy 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 podać deklaracji funkcji podczas inicjowania obiektu modelu. Funkcje deklarujesz, ustawiając 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)))
)

Generowanie wywołania funkcji

Po zainicjowaniu modelu za pomocą deklaracji funkcji możesz wywołać model za pomocą zdefiniowanej funkcji. Wywoływania funkcji należy używać za pomocą promptów na czacie (sendMessage()), ponieważ wywołanie funkcji zazwyczaj przynosi korzyści w kontekście 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)
}