Samouczek wywoływania funkcji

Wywołanie funkcji ułatwia pobieranie danych wyjściowych z uporządkowanych danych modeli generatywnych. Następnie możesz używać tych danych do wywoływania innych interfejsów API i zwracania odpowiednich danych odpowiedzi do modelu. Innymi słowy, wywoływanie funkcji pomaga Ci łączyć modele generatywne z systemami zewnętrznymi, aby generowane treści zawierały jak najbardziej aktualne i dokładne informacje.

Możesz przekazywać modelom Gemini opisy funkcji. Są to funkcje napisane w języku aplikacji (czyli nie są to funkcje Google Cloud Functions). Model może poprosić o wywołanie funkcji i odesłanie aby ułatwić modelowi obsługę zapytania.

Zapoznaj się z Wprowadzenie do wywoływania funkcji więcej.

Przykład interfejsu API do sterowania oświetleniem

Wyobraź sobie, że masz podstawowy system sterowania oświetleniem i programowanie interfejsu (API) i chcesz umożliwić użytkownikom sterowanie oświetleniem za pomocą prostego żądań tekstowych. Możesz skorzystać z funkcji wywoływania funkcji, aby interpretować oświetlenie zmieniać żądania użytkowników i przekształcać je w wywołania interfejsu API w celu ustawienia oświetlenia . Ten hipotetyczny system sterowania oświetleniem umożliwia kontrolowanie jasności światła i jego temperatury barwowej, zdefiniowanych jako dwa oddzielne parametry:

Parametr Typ Wymagane Opis
brightness liczba tak Poziom światła od 0 do 100. Zero oznacza wyłączone, a 100 – pełną jasność.
colorTemperature ciąg znaków tak Temperatura kolorów oprawy oświetleniowej może wynosić daylight, cool lub warm.

W ramach uproszczenia tego wyimaginowanego systemu oświetlenia ma on tylko jedną lampę, więc użytkownik nie musi określać pokoju ani lokalizacji. Oto przykładowe żądanie JSON można wysłać do interfejsu API sterowania oświetleniem, aby zmienić poziom światła na 50% używając temperatury barwowej światła dziennego:

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

W tym samouczku pokazujemy, jak skonfigurować wywołanie funkcji w interfejsie Gemini API, aby interpretować żądania dotyczące oświetlenia użytkowników i mapować je na ustawienia interfejsu API w celu sterowania wartościami jasności i temperatury barwowej światła.

Zanim zaczniesz: skonfiguruj projekt i klucz interfejsu API

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

Zdefiniuj funkcję interfejsu API

Utwórz funkcję, która wysyła żądanie do interfejsu API. Tę funkcję należy zdefiniować w kodzie aplikacji, ale może wywoływać usługi lub interfejsy API poza Twojej aplikacji. Gemini API nie wywołuje tej funkcji bezpośrednio, więc może kontrolować sposób i czas wykonywania tej funkcji w aplikacji w kodzie. Dla celów demonstracyjnych w tym samouczku zdefiniowano imitację funkcji interfejsu API, która po prostu 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'],
    };

Tworzenie deklaracji funkcji

Utwórz deklarację funkcji, którą przekażesz do modelu generatywnego. Kiedy zadeklarujesz funkcję do użytku przez model, podaj jak najwięcej szczegółów w opisach funkcji i parametrów. Model generatywny używa tych informacji, aby określić, którą funkcję wybrać i jak podać wartości parametrów w wywołaniu funkcji. Poniższy 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ływania funkcji w przypadku modelu, podczas inicjowania obiektu modelu musisz podać deklaracje funkcji. Deklarujesz przez ustawienie parametru tools modelu. Pakiet Dart SDK obsługuje również deklarowanie funkcji jako argumentów funkcji generateContent lub Interfejsy API: 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 poprosić model ze zdefiniowaną funkcją. Wywoływania funkcji należy używać za pomocą: promptów na czacie (sendMessage()), ponieważ wywołanie funkcji zazwyczaj przynosi korzyści w kontekście 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);
}