muse-spark-1.2-contributor ile araç çağrısı döngüsü kurma

Araç seçimini model, çalıştırma kararını uygulama verir

muse-spark-1.2-contributor ile araç çağrısı döngüsü, LLMTR’de meta/muse-spark-1.2-contributor kimliğiyle POST /v1/chat/completions üzerinden kurulur. Uygulama araç tanımlarını gönderir, dönen çağrıları denetler, izin verdiği fonksiyonları çalıştırır ve sonuçları yeni bir istekte modele iletir. Modelin bir fonksiyon adı üretmesi, o fonksiyona erişim yetkisi aldığı anlamına gelmez.

Muse için araç seçimi yalnızca tool_choice: auto ile kullanılabilir; alanı göndermemek de mümkündür. required, none ve isimli seçim LLMTR tarafından reddedilir. Dolayısıyla işin tamamlanması mutlaka bir araç sonucuna bağlıysa, bu koşulu uygulamanız kontrol etmelidir. İstemde aracı kullanmasını istemek bir yürütme garantisi değildir.

Önce Contributor veri sınırını belirleyin

Contributor katmanında gönderdiğiniz istemler ve aldığınız yanıtlar Meta’nın model eğitiminde kullanılabilir. Gizli, kişisel veya müşteri verisi göndermeyin. Bu uyarı araç sonuçlarını da kapsar: bir araçtan dönen içerik, konuşmaya eklendiğinde sonraki model isteğinin parçası olur.

Örnek bu nedenle yalnızca santimetreyi metreye çevirir; hesap, müşteri kaydı, dosya yolu veya dış servis kullanmaz. Kamuya açık bir belge bile e-posta adresleri içerebilir; yalnız belgenin erişilebilir olması yeterli bir veri kontrolü değildir. Gerçek bir entegrasyonda araç çıktısını modele aktarmadan önce gerekli alanlarla sınırlayın.

Geçmişte hangi mesajlar korunmalı?

function.arguments alanı bir JSON metnidir. Önce ayrıştırın; ardından alan adlarını, türlerini ve izin verilen aralıkları doğrulayın. Araç tanımındaki şema uygulamadaki bu kontrolün yerini tutmaz. Python JSON belgeleri de güvenilmeyen girdinin ayrıştırılmadan önce boyutunun sınırlandırılmasını önerir.

Her turda tool_calls alanına bakın. Araç çağrısı varsa dönen assistant mesajını geçmişe ekleyin; ardından her çağrı için aynı tool_call_id değerini taşıyan ayrı bir tool mesajı gönderin. Sonuç içeriği JSON nesnesi değil, serileştirilmiş metin olmalıdır.

Python ile sınırlı ve yan etkisiz bir döngü

LLMTR_BASE_URL değişkenine hesabınız için doğruladığınız, /v1 bölümünü içeren tam API taban adresini; LLMTR_API_KEY değişkenine LLMTR anahtarınızı tanımlayın. Bunlar doğrudan Meta erişim bilgileri değildir. Kod taban adrese yalnızca /chat/completions ekler; ikinci bir /v1 eklemez.

Bu öğretici örnek çalıştırıldığında ücretli model istekleri yapabilir; burada canlı çalıştırılmadı. En fazla üç model isteği ve ilk iki turda tur başına iki yerel araç işlemi vardır. Son turda tools ile tool_choice gönderilmez. 4096 token ve 45 saniye örnek uygulama ayarlarıdır, modelin garanti edilen sınırları değildir. Sonuç answer değişkeninde tutulur; içerik loglanmaz.

Yalnızca hassas olmayan birim dönüşümü için öğretici örnek

import json
import math
import os
from urllib.request import Request, urlopen

TOOL = {
    "type": "function",
    "function": {
        "name": "cm_to_m",
        "description": "Convert a nonnegative length from centimeters to meters.",
        "parameters": {
            "type": "object",
            "properties": {"cm": {"type": "number", "minimum": 0, "maximum": 100000}},
            "required": ["cm"],
            "additionalProperties": False,
        },
    },
}

def execute(call):
    if call.get("type") != "function":
        raise ValueError("Unsupported tool type")
    function = call["function"]
    if function["name"] not in {"cm_to_m"}:
        raise ValueError("Tool not allowed")
    raw = function["arguments"]
    if not isinstance(raw, str) or len(raw) > 256:
        raise ValueError("Invalid argument size")
    args = json.loads(raw)
    if type(args) is not dict or set(args) != {"cm"}:
        raise ValueError("Invalid argument fields")
    value = args["cm"]
    if type(value) not in (int, float) or not math.isfinite(value):
        raise ValueError("A finite number is required")
    if not 0 <= value <= 100000:
        raise ValueError("Length outside permitted range")
    return {"meters": value / 100}

def run():
    endpoint = os.environ["LLMTR_BASE_URL"].rstrip("/") + "/chat/completions"
    messages = [{"role": "user", "content": "250 santimetreyi cm_to_m aracıyla metreye çevir ve kısaca açıkla."}]
    seen_ids = set()
    for turn in range(3):
        payload = {
            "model": "meta/muse-spark-1.2-contributor",
            "messages": messages, "stream": False,
            "reasoning_effort": "minimal", "max_tokens": 4096,
        }
        if turn < 2:
            payload.update(tools=[TOOL], tool_choice="auto")
        request = Request(endpoint, data=json.dumps(payload).encode("utf-8"),
                          headers={"Authorization": "Bearer " + os.environ["LLMTR_API_KEY"],
                                   "Content-Type": "application/json"}, method="POST")
        with urlopen(request, timeout=45) as response:
            raw = response.read(1_000_001)
        if len(raw) > 1_000_000:
            raise RuntimeError("Response too large")
        choice = json.loads(raw)["choices"][0]
        message = choice["message"]
        calls = message.get("tool_calls") or []
        if choice.get("finish_reason") == "length":
            raise RuntimeError("Incomplete response")
        if not calls:
            text = message.get("content")
            if not isinstance(text, str) or not text.strip():
                raise RuntimeError("No final text")
            return text
        if turn == 2 or len(calls) > 2:
            raise RuntimeError("Tool budget exhausted")
        ids = [call["id"] for call in calls]
        if any(not isinstance(i, str) or not 1 <= len(i) <= 256 for i in ids):
            raise ValueError("Invalid call id")
        if len(set(ids)) != len(ids) or seen_ids.intersection(ids):
            raise ValueError("Repeated call id")
        results = [execute(call) for call in calls]
        seen_ids.update(ids)
        messages.append(message)
        for call_id, result in zip(ids, results):
            messages.append({"role": "tool", "tool_call_id": call_id,
                             "content": json.dumps(result, allow_nan=False)})
    raise RuntimeError("Turn budget exhausted")

if __name__ == "__main__":
    answer = run()

Hatalı çağrıyı yeniden denemeden önce sınıflandırın

Örnekte geçersiz JSON, fazla alan, sayısal metin, boolean, sonsuz sayı ve aralık dışı değer işlemi durdurur. İzinli listeden geçmeyen bir adla dinamik fonksiyon araması yapılmaz. Araç kodu dosya yazmaz ve kabuk komutu çalıştırmaz; modelin argümanlarına böyle yetkiler eklemeyin.

HTTP hataları da örnekte döngüyü keser. 400 durumunda aynı hatalı isteği tekrar göndermek çözüm değildir. 429 için yeniden deneme eklerseniz deneme sayısını ve beklemeyi sınırlayın; Contributor katmanında yük testi başlatmayın. Zaman aşımı sonrasında önceki isteğin hiç işlenmediğini varsaymayın.

Üretim akışına taşırken korunacak sınırlar

Birden çok aracın döndüğü turda hepsinin sonucu eşleşmeden sonraki modele geçmeyin. Yazma işlemleri ekleyecekseniz ayrıca kullanıcı yetkisi, işlem onayı ve tekrar çalıştırmayı önleyen işlem kimliği gerekir. Bu örnekteki çağrı kimliği kontrolü, kalıcı işlem tekilleştirmesinin yerine geçmez.

Tur sayısını, hata sınıfını ve raporlanan kullanım değerlerini izleyin; istemleri ve araç sonuçlarını loglamayın. Her model turu yeni bir istek olduğundan, yalnız ilk turun kullanımına bakmak toplam tüketimi eksik gösterir. Gereksiz büyük araç sonuçlarını sonraki isteğe taşımamak hem veri sınırını hem konuşma bütçesini korur.

Sık sorulan sorular

Model araç çağırmadan cevap verirse ne yapmalıyım?

Auto bunu mümkün kılar. İş kuralı araç kanıtı gerektiriyorsa metni doğrulanmış sonuç saymayın; akışı kontrollü şekilde durdurun veya işlemi uygulamanızın belirlediği yoldan yapın.

Araç kullanımını tool_choice none ile kapatabilir miyim?

Muse için hayır. O istekte tools ve tool_choice alanlarını göndermeyin. Yine de beklenmeyen bir araç çağrısını çalıştırmayacak uygulama kontrolünü koruyun.

Şema geçerli JSON döndürmeyi güvenlik açısından yeterli kılar mı?

Hayır. Geçerli JSON yanlış tür, ek alan veya yetkisiz işlem isteği taşıyabilir. İzinli araç listesi ve uygulamanın bağımsız doğrulaması birlikte gereklidir.

İlgili yazılar

• muse-spark-1.2-contributor: LLMTR model kimliği ve endpoint
• Muse Spark 1.2 Contributor nedir? Veri politikası ve standart katman

• meta/muse-spark-1.2-contributor
• Model kataloğu
• Gateway dokümantasyonu
• OpenAI / OpenRouter