Tutorial: chiamate di funzioni con l'API Gemini

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

Le chiamate di funzione consentono di ottenere più facilmente output di dati strutturati dai modelli generativi. Puoi quindi utilizzare questi output per chiamare altre API e restituire al modello i dati di risposta pertinenti. In altre parole, le chiamate di funzione consentono di collegare i modelli generativi a sistemi esterni in modo che i contenuti generati includano le informazioni più aggiornate e accurate.

Puoi fornire ai modelli Gemini le descrizioni delle funzioni. Si tratta di funzioni che scrivi nel linguaggio dell'app (ovvero non sono funzioni di Google Cloud Functions). Il modello potrebbe chiederti di chiamare una funzione e inviare il risultato per aiutarlo a gestire la query.

Se non l'hai ancora fatto, consulta l'introduzione alle chiamate di funzione per saperne di più.

Configura il progetto

Prima di chiamare l'API Gemini, devi configurare il progetto Xcode, che include la configurazione della chiave API, l'aggiunta del pacchetto SDK al progetto Xcode e l'inizializzazione del modello.

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

Imposta una chiamata funzione

Per questo tutorial, il modello interagirà con un'API ipotetica di scambio di valute che supporta i seguenti parametri:

Esempio di richiesta API

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

Esempio di risposta dell'API

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

Passaggio 1: crea la funzione che effettua la richiesta API

Se non l'hai già fatto, inizia creando la funzione che effettui una richiesta API.

A scopo dimostrativo, in questo tutorial, anziché inviare una richiesta API effettiva, riceverai valori impostati come hardcoded nello stesso formato restituito da un'API effettiva.

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)]),
  ]
}

Passaggio 2: crea una dichiarazione di funzione

Crea la dichiarazione della funzione che passerai al modello generativo (passaggio successivo di questo tutorial).

Includi il maggior numero di dettagli possibile nelle descrizioni delle funzioni e dei parametri. Il modello generativo utilizza queste informazioni per determinare quale funzione selezionare e in che modo fornire valori per i parametri nella chiamata di funzione.

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"]
)

Passaggio 3: specifica la dichiarazione della funzione durante l'inizializzazione del modello

Specifica la dichiarazione della funzione durante l'inizializzazione del modello generativo impostando il parametro tools del modello:

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

Passaggio 4: genera una chiamata funzione

Ora puoi richiedere al modello la funzione definita.

Consigliamo di utilizzare le chiamate di funzione tramite l'interfaccia della chat, poiché le chiamate di funzione si adattano perfettamente alla struttura multi-turno della 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)