Gemini API를 사용한 함수 호출

생성형 모델은 다양한 유형의 문제를 해결하는 데 효과적입니다. 그러나 다음과 같은 제한사항이 적용됩니다.

• 학습 후 고정되므로 오래된 지식이 제공됩니다.
• 외부 데이터를 쿼리하거나 수정할 수 없습니다.

함수 호출을 사용하면 이러한 제한사항 중 일부를 극복할 수 있습니다. 함수 호출을 도구 사용이라고도 합니다. 모델이 API 및 함수와 같은 외부 도구를 사용하여 최종 응답을 생성할 수 있기 때문입니다.

Google Cloud 문서에서 함수 호출 사용 사례의 유용한 목록을 비롯하여 함수 호출에 관해 자세히 알아보세요.

함수 호출은 Gemini 1.0 Pro, Gemini 1.5 Pro, Gemini 1.5 Flash에서 지원됩니다.

이 가이드에서는 이 페이지의 다음 주요 섹션에 설명된 예와 유사한 함수 호출 설정을 구현하는 방법을 보여줍니다. 앱에서 함수 호출을 설정하는 단계는 대략 다음과 같습니다.

1. 모델에 최종 응답을 생성하는 데 필요한 정보를 제공할 수 있는 함수를 작성합니다 (예: 함수가 외부 API를 호출할 수 있음).

2. 함수와 매개변수를 설명하는 함수 선언을 만듭니다.

3. 필요한 경우 모델이 함수를 사용하는 방법을 알 수 있도록 모델 초기화 중에 함수 선언을 제공합니다.

4. 모델이 앱에서 함수를 호출하는 데 필요한 정보를 전송할 수 있도록 앱을 설정합니다.

5. 모델이 최종 응답을 생성할 수 있도록 함수의 응답을 모델에 다시 전달합니다.

코드 구현으로 이동

함수 호출 예시 개요

모델에 요청을 전송할 때 최종 응답을 생성하는 데 사용할 수 있는 '도구' (예: 함수) 모음을 모델에 제공할 수도 있습니다. 이러한 함수를 활용하고 호출하려면 ('함수 호출') 모델과 앱이 서로 정보를 주고받아야 하므로 함수 호출을 사용하는 권장 방법은 멀티턴 채팅 인터페이스를 사용하는 것입니다.

사용자가 다음과 같은 프롬프트를 입력할 수 있는 앱이 있다고 가정해 보겠습니다. What was the weather in Boston on October 17, 2024?.

Gemini 모델은 이 날씨 정보를 알지 못할 수 있습니다. 하지만 이를 제공할 수 있는 외부 날씨 서비스 API를 알고 있다고 가정해 보겠습니다. 함수 호출을 사용하여 Gemini 모델에 해당 API 및 날씨 정보의 경로를 제공할 수 있습니다.

먼저 앱에서 다음과 같은 입력과 출력이 있는 가상의 외부 API와 상호작용하는 함수 fetchWeather를 작성합니다.

매개변수	유형	필수	설명
입력
location	객체	예	날씨를 가져올 도시 및 해당 도시의 시/도 이름입니다. 미국의 도시만 지원됩니다. 항상 city 및 state의 중첩 객체여야 합니다.
date	문자열	예	날씨를 가져올 날짜입니다 (항상 YYYY-MM-DD 형식이어야 함).
출력
temperature	정수	예	온도 (화씨)
chancePrecipitation	문자열	예	강수 확률 (백분율로 표시)
cloudConditions	문자열	예	구름 상태 (clear, partlyCloudy, mostlyCloudy, cloudy 중 하나)

모델을 초기화할 때 모델에 이 fetchWeather 함수가 존재하며 필요한 경우 수신 요청을 처리하는 데 어떻게 사용할 수 있는지 알려줍니다. 이를 '함수 선언'이라고 합니다. 모델은 함수를 직접 호출하지 않습니다. 대신 모델은 수신되는 요청을 처리할 때 fetchWeather 함수가 요청에 응답하는 데 도움이 될지 결정합니다. 모델이 함수가 실제로 유용할 수 있다고 판단하면 앱에서 함수를 호출하는 데 도움이 되는 구조화된 데이터를 생성합니다.

수신 요청인 What was the weather in Boston on October 17, 2024?을 다시 살펴봅니다. 모델은 fetchWeather 함수가 응답을 생성하는 데 도움이 될 수 있다고 판단할 수 있습니다. 모델은 fetchWeather에 필요한 입력 매개변수를 확인한 다음 대략 다음과 같이 함수의 구조화된 입력 데이터를 생성합니다.

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

모델은 앱에서 fetchWeather 함수를 호출할 수 있도록 이 정형 입력 데이터를 앱에 전달합니다. 앱이 API에서 날씨 상태를 다시 수신하면 정보를 모델에 전달합니다. 이 날씨 정보를 통해 모델은 최종 처리를 완료하고 What was the weather in Boston on October 17, 2024?의 초기 요청에 대한 응답을 생성할 수 있습니다.

