Panduan inti

Structured Outputs & Tool Calling

Kembalikan JSON atau biarkan model memanggil fungsi di aplikasi Anda

Structured output meminta JSON dari model. Tool calling memungkinkan model untuk meminta fungsi yang dieksekusi oleh aplikasi Anda. Bidang yang tersedia bergantung pada format API dan model, jadi gunakan satu format yang konsisten di sepanjang percakapan dan validasi setiap nilai yang dihasilkan model di aplikasi Anda.

Pilih format API

KebutuhanAPIBidang
Respons objek JSON portabel/v1/chat/completionsresponse_format: {"type": "json_object"}
Pemanggilan fungsi yang kompatibel dengan OpenAI/v1/chat/completionstools: [{ "type": "function", "function": ... }]
Alat Respons OpenAI/v1/responsesBidang tools, tool_choice, dan text pada Respons
Penggunaan alat atau pemikiran native Claude/v1/messagesSkema alat Anthropic Messages
Deklarasi fungsi atau alat bawaan Gemini/v1beta/models/:model:generateContenttools dan bagian konten native Gemini

Gunakan alat bawaan hanya dengan format API yang mendokumentasikannya; TokenLab tidak mengonversi alat tersebut antar format.

Mode JSON

Untuk objek JSON yang berfungsi di berbagai model chat, gunakan mode JSON Chat Completions:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

Model yang mendukung mode JSON mencantumkan json-mode dalam capabilities di GET /v1/models. Chat Completions menerima text dan json_object. json_schema dan strict bersifat spesifik untuk model dan format; gunakan hanya jika model yang dipilih mendokumentasikan dukungannya.

Selalu lakukan parsing dan validasi JSON yang dikembalikan di server Anda. Mode JSON tidak menggantikan validasi skema di tingkat aplikasi.

Menyelesaikan tool call

TokenLab mengembalikan nama fungsi dan argumen; aplikasi Anda yang mengeksekusinya:

  1. Kirim pesan beserta definisi alat (tool definitions).
  2. Baca respons model untuk tool_calls, function_call, tool_use Anthropic, atau bagian pemanggilan fungsi Gemini.
  3. Eksekusi alat di backend Anda sendiri.
  4. Lampirkan hasil alat dalam format API yang sama.
  5. Lanjutkan percakapan hingga model memberikan jawaban akhir.

Gunakan format API yang sama hingga tool call dan jawaban akhir selesai. Keempat format tersebut merepresentasikan status alat dengan cara yang berbeda.

Contoh Chat Completions

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'
  • Buat skema yang ringkas dan eksplisit. Skema bersarang yang besar menambah token dan mengurangi keandalan.
  • Utamakan bidang wajib (required fields) untuk nilai yang tanpanya produk Anda tidak dapat berjalan.
  • Gunakan enum untuk kumpulan nilai tertutup yang bergantung pada UI atau backend Anda.
  • Sertakan contoh dalam prompt jika model kesulitan dengan bentuk skema.
  • Jika suatu bidang tidak didukung, hapus bidang tersebut atau gunakan format API yang mendokumentasikannya.

Sebelum mengeksekusi alat

  • Catat format API, model, nama alat, dan nama bidang skema.
  • Validasi argumen alat sebelum mengeksekusi efek samping apa pun.
  • Terapkan pemeriksaan izin Anda sendiri sebelum eksekusi alat.
  • Buat eksekusi alat menjadi idempoten jika percobaan ulang (retry) klien dapat mengulangi pemanggilan alat yang sama.
  • Jangan mencatat rahasia yang dikembalikan oleh alat ke dalam pesan yang dapat dilihat model.

Referensi API

TopikReferensi
API Multi-FormatMulti-Format API
Membuat Chat CompletionBuat Chat Completion
Membuat ResponsBuat Respons
Membuat PesanCreate Message
Menghasilkan Konten GeminiGenerate Gemini Content

Di halaman ini