Panggilan fungsi untuk model terbuka

Pemanggilan fungsi memungkinkan Anda menentukan fungsi kustom dan memberi LLM kemampuan untuk memanggilnya guna mengambil informasi real-time atau berinteraksi dengan sistem eksternal seperti database SQL atau alat layanan pelanggan.

Untuk mengetahui informasi konseptual selengkapnya tentang panggilan fungsi, lihat Pengantar panggilan fungsi.

Sebelum memulai

Untuk menggunakan model terbuka dengan Gemini Enterprise Agent Platform, Anda harus melakukan langkah-langkah berikut. Agent Platform API (aiplatform.googleapis.com) dan Cloud Commerce Consumer Procurement API (cloudcommerceconsumerprocurement.googleapis.com) harus diaktifkan untuk menggunakan model terbuka di Gemini Enterprise Agent Platform. Jika sudah memiliki project dengan API ini yang diaktifkan, Anda dapat menggunakan project tersebut, bukan membuat project baru.

  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. Buka kartu model Model Garden untuk model yang ingin Anda gunakan, lalu klik Enable guna mengaktifkan model untuk digunakan dalam project Anda.

    Buka Model Garden

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengaktifkan dan menggunakan model terbuka, minta administrator untuk memberi Anda peran IAM berikut pada project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Untuk mengetahui informasi selengkapnya tentang cara memberikan izin dan mengonfigurasi kebijakan organisasi untuk model terbuka, lihat Memberikan akses pengguna ke model terbuka.

Menggunakan pemanggilan fungsi

Contoh berikut menunjukkan cara menggunakan panggilan fungsi.

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Sebelum menjalankan contoh ini, pastikan untuk menetapkan variabel lingkungan OPENAI_BASE_URL. Untuk mengetahui informasi selengkapnya, lihat Autentikasi dan kredensial.

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: Nama model yang ingin Anda gunakan, misalnya zai-org/glm-5.2-maas.
  • CONTENT: Perintah pengguna yang akan dikirim ke model.
  • FUNCTION_NAME: Nama fungsi yang akan dipanggil.
  • FUNCTION_DESCRIPTION: Deskripsi fungsi.
  • PARAMETERS_OBJECT: Kamus yang menentukan parameter fungsi, misalnya:
    {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

REST

Setelah menyiapkan lingkungan, Anda dapat menggunakan REST untuk menguji perintah teks. Contoh berikut mengirimkan permintaan ke endpoint model penayang.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda.
  • MODEL: Nama model yang ingin Anda gunakan, misalnya zai-org/glm-5.2-maas.
  • CONTENT: Perintah pengguna yang akan dikirim ke model.
  • FUNCTION_NAME: Nama fungsi yang akan dipanggil.
  • FUNCTION_DESCRIPTION: Deskripsi fungsi.
  • PARAMETERS_OBJECT: Objek skema JSON yang menentukan parameter fungsi, misalnya:
    {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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

Anda akan menerima kode status berhasil (2xx) dan respons kosong.

Contoh

Berikut adalah output lengkap yang dapat Anda harapkan setelah menggunakan fungsi get_current_weather untuk mengambil informasi meteorologi.

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"
}'
Setelah menerima informasi yang diambil melalui pemanggilan fungsi `get_current_weather` eksternal, model dapat menggabungkan informasi dari dua respons `tool` dan menjawab pertanyaan pengguna. Berikut adalah contoh tampilan output model tersebut: 
{
 "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
 }
}

Panduan khusus model

Bagian berikut memberikan panduan khusus model untuk pemanggilan fungsi.

DeepSeek

Model DeepSeek tidak berperforma sebaik itu dalam pemanggilan fungsi jika Anda menggunakan perintah sistem. Untuk performa optimal, hapus perintah sistem saat menggunakan panggilan fungsi dengan model DeepSeek.

Llama

meta/llama3-405b-instruct-maas tidak mendukung tool_choice = 'required'.

OpenAI

Saat menggunakan openai/gpt-oss-120b-maas, tempatkan definisi alat Anda di perintah sistem untuk performa yang optimal. Contoh:

{"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?"},
    ...
]}

Model ini tidak mendukung tool_choice = 'required' atau panggilan alat bernama.

Langkah berikutnya