Tutorial sulla chiamata di funzione

La chiamata di funzione semplifica l'ottenimento di output di dati strutturati da e modelli generativi. Puoi quindi utilizzare questi output per chiamare altre API e restituire i dati di risposta pertinenti al modello. In altre parole, la chiamata di funzione colleghi modelli generativi a sistemi esterni in modo che i contenuti generati includa le informazioni più aggiornate e accurate.

Puoi fornire ai modelli Gemini descrizioni delle funzioni. Si tratta di di funzioni che scrivi nella lingua della tua app (ovvero, Google Cloud Functions). Il modello potrebbe chiederti di richiamare una funzione e restituirla il risultato per aiutare il modello a gestire la query.

Se non l'hai già fatto, consulta il Introduzione alle chiamate di funzione per imparare altro ancora.

API di esempio per il controllo dell'illuminazione

Immagina di avere un sistema di base per il controllo dell'illuminazione con una programmazione di un'applicazione (API) e vuoi consentire agli utenti di controllare le luci tramite semplici richieste di testo. Puoi utilizzare la funzionalità di chiamata di funzione per interpretare l'illuminazione modificare le richieste degli utenti e tradurle in chiamate API per e i relativi valori. Questo ipotetico sistema di controllo dell'illuminazione ti consente di controllare luminosità della luce e la relativa temperatura di colore, definita come due parametri:

Parametro Tipo Obbligatorio Descrizione
brightness numero Livello di luce da 0 a 100. Lo zero è disattivato e 100 è piena luminosità.
colorTemperature stringa Temperatura di colore del dispositivo di illuminazione che può essere daylight, cool o warm.

Per semplicità, questo sistema di illuminazione immaginario ha una sola illuminazione, quindi l'utente non richiede di specificare una stanza o un luogo. Ecco un esempio di richiesta JSON puoi inviare all'API di controllo della luce per impostare il livello della luce al 50% utilizzando la temperatura di colore della luce diurna:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

Questo tutorial mostra come configurare una chiamata di funzione per l'API Gemini interpretare le richieste di illuminazione degli utenti e mapparle alle impostazioni API per controllare i valori di luminosità e temperatura di colore della luce.

Prima di iniziare: configura il progetto e la chiave API

Prima di chiamare l'API Gemini, devi impostare il tuo progetto la chiave API.

Definisci una funzione API

Creare una funzione che invia una richiesta API. Questa funzione deve essere definita nel codice della tua applicazione, ma potresti chiamare servizi o API all'esterno la tua applicazione. L'API Gemini non chiama direttamente questa funzione, quindi puoi controllare come e quando questa funzione viene eseguita tramite la tua applicazione le API nel tuo codice. A scopo dimostrativo, questo tutorial definisce una funzione API fittizia che restituisce solo i valori di illuminazione richiesti:

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

crea dichiarazioni di funzione

Crea la dichiarazione di funzione che passerai al modello generativo. Quando dichiari una funzione che deve essere utilizzata dal modello, devi includere il maggior numero di dettagli il più possibile nelle descrizioni delle funzioni e dei parametri. Il modello generativo utilizza queste informazioni per determinare quale funzione selezionare e come offrire per i parametri nella chiamata di funzione. Il seguente codice mostra come dichiara la funzione di controllo dell'illuminazione:

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      'brightness',
      'colorTemperature'
    ]));

Dichiara le funzioni durante l'inizializzazione del modello

Quando vuoi utilizzare la chiamata di funzione con un modello, devi fornire le dichiarazioni di funzione quando inizializzato l'oggetto modello. Hai dichiarato impostando il parametro tools del modello. L'SDK Dart supporta inoltre che dichiara le funzioni come argomenti all'oggetto generateContent generateContentStream API.

final model = GenerativeModel(
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

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

Genera una chiamata di funzione

Dopo aver inizializzato il modello con le dichiarazioni di funzione, puoi richiedere del modello con la funzione definita. Dovresti usare le chiamate di funzione utilizzando prompt di chat (sendMessage()), poiché le chiamate di funzione in genere beneficiano contesto dei prompt e delle risposte precedenti.

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// 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.
    'setLightValues' => await setLightValues(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);
}