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.

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:

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: 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:

// Function declaration, to pass to the model.
const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Executable function code. Put it in a map keyed by the function name
// so that you can call it once you get the name string from the model.
const functions = {
  controlLight: ({ brightness, colorTemp }) => {
    return setLightValues( brightness, colorTemp)
  }
};

Deklarowanie funkcji podczas inicjowania modelu

Jeśli chcesz używać wywołań funkcji z modelem, musisz podczas inicjowania obiektu modelu przesłać deklaracje funkcji. Aby zadeklarować funkcje, ustaw parametr tools modelu:

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

      const generativeModel = genAI.getGenerativeModel({
        // Use a model that supports function calling, like a Gemini 1.5 model
        model: "gemini-1.5-flash",

        // Specify the function declaration.
        tools: {
          functionDeclarations: [controlLightFunctionDeclaration],
        },
      });
    </script>
  </body>
</html>

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.

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

// Send the message to the model.
const result = await chat.sendMessage(prompt);

// For simplicity, this uses the first function call found.
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function named in the function call
  // with the arguments specified in the function call and
  // let it call the hypothetical API.
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model so it can generate
  // a text response that can be displayed to the user.
  const result = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result.response.text());
}