Fine grained tool calling

Bu modül için tahmini süre: 11 dakika

Genel bakış

Claude’da tool use’u streaming ile birleştirdiğinizde, AI tool argümanlarını üretirken real-time güncellemeler alırsınız. Bu, daha duyarlı bir kullanıcı deneyimi yaratır; ancak perde arkasında nasıl çalıştığına dair anlaşılması gereken bazı önemli detaylar vardır. Bu derste input_json event’ini, default JSON validation davranışını ve fine_grained=True ile bu davranışın nasıl devre dışı bırakıldığını göreceksiniz.

Temel tool streaming

Streaming aktifken Claude isteğinizi işlerken farklı türde event’ler geri gönderir. Normal text generation için ContentBlockDelta gibi event’lere zaten aşinasınız. Tool use için ayrıca InputJsonEvent adında yeni bir event tipini yönetmeniz gerekir.

Her InputJsonEvent iki anahtar property içerir:

• partial_json — Tool argümanlarının bir parçasını temsil eden bir JSON chunk
• snapshot — Şimdiye kadar alınan tüm chunk’lardan inşa edilmiş kümülatif JSON

Streaming pipeline’ınızda bu event’leri şöyle yönetirsiniz:

for chunk in stream:
    if chunk.type == "input_json":
        # Process the partial JSON chunk
        print(chunk.partial_json)
        # Or use the complete snapshot so far
        current_args = chunk.snapshot

JSON validation nasıl çalışır

İşin ilginçleştiği yer burası. Anthropic API, Claude chunk’ları üretir üretmez size hemen göndermez. Bunun yerine chunk’ları buffer’da tutar ve önce doğrular.

API bir şey göndermeden önce tam top-level key-value çiftlerini bekler. Örneğin tool’unuz şu yapıyı bekliyorsa:

{
  "abstract": "This paper presents a novel...",
  "meta": {
    "word_count": 847,
    "review": "This paper introduces QuanNet..."
  }
}

API şunu yapacaktır:

1. Tüm abstract değeri tamamlanana kadar bekler
2. O key-value çiftini schema’nıza karşı doğrular
3. abstract için buffer’daki tüm chunk’ları aynı anda gönderir
4. meta object’i için süreci tekrarlar

Bu validation süreci, streaming aktif olsa bile neden gecikmelerin ardından text patlamaları gördüğünüzü açıklar. Chunk’lar, geçerli bir top-level key-value çift tamamlanana kadar geri tutulur.

Fine-grained tool calling

Daha hızlı, daha granüler bir streaming’e ihtiyacınız varsa — belki kullanıcılara anında güncelleme göstermek veya kısmi sonuçları hızlıca işlemeye başlamak için — fine-grained tool calling’i etkinleştirebilirsiniz.

Fine-grained tool calling tek bir şey yapar: API tarafındaki JSON validation’ı devre dışı bırakır. Bu şu demektir:

• Claude’un ürettiği anda chunk’ları alırsınız
• Top-level key’ler arasında buffering gecikmesi yoktur
• Daha geleneksel streaming davranışı
• Kritik: JSON validation devre dışıdır — kodunuz invalid JSON’ı yönetmek zorundadır

API çağrınıza fine_grained=True ekleyerek etkinleştirin:

run_conversation(
    messages, 
    tools=[save_article_schema], 
    fine_grained=True
)

Fine-grained tool calling ile, word_count değerini tüm meta object’in tamamlanmasını beklemeden stream’de çok daha erken alabilirsiniz.

Invalid JSON’ı yönetmek

Fine-grained tool calling kullanırken Claude düzgün bir number yerine "word_count": undefined gibi invalid JSON üretebilir. Uygulamanızın bu durumları zarif şekilde yönetmesi gerekir:

try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # Handle invalid JSON appropriately
    print("Received invalid JSON, continuing...")

Fine-grained tool calling olmadan API’nin validation’ı bu hatayı yakalardı ve sorunlu değerleri string’lere sarabilirdi; bu beklenen schema’nızla uyuşmayabilir.

Fine-grained tool calling ne zaman kullanılır

Şu durumlarda fine-grained tool calling’i etkinleştirmeyi düşünün:

• Kullanıcılara tool argüman üretiminin real-time progress’ini göstermeniz gerektiğinde
• Kısmi tool sonuçlarını mümkün olduğunca hızlı işlemeye başlamak istediğinizde
• Buffering gecikmeleri kullanıcı deneyiminizi olumsuz etkilediğinde
• Sağlam JSON error handling implement etmekte rahat olduğunuzda

Çoğu uygulama için validation’lı default davranış yeterlidir. Ancak ekstra responsiveness’a ihtiyacınız olduğunda fine-grained tool calling, Claude üretebildiği kadar hızlı chunk almanın kontrolünü size verir.

Temel çıkarımlar

• Tool streaming’de yeni event tipi InputJsonEvent; partial_json ve snapshot property’leri taşır
• Default davranış: API top-level key-value çift tamamlanana kadar chunk’ları buffer’da tutup validate eder
• Bu nedenle streaming aktif olsa bile gecikme + patlama şeklinde gelen burst’ler görürsünüz
• fine_grained=True server-side JSON validation’ı kapatır; chunk’lar oluştukları anda gelir
• Trade-off: latency düşer ama uygulama tarafında invalid JSON ve JSONDecodeError ile başa çıkmalısınız
• Default mode çoğu use case için yeterli; fine-grained, gerçek zamanlı progress UI veya partial result işleme için tercih edilir