Panggilan alat ialah perkara yang menukar model menjadi ejen. Dengan model terbuka pada API yang serasi OpenAI, format permintaannya sama seperti yang anda gunakan dengan OpenAI. Yang berbeza ialah kekerapan sesuatu menjadi salah dan apa yang dilakukan oleh pelayan untuk mencegahnya. Artikel ini merangkumi format itu, cara menulis skema yang dikendalikan dengan baik oleh model terbuka, panggilan selari, lima kegagalan yang benar-benar akan anda lihat, dan gelung Python yang mampu menanganinya.
Bagaimanakah panggilan alat berfungsi pada API yang serasi OpenAI?
- Anda menghantar
messagesbersama senaraitools. Setiap tool mempunyai nama, penerangan dan JSON Schema untuk argumennya. - Model menjawab dengan
finish_reason: "tool_calls"dan senaraitool_calls. Setiap entri mempunyaiid, nama fungsi danargumentssebagai rentetan JSON. - Kod anda menjalankan setiap panggilan dan menambah satu mesej
role: "tool"bagi setiap panggilan, dengantool_call_idyang sepadan. - Anda memanggil API sekali lagi. Model menjawab atau meminta lebih banyak tool.
Model tidak pernah menjalankan apa-apa. Kod anda yang memutuskan apa yang dilaksanakan.
Bagaimanakah skema tool patut ditulis?
Model terbuka mengikut skema ringkas dengan lebih boleh dipercayai. Peraturan ini datang daripada panduan OpenAI dan daripada perkara yang biasanya rosak:
- Namakan tool mengikut tindakan, seperti
read_fileatausearch_code, dan nyatakan dalam penerangan bila setiap satu patut digunakan. - Kekalkan senarai pendek. Panduan OpenAI menyebut kurang daripada 20 fungsi pada permulaan satu giliran sebagai cadangan longgar. Setiap skema juga dihantar pada setiap panggilan; lihat bajet token ejen.
- Utamakan argumen rata. Rentetan, nombor, boolean dan enum. Elakkan sarang yang dalam dan objek bentuk bebas.
- Gunakan enum untuk pilihan tetap, supaya model tidak boleh mereka nilai. Penjana skema JSON menukar objek argumen sampel kepada skema rata yang boleh anda tampal ke dalam
parameters. - Tandakan medan wajib. Mod strict OpenAI memerlukan
additionalProperties: falsedan setiap medan dalamrequired, dengannullsebagai jenis bagi medan pilihan. Sama ada penyedia menguatkuasakanstrictberbeza-beza, jadi tetap sahkan.
Bagaimana pula dengan panggilan alat selari?
Model mungkin memulangkan beberapa entri dalam tool_calls dalam satu giliran, contohnya tiga bacaan fail. Jalankan panggilan yang bebas secara serentak dan pulangkan satu hasil bagi setiap tool_call_id, dalam sebarang susunan. Jika tool anda mempunyai kesan sampingan yang bergantung antara satu sama lain, tetapkan parallel_tool_calls: false; panduan OpenAI menyatakan itu mengehadkan model kepada sifar atau satu panggilan setiap giliran. Uji sama ada penyedia anda mematuhinya.
Mengapakah panggilan alat gagal?
| Kegagalan | Apa yang anda lihat | Pembaikan |
|---|---|---|
| Argumen rosak | json.loads menimbulkan ralat |
Pulangkan ralat hurai sebagai hasil tool; cuba semula |
| Tidak sepadan dengan skema | Medan hilang, jenis salah, enum rekaan | Sahkan; pulangkan ralat pengesahan |
| Tool tidak dikenali | Nama yang anda tidak pernah takrifkan | Pulangkan “unknown tool, available: …” |
| Tiada panggilan walaupun diperlukan | Jawapan teks sebaliknya | tool_choice: "required" atau fungsi bernama |
| Panggilan terpotong | finish_reason: "length" |
Naikkan max_tokens; penaakulan berkongsi had itu |
Dua yang pertama dijangka, bukan jarang berlaku. Dokumentasi tool calling vLLM menyatakan bahawa dalam mod auto, melainkan tool menetapkan strict: true (atau pelayan menguatkuasakan tahap ketegasan minimum) dan penghurai model menyokong kekangan, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (Terjemahan: vLLM mengekstrak panggilan alat daripada teks mentah, jadi argumen kadangkala rosak atau melanggar skema parameter fungsi.) Fungsi bernama menggunakan backend structured-outputs vLLM. Penyedia anda mungkin menghidangkan model secara berbeza, jadi anggap pengesahan sebagai wajib.
Baris terakhir memerangkap pengguna model penaakulan. GLM 5.3 dan Qwen3.8 27B berfikir sebelum menjawab, dan proses berfikir dikira dalam max_tokens. Mengapa jawapan kembali kosong atau terpotong menerangkan berapa banyak ruang yang perlu ditinggalkan.
Gelung tool yang mengesah dan mencuba semula
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 pilihan reka bentuk penting di sini:
- Ralat kembali kepada model sebagai hasil tool. Model melihat apa yang salah dan biasanya membetulkannya pada giliran seterusnya. Menimbulkan pengecualian membuang peluang itu.
- Gelung itu terhad.
max_stepsmenghentikan model yang terus memanggil tool tanpa kemajuan. - Cuba semula pengangkutan adalah berasingan.
max_retriespada klien mengendalikan 429 dan 5xx. Argumen yang salah dikendalikan dalam gelung. Jangan campurkan kedua-duanya; lihat ralat dan cuba semula.
Untuk tool yang mempunyai kesan sampingan, seperti menghantar e-mel, tambah kunci idempotensi supaya langkah yang dicuba semula tidak bertindak dua kali. Ejen yang berjalan lama membincangkan perkara ini.
Model BroadNet manakah yang menyokong panggilan alat?
| Model | Tools disenaraikan | Konteks | Nota |
|---|---|---|---|
| GLM 5.3 | Ya | 1,048,576 | Juga output berstruktur |
| Qwen3.8 27B | Ya | 262,144 | Juga input imej |
| DeepSeek V4.1 Flash | Tidak disenaraikan | 1,048,576 | Input imej; uji tools sebelum bergantung padanya |
| Gemma 4 VL 26B | Tidak disenaraikan | 32,768 | Bukan untuk gelung tool |
Untuk memilih antara dua model yang menyokong tool, lihat GLM 5.3 vs Qwen3.8 27B. Apabila jawapan akhir mesti mengikut sesuatu bentuk tetapi tiada fungsi perlu dijalankan, output berstruktur lebih mudah daripada tool.
Di manakah BroadNet Inference sesuai
BroadNet Inference menghidangkan GLM 5.3 dan Qwen3.8 27B dengan panggilan alat disenaraikan, melalui format chat-completions standard, jadi gelung di atas berjalan tanpa perubahan dengan OpenAI Python SDK. Harga setiap token ada di halaman harga. Ia tidak mengehos tool sisi pelayan seperti carian web atau pelaksanaan kod, dan dokumentasinya tidak menyenaraikan panggilan alat untuk DeepSeek V4.1 Flash, model pada pelan tanpa had. Untuk ejen yang banyak menggunakan tools, gunakan GLM 5.3 atau Qwen3.8 27B secara per token. Jika anda tetap mahukan pelan kadar tetap, semak pada satu jam Meteor $1 bahawa DeepSeek V4.1 Flash memanggil tools anda dengan boleh dipercayai sebelum membeli sebulan.