모델은 다음과 같은 최종 자연어 응답을 제공할 수 있습니다. On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

 

함수 호출 구현

시작하기 전에

Vertex AI in Firebase SDK 시작 가이드를 아직 완료하지 않았다면 완료하세요. 다음 작업을 모두 완료했는지 확인합니다.

1. Blaze 요금제 사용 및 필요한 API 사용 설정을 포함하여 새 Firebase 프로젝트 또는 기존 Firebase 프로젝트를 설정합니다.

2. 앱을 등록하고 앱에 Firebase 구성을 추가하는 등 앱을 Firebase에 연결합니다.

3. SDK를 추가하고 앱에서 Vertex AI 서비스와 생성형 모델을 초기화합니다.

앱을 Firebase에 연결하고, SDK를 추가하고, Vertex AI 서비스와 생성형 모델을 초기화한 후에는 Gemini API를 호출할 수 있습니다.

이 가이드의 나머지 단계에서는 함수 호출 예시 개요(이 페이지의 상단 섹션 참고)에 설명된 워크플로와 유사한 함수 호출 설정을 구현하는 방법을 보여줍니다.

이 페이지 뒷부분에서 이 함수 호출 예의 전체 코드 샘플을 확인할 수 있습니다.

1단계: 함수 작성

사용자가 다음과 같은 프롬프트를 입력할 수 있는 앱이 있다고 가정해 보겠습니다. What was the weather in Boston on October 17, 2024?. Gemini 모델은 이 날씨 정보를 알지 못할 수 있습니다. 하지만 이를 제공할 수 있는 외부 날씨 서비스 API를 알고 있다고 가정해 보겠습니다. 이 가이드의 예에서는 이 가상의 외부 API를 사용합니다.

가상의 외부 API와 상호작용하고 모델에 최종 요청을 생성하는 데 필요한 정보를 제공하는 함수를 앱에 작성합니다. 이 날씨 예시에서는 이 가상의 외부 API를 호출하는 fetchWeather 함수입니다.

2단계: 함수 선언 만들기

나중에 모델에 제공할 함수 선언을 만듭니다(이 가이드의 다음 단계).

선언에서 함수 및 매개변수의 설명에 최대한 많은 세부정보를 포함합니다.

모델은 함수 선언의 정보를 사용하여 선택할 함수와 실제 함수 호출에 매개변수 값을 제공하는 방법을 결정합니다. 모델이 함수 중에서 선택하는 방법과 이러한 선택을 제어하는 방법은 이 페이지의 뒷부분에 있는 추가 동작 및 옵션을 참고하세요.

제공하는 스키마에 관해 다음 사항에 유의하세요.

• OpenAPI 스키마와 호환되는 스키마 형식으로 함수 선언을 제공해야 합니다. Vertex AI는 OpenAPI 스키마를 제한적으로 지원합니다.

  • type, nullable, required, format, description, properties, items, enum 속성이 지원됩니다.

  • default, optional, maximum, oneOf 속성은 지원되지 않습니다.

• 기본적으로 Vertex AI in Firebase SDK의 경우 optionalProperties 배열에서 선택사항으로 지정하지 않는 한 모든 필드는 필수 필드로 간주됩니다. 이러한 선택적 필드의 경우 모델이 필드를 채우거나 건너뛸 수 있습니다. 이는 Vertex AI Gemini API의 기본 동작과는 반대입니다.

이름 및 설명에 관한 도움말을 비롯하여 함수 선언과 관련된 권장사항은 Google Cloud 문서의 권장사항을 참고하세요.

함수 선언을 작성하는 방법은 다음과 같습니다.

3단계: 모델 초기화 중에 함수 선언 제공

요청에 제공할 수 있는 최대 함수 선언 수는 128개입니다. 모델이 함수 중에서 선택하는 방법과 이러한 선택을 제어하는 방법 (toolConfig를 사용하여 함수 호출 모드 설정)은 이 페이지의 추가 동작 및 옵션을 참고하세요.

사용 사례 및 앱에 적합한 Gemini 모델과 선택적으로 위치를 선택하는 방법을 알아보세요.

4단계: 함수를 호출하여 외부 API 호출

모델이 fetchWeather 함수가 최종 응답을 생성하는 데 실제로 도움이 된다고 판단하면 앱은 모델에서 제공한 구조화된 입력 데이터를 사용하여 해당 함수를 실제로 호출해야 합니다.

모델과 앱 간에 정보를 주고받아야 하므로 함수 호출을 사용하는 권장 방법은 멀티턴 채팅 인터페이스를 사용하는 것입니다.

다음 코드 스니펫은 모델이 fetchWeather 함수를 사용하려는 것을 앱에 알리는 방법을 보여줍니다. 또한 모델이 함수 호출 (및 기본 외부 API)에 필요한 입력 매개변수 값을 제공했음을 보여줍니다.

