Function Calling API

함수 호출은 관련성이 있는 상황별 답변을 제공하는 LLM 기능을 향상시킵니다.

Function Calling API를 사용하여 커스텀 함수를 생성형 AI 모델에 제공할 수 있습니다. 모델은 이러한 함수를 직접 호출하지 않지만 대신 함수 이름과 추천 인수를 지정하는 구조화된 데이터 출력을 생성합니다. 이 출력을 통해 외부 API 또는 정보 시스템(예: 데이터베이스, 고객 관계 관리 시스템, 문서 저장소)을 호출할 수 있습니다. LLM에서 응답 품질을 개선하는 데 결과 API 출력을 사용할 수 있습니다.

지원되는 모델:

Gemini 1.0 Pro
- gemini-1.0-pro
- gemini-1.0-pro-001
- gemini-1.0-pro-002
Gemini 1.5 Pro
- gemini-1.5-pro-preview-0409

제한사항:

제공할 수 있는 최대 함수 수는 64개입니다.
FunctionCallingConfig는 미리보기 버전이며 'gemini-1.5-pro-preview-0409'에서만 사용 가능합니다.

구문

PROJECT_ID = PROJECT_ID
REGION = REGION
MODEL_ID = MODEL_ID

curl

https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      ...
    }],
    "tools": [{
      "function_declarations": [
        {
          ...
        }
      ]
    }]
  }'

Python

gemini_model = GenerativeModel(
    MODEL_ID,
    generation_config=generation_config,
    tools=[
        Tool(
            function_declarations=[
                FunctionDeclaration(
                    ...
                )
            ]
        )
    ],
)

매개변수 목록

FunctionDeclaration

모델에서 JSON 입력을 생성할 수 있는 함수를 나타내는 OpenAPI 3.0 사양에서 정의된 함수 선언의 구조화된 표현입니다.

매개변수
`name`	`string` 호출하려는 함수의 이름입니다.
`description`	선택사항: `string` 함수 설명 및 용도입니다.
`parameters`	선택사항: `Schema` 이 함수의 매개변수를 OpenAPI JSON 스키마 객체 형식인 OpenAPI 3.0 사양으로 설명합니다.
`response`	선택사항: `Schema` 이 함수의 출력을 JSON 스키마 형식으로 설명합니다.

FunctionCallingConfig[미리보기]

이는 gemini-1.5-pro-preview-0409에서만 사용할 수 있는 함수 호출 기능을 사용하기 위한 추가 구성입니다.

매개변수

매개변수
`mode`	선택사항: `enum/string[]` `AUTO`: 기본 모델 동작으로, 모델이 함수 호출 또는 자연어 응답을 예측하도록 결정합니다. `NONE`: 모델에서 어떠한 함수 호출도 예측하지 않습니다. 모델 동작은 함수 선언을 전달하지 않는 경우와 동일합니다. `ANY`: 모델이 항상 단일 함수 호출을 예측하도록 제한됩니다. `allowed_function_names`가 설정되면 예측 함수 호출이 `allowed_function_names` 중 하나로 제한됩니다. 기본적으로 예측 함수 호출은 제공된 `function_declarations` 중 하나에서 시작됩니다.
`allowed_function_names`	선택사항: `string[]` 호출할 함수 이름입니다. `mode`가 `ANY`인 경우에만 설정합니다. 함수 이름은 `[FunctionDeclaration.name]`과 일치해야 합니다. 모드를 `ANY`로 설정하면 모델이 제공된 함수 이름 세트에서 함수 호출을 예측합니다.

mode

선택사항: enum/string[]

AUTO: 기본 모델 동작으로, 모델이 함수 호출 또는 자연어 응답을 예측하도록 결정합니다.
NONE: 모델에서 어떠한 함수 호출도 예측하지 않습니다. 모델 동작은 함수 선언을 전달하지 않는 경우와 동일합니다.
ANY: 모델이 항상 단일 함수 호출을 예측하도록 제한됩니다.

allowed_function_names가 설정되면 예측 함수 호출이 allowed_function_names 중 하나로 제한됩니다. 기본적으로 예측 함수 호출은 제공된 function_declarations 중 하나에서 시작됩니다.

allowed_function_names

선택사항: string[]

호출할 함수 이름입니다. mode가 ANY인 경우에만 설정합니다. 함수 이름은 [FunctionDeclaration.name]과 일치해야 합니다. 모드를 ANY로 설정하면 모델이 제공된 함수 이름 세트에서 함수 호출을 예측합니다.

스키마

스키마는 함수 호출에서 입력 및 출력 데이터의 형식을 정의하는 데 사용됩니다. OpenAPI 3.0 스키마 사양에서 정의된 함수 선언의 구조화된 표현입니다.

매개변수
유형	`string` Enum. 데이터 유형입니다. 다음 중 하나여야 합니다. `STRING` `INTEGER` `BOOLEAN` `NUMBER` `ARRAY` `OBJECT`
`description`	선택사항: `string` 데이터에 대한 설명입니다.
`enum`	선택사항: `string[]` enum 형식의 가능한 `Type.STRING` 요소 값입니다.
`items`	선택사항: `Schema[]` `Type.ARRAY` 요소의 스키마
`properties`	선택사항: `Schema` `Type.OBJECT` 속성의 스키마
`required`	선택사항: `string[]` `Type.OBJECT`의 필수 속성입니다.
`nullable`	선택사항: `bool` 값이 `null`인지 나타냅니다.

예시

PROJECT_ID = PROJECT_ID
REGION = REGION
MODEL_ID = MODEL_ID

기본 사용 사례

다음은 쿼리 및 함수 선언을 모델에 제출하는 방법에 대한 예시입니다.

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "What is the weather in Boston?"
      }]
    }],
    "tools": [{
      "function_declarations": [
        {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              }
            },
            "required": [
              "location"
            ]
          }
        }
      ]
    }]
  }'

Python

import vertexai
from vertexai.generative_models import (
    FunctionDeclaration,
    GenerativeModel,
    GenerationConfig,
    Part,
    Tool,
)

vertexai.init(project=PROJECT_ID, location=REGION)

# Specify a function declaration and parameters for an API request
get_current_weather_func = FunctionDeclaration(
    name="get_current_weather",
    description="Get the current weather in a given location",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"}},
    },
)

# Define a tool that includes the above get_current_weather_func
weather_tool = Tool(
    function_declarations=[get_current_weather_func],
)

gemini_model = GenerativeModel(
    MODEL_ID, generation_config={"temperature": 0}, tools=[weather_tool]
)
model_response = gemini_model.generate_content("What is the weather in Boston?")

print(model_response)

고급 사용 사례

다음 예시에서는 생성 구성과 도구 구성을 모델에 전달하는 방법을 보여줍니다. 함수 호출 구성을 사용하여 모델 출력이 항상 특정 함수 호출인지 확인할 수 있습니다. 이를 위해 함수 호출 모드를 ANY로 설정하고 허용되는 함수 이름을 allowed_function_names 매개변수에 지정합니다. allowed_function_names이 비어 있으면 제공된 함수 중 하나가 반환될 수 있습니다.

MODEL_ID = gemini-1.5-pro-preview-0409

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
      }]
    }],
    "tools": [{
      "function_declarations": [
        {
          "name": "get_product_sku",
          "description": "Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
          "parameters": {
            "type": "object",
            "properties": {
                "product_name": {"type": "string", "description": "Product name"}
            }
          }
        },
        {
          "name": "get_store_location",
          "description": "Get the location of the closest store",
          "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Location"}},
          }
        }
      ]
    }],
    "tool_config": {
        "function_calling_config": {
            "mode":"ANY",
            "allowed_function_names": ["get_product_sku"]
       }
    },
    "generationConfig": {
      "temperature": 0.95,
      "topP": 1.0,
      "maxOutputTokens": 8192
    }
  }'

Python

import vertexai
from vertexai.generative_models import (
    FunctionDeclaration,
    GenerativeModel,
    GenerationConfig,
    Part,
    Tool,
    ToolConfig,
)

vertexai.init(project=PROJECT_ID, location=REGION)

# Specify a function declaration and parameters for an API request
get_product_info_func = FunctionDeclaration(
    name="get_product_sku",
    description="Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {
            "product_name": {"type": "string", "description": "Product name"}
        },
    },
)

# Specify another function declaration and parameters for an API request
get_store_location_func = FunctionDeclaration(
    name="get_store_location",
    description="Get the location of the closest store",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "Location"}},
    },
)

# Define a tool that includes the above functions
retail_tool = Tool(
    function_declarations=[
        get_product_info_func,
        get_store_location_func,
    ],
)

# Define a tool config for the above functions
retail_tool_config = ToolConfig(
    function_calling_config=ToolConfig.FunctionCallingConfig(
        # ANY mode forces the model to predict a function call
        mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
        # List of functions that can be returned when the mode is ANY.
        # If the list is empty, any declared function can be returned.
        allowed_function_names=["get_product_sku"],
    )
)

generation_config = GenerationConfig(
    temperature=0.95, top_p=1.0, max_output_tokens=8192
)

gemini_model = GenerativeModel(
    MODEL_ID,
    generation_config=generation_config,
    tools=[retail_tool],
    tool_config=retail_tool_config,
)
model_response = gemini_model.generate_content(
    "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
)

print(model_response)

더 살펴보기

자세한 문서는 다음을 참조하세요.

함수 호출