BroadRouter
Mulakan

Tool calling pada model terbuka: skema, panggilan selari, cuba semula

Oleh pasukan BroadNet Inference · 4 minit bacaan · Diterbitkan · Dikemas kini

Model terbuka pada API yang serasi OpenAI menggunakan format tools dan tool_calls yang sama seperti OpenAI. Kekalkan skema kecil dan rata, hurai argumen sebagai rentetan JSON, sahkan sebelum menjalankan apa-apa, dan pulangkan ralat kepada model sebagai hasil tool supaya ia boleh mencuba semula. Hadkan bilangan langkah. Di BroadNet, GLM 5.3 dan Qwen3.8 27B menyenaraikan sokongan tool.

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?

  1. Anda menghantar messages bersama senarai tools. Setiap tool mempunyai nama, penerangan dan JSON Schema untuk argumennya.
  2. Model menjawab dengan finish_reason: "tool_calls" dan senarai tool_calls. Setiap entri mempunyai id, nama fungsi dan arguments sebagai rentetan JSON.
  3. Kod anda menjalankan setiap panggilan dan menambah satu mesej role: "tool" bagi setiap panggilan, dengan tool_call_id yang sepadan.
  4. 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_file atau search_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: false dan setiap medan dalam required, dengan null sebagai jenis bagi medan pilihan. Sama ada penyedia menguatkuasakan strict berbeza-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:

  1. Ralat kembali kepada model sebagai hasil tool. Model melihat apa yang salah dan biasanya membetulkannya pada giliran seterusnya. Menimbulkan pengecualian membuang peluang itu.
  2. Gelung itu terhad. max_steps menghentikan model yang terus memanggil tool tanpa kemajuan.
  3. Cuba semula pengangkutan adalah berasingan. max_retries pada 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.

Soalan lazim

Adakah model terbuka menyokong function calling?

Banyak yang menyokong, tetapi sokongan bergantung pada model dan cara penyedia menghidangkannya. Di BroadNet Inference, dokumentasi menyenaraikan panggilan alat untuk GLM 5.3 dan Qwen3.8 27B. Ia tidak disenaraikan untuk DeepSeek V4.1 Flash atau Gemma 4 VL 26B.

Mengapakah argumen panggilan alat saya ialah JSON tidak sah?

Melainkan pelayan mengekang penyahkodan, argumen dijana sebagai teks dan dihurai kemudian. Dokumentasi vLLM menyatakan argumen yang diekstrak daripada teks mentah kadangkala rosak. Tangkap ralat hurai itu dan hantar semula sebagai hasil tool supaya model boleh membetulkan dirinya.

Bagaimanakah saya mematikan panggilan alat selari?

Dalam format OpenAI, tetapkan parallel_tool_calls kepada false. Itu mengehadkan model kepada sifar atau satu panggilan alat setiap giliran. Semak sama ada penyedia anda mematuhi medan itu.

Mengapakah model menjawab dalam teks dan bukannya memanggil tool?

Dengan tool_choice auto, model yang membuat keputusan. Tetapkan tool_choice kepada required, atau kepada fungsi tertentu, apabila panggilan itu wajib. Semak juga sama ada penerangan tool menyatakan bila ia patut digunakan.

Mengapakah panggilan alat saya terpotong?

Model penaakulan mengira proses berfikir dalam max_tokens. Had yang kecil boleh menamatkan jawapan di tengah-tengah argumen. Semak finish_reason dan naikkan max_tokens.

Baca sebagai MarkdownTanya ChatGPTTanya ClaudeTanya Perplexity