Araç çağırma, bir modeli ajana dönüştüren şeydir. OpenAI uyumlu bir API üzerindeki açık modellerde istek formatı, OpenAI ile kullanacağınızın aynısıdır. Farklı olan, işlerin ne sıklıkla ters gittiği ve sunucunun bunu önlemek için ne yaptığıdır. Bu yazı formatı, açık modellerin iyi işlediği şemaların nasıl yazılacağını, paralel çağrıları, gerçekte göreceğiniz beş hatayı ve bunlara dayanan bir Python döngüsünü ele alıyor.
OpenAI uyumlu bir API’de araç çağırma nasıl çalışır?
messagesile birlikte birtoolslistesi gönderirsiniz. Her aracın bir adı, bir açıklaması ve argümanları için bir JSON Schema’sı vardır.- Model
finish_reason: "tool_calls"ve birtool_callslistesiyle yanıt verir. Her girdide birid, bir fonksiyon adı ve JSON dizesi olarakargumentsbulunur. - Kodunuz her çağrıyı çalıştırır ve her çağrı için eşleşen
tool_call_idile birrole: "tool"mesajı ekler. - API’yi yeniden çağırırsınız. Model yanıt verir ya da başka araçlar ister.
Model hiçbir şeyi kendisi çalıştırmaz. Neyin çalıştırılacağına kodunuz karar verir.
Araç şemaları nasıl yazılmalı?
Açık modeller basit şemaları daha güvenilir şekilde izler. Bu kurallar OpenAI’nin rehberinden ve genellikle neyin bozulduğundan geliyor:
- Araçlara eyleme göre ad verin, örneğin
read_fileveyasearch_code, ve açıklamada her birinin ne zaman kullanılacağını söyleyin. - Listeyi kısa tutun. OpenAI’nin rehberi, bir turun başında 20’den az fonksiyonu esnek bir öneri olarak sunuyor. Her şema her çağrıda da gönderilir; bkz. ajan token bütçesi.
- Düz argümanları tercih edin. Dizeler, sayılar, boolean’lar ve enum’lar. Derin iç içe yapılardan ve serbest biçimli nesnelerden kaçının.
- Sabit seçenekler için enum kullanın; böylece model bir değer uyduramaz. JSON şema oluşturucu, örnek bir argüman nesnesini
parametersiçine yapıştırabileceğiniz düz bir şemaya dönüştürür. - Zorunlu alanları işaretleyin. OpenAI’nin strict modu
additionalProperties: falseister ve her alanınrequirediçinde olmasını, isteğe bağlı olanlar için tür olaraknulleklenmesini gerektirir. Bir sağlayıcınınstrictayarını zorlayıp zorlamadığı değişir; bu yüzden her durumda doğrulayın.
Paralel araç çağrıları ne olacak?
Bir model tek turda tool_calls içinde birden fazla girdi döndürebilir, örneğin üç dosya okuma. Bağımsız çağrıları eşzamanlı çalıştırın ve her tool_call_id için, herhangi bir sırayla, bir sonuç döndürün. Araçlarınızın birbirine bağlı yan etkileri varsa parallel_tool_calls: false ayarlayın; OpenAI’nin rehberi bunun modeli tur başına sıfır veya bir çağrıyla sınırladığını söylüyor. Sağlayıcınızın bunu dikkate aldığını test edin.
Araç çağrıları neden başarısız olur?
| Hata | Gördüğünüz | Çözüm |
|---|---|---|
| Bozuk argümanlar | json.loads hata fırlatır |
Ayrıştırma hatasını araç sonucu olarak döndürün; yeniden deneyin |
| Şema uyuşmazlığı | Eksik alan, yanlış tür, uydurulmuş enum | Doğrulayın; doğrulama hatasını döndürün |
| Bilinmeyen araç | Hiç tanımlamadığınız bir ad | “unknown tool, available: …” döndürün |
| Gerektiği halde çağrı yok | Bunun yerine metin yanıtı | tool_choice: "required" veya adı belirtilmiş bir fonksiyon |
| Kesilmiş çağrı | finish_reason: "length" |
max_tokens’ı yükseltin; akıl yürütme de bu sınırı paylaşır |
İlk ikisi nadir değil, beklenen durumlardır. vLLM’nin araç çağırma belgeleri, auto modunda, bir araç strict: true ayarlamadıkça (veya sunucu bir katılık alt sınırı zorlamadıkça) ve modelin ayrıştırıcısı kısıtlamaları desteklemedikçe şunu söylüyor: “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (BroadRouter çevirisi: vLLM araç çağrılarını ham metinden çıkarır, bu yüzden argümanlar zaman zaman bozuk olabilir veya fonksiyonun parametre şemasını ihlal edebilir.) Adı belirtilmiş bir fonksiyon, vLLM’nin structured-outputs arka ucunu kullanır. Sağlayıcınız modelleri farklı şekilde sunuyor olabilir; bu yüzden doğrulamayı zorunlu sayın.
Son satır, akıl yürüten modeller kullananları yakalar. GLM 5.3 ve Qwen3.8 27B yanıt vermeden önce düşünür ve düşünme max_tokens’tan düşülür. Yanıtlar neden boş ya da kesik gelir rehberi ne kadar yer bırakmanız gerektiğini açıklıyor.
Doğrulayan ve yeniden deneyen bir araç döngüsü
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")
Burada üç tasarım tercihi önemli:
- Hatalar modele araç sonucu olarak geri gider. Model neyin yanlış olduğunu görür ve genellikle bir sonraki turda düzeltir. Bir istisna fırlatmak bu şansı ortadan kaldırır.
- Döngü sınırlıdır.
max_steps, ilerleme kaydetmeden araç çağırmaya devam eden bir modeli durdurur. - Aktarım katmanı yeniden denemeleri ayrıdır. İstemcideki
max_retries, 429 ve 5xx hatalarını ele alır. Hatalı argümanlar döngüde ele alınır. İkisini karıştırmayın; bkz. hatalar ve yeniden denemeler.
E-posta göndermek gibi yan etkisi olan araçlar için bir idempotency anahtarı ekleyin; böylece yeniden denenen bir adım aynı işi iki kez yapmaz. Uzun süre çalışan ajanlar yazısı bunu ele alıyor.
Hangi BroadNet modelleri araç çağırmayı destekliyor?
| Model | Araç desteği listelenmiş mi | Bağlam | Notlar |
|---|---|---|---|
| GLM 5.3 | Evet | 1.048.576 | Yapılandırılmış çıktı da var |
| Qwen3.8 27B | Evet | 262.144 | Görsel girdi de var |
| DeepSeek V4.1 Flash | Listelenmemiş | 1.048.576 | Görsel girdi; araçlara güvenmeden önce test edin |
| Gemma 4 VL 26B | Listelenmemiş | 32.768 | Araç döngüleri için değil |
Araç destekli iki model arasında seçim yapmak için GLM 5.3 vs Qwen3.8 27B karşılaştırmasına bakın. Nihai yanıtın belirli bir yapıya uyması gerekiyor ama hiçbir fonksiyonun çalışması gerekmiyorsa, yapılandırılmış çıktı bir araçtan daha basittir.
BroadNet Inference’ın yeri
BroadNet Inference, araç çağırması listelenmiş GLM 5.3 ve Qwen3.8 27B modellerini standart chat-completions formatıyla sunar; bu yüzden yukarıdaki döngü OpenAI Python SDK ile değiştirilmeden çalışır. Token başına fiyatlar fiyatlandırma sayfasında. Web araması veya kod çalıştırma gibi sunucu tarafı araçlar barındırmaz ve belgeleri, sınırsız planlardaki model olan DeepSeek V4.1 Flash için araç çağırmayı listelemez. Araç ağırlıklı bir ajan için token başına GLM 5.3 veya Qwen3.8 27B kullanın. Yine de sabit planı istiyorsanız, bir ay satın almadan önce $1 karşılığında bir Meteor saatinde DeepSeek V4.1 Flash’ın araçlarınızı güvenilir biçimde çağırdığını kontrol edin.