이 예시에서 수신 요청에는 What was the weather in Boston on October 17, 2024? 프롬프트가 포함되어 있습니다. 이 프롬프트에서 모델은 fetchWeather 함수에 필요한 입력 매개변수 (city, state, date)를 추론했습니다.

5단계: 모델에 함수의 출력을 제공하여 최종 응답 생성

fetchWeather 함수가 날씨 정보를 반환하면 앱에서 이를 모델에 다시 전달해야 합니다.

그런 다음 모델은 최종 처리를 실행하고 다음과 같은 최종 자연어 응답을 생성합니다. On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

추가 동작 및 옵션

다음은 코드에 수용해야 하는 함수 호출의 추가 동작과 제어할 수 있는 옵션입니다.

모델이 함수를 다시 호출하거나 다른 함수를 호출하도록 요청할 수 있습니다.

한 함수 호출의 응답이 모델이 최종 응답을 생성하기에 충분하지 않으면 모델이 추가 함수 호출을 요청하거나 완전히 다른 함수 호출을 요청할 수 있습니다. 후자는 함수 선언 목록에서 모델에 두 개 이상의 함수를 제공하는 경우에만 발생할 수 있습니다.

앱은 모델이 추가 함수 호출을 요청할 수 있다는 점을 고려해야 합니다.

모델이 여러 함수를 동시에 호출하도록 요청할 수 있습니다.

함수 선언 목록에서 모델에 최대 128개의 함수를 제공할 수 있습니다. 이를 고려하여 모델은 최종 응답을 생성하는 데 여러 함수가 필요하다고 판단할 수 있습니다. 그리고 이러한 함수 중 일부를 동시에 호출하기로 결정할 수도 있습니다. 이를 병렬 함수 호출이라고 합니다.

앱은 모델이 동시에 실행되는 여러 함수를 요청할 수 있다는 점을 고려해야 하며, 앱은 함수의 모든 응답을 모델에 다시 제공해야 합니다.

병렬 함수 호출은 Gemini 1.5 Pro 및 Gemini 1.5 Flash에서 지원됩니다.

모델이 함수 호출을 요청할 수 있는 방법과 여부를 제어할 수 있습니다.

모델이 제공된 함수 선언을 사용하는 방법과 여부에 몇 가지 제약조건을 지정할 수 있습니다. 이를 함수 호출 모드 설정이라고 합니다. 예를 들면 다음과 같습니다.

• 모델이 즉각적인 자연어 응답과 함수 호출 중에서 선택하도록 허용하는 대신 항상 함수 호출을 사용하도록 강제할 수 있습니다. 이를 강제 함수 호출이라고 합니다.

• 함수 선언을 여러 개 제공하는 경우 제공된 함수의 하위 집합만 사용하도록 모델을 제한할 수 있습니다.

이러한 제약조건 (또는 모드)은 프롬프트 및 함수 선언과 함께 도구 구성(toolConfig)을 추가하여 구현합니다. 도구 구성에서 다음 모드 중 하나를 지정할 수 있습니다. 가장 유용한 모드는 ANY입니다.

모드	설명
AUTO	기본 모델 동작입니다. 모델이 함수 호출과 자연어 응답 중 무엇을 사용할지 결정합니다.
ANY	모델이 함수 호출 ('강제 함수 호출')을 사용해야 합니다. 모델이 일부 함수만 예측하도록 제한하려면 allowedFunctionNames에 허용되는 함수 이름을 지정합니다.
NONE	모델이 함수 호출을 사용해서는 안 됩니다. 이 동작은 연결된 함수 선언이 없는 모델 요청과 동일합니다.

함수 호출 모드는 Gemini 1.5 Pro 및 Gemini 1.5 Flash에서 지원됩니다.

할 수 있는 다른 조치

Gemini API의 다른 기능 사용해 보기

• 멀티턴 대화 (채팅)를 빌드합니다.
• 텍스트 전용 프롬프트에서 텍스트를 생성합니다.
• 멀티모달 프롬프트(텍스트, 이미지, PDF, 동영상, 오디오 포함)에서 텍스트를 생성합니다.

콘텐츠 생성을 제어하는 방법 알아보기

• 권장사항, 전략, 프롬프트 예시를 포함하여 프롬프트 설계 이해하기
• 강도 및 최대 출력 토큰과 같은 모델 매개변수를 구성합니다.
• 안전 설정을 사용하여 유해하다고 간주될 수 있는 대답이 표시될 가능성을 조정합니다.

Vertex AI Studio를 사용하여 프롬프트 및 모델 구성을 실험할 수도 있습니다.

Gemini 모델 자세히 알아보기

다양한 사용 사례에 사용할 수 있는 모델과 할당량 및 가격에 대해 알아보세요.

Vertex AI in Firebase 사용 경험에 관한 의견 보내기