Samouczek wywoływania funkcji

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

Wywołania funkcji ułatwiają uzyskiwanie danych wyjściowych uporządkowanych danych z modeli generatywnych. Następnie możesz używać tych danych wyjściowych do wywoływania innych interfejsów API i zwracania odpowiednich danych odpowiedzi do modelu. Inaczej mówiąc, wywołanie funkcji pomaga połączyć modele generatywne z systemami zewnętrznymi, aby generowane treści zawierały najbardziej aktualne i dokładne informacje.

Modele Gemini możesz przesłać z opisami funkcji. Są to funkcje, które piszesz w języku aplikacji (czyli nie są to funkcje Google Cloud). Model może poprosić o wywołanie funkcji i odesłanie wyniku, aby ułatwić mu obsługę zapytania.

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

Przykładowy interfejs API do sterowania oświetleniem

Załóżmy, że masz podstawowy system sterowania oświetleniem z interfejsem programowania aplikacji (API) i chcesz umożliwić użytkownikom sterowanie oświetleniem za pomocą prostych żądań tekstowych. Możesz użyć funkcji wywołań funkcji, aby zinterpretować prośby użytkowników o zmianę oświetlenia i przełożyć je na wywołania interfejsu API w celu ustawienia wartości oświetlenia. Ten hipotetyczny system sterowania oświetleniem umożliwia kontrolowanie jasności światła oraz temperatury barwowej za pomocą 2 osobnych parametrów:

Dla uproszczenia ten wymyślony system oświetleniowy ma tylko 1 światło, więc użytkownik nie musi określać pomieszczenia ani lokalizacji. Oto przykładowe żądanie JSON, które możesz wysłać do interfejsu API sterowania oświetleniem, aby zmienić poziom jasności na 50% z użyciem temperatury barwowej światła dziennego:

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

Ten samouczek pokazuje, jak skonfigurować wywołanie funkcji dla interfejsu Gemini API, aby zinterpretować żądania dotyczące oświetlenia i mapować je na ustawienia interfejsu API w celu sterowania wartościami jasności i temperatury kolorów.

Zanim zaczniesz: skonfiguruj projekt i klucz interfejsu API

Zanim wywołasz Gemini API, musisz skonfigurować projekt i klucz interfejsu API.

dart pub add google_generative_ai

flutter pub add google_generative_ai

Zdefiniuj funkcję interfejsu API

utworzyć funkcję, która wysyła żądanie do interfejsu API; Ta funkcja powinna być zdefiniowana w kodzie aplikacji, ale może wywoływać usługi lub interfejsy API poza nią. Interfejs Gemini API nie wywołuje tej funkcji bezpośrednio, więc możesz kontrolować, jak i kiedy ta funkcja jest wykonywana za pomocą kodu aplikacji. Dla celów demonstracyjnych ten samouczek definiuje przykładową funkcję interfejsu API, która zwraca żądane wartości oświetlenia:

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

Utwórz deklaracje funkcji

Utwórz deklarację funkcji, którą przekażesz do modelu generatywnego. Deklarując funkcję do użycia przez model, podaj jak najwięcej szczegółów w opisach funkcji i parametrów. Na podstawie tych informacji model generatywny określa, którą funkcję wybrać i jak podać wartości dla parametrów w wywołaniu funkcji. Ten kod pokazuje, jak zadeklarować funkcję sterowania oświetleniem:

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'
    ]));

Deklarowanie funkcji podczas inicjowania modelu

Jeśli chcesz używać wywołań funkcji z modelem, musisz podczas inicjowania obiektu modelu przesłać deklaracje funkcji. Funkcje deklarujesz, ustawiając parametr tools modelu. Pakiet Dart SDK obsługuje również deklarowanie funkcji jako argumentów do interfejsów API generateContent lub generateContentStream.

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

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

Wygeneruj wywołanie funkcji

Po zainicjowaniu modelu z deklaracjami funkcji możesz wyświetlić prompt za pomocą zdefiniowanej funkcji. Wywoływać funkcji należy używać za pomocą promptów na czacie (sendMessage()), ponieważ wywołanie funkcji zwykle korzysta z kontekstu poprzednich promptów i odpowiedzi.

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