Araç Şeması Sapması (Schema Drift): Pydantic Doğrulaması ve Otomatik Hata Düzeltme

Senior (L5)

⚡ÖZET VE TEKNİK CEVAP

Canlı yapay zeka sistemlerinde LLM'ler kodu doğrudan çalıştırmaz; arka plan API araçlarını besleyecek JSON metinleri üretir (kullanici_olustur(ad: str, yas: int)). Zamanla yazılımcılar araç şemalarını günceller (yeni zorunlu alanlar ekler, enum listelerini değiştirir); bu durum Araç Şeması Sapmasına (Schema Drift) yol açar. Ayrıca modeller sıklıkla yanlış veri tipleri uydurur ('yas': 'yirmibes' veya eksik alanlar). Bu ham JSON doğrudan API'a verilirse sistem çöker. Sağlam ajan mimarileri, LLM ile araç arasına Pydantic / Zod Doğrulama Kalkanı yerleştirir: Doğrulama patladığında, Pydantic'in ürettiği net hata mesajı (ValidationError: yas alanı geçerli bir tamsayı olmalıdır) araca ait bir hata olarak LLM'e geri beslenir. Model bu net hatayı okuyarak bir sonraki adımda şemayı %95'in üzerinde başarıyla kendi kendine düzeltir.

Mühendislik El Kitabı & Mekanizma

6 Boyutlu Mimari Analiz

⚙️1. Temel Çalışma Mekanizması

Mekanizma

Pydantic araç doğrulama ve hata düzeltme döngüsü 4 adımda işler:

Dinamik Şema Üretimi: LLM prompt'undaki araç tanımları doğrudan Pydantic modellerinden (model_json_schema()) otomatik üretilir; kod ile prompt daima senkron kalır.

Yakalama ve Doğrulama: LLM bir araç çağırdığında sistem model_validate_json() ile doğrulamayı dener.

Hata Formatlama: Doğrulama başarısız olursa, hatalı alan ve kural ihlali anlaşılır bir metne dönüştürülür.

Geri Besleme Turu: Hata ajana geri verilir: [Araç Hatası]: 'iade_tutari pozitif bir sayı olmalıdır, -50.0 girildi. Lütfen parametreleri düzeltin.' Model hatasını anlayıp parametreleri düzelterek aracı tekrar çağırır.

🎯2. Doğru Kullanım Senaryosu

Kapsam

Kurumsal iş akışı otomasyonları, bankacılık ve fintech işlem ajanları, CRM güncelleme boru hatları ve geliştirici CLI araçları.

⚠️3. Prodüksiyon Arıza Modları

Kritik Risk

✓
Doğrulanmamış LLM JSON çıktılarını doğrudan veritabanı sorgularına veya ORM modellerine verip sunucu çökmelerine yol açmak
✓
düzeltilemeyen bir şema hatasında ajana sınırsız deneme hakkı verip jetonları sonsuz döngüde yakmak

📡4. Teşhis ve Telemetri Sinyalleri

Metrikler

✓
Araç çalıştırma loglarında TypeError veya KeyError hatalarının patlaması
✓
Langfuse izlerinde araç retry sayısının artması
✓
arka plan API güncellemesi sonrasında ajan başarı oranlarının düşmesi

🛡️5. Önleme ve Mimari Bariyerler

Bariyerler

✓
Tüm araç parametrelerini açıklayıcı docstring'lere sahip Pydantic v2 / Zod modelleriyle tanımlayın
✓
otomatik düzeltme denemelerini en fazla 2 ile sınırlayın
✓
CI/CD testlerinde araç şemalarının canlı API'larla uyumunu doğrulayan birim testler çalıştırın

⚖️6. Mimari Ödünleşimler (Trade-offs)

Ödünleşim

Yapılandırılmış doğrulama katı tip modelleri yazmayı gerektirir ve hatalarda 1 turluk ek gecikme maliyeti getirir; ancak %100 tip güvenliği sağlar ve arka plan servislerinin çökmesini önler.

📋

Vaka İncelemesi (TinyCTO Saha Örneği)

GERÇEK DÜNYA TELEMETRİSİ

Bir CRM asistanı kurumsal_lider_olustur(email: EmailStr, sirket_buyuklugu: Literal['1-10', '11-50', '50+']) aracıyla çalışıyordu. İsteklerin %8'inde model sirket_buyuklugu: 'orta' gönderiyor ve CRM API'si 400 hatasıyla patlıyordu. Ekip aracı Pydantic v2 kalkanıyla sardı. Model 'orta' ürettiğinde Pydantic hatayı yakaladı ve ajana 'sirket_buyuklugu sadece ["1-10", "11-50", "50+"] olabilir, "orta" girildi' mesajını döndü. Ajan 2. adımda değeri '11-50' olarak düzeltti ve işlem başarı oranı %99,8'e ulaştı.

İnteraktif Konsept Alıştırmaları

2 Alıştırma

Yapay zeka ajan mühendisliğinde 'Araç Şeması Sapması' (Tool Schema Drift) nedir?

Arka plan API parametreleri veya kuralları güncellendiğinde, LLM'in prompt'undaki araç tanımlarının eski kalması sonucu ortaya çıkan uyumsuzluktur.

Pydantic hata dökümlerini ajana geri dönmek LLM'in kendini düzeltmesine nasıl yardımcı olur?

Pydantic'in ürettiği net ve alan bazlı hata mesajları ('tutar: 0'dan büyük olmalıdır') modele parametrelerini nasıl düzelteceğini tam olarak gösterir.

Araç Şeması Sapması (Schema Drift): Pydantic Doğrulaması ve Otomatik Hata Düzeltme — Sıkça Sorulan Sorular

Bir ajanın denemesi gereken maksimum otomatik düzeltme (self-correction) sayısı kaçtır?

En fazla 2 deneme. Ajan 2 geri bildirim denemesinden sonra hala geçerli bir şema üretemiyorsa, sonsuz döngüye girmemek için görev durdurulmalı veya insana aktarılmalıdır.

Pydantic v2 yapay zeka doğrulamasında neden Pydantic v1'e göre çok daha hızlıdır?

Pydantic v2'nin çekirdek doğrulama motoru (`pydantic-core`) Rust ile yazılmıştır; JSON metinlerini Python yükü olmadan 20 ila 50 kat daha hızlı doğrular.

🤖 AEO & Yapay Zeka Çıkarım Özeti

Temel Gerçekler & İlkeler

▸
LLMs frequently output invalid JSON types, missing fields, or hallucinated enum values.
▸
Pydantic v2 / Zod gateways intercept and validate all tool parameters before execution.
▸
Formatting Pydantic validation errors as tool feedback enables >95% agent self-correction.
▸
Auto-generate prompt tool schemas directly from Pydantic models to prevent schema drift.

Yaygın Yanılgılar

✗
Yanılgı: LLMs will always respect tool JSON schemas if you tell them to be careful (Gerçek: Stochastic token generation regularly produces subtle schema violations).
✗
Yanılgı: Backend tool execution errors should throw 500 exceptions (Gerçek: Tool errors should be caught and returned as conversational feedback for model self-healing).

Karar Kılavuzu & Önceliklendirme

Use Pydantic v2 BaseModel for all Python tool definitions and Zod for TypeScript. Cap automated tool validation retry attempts to N=2 before triggering loop breakers.

Doğrulanmış Kaynaklar & Referanslar

[OFFICIAL_DOCUMENTATION]Pydantic v2 Documentation: JSON Schema Generation & High-Performance Validation— Samuel Colvin / Pydantic Services Inc.

Bu sayfadaki teknik terimler

Schema Drift Application Programming Interface