함수 호출 튜토리얼

함수 호출을 사용하면 생성형 모델에서 구조화된 데이터 출력을 더 쉽게 가져올 수 있습니다. 그런 다음 이러한 출력을 사용하여 다른 API를 호출하고 관련 응답 데이터를 모델에 반환할 수 있습니다. 즉, 함수 호출을 사용하면 생성형 모델을 외부 시스템에 연결하여 생성된 콘텐츠에 최신 정보와 정확한 정보를 포함할 수 있습니다.

Gemini 모델에 함수 설명을 제공할 수 있습니다. 앱의 언어로 작성하는 함수입니다 (즉, Google Cloud Functions가 아님). 모델이 쿼리를 처리하는 데 도움이 되도록 함수를 호출하고 결과를 다시 전송하도록 요청할 수 있습니다.

아직 확인하지 않았다면 함수 호출 소개를 참고하여 자세히 알아보세요.

조명 제어 API 예시

애플리케이션 프로그래밍 인터페이스 (API)가 있는 기본 조명 제어 시스템이 있고 사용자가 간단한 텍스트 요청을 통해 조명을 제어할 수 있도록 허용하려고 한다고 가정해 보겠습니다. 함수 호출 기능을 사용하여 사용자의 조명 변경 요청을 해석하고 이를 API 호출로 변환하여 조명 값을 설정할 수 있습니다. 이 가상의 조명 제어 시스템을 사용하면 조명의 밝기와 색온도를 제어할 수 있습니다. 색온도는 두 개의 별도 매개변수로 정의됩니다.

매개변수 유형 필수 설명
brightness 숫자 예 밝기 수준(0~100) 0은 꺼짐이고 100은 최대 밝기입니다.
colorTemperature 문자열 예 조명기구의 색상 온도(daylight, cool 또는 warm)입니다.

편의상 이 가상의 조명 시스템에는 조명이 하나만 있으므로 사용자는 방이나 위치를 지정할 필요가 없습니다. 다음은 조명 제어 API에 전송하여 일광 색온도를 사용하여 조명 수준을 50%로 변경할 수 있는 JSON 요청의 예입니다.

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

이 튜토리얼에서는 Gemini API의 함수 호출을 설정하여 사용자 조명 요청을 해석하고 이를 API 설정에 매핑하여 조명의 밝기 및 색온도 값을 제어하는 방법을 보여줍니다.

시작하기 전에: 프로젝트 및 API 키 설정

Gemini API를 호출하기 전에 프로젝트를 설정하고 API 키를 구성해야 합니다.

API 함수 정의

API 요청을 실행하는 함수를 만듭니다. 이 함수는 애플리케이션 코드 내에 정의되어야 하지만 애플리케이션 외부의 서비스나 API를 호출할 수 있습니다. Gemini API는 이 함수를 직접 호출하지 않으므로 애플리케이션 코드를 통해 이 함수가 실행되는 방식과 시점을 제어할 수 있습니다. 이 튜토리얼에서는 데모 목적으로 요청된 조명 값만 반환하는 모의 API 함수를 정의합니다.

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

함수 선언 만들기

생성형 모델에 전달할 함수 선언을 만듭니다. 모델에서 사용할 함수를 선언할 때는 함수 및 매개변수 설명에 최대한 많은 세부정보를 포함해야 합니다. 생성형 모델은 이 정보를 사용하여 선택할 함수와 함수 호출에서 매개변수의 값을 제공하는 방법을 결정합니다. 다음 코드는 조명 제어 함수를 선언하는 방법을 보여줍니다.

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

모델 초기화 중에 함수 선언

모델에서 함수 호출을 사용하려면 모델 객체를 초기화할 때 함수 선언을 제공해야 합니다. 모델의 tools 매개변수를 설정하여 함수를 선언합니다.

<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>

함수 호출 생성

함수 선언으로 모델을 초기화한 후 정의된 함수로 모델에 프롬프트를 표시할 수 있습니다. 함수 호출은 일반적으로 이전 프롬프트와 응답의 컨텍스트를 갖는 것이 유용하므로 채팅 프롬프트 (sendMessage())를 사용하여 함수 호출을 사용해야 합니다.

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