Tutorial: chamada de funções com a API Gemini

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

A chamada de função facilita a geração de saídas de dados estruturados de modelos generativos. Assim, é possível usar essas saídas para chamar outras APIs e retornar os dados de resposta relevantes para o modelo. Em outras palavras, a chamada de função ajuda a conectar modelos generativos a sistemas externos para que o conteúdo gerado inclua as informações mais atualizadas e precisas.

É possível fornecer modelos do Gemini com descrições de funções. São funções que você escreve na linguagem do seu app (ou seja, não são funções do Google Cloud). O modelo pode pedir que você chame uma função e envie o resultado para ajudar o modelo a processar a consulta.

Se ainda não fez isso, confira a Introdução à chamada de função para saber mais.

Configurar seu projeto

Antes de chamar a API Gemini, você precisa configurar seu projeto do Xcode, o que inclui a configuração da chave de API, a adição do pacote do SDK ao projeto do Xcode e a inicialização do modelo.

enum APIKey {
  // Fetch the API key from `GenerativeAI-Info.plist`
  static var `default`: String {
    guard let filePath = Bundle.main.path(forResource: "GenerativeAI-Info", ofType: "plist")
    else {
      fatalError("Couldn't find file 'GenerativeAI-Info.plist'.")
    }
    let plist = NSDictionary(contentsOfFile: filePath)
    guard let value = plist?.object(forKey: "API_KEY") as? String else {
      fatalError("Couldn't find key 'API_KEY' in 'GenerativeAI-Info.plist'.")
    }
    if value.starts(with: "_") {
      fatalError(
        "Follow the instructions at https://ai.google.dev/tutorials/setup to get an API key."
      )
    }
    return value
  }
}

Configurar uma chamada de função

Neste tutorial, o modelo vai interagir com uma API hipotética de troca de moedas compatível com os seguintes parâmetros:

Exemplo de solicitação de API

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

Exemplo de resposta da API

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

Etapa 1: criar a função que faz a solicitação de API

Comece criando a função que faz uma solicitação de API, caso ainda não tenha feito isso.

Para fins de demonstração neste tutorial, em vez de enviar uma solicitação de API real, você retornará valores fixados no código no mesmo formato que uma API real retornaria.

func makeAPIRequest(currencyFrom: String,
                    currencyTo: String) -> JSONObject {
  // This hypothetical API returns a JSON such as:
  // {"base":"USD","rates":{"SEK": 0.091}}
  return [
    "base": .string(currencyFrom),
    "rates": .object([currencyTo: .number(0.091)]),
  ]
}

Etapa 2: criar uma declaração de função

Crie a declaração da função que você vai transmitir para o modelo generativo (próxima etapa deste tutorial).

Inclua o máximo de detalhes possível nas descrições da função e do parâmetro. O modelo generativo usa essas informações para determinar qual função selecionar e como fornecer valores para os parâmetros na chamada de função.

let getExchangeRate = FunctionDeclaration(
  name: "getExchangeRate",
  description: "Get the exchange rate for currencies between countries",
  parameters: [
    "currencyFrom": Schema(
      type: .string,
      description: "The currency to convert from."
    ),
    "currencyTo": Schema(
      type: .string,
      description: "The currency to convert to."
    ),
  ],
  requiredParameters: ["currencyFrom", "currencyTo"]
)

Etapa 3: especificar a declaração da função durante a inicialização do modelo

Especifique a declaração da função ao inicializar o modelo generativo definindo o parâmetro tools do modelo:

// Use a model that supports function calling, like a Gemini 1.5 model
let generativeModel = GenerativeModel(
  name: "gemini-1.5-flash",
  apiKey: apiKey,
  // Specify the function declaration.
  tools: [Tool(functionDeclarations: [getExchangeRate])]
)

Etapa 4: gerar uma chamada de função

Agora é possível solicitar o modelo com a função definida.

A maneira recomendada de usar a chamada de funções é pela interface de chat, já que as chamadas de função se encaixam perfeitamente na estrutura de várias interações do chat.

let chat = generativeModel.startChat()

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

// Send the message to the generative model
let response1 = try await chat.sendMessage(prompt)

// Check if the model responded with a function call
guard let functionCall = response1.functionCalls.first else {
  fatalError("Model did not respond with a function call.")
}
// Print an error if the returned function was not declared
guard functionCall.name == "getExchangeRate" else {
  fatalError("Unexpected function called: \(functionCall.name)")
}
// Verify that the names and types of the parameters match the declaration
guard case let .string(currencyFrom) = functionCall.args["currencyFrom"] else {
  fatalError("Missing argument: currencyFrom")
}
guard case let .string(currencyTo) = functionCall.args["currencyTo"] else {
  fatalError("Missing argument: currencyTo")
}

// Call the hypothetical API
let apiResponse = makeAPIRequest(currencyFrom: currencyFrom, currencyTo: currencyTo)

// Send the API response back to the model so it can generate a text response that can be
// displayed to the user.
let response = try await chat.sendMessage([ModelContent(
  role: "function",
  parts: [.functionResponse(FunctionResponse(
    name: functionCall.name,
    response: apiResponse
  ))]
)])

// Log the text response.
guard let modelResponse = response.text else {
  fatalError("Model did not respond with text.")
}
print(modelResponse)