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, che include la configurazione della chiave API, l'aggiunta dell'SDK alle dipendenze pub e l'inizializzazione del modello.

dart pub add google_generative_ai

flutter pub add google_generative_ai

import 'package:google_generative_ai/google_generative_ai.dart';

// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
  print('No \$API_KEY environment variable');
  exit(1);
}

// Use a model that supports function calling, like a Gemini 1.5 model
final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);

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

{
  "currencyDate": "2024-04-17",
  "currencyFrom": "USD",
  "currencyTo": "SEK"
}

Esempio di risposta dell'API

{
  "base": "USD",
  "date": "2024-04-17",
  "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.

Future<Map<String, Object?>> findExchangeRate(
  Map<String, Object?> arguments,
) async =>
    // This hypothetical API returns a JSON such as:
    // {"base":"USD","date":"2024-04-17","rates":{"SEK": 0.091}}
    {
      'date': arguments['currencyDate'],
      'base': arguments['currencyFrom'],
      'rates': <String, Object?>{arguments['currencyTo'] as String: 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.

final exchangeRateTool = FunctionDeclaration(
    'findExchangeRate',
    'Returns the exchange rate between currencies on given date.',
    Schema(SchemaType.object, properties: {
      'currencyDate': Schema(SchemaType.string,
          description: 'A date in YYYY-MM-DD format or '
              'the exact value "latest" if a time period is not specified.'),
      'currencyFrom': Schema(SchemaType.string,
          description: 'The currency code of the currency to convert from, '
              'such as "USD".'),
      'currencyTo': Schema(SchemaType.string,
          description: 'The currency code of the currency to convert to, '
              'such as "USD".')
    }, requiredProperties: [
      'currencyDate',
      'currencyFrom'
    ]));

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

Specifica la dichiarazione della funzione durante l'inizializzazione del modello generativo passandola al parametro tools del modello:

final model = GenerativeModel(
  // Use a model that supports function calling, like a Gemini 1.5 model
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [exchangeRateTool])
  ],
);

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.

final chat = model.startChat();
final prompt = 'How much is 50 US dollars worth in Swedish krona?';

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

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'findExchangeRate' => await findExchangeRate(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}