BroadRouter
Mulai

Tool calling dengan model terbuka: skema, panggilan paralel, retry

Oleh tim BroadNet Inference · 4 menit baca · Dipublikasikan · Diperbarui

Model terbuka di API yang kompatibel dengan OpenAI memakai format tools dan tool_calls yang sama dengan OpenAI. Buat skema kecil dan datar, parse argumen sebagai string JSON, validasi sebelum menjalankan apa pun, dan kembalikan error ke model sebagai hasil tool agar model bisa mencoba lagi. Batasi jumlah langkah. Di BroadNet, GLM 5.3 dan Qwen3.8 27B tercantum mendukung tools.

Tool calling adalah yang mengubah model menjadi agen. Dengan model terbuka di API yang kompatibel dengan OpenAI, format permintaannya sama dengan yang Anda pakai di OpenAI. Yang berbeda adalah seberapa sering terjadi masalah dan apa yang dilakukan server untuk mencegahnya. Artikel ini membahas formatnya, cara menulis skema yang ditangani model terbuka dengan baik, panggilan paralel, lima kegagalan yang benar-benar akan Anda temui, dan loop Python yang tahan terhadap semuanya.

Bagaimana tool calling bekerja di API yang kompatibel dengan OpenAI?

  1. Anda mengirim messages beserta daftar tools. Setiap tool punya nama, deskripsi, dan JSON Schema untuk argumennya.
  2. Model membalas dengan finish_reason: "tool_calls" dan daftar tool_calls. Setiap entri berisi id, nama fungsi, dan arguments sebagai string JSON.
  3. Kode Anda menjalankan setiap panggilan dan menambahkan satu pesan role: "tool" per panggilan, dengan tool_call_id yang cocok.
  4. Anda memanggil API lagi. Model menjawab atau meminta tool lain.

Model tidak pernah menjalankan apa pun. Kode Anda yang memutuskan apa yang dieksekusi.

Bagaimana sebaiknya menulis skema tool?

Model terbuka lebih andal mengikuti skema yang sederhana. Aturan berikut berasal dari panduan OpenAI dan dari hal-hal yang biasanya rusak:

  • Beri nama tool berdasarkan aksinya, misalnya read_file atau search_code, dan tulis di deskripsi kapan masing-masing dipakai.
  • Buat daftarnya pendek. Panduan OpenAI menyebut kurang dari 20 fungsi di awal satu giliran sebagai saran yang tidak mengikat. Setiap skema juga dikirim di setiap panggilan; lihat anggaran token agen.
  • Utamakan argumen datar. String, angka, boolean, dan enum. Hindari nesting dalam dan objek berbentuk bebas.
  • Pakai enum untuk pilihan tetap, agar model tidak bisa mengarang nilai. Generator JSON schema mengubah contoh objek argumen menjadi skema datar yang bisa Anda tempel ke parameters.
  • Tandai field wajib. Strict mode OpenAI mensyaratkan additionalProperties: false dan setiap field ada di required, dengan null sebagai tipe untuk field opsional. Apakah penyedia memaksakan strict atau tidak itu bervariasi, jadi tetap lakukan validasi.

Bagaimana dengan tool call paralel?

Model bisa mengembalikan beberapa entri di tool_calls dalam satu giliran, misalnya tiga pembacaan file. Jalankan panggilan yang saling independen secara bersamaan dan kembalikan satu hasil per tool_call_id, dalam urutan apa pun. Jika tool Anda punya efek samping yang saling bergantung, set parallel_tool_calls: false; panduan OpenAI menyebut itu membatasi model ke nol atau satu panggilan per giliran. Uji apakah penyedia Anda menghormatinya.

Kenapa tool call gagal?

Kegagalan Yang Anda lihat Solusi
Argumen rusak json.loads memunculkan exception Kembalikan error parse sebagai hasil tool; retry
Skema tidak cocok Field hilang, tipe salah, enum karangan Validasi; kembalikan error validasinya
Tool tidak dikenal Nama yang tidak pernah Anda definisikan Kembalikan “unknown tool, available: …”
Tidak memanggil saat diperlukan Malah menjawab dengan teks tool_choice: "required" atau fungsi bernama
Panggilan terpotong finish_reason: "length" Naikkan max_tokens; penalaran ikut memakainya

Dua yang pertama memang bisa diperkirakan, bukan hal langka. Dokumentasi tool calling vLLM menyebut bahwa dalam mode auto, kecuali sebuah tool menyetel strict: true (atau server memaksakan batas minimum strictness) dan parser model mendukung constraint, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (Terjemahan BroadRouter: vLLM mengekstrak tool call dari teks mentah, sehingga argumen sesekali bisa rusak atau melanggar skema parameter fungsi.) Fungsi bernama memakai backend structured outputs milik vLLM. Penyedia Anda mungkin menyajikan model dengan cara berbeda, jadi anggap validasi sebagai keharusan.

Baris terakhir sering menjebak pengguna model penalaran. GLM 5.3 dan Qwen3.8 27B berpikir dulu sebelum menjawab, dan proses berpikir itu dihitung ke dalam max_tokens. Kenapa balasan kosong atau terpotong menjelaskan berapa banyak ruang yang perlu disisakan.

Loop tool yang memvalidasi dan retry

import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up one order by its ID. Use when the user asks where an order is.",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}

def run_call(call):
    name = call.function.name
    if name not in IMPL:
        return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
    try:
        args = json.loads(call.function.arguments or "{}")
        validate(args, SCHEMAS[name])
    except (json.JSONDecodeError, ValidationError) as e:
        return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
    return str(IMPL[name](**args))

def agent(messages, max_steps=8):
    for _ in range(max_steps):
        r = client.chat.completions.create(model=MODEL, messages=messages,
                                           tools=TOOLS, max_tokens=4000)
        msg = r.choices[0].message
        if r.choices[0].finish_reason == "length":
            raise RuntimeError("Output limit reached; raise max_tokens")
        messages.append(msg.model_dump(exclude_none=True))
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            messages.append({"role": "tool", "tool_call_id": call.id,
                             "content": run_call(call)})
    raise RuntimeError("Step limit reached")

Tiga keputusan desain penting di sini:

  1. Error dikembalikan ke model sebagai hasil tool. Model melihat apa yang salah dan biasanya memperbaikinya di giliran berikutnya. Memunculkan exception membuang kesempatan itu.
  2. Loop-nya dibatasi. max_steps menghentikan model yang terus memanggil tool tanpa kemajuan.
  3. Retry di level transport dipisahkan. max_retries di client menangani 429 dan 5xx. Argumen yang buruk ditangani di dalam loop. Jangan campur keduanya; lihat error dan retry.

Untuk tool yang punya efek samping, seperti mengirim email, tambahkan idempotency key agar langkah yang di-retry tidak bertindak dua kali. Agen yang berjalan lama membahas hal ini.

Model BroadNet mana yang mendukung tool calling?

Model Tools tercantum Konteks Catatan
GLM 5.3 Ya 1.048.576 Juga output terstruktur
Qwen3.8 27B Ya 262.144 Juga input gambar
DeepSeek V4.1 Flash Tidak tercantum 1.048.576 Input gambar; uji tools sebelum mengandalkannya
Gemma 4 VL 26B Tidak tercantum 32.768 Bukan untuk loop tool

Untuk memilih di antara dua model yang mendukung tool, lihat GLM 5.3 vs Qwen3.8 27B. Jika jawaban akhir harus mengikuti bentuk tertentu tetapi tidak ada fungsi yang perlu dijalankan, output terstruktur lebih sederhana daripada tool.

Posisi BroadNet Inference

BroadNet Inference menyajikan GLM 5.3 dan Qwen3.8 27B dengan tool calling tercantum, lewat format chat-completions standar, sehingga loop di atas berjalan tanpa perubahan dengan OpenAI Python SDK. Harga per token ada di halaman harga. BroadNet tidak meng-host tool sisi server seperti web search atau eksekusi kode, dan dokumentasinya tidak mencantumkan tool calling untuk DeepSeek V4.1 Flash, model di paket unlimited. Untuk agen yang banyak memakai tools, gunakan GLM 5.3 atau Qwen3.8 27B dengan harga per token. Jika Anda tetap menginginkan paket harga tetap, pastikan dengan satu jam Meteor seharga $1 bahwa DeepSeek V4.1 Flash memanggil tools Anda dengan andal sebelum membeli paket bulanan.

Pertanyaan umum

Apakah model terbuka mendukung function calling?

Banyak yang mendukung, tetapi tergantung modelnya dan cara penyedia menyajikannya. Di BroadNet Inference, dokumentasinya mencantumkan tool calling untuk GLM 5.3 dan Qwen3.8 27B. Fitur ini tidak tercantum untuk DeepSeek V4.1 Flash atau Gemma 4 VL 26B.

Kenapa argumen tool call saya bukan JSON yang valid?

Kecuali server membatasi decoding, argumen dihasilkan sebagai teks lalu di-parse belakangan. Dokumentasi vLLM menyebut argumen yang diekstrak dari teks mentah sesekali bisa rusak. Tangkap error parse-nya dan kirim kembali sebagai hasil tool agar model bisa memperbaiki dirinya.

Bagaimana cara mematikan tool call paralel?

Dalam format OpenAI, set parallel_tool_calls ke false. Itu membatasi model ke nol atau satu tool call per giliran. Pastikan penyedia Anda menghormati field tersebut.

Kenapa model menjawab dengan teks alih-alih memanggil tool?

Dengan tool_choice auto, model yang memutuskan. Set tool_choice ke required, atau ke fungsi tertentu, jika panggilan wajib dilakukan. Periksa juga apakah deskripsi tool menyebutkan kapan tool itu dipakai.

Kenapa tool call saya terpotong?

Model penalaran menghitung proses berpikir ke dalam max_tokens. Batas yang kecil bisa mengakhiri balasan di tengah argumen. Cek finish_reason dan naikkan max_tokens.

Baca sebagai MarkdownTanya ChatGPTTanya ClaudeTanya Perplexity