BroadRouter
Başlayın

Açık modellerle araç çağırma: şema, paralel çağrı, yeniden deneme

BroadNet Inference ekibi · 4 dk okuma · Yayımlandı · Güncellendi

OpenAI uyumlu API'lerdeki açık modeller, OpenAI ile aynı tools ve tool_calls formatını kullanır. Şemaları küçük ve düz tutun, argümanları JSON dizesi olarak ayrıştırın, bir şey çalıştırmadan önce doğrulayın ve hataları modele araç sonucu olarak döndürün ki yeniden deneyebilsin. Adım sayısını sınırlayın. BroadNet'te araç desteği GLM 5.3 ve Qwen3.8 27B için listeleniyor.

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?

  1. messages ile birlikte bir tools listesi gönderirsiniz. Her aracın bir adı, bir açıklaması ve argümanları için bir JSON Schema’sı vardır.
  2. Model finish_reason: "tool_calls" ve bir tool_calls listesiyle yanıt verir. Her girdide bir id, bir fonksiyon adı ve JSON dizesi olarak arguments bulunur.
  3. Kodunuz her çağrıyı çalıştırır ve her çağrı için eşleşen tool_call_id ile bir role: "tool" mesajı ekler.
  4. 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_file veya search_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 parameters içine yapıştırabileceğiniz düz bir şemaya dönüştürür.
  • Zorunlu alanları işaretleyin. OpenAI’nin strict modu additionalProperties: false ister ve her alanın required içinde olmasını, isteğe bağlı olanlar için tür olarak null eklenmesini gerektirir. Bir sağlayıcının strict ayarı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:

  1. 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.
  2. Döngü sınırlıdır. max_steps, ilerleme kaydetmeden araç çağırmaya devam eden bir modeli durdurur.
  3. 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.

Sık sorulan sorular

Açık modeller function calling destekliyor mu?

Çoğu destekliyor, ama destek modele ve sağlayıcının onu nasıl sunduğuna bağlı. BroadNet Inference'ta belgeler araç çağırmayı GLM 5.3 ve Qwen3.8 27B için listeliyor. DeepSeek V4.1 Flash veya Gemma 4 VL 26B için listelemiyor.

Araç çağrısı argümanlarım neden geçersiz JSON?

Sunucu çözümlemeyi kısıtlamadıkça argümanlar metin olarak üretilir ve sonradan ayrıştırılır. vLLM belgeleri, ham metinden çıkarılan argümanların zaman zaman bozuk olabileceğini söylüyor. Ayrıştırma hatasını yakalayın ve modelin kendini düzeltebilmesi için araç sonucu olarak geri gönderin.

Paralel araç çağrılarını nasıl kapatırım?

OpenAI formatında parallel_tool_calls değerini false yapın. Bu, modeli tur başına sıfır veya bir araç çağrısıyla sınırlar. Sağlayıcınızın bu alanı dikkate aldığını kontrol edin.

Model neden araç çağırmak yerine metinle yanıt veriyor?

tool_choice auto olduğunda kararı model verir. Bir çağrı zorunluysa tool_choice değerini required veya belirli bir fonksiyon yapın. Araç açıklamasının ne zaman kullanılacağını söylediğinden de emin olun.

Araç çağrım neden yarıda kesiliyor?

Akıl yürüten modeller düşünmeyi max_tokens'tan düşer. Küçük bir sınır, yanıtı argümanların ortasında bitirebilir. finish_reason değerini kontrol edin ve max_tokens'ı yükseltin.

Markdown olarak okuChatGPT asistanına sorClaude asistanına sorPerplexity asistanına sor