Samouczek: wywoływanie funkcji za pomocą interfejsu Gemini API

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

Wywoływanie funkcji ułatwia uzyskiwanie uporządkowanych danych wyjściowych z modeli generatywnych. Następnie możesz użyć tych danych wyjściowych, aby wywoływać inne interfejsy API i zwracać odpowiednie dane odpowiedzi do modelu. Inaczej mówiąc, wywołania funkcji pomagają połączyć modele generatywne z systemami zewnętrznymi, aby generowane treści zawierały aktualne i dokładne informacje.

Modelom Gemini możesz podawać opisy funkcji. Są to funkcje, które piszesz w języku swojej aplikacji (nie należą one do Google Cloud Functions). Model może poprosić Cię o wywołanie funkcji i odesłanie wyniku, aby model mógł lepiej obsłużyć zapytanie.

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

Konfigurowanie projektu

Zanim wywołasz interfejs Gemini API, musisz skonfigurować projekt Androida, co obejmuje skonfigurowanie klucza interfejsu API, dodanie zależności SDK do projektu na Androida oraz zainicjowanie modelu.

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

val generativeModel = GenerativeModel(

    // Use a model that supports function calling, like Gemini 1.0 Pro.
    // See "Supported models" in the "Introduction to function calling" page.
    modelName = "MODEL_NAME",

    // Access your API key as a Build Configuration variable (see "Set up your API key" above).
    apiKey = BuildConfig.apiKey
)

Konfigurowanie wywołania funkcji

W tym samouczku model będzie wchodzić w interakcje z hipotetycznym interfejsem API wymiany walut, który obsługuje te parametry:

Przykładowe żądanie do interfejsu API

{
  "currencyFrom": "USD",
  "currencyTo": "SEK"
}

Przykładowa odpowiedź interfejsu API

{
  "base": "USD",
  "rates": {"SEK": 0.091}
}

Krok 1. Utwórz funkcję, która wysyła żądanie do interfejsu API

Zacznij od utworzenia funkcji, która wysyła żądanie do interfejsu API.

Na potrzeby demonstracji w tym samouczku zamiast wysyłania rzeczywistego żądania do interfejsu API będziesz zwracać wartości zakodowane na stałe w tym samym formacie, w jakim jest zwrócony interfejs API.

suspend fun makeApiRequest(
    currencyFrom: String,
    currencyTo: String
): JSONObject {
    // This hypothetical API returns a JSON such as:
    // {"base":"USD","rates":{"SEK": 0.091}}
    return JSONObject().apply {
        put("base", currencyFrom)
        put("rates", hashMapOf(currencyTo to 0.091))
    }
}

Krok 2. Utwórz deklarację funkcji

Utwórz deklarację funkcji, którą przekażesz do modelu generatywnego (następny krok tego samouczka).

W opisach funkcji i parametrów podaj jak najwięcej szczegółów. Model generatywny wykorzystuje te informacje do określenia, którą funkcję wybrać i jak podać wartości parametrów w jej wywołaniu.

val getExchangeRate = defineFunction(
  name = "getExchangeRate",
  description = "Get the exchange rate for currencies between countries",
  Schema.str("currencyFrom", "The currency to convert from."),
  Schema.str("currencyTo", "The currency to convert to.")
) { from, to ->
    // Call the function that you declared above
    makeApiRequest(from, to)
}

Krok 3. Określ deklarację funkcji podczas inicjowania modelu

Podczas inicjowania modelu generatywnego określ deklarację funkcji, przekazując ją do parametru tools modelu:

val generativeModel = GenerativeModel(
  // Use a model that supports function calling, like Gemini 1.0 Pro
  // (see "Supported models" in the "Introduction to function calling" page)
  modelName = "gemini-1.0-pro",
  // Access your API key as a Build Configuration variable (see "Set up your API key" above)
  apiKey = BuildConfig.apiKey,
  // Specify the function declaration.
  tools = listOf(Tool(listOf(getExchangeRate)))
)

Krok 4. Wygeneruj wywołanie funkcji

Teraz możesz wywołać dla modelu zdefiniowaną funkcję.

Zalecanym sposobem korzystania z wywołań funkcji jest korzystanie z interfejsu czatu, ponieważ wywołania funkcji dobrze pasują do wieloetapowej struktury czatu.

val chat = generativeModel.startChat()

val prompt = "How much is 50 US dollars worth in Swedish krona?"

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