개방형 모델의 함수 호출

함수 호출을 사용하면 커스텀 함수를 정의하고 LLM에 함수를 호출하여 실시간 정보를 검색하거나 SQL 데이터베이스 또는 고객 서비스 도구와 같은 외부 시스템과 상호작용하는 기능을 제공할 수 있습니다.

함수 호출에 관한 자세한 개념 정보는 함수 호출 소개를 참조하세요.

시작하기 전에

Gemini Enterprise Agent Platform에서 개방형 모델을 사용하려면 다음 단계를 수행해야 합니다. Gemini Enterprise Agent Platform에서 개방형 모델을 사용하려면 Agent Platform API(aiplatform.googleapis.com) 및 Cloud Commerce Consumer Procurement API(cloudcommerceconsumerprocurement.googleapis.com)를 사용 설정해야 합니다. 이러한 API가 사용 설정된 기존 프로젝트가 이미 있는 경우 새 프로젝트를 만드는 대신 해당 프로젝트를 사용할 수 있습니다.

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform and Cloud Commerce Consumer Procurement APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. 사용하려는 모델의 Model Garden 모델 카드로 이동한 다음 사용 설정을 클릭하여 프로젝트에서 사용할 수 있도록 모델을 사용 설정합니다.

    Model Garden으로 이동

필요한 역할

개방형 모델을 사용 설정하고 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

개방형 모델에 대한 권한 부여 및 조직 정책 구성에 대한 자세한 내용은 개방형 모델에 대한 사용자 액세스 권한 부여를 참조하세요.

함수 호출 사용

다음 샘플에서는 함수 호출을 사용하는 방법을 보여줍니다.

Python

이 샘플을 사용해 보기 전에 Agent Platform 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요.

Agent Platform에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

이 샘플을 실행하기 전에 OPENAI_BASE_URL 환경 변수를 설정해야 합니다. 자세한 내용은 인증 및 사용자 인증 정보를 참조하세요.

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="MODEL",
  messages=[
    {"role": "user", "content": "CONTENT"}
  ],
  tools=[
    {
      "type": "function",
      "function": {
        "name": "FUNCTION_NAME",
        "description": "FUNCTION_DESCRIPTION",
        "parameters": PARAMETERS_OBJECT,
      }
    }
  ],
  tool_choice="auto",
)
  • MODEL: 사용하려는 모델 이름입니다(예: zai-org/glm-5.2-maas).
  • CONTENT: 모델에 전송할 사용자 프롬프트입니다.
  • FUNCTION_NAME: 호출하려는 함수의 이름입니다.
  • FUNCTION_DESCRIPTION: 함수에 대한 설명입니다.
  • PARAMETERS_OBJECT: 함수 파라미터를 정의하는 사전입니다. 예를 들면 다음과 같습니다.
    {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

REST

환경을 설정하면 REST를 사용하여 텍스트 프롬프트를 테스트할 수 있습니다. 다음 샘플은 요청을 게시자 모델 엔드포인트에 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • MODEL: 사용하려는 모델 이름입니다(예: zai-org/glm-5.2-maas).
  • CONTENT: 모델에 전송할 사용자 프롬프트입니다.
  • FUNCTION_NAME: 호출하려는 함수의 이름입니다.
  • FUNCTION_DESCRIPTION: 함수에 대한 설명입니다.
  • PARAMETERS_OBJECT: 함수 파라미터를 정의하는 JSON 스키마 객체입니다. 예를 들면 다음과 같습니다.
    {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

HTTP 메서드 및 URL: 

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions

JSON 요청 본문: 

{
  "model": "MODEL",
  "messages": [
    {
      "role": "user",
      "content": "CONTENT"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "FUNCTION_NAME",
        "description": "FUNCTION_DESCRIPTION",
        "parameters": PARAMETERS_OBJECT
      }
    }
  ],
  "tool_choice": "auto"
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다. 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다. 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions" | Select-Object -Expand Content

성공 상태 코드(2xx)와 빈 응답을 받게 됩니다.

예시

get_current_weather 함수를 사용하여 기상 정보를 가져온 후 예상되는 전체 출력은 다음과 같습니다.

Python

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="zai-org/glm-5.2-maas",
  messages=[
    {
      "role": "user",
      "content": "Which city has a higher temperature, Boston or new Delhi and by how much in F?"
    },
    {
      "role": "assistant",
      "content": "I'll check the current temperatures for Boston and New Delhi in Fahrenheit and compare them. I'll call the weather function for both cities.",
      "tool_calls": [{"function":{"arguments":"{\"location\":\"Boston, MA\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"},{"function":{"arguments":"{\"location\":\"New Delhi, India\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"}]
    },
    {
      "role": "tool",
      "content": "The temperature in Boston is 75 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    },
    {
      "role": "tool",
      "content": "The temperature in New Delhi is 50 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    }
  ],
  tools=[
    {
      "type": "function",
      "function": {
        "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"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  tool_choice="auto"
)

curl

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/sample-project/locations/global/endpoints/openapi/chat/completions -d \
'{
  "model": "zai-org/glm-5.2-maas",
  "messages": [
    {
      "role": "user",
      "content": "Which city has a higher temperature, Boston or new Delhi and by how much in F?"
    },
    {
      "role": "assistant",
      "content": "I'll check the current temperatures for Boston and New Delhi in Fahrenheit and compare them. I'll call the weather function for both cities.",
      "tool_calls": [{"function":{"arguments":"{\"location\":\"Boston, MA\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"},{"function":{"arguments":"{\"location\":\"New Delhi, India\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"}]
    },
    {
      "role": "tool",
      "content": "The temperature in Boston is 75 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    },
    {
      "role": "tool",
      "content": "The temperature in New Delhi is 50 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "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"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}'
외부 `get_current_weather` 함수 호출을 통해 가져온 정보를 받은 후 모델은 두 `tool` 응답의 정보를 취합하여 사용자의 질문에 답변할 수 있습니다. 다음은 모델 출력의 예시입니다. 
{
 "choices": [
  {
   "finish_reason": "stop",
   "index": 0,
   "logprobs": null,
   "message": {
    "content": "Based on the current weather data:\n\n- **Boston, MA**: 75°F
    \n- **New Delhi, India**: 50°F  \n\n**Comparison**:
    \nBoston is **25°F warmer** than New Delhi.  \n\n**Answer**:
    \nBoston has a higher temperature than New Delhi by 25 degrees Fahrenheit.",
    "role": "assistant"
   }
  }
 ],
 "created": 1750450289,
 "id": "2025-06-20|13:11:29.240295-07|6.230.75.101|-987540014",
 "model": "zai-org/glm-5.2-maas",
 "object": "chat.completion",
 "system_fingerprint": "",
 "usage": {
  "completion_tokens": 66,
  "prompt_tokens": 217,
  "total_tokens": 283
 }
}

모델별 안내

다음 섹션에서는 함수 호출에 관한 모델별 안내를 제공합니다.

DeepSeek

시스템 프롬프트를 사용하는 경우 DeepSeek 모델이 함수 호출에서 제대로 작동하지 않습니다. 최적의 성능을 위해 DeepSeek 모델과 함께 함수 호출을 사용할 때는 시스템 프롬프트를 생략하세요.

Llama

meta/llama3-405b-instruct-maas는 tool_choice = 'required'를 지원하지 않습니다.

OpenAI

openai/gpt-oss-120b-maas를 사용할 때는 최적의 성능을 위해 시스템 프롬프트에 도구 정의를 배치하세요. 예를 들면 다음과 같습니다.

{"messages": [
    {"role": "system", "content": "You are a helpful assistant with access to the following functions. Use them if required:\n..."},
    {"role": "user", "content": "What's the weather like in Boston?"},
    ...
]}

이 모델은 tool_choice = 'required' 또는 명명된 도구 호출을 지원하지 않습니다.

다음 단계