1. 개요
Gemini의 함수 호출이란 무엇인가요?
Vertex AI Gemini API는 멀티모달 사용 사례를 위해 설계된 Google DeepMind에서 개발한 생성형 AI 모델 제품군입니다. 함수 호출은 개발자가 생성 모델에서 구조화된 데이터 출력을 더 쉽게 얻을 수 있는 Gemini 모델의 기능입니다.
그러면 개발자는 이러한 출력을 사용하여 다른 API를 호출하고 관련 응답 데이터를 모델에 반환할 수 있습니다. 즉, 함수 호출은 생성 모델을 외부 시스템에 연결하여 생성된 콘텐츠에 정확한 최신 정보가 포함되도록 하는 데 도움이 됩니다.
함수 호출 작동 방식
함수는 함수 선언을 사용하여 설명되므로 생성 모델이 함수 내의 목적과 매개변수를 이해하는 데 도움이 됩니다. 쿼리의 함수 선언을 생성 모델에 전달하면 모델은 관련 함수의 이름과 사용자 쿼리를 기반으로 하는 인수가 포함된 구조화된 객체를 반환합니다. 함수 호출을 사용하면 모델이 실제로 함수를 호출하지 않습니다. 대신 반환된 함수와 매개변수를 사용하여 원하는 언어, 라이브러리 또는 프레임워크에서 함수를 호출할 수 있습니다.
빌드할 항목
이 Codelab에서는 Vertex AI Gemini API와 Python을 사용하여 생성형 AI 파이프라인을 빌드합니다. 앱을 사용하여 사용자가 환율에 대해 질문하면 시스템이 외부 API에서 최신 데이터를 가져와 사용자에게 답변합니다.
학습할 내용
- Python 클라이언트 라이브러리를 사용하여 Gemini 모델과 상호작용하는 방법
- 함수 선언을 정의하고 도구로 등록하는 방법
- Gemini를 호출하고 함수 호출 응답을 얻는 방법
- 함수 응답을 Gemini에 반환하고 사용자에게 응답하는 방법
필요한 항목
- Google Cloud 프로젝트
- 브라우저(예: Chrome)
- Python 개발 환경(예: Colab 또는 Colab Enterprise)
2. 설정 및 요건
Gemini에서 함수 호출을 사용하려면 먼저 Vertex AI API를 사용 설정하고 최신 버전의 Vertex AI Python 클라이언트 라이브러리를 설치해야 합니다.
Vertex AI API 사용 설정
Vertex AI API를 사용 설정하려면 다음 단계를 따르세요.
- 브라우저에서 Vertex AI API 서비스 세부정보 페이지로 이동합니다.
- 사용 설정 버튼을 클릭하여 Google Cloud 프로젝트에서 Vertex AI API를 사용 설정합니다.
Vertex AI용 Python 클라이언트 라이브러리 설치
Vertex AI용 Python 클라이언트 라이브러리를 설치하려면 다음 단계를 따르세요.
- 개발 환경에서 터미널을 엽니다.
- Python 개발 환경이 유효한지 확인하고 필요한 경우 이 가이드라인을 참고하세요.
- 다음 명령어를 실행하여 Vertex AI용 Python 클라이언트 라이브러리를 설치합니다.
pip install --upgrade google-cloud-aiplatform - 노트북 환경에서 실행하는 경우 새로 설치된 패키지를 사용하려면 런타임/커널을 다시 시작해야 할 수도 있습니다.
이제 Vertex AI API를 사용할 준비가 되었습니다.
3. 문제 파악
대규모 언어 모델 또는 생성형 AI 모델과 상호작용하면서 실시간 또는 현재 정보에 관해 질문했는데 오래된 정보나 부정확한 정보로 대답한 적이 있으신가요?
지금 해볼까요? 먼저 관련 Python 패키지를 가져오고 Gemini 모델을 초기화합니다. Colab 또는 Colab Enterprise와 같은 Python 개발 환경에서 최신 버전의 Python용 Vertex AI SDK를 설치하여 다음 코드를 실행할 수 있습니다.
import vertexai
from vertexai.generative_models import GenerativeModel
model = GenerativeModel("gemini-1.5-pro-001")
이제 오늘 여러 통화의 환율에 대해 질문해 보겠습니다.
response = model.generate_content(
"What's the exchange rate for euros to dollars today?"
)
print(response.text)
이 모델은 다음과 같이 제한되거나 오래된 응답을 생성합니다.
As an AI language model, I don't have access to real-time currency exchange rates. However, as of my last update in September 2021, the approximate exchange rate between euros (EUR) and US dollars (USD) was: 1 EUR ≈ 1.18 USD Please note that currency exchange rates constantly fluctuate and can vary depending on various factors such as economic conditions, supply and demand, political events, and more. To obtain the most up-to-date and accurate exchange rate, I recommend using a reliable currency converter or financial website that provides live rates. [...]
최종 사용자가 이러한 유형의 응답을 받으면 컨텍스트를 전환하여 관심 있는 통화를 조회하고, 최신 환율을 가져오고, 직접 변환을 수행해야 합니다.
이상적으로 생성 모델 파이프라인은 사용자를 위해 이러한 작업의 일부 또는 전부를 처리할 수 있습니다. 다음 섹션에서는 외부 시스템을 호출할 수 있도록 생성 모델에서 구조화된 응답을 가져오는 일반적인 해결 방법을 시도해 보겠습니다.
4. 일반적인 해결 방법 시도
최신 정보나 외부 소스의 데이터가 필요한 시나리오에서 생성 모델을 사용할 때는 외부 API를 호출한 다음 생성 모델에 결과를 다시 피드하여 응답에 사용할 수 있습니다.
외부 시스템을 호출하기 전에 사용하기에 적합한 함수를 결정하고 사용자로부터 관련 매개변수를 추출하며 이 매개변수를 구조화된 데이터 객체에 넣어야 합니다. 여기에는 일반적으로 생성 모델이 유효한 구조화된 데이터를 출력하도록 강제하는 철저한 프롬프트 엔지니어링이 포함됩니다.
이전 섹션에서 했던 질문을 다시 살펴보고 모델에 대한 몇 가지 지침을 추가해 보겠습니다. Gemini 모델에 다음 요청을 전송해 보세요.
user_prompt = "What's the exchange rate from euros to US dollars today?"
response = model.generate_content("""
Your task is to extract parameters from the user's input and return it as a
structured JSON payload. The user will ask about the exchange rate and which
currency they are converting from and converting to.
User input: {user_prompt}
Please extract the currencies as parameters and put them in a JSON object.
""".format(user_prompt=user_prompt))
print(response.text)
이 결과는 다음과 같은 텍스트 응답으로, 유효한 JSON이 아니며 사용하기가 어렵습니다.
```json
{
"currency_from": "euros",
"currency_to": "US dollars"
}
```
특히 텍스트 응답의 첫 번째와 마지막 줄에는 코드 블록을 구분하는 백틱이 있고, 첫 번째 줄에는 언어 지정자가 포함되어 있으며, JSON 객체의 값은 통화 교환 API가 입력 매개변수로 사용할 수 있는 표준 3글자 통화 약어가 아닙니다.
Python을 사용하여 이 텍스트를 유효한 JSON 및 사전으로 후처리하거나, 프롬프트에 지침을 추가하거나, 원하는 출력의 예시를 하나 이상 제공하거나, 모델을 미세 조정하거나, JSON을 정리하도록 생성 모델을 다시 호출해 볼 수 있습니다.
하지만 더 결정론적인 방법이 있습니다. Gemini의 함수 호출을 사용하여 외부 서비스의 정보를 쿼리하고 최종 사용자에게 관련 응답을 반환하는 방법을 알아보세요.
5. 함수 호출 작동 방식
매개변수 추출 및 함수 호출을 시작하기 전에 함수 호출 단계와 런타임에 사용되는 구성요소를 살펴보겠습니다.
Gemini API에 대한 사용자 입력
사용자의 프롬프트는 Gemini API로 전송되며, 해당 Gemini 모델에 대한 API 호출에서 개발자는 Gemini 모델이 어떤 함수를 호출하고 어떻게 호출하는지 알 수 있도록 도구 내에 하나 이상의 함수 선언을 정의했습니다.
Gemini API가 함수 호출을 반환
Gemini는 사용자 입력 및 프롬프트의 내용에 따라 호출할 함수의 이름과 사용할 해당 매개변수가 포함된 구조화된 데이터가 포함된 함수 호출 응답을 반환합니다.
API 요청
그런 다음 함수 이름과 매개변수를 사용하여 외부 시스템 또는 API에서 정보를 검색하는 API 요청을 만듭니다. 이 API 요청 및 응답은 개발자가 애플리케이션 코드로 구현하며 Gemini API 및 SDK의 범위 밖에서 발생합니다. 예를 들어 Python의 requests 라이브러리를 사용하여 REST API를 호출하고 JSON 응답을 받을 수 있습니다. 또는 원하는 방식과 클라이언트 라이브러리를 사용하여 함수를 호출할 수 있습니다.
Gemini에 API 응답 반환
마지막으로, 최종 사용자의 초기 프롬프트에 대한 응답을 생성하거나 Gemini 모델에서 추가 정보가 필요하다고 판단할 경우 다른 함수 호출 응답을 호출할 수 있도록 API 응답을 다시 Gemini 모델에 전달합니다.
6. API 선택
이제 함수 호출의 전반적인 흐름과 구체적인 단계를 이해했으니 최신 통화 환율을 가져오는 생성형 AI 파이프라인을 빌드해 보겠습니다. 먼저 정보 소스로 사용할 API를 선택해야 합니다.
환율 앱의 경우 https://www.frankfurter.app/의 REST API를 사용하여 세계 환율에 대한 최신 정보를 가져옵니다.
이 REST API와 상호작용하기 위해 다음과 같이 Python에서 requests로 REST API를 호출할 수 있습니다.
import requests
url = "https://api.frankfurter.app/latest"
response = requests.get(url)
response.text
또는 다음과 같은 cURL 요청을 실행합니다.
curl https://api.frankfurter.app/latest
그러면 다음과 비슷한 응답이 반환됩니다.
{
"amount": 1,
"base": "EUR",
"date": "2023-12-20",
"rates": {
"AUD": 1.6186, "BGN": 1.9558, "BRL": 5.3287,
"CAD": 1.4609, "CHF": 0.946, "CNY": 7.8121,
"CZK": 24.538, "DKK": 7.4565, "GBP": 0.86555,
"HKD": 8.5439, "HUF": 385.23, "IDR": 16994,
"ILS": 3.9983, "INR": 91.06, "ISK": 150.3,
"JPY": 157.12, "KRW": 1425.62, "MXN": 18.6867,
"MYR": 5.0977, "NOK": 11.2895, "NZD": 1.7421,
"PHP": 60.991, "PLN": 4.3413, "RON": 4.9699,
"SEK": 11.129, "SGD": 1.4562, "THB": 38.252,
"TRY": 31.883, "USD": 1.0944, "ZAR": 20.111
}
}
Gemini의 함수 호출은 실제로 외부 API 호출을 실행하지 않으므로 사용하는 API 유형에 대한 제한이 없습니다. Cloud Run 서비스, Cloud 함수, Google Cloud 서비스에 대한 API 요청 또는 외부 REST API를 사용할 수 있습니다.
7. 함수 및 도구 정의
사용할 REST API를 선택했으므로 이제 API 사양을 정의하고 도구에 함수를 등록할 수 있습니다.
최신 버전의 Python용 Vertex AI SDK를 설치했는지 확인합니다.
그런 다음 Python SDK에서 필요한 모듈을 가져오고 Gemini 모델을 초기화합니다.
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerativeModel,
Part,
Tool,
)
model = GenerativeModel("gemini-1.5-pro-001")
REST API(https://api.frankfurter.app/)를 다시 살펴보면 다음과 같은 입력 매개변수가 허용되는 것을 확인할 수 있습니다.
매개변수 | 유형 | 설명 |
| 문자열 | 변환할 통화 |
| 문자열 | 변환할 통화 |
| 문자열 | 환율을 가져올 날짜입니다. |
이러한 매개변수를 사용할 경우 YAML 형식으로 된 이 REST API의 부분 OpenAPI 사양은 다음과 같습니다.
openapi: 3.0.0
info:
title: Frankfurter Exchange Rate API
description: This API provides current and historical exchange rates
version: 1.0.0
servers:
- url: https://api.frankfurter.app
paths:
/{date}:
get:
summary: Get the latest currency exchange rates.
parameters:
- name: date
in: path
description: Get currency rates for a specific date or 'latest' if a date is not specified
required: true
schema:
type: string
- name: from
in: query
description: The currency to convert from.
required: true
schema:
type: string
- name: to
in: query
description: The currency to convert to.
schema:
type: string
이제 Gemini용 Python SDK를 사용하여 이를 FunctionDeclaration로 등록해 보겠습니다.
get_exchange_rate_func = FunctionDeclaration(
name="get_exchange_rate",
description="Get the exchange rate for currencies between countries",
parameters={
"type": "object",
"properties": {
"currency_date": {
"type": "string",
"description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
},
"currency_from": {
"type": "string",
"description": "The currency to convert from in ISO 4217 format"
},
"currency_to": {
"type": "string",
"description": "The currency to convert to in ISO 4217 format"
}
},
"required": [
"currency_from",
"currency_date",
]
},
)
생성 모델은 선택할 함수와 함수 호출에서 매개변수를 채우는 방법을 결정하는 데 이 정보를 사용하므로 함수와 매개변수 설명에는 최대한 많은 세부정보를 사용해야 합니다.
마지막으로 함수 선언이 포함된 Tool를 정의합니다.
exchange_rate_tool = Tool(
function_declarations=[get_exchange_rate_func],
)
여기서는 도구 내에서 하나의 함수 선언을 사용하지만 도구에 하나 이상의 함수 선언을 등록할 수 있으며 모델은 런타임에 사용할 적절한 함수를 선택합니다. Python용 Gemini SDK의 FunctionDeclaration, Tool 및 관련 클래스에 관한 자세한 내용은 Gemini API의 함수 호출 문서를 참고하세요.
함수 및 도구 정의의 구성을 완료했습니다. 다음 섹션에서는 이 도구로 생성 모델을 호출하고 REST API를 호출하는 데 사용할 수 있는 함수 호출을 다시 가져옵니다.
8. 함수 호출 생성
이제 생성 모델에 프롬프트를 표시하고 정의한 tool를 포함할 수 있습니다.
prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""
response = model.generate_content(
prompt,
tools=[exchange_rate_tool],
)
응답 객체를 살펴보겠습니다.
print(response.candidates[0].content)
role: "model"
parts {
function_call {
name: "get_exchange_rate"
args {
fields {
key: "currency_to"
value {
string_value: "SEK"
}
}
fields {
key: "currency_from"
value {
string_value: "AUD"
}
}
fields {
key: "currency_date"
value {
string_value: "latest"
}
}
}
}
}
모델이 사용 가능한 함수 하나를 선택하고 매개변수와 함께 get_exchange_rate 함수의 함수 호출을 반환한 것으로 보입니다. 또한 매개변수의 형식이 우리가 원하는 대로 올바르게 지정되었습니다. 축하합니다. 생성 모델에서 구조화된 응답을 받았습니다.
다음 섹션에서는 응답의 정보를 사용하여 API 요청을 실행합니다.
9. API 요청
Gemini에서 함수를 호출하면 실제로 외부 API를 호출하지 않습니다. 그보다는 원하는 모든 언어, 라이브러리 또는 프레임워크를 자유롭게 사용할 수 있습니다.
여기에서는 Python의 requests 라이브러리를 사용하여 환율 REST API를 호출합니다.
Python 딕셔너리로 응답을 압축해제해 보겠습니다.
params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
params[key[9:]] = value
params
이제 requests 또는 다른 메서드를 호출할 수 있습니다.
import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text
그 결과 다음과 비슷한 응답이 표시됩니다.
'{"amount":1.0,"base":"AUD","date":"2024-01-16","rates":{"SEK":6.8682}}'
REST API의 응답에 오늘 날짜의 최신 환율 정보가 포함되어 있습니다. 다음 섹션에서는 이 정보를 모델에 다시 전달하여 사용자와 관련된 응답을 생성할 수 있도록 합니다.
10. 대답 생성
마지막으로 다음 대화 차례에서 함수 응답을 모델에 다시 전달하여 사용자에 대한 응답을 생성해 보겠습니다.
response = model.generate_content(
[
Content(role="user", parts=[
Part.from_text(prompt + """Give your answer in steps with lots of detail
and context, including the exchange rate and date."""),
]),
Content(role="function", parts=[
Part.from_dict({
"function_call": {
"name": "get_exchange_rate",
}
})
]),
Content(role="function", parts=[
Part.from_function_response(
name="get_exchange_rate",
response={
"content": api_response.text,
}
)
]),
],
tools=[exchange_rate_tool],
)
response.candidates[0].content.parts[0].text
함수 응답을 모델에 다시 전달하면 모델은 API 응답의 관련 정보와 함께 사용자의 프롬프트에 응답합니다.
The exchange rate from Australian dollars to Swedish krona on January 16, 2024, is 1 Australian dollar is equal to 6.8663 Swedish krona. So, 500 Australian dollars would be worth 500 * 6.8663 = 3,433.15 Swedish krona.
11. 전체 코드 예시 보기
이 시점에서 Cloud Run 서비스, Cloud 함수 또는 다른 Cloud 서비스를 사용하여 백엔드 API에 Python 코드를 배치하고 이 백엔드 API를 사용하여 모델 쿼리 및 API 호출을 수행하는 프런트엔드 앱을 배포할 수 있습니다.
다음은 최종 솔루션의 전체 코드 예입니다.
import requests
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerativeModel,
Part,
Tool,
)
model = GenerativeModel("gemini-1.5-pro-001")
get_exchange_rate_func = FunctionDeclaration(
name="get_exchange_rate",
description="Get the exchange rate for currencies between countries",
parameters={
"type": "object",
"properties": {
"currency_date": {
"type": "string",
"description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
},
"currency_from": {
"type": "string",
"description": "The currency to convert from in ISO 4217 format"
},
"currency_to": {
"type": "string",
"description": "The currency to convert to in ISO 4217 format"
}
},
"required": [
"currency_from",
"currency_date",
]
},
)
exchange_rate_tool = Tool(
function_declarations=[get_exchange_rate_func],
)
prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""
response = model.generate_content(
prompt,
tools=[exchange_rate_tool],
)
response.candidates[0].content
params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
params[key[9:]] = value
params
import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text
response = model.generate_content(
[
Content(role="user", parts=[
Part.from_text(prompt + """Give your answer in steps with lots of detail
and context, including the exchange rate and date."""),
]),
Content(role="function", parts=[
Part.from_dict({
"function_call": {
"name": "get_exchange_rate",
}
})
]),
Content(role="function", parts=[
Part.from_function_response(
name="get_exchange_rate",
response={
"content": api_response.text,
}
)
]),
],
tools=[exchange_rate_tool],
)
response.candidates[0].content.parts[0].text
이 구현에서는 생성 모델에 두 개의 요청을 사용했습니다. 하나는 함수 호출을 생성하는 요청과 다른 하나는 함수 응답을 반환하는 요청입니다. 이는 Gemini로 함수 호출과 함수 응답을 처리하는 한 가지 방법일 뿐입니다. 또한 함수 호출을 추가로 실행하여 쿼리에 대한 자세한 정보를 얻거나 함수 호출을 채팅 및 비동기 메서드와 함께 사용할 수도 있습니다.
추가 코드 샘플은 Gemini의 함수 호출을 위한 샘플 노트북을 참고하세요.
12. 축하합니다
Gemini의 함수 호출을 사용하여 Vertex AI Gemini API 및 Python과 함께 사용하는 생성형 AI 파이프라인을 빌드했습니다. 사용자가 환율에 대해 물으면 시스템이 외부 API에서 최신 데이터를 가져와 답변으로 응답합니다.
최종 사용자의 프롬프트가 주어지면 Gemini의 함수 호출은 적절한 함수를 선택하고, 프롬프트에서 매개변수를 추출하고, 외부 API 호출을 할 수 있도록 구조화된 데이터 객체를 반환합니다.
Gemini의 함수 호출 설계는 요약 및 콘텐츠 생성은 생성 모델에 맡기고 매개변수를 결정론적으로 추출하는 두 가지 이점을 모두 제공하도록 설계되었습니다. 파이프라인에서 다른 API 및 프롬프트를 자유롭게 사용해 보고 Vertex AI Gemini API와 관련하여 제공되는 다른 기능을 살펴보세요.
삭제
이 Codelab에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 다음 정리를 수행할 수 있습니다.
- 불필요한 Google Cloud 요금이 청구되지 않도록 하려면 Google Cloud 콘솔을 사용하여 필요하지 않은 프로젝트를 삭제하세요.
- Vertex AI용 API를 사용 중지하려면 Vertex AI API 서비스 세부정보 페이지로 이동하여 API 사용 중지를 클릭하고 확인합니다.
자세히 알아보기
다음 가이드와 리소스를 통해 대화형 AI와 생성형 AI에 대해 계속 알아보세요.
라이선스
이 작업물은 Creative Commons Attribution 2.0 일반 라이선스에 따라 사용이 허가되었습니다.