Pydantic AI ile Üretim Kalitesinde Yapay Zeka Ajanları Geliştirme
Pydantic AI iddiası ne anlatıyor? Ham LLM SDK'larıyla yapay zeka aracıları oluşturmak, yapılandırılmış çıktılara, test edilebilir koda ve üretim güvenilirliğine ihtiyaç duyana kadar prototipler için gayet iyi çalışır. Boşluk öngörülebilir bir şekilde ortaya çıkıyor. İçindekilerPydantic AI…
Pydantic AI iddiası ne anlatıyor?
Ham LLM SDK’larıyla yapay zeka aracıları oluşturmak, yapılandırılmış çıktılara, test edilebilir koda ve üretim güvenilirliğine ihtiyaç duyana kadar prototipler için gayet iyi çalışır. Boşluk öngörülebilir bir şekilde ortaya çıkıyor.
Not defteri kodunuz çalışır, böylece onu üretime doğru hareket ettirirsiniz ve yama uygulamaya başlarsınız: json.loads çevresinde bir try/hariç, işaretleme çitlerini kaldırmak için bir yardımcı, alan türlerini kontrol etmek için birkaç if ifadesi, bir yeniden deneme döngüsü, çağrılabilirlere araç adlarını eşleyen bir gönderme işlevi. Bunların hiçbiri tek başına zor değil.
Birlikte kod tabanınızın çoğunluğunu oluştururlar ve gerçek aracı mantığı, yapıştırıcının altında kaybolur. Bu makale, bu sorunların altısını, karşılaştığınız sıraya göre ele alıyor ve Pydantic AI’nin her birini kodla nasıl çözdüğünü gösteriyor: Yapılandırılmamış çıktılar, hassas ayrıştırma gerektirir; çıktı şemanız, kodunuzun beklediği dikteden kopuk bir İngilizce bilgi istemi dizesinde yaşar.
Tasarım ve teknik ayrıntılar
Araç tanımları çok ağırdır; ~70 satır elle yazılmış JSON şeması ve üç araç için gönderme kodu; şemayı işlev imzalarınızla senkronize tutan hiçbir şey yoktur. Çalışma zamanı bağlamını aktarmanın temiz bir yolu yok; çerçeve araçlarınızı çağırdığında, globallere veya kapanışlara ulaşmadan onlara bir veritabanı bağlantısı veya kullanıcı kimliği veremezsiniz.
Test, gerçek LLM çağrıları gerektirir; her test paraya mal olur, saniyeler sürer, ağ erişimi gerektirir ve pullar gerektirir. Yeniden deneme ve doğrulama mantığı elle yuvarlanır; aynı doğrulama/yeniden yazma işlemini yeniden yazarsınız. Oluşturduğunuz her aracıda istem/yeniden deneme modeli.
Modelleri değiştirmek, entegrasyon kodunu yeniden yazmak anlamına gelir; her sağlayıcının farklı bir SDK şekli, araç formatı ve yanıt yapısı vardır. Baştan sona çalışan bir örnek kullanacağız: bir makbuz analiz aracısı.
Bugünden bakınca ne kadar güvenilir?
Ham makbuz metnini (fotoğraftan metne taramadan elde edeceğiniz şey) alır, satıcı kategorilerini ve döviz kurlarını aramak için araçları çağırır ve bir bütçeleme panosunun veya gider aracının doğrudan kullanabileceği yazılı bir özeti (tüccar, harcama kategorisi, ayrıntılı döküm ve güven puanı) döndürür. Yapılandırılmış giriş, aramalar için araç çağrıları, alt sistemler için yazılı çıktı.
Ortaya çıkardığı sorunların tanıdık gelmesine neden olacak kadar yaygın bir şekil. Sonunda, yazılı çıktılara sahip bir çalışma aracısına, bağımlılık eklenmiş araçlara, otomatik yeniden denemeli iş kuralı doğrulamaya ve API anahtarı olmadan milisaniyeler içinde çalışan bir test paketine sahip olacaksınız.
l Kalıp Ağırdır Sorun 3: Çalışma Zamanı Bağlamını Geçmenin Temiz Bir Yolu Yok Sorun 4: Test Gerçek LLM Çağrıları Gerektirir Sorun 5: Yeniden Deneme ve Doğrulama Mantığı Elle İşlenir Sorun 6: Modelleri Değiştirmek Yeniden Yazmak Anlamına Gelir Entegrasyon Kodu Pydantic AI Hakkında Kısa Bir Özet Pydantic, Python tabanlı veri doğrulamadır kütüphane.
Okuyucu için pratik anlamı
Bir şemayı, tür ipuçlarına sahip normal bir Python sınıfı olarak tanımlarsınız ve Pydantic bunu çalışma zamanında uygular; mantıklı olduğunda türleri zorlar, uymayanları reddeder ve rahatsız edici alanı pydantic içe aktarma BaseModel, Field class Item(BaseModel)’den adlandıran kesin hatalar üretir: isim: str miktar: float = Field(gt=0) Item(name = “Espresso”, miktar = “2,50”) # → miktar=2,5, coerced Item(name=”Espresso”, miktar=-1) # → ValidationError: miktar > 0 olmalıdır Pydantic AI, LLM sınırını yöneten bir aracı çerçevesidir; modellerinizi sağlayıcıya özgü şema isteklerine dönüştürür, geri gelenleri ayrıştırır ve doğrular, işlev imzalarından araç tanımları oluşturur, bağımlılıkları enjekte eder ve doğrulama hatası durumunda yeniden deneyebilir.
Aracı mantığınız Python olarak kalır; çerçeve çeviriyi her iki yönde de gerçekleştirir. Önkoşullar Bu makale aşağıdaki konularda rahat olduğunuzu varsaymaktadır: Python 3.10+ — tür ipuçları, veri sınıfları, eşzamansız/beklemede LLM API temelleri — OpenAI, Antropik veya benzer SDK’ların Aracı kavramlarına en az birkaç çağrı yaptınız — bir AI aracısının ne olduğunu anladınız (LLM + araçlar + muhakeme döngüsü).
Değilse, AI Agents – İnşaatçı Kılavuzu ile başlayın. Pydantic AI ile önceden deneyim sahibi olmanıza gerek yoktur. Sıfırdan inşa edeceğiz. Sorun: Çerçevesiz Aracılar Oluşturmak Bu sorunları daha iyi ortaya çıkarmak ve açıklamak için, çalışan bir örnek kullanacağız: makbuz analiz aracısı.
Ham r alır makbuz metni (fotoğraftan metne taramadan elde edeceğiniz metin), harcamaları kategorilere ayırır, satıcı bilgilerini arar ve yapılandırılmış bir özet döndürür. Bu size satıcı adını, harcama kategorisini, ayrıntılı dökümü ve güven puanını verir. Alt sistemler (bir bütçeleme panosu, bir gider raporu aracı) bu yapılandırılmış çıktıyı doğrudan tüketir.
Bu, gerçek dünyadaki yaygın bir kalıptır: yapılandırılmış girdi, aramalar için araç çağrıları ve aşağı akış sistemleri için yazılı çıktı. Ham OpenAI SDK çağrılarıyla binanın nasıl göründüğüne bakalım. Sorun 1: Yapılandırılmamış Çıktılar Kırılgan Ayrıştırma Gerektirir Özünde, bir Yüksek Lisans ile her etkileşim yalnızca metin girişi ve çıkışından ibarettir.
Modelle olan sözleşmenizin tamamı (giriş verileri, hedef ve istenen çıktı formatı) tek bir metin istemine sıkıştırılmıştır. Doğruluğu zorunlu kılan bir şema, tür sistemi veya derleyici yoktur. Ne istediğinizi İngilizce olarak anlatırsınız ve modelin size uygun olmasını umarsınız. İşte OpenAI SDK’yı kullanan basit uygulama.
Sistem isteminin giriş bağlamını, görev talimatını ve çıktı şemasını tek bir metin bloğunda nasıl kodlaması gerektiğine dikkat edin: import json openai’den içe aktarma OpenAI istemcisi = OpenAI() def analyze_receipt(receipt_text: str) -> dict: yanıt = client.chat.completions.create( modeli = “gpt-4o”, mesajlar=[ {“role”: “system”, “content”: “””Bu makbuzu analiz edin ve JSON’u döndürün: { “tüccar”: “dize”, “kategori”: “bir o f: yiyecek, ulaşım, kamu hizmetleri, eğlence, alışveriş, diğer”, “toplam”: kayan nokta, “para birimi”: “dize”, “items”: [{“name”: “string”, “tutar”: float}], “iş_harcaması”: bool, “güven”: 0 ile 1 arasında kayar }”””}, {“rol”: “kullanıcı”, “içerik”: makbuz_metni} ] ) raw = yanıt.seçimler[0].message.content # Yanıtı ayrıştır şunu dene: if raw.startswith(““`”): raw = raw.split(“n”, 1)[1].rsplit(““`”, 1)[0] sonuç = json.loads(raw) json.JSONDecodeError hariç: Raise ValueError(f”LLM geçersiz JSON döndürdü: {raw[:200]}”) # Alanları manuel olarak doğrulayın izin verilen_kategoriler = {“yiyecek”, “ulaşım”, “yardımcı programlar”, “eğlence”, “alışveriş”, “diğer”} result.get(“kategori”) izin verilen_kategorilerde değilse: result[“category”] = “other” return result Bu kod temiz ve okunabilirdir ve not defterinizde çalışır.
Ancak temel sorun, LLM ile olan sözleşmenizin tamamının (girdi, hedef ve çıktı formatı) yapılandırılmamış bir dizide yer almasıdır. Her iki tarafta da bu sözleşmeyi zorlayan hiçbir şey yok. Üretime doğru iterseniz sorunlar yüzeye çıkmaya başlar: Bilgi istemi şemadır ve yalnızca İngilizcedir: Sistem istemi çıktı formatını doğal dilde açıklar. Bu açıklamayı kodunuzun gerçekte beklediği ifadeye bağlayan hiçbir şey yok.
Komut istemine bir alan ekleyin ve bunu aşağı yönde işlemeyi unutun; üretime kadar hata almazsınız. Yüksek Lisans her zaman geri dönmez temiz JSON: Çıktıyı “`json “` çitleri içine sarar, öncesine/sonrasına açıklayıcı metin ekler, sondaki virgülleri içerir veya zaman aşımı durumunda kısmi bir yanıt döndürür. Ayrıştırma kodunuz bir durumu (çitler) ele alır, ancak diğerlerini işlemez.
Gerçek bir doğrulama yok: Toplam gerçekten bir sayı mı, yoksa Yüksek Lisans “45,99 $” dizesini mi döndürdü? Güven 0 ile 1 arasında mı yoksa 95 (yüzde) mi döndürdü? Öğe listesi doğru tuşlara sahip dikteler içeriyor mu? Bunların hepsini manuel olarak kontrol etmeniz gerekir.
Başarısızlıklar sessiz veya yıkıcıdır: Geri dönüş kategorisi (sonuç[“kategori”] = “diğer”), yeniden denemeyi tetiklemesi gereken bir sorunu gizler. Json.loads hatası, kurtarma yolu olmayan bir istisna oluşturur. Aslında ihtiyacımız olan şey, çıktı şemasını bir bilgi istemi dizesindeki İngilizce açıklama olarak değil, yazılı bir veri yapısı olarak kodda bir kez tanımlamanın bir yoludur.
Şema, hem LLM hem de tüketen kod için tek gerçek kaynak olmalıdır. Ayrıca şemayı otomatik olarak uygulamak ve LLM’nin tür tanımlarına karşı yanıtını uyumsuzluk durumunda uygun hatalarla doğrulamak için de çerçeveye ihtiyacımız var. Ve son olarak, manuel mantık olmadan doğrulama hatası durumunda yeniden denememiz gerekiyor.
Çıktı şemayla eşleşmiyorsa LLM’ye doğrulama hatasını yeniden sorun, böylece kendi kendini düzeltebilir. Kısaca: Çıktı formatı İngilizce olarak ifade edilen bir öneri değil, tip sisteminde ifade edilen bir sözleşme olmalıdır. Pydantic AI Bunu Nasıl Çözüyor? Pydantic AI, çıktıyı bir Pydantic modeli olarak tanımlamanıza olanak tanır.
Çerçeve, şema oluşturmayı, istem eklemeyi, JSON ayrıştırmayı, doğrulamayı ve yeniden denemeyi yönetir.
Ve bunların hepsi tek model tanımından türetilmiştir: pydantic import BaseModel, Field’dan pydantic_ai ithalat Aracısından enum import Enum class’tan HarcamaCategory(str, Enum): GIDA = “yiyecek” ULAŞIM = “ulaşım” YARDIMCI PROGRAMLAR = “yardımcı programlar” EĞLENCE = “eğlence” ALIŞVERİŞ = “alışveriş” DİĞER = “diğer” sınıf LineItem(BaseModel): isim: str miktar: float sınıfı ReceiptAnaliz(BaseModel): tüccar: str kategori: HarcamaKategorisi toplam: kayan nokta = Alan(gt=0) para birimi: str = Alan(min_uzunluk=3, maksimum_uzunluk=3) öğeler: liste[SatırItem] is_business_expense: bool güven: float = Field(ge=0, le=1) makbuz_agent = Aracı( “openai:gpt-4o”, Output_type=MakbuzAnalizi, system_prompt=”Sağlanan makbuzu analiz edin ve yapılandırılmış ayrıntıları çıkarın.”, ) result = quote_agent.run_sync(“CAFE PARISn€12,50nKruvasan x2 €5,00nEspresso €2,50nCroque Monsieur €5,00”) yazdır(sonuç.çıktı) # trader=’CAFE PARIS’category= total=12.5 …
Peki burada farklı olan ne? İlk olarak şema modeldir. ReceiptAnalytics alanları, türleri ve kısıtlamaları tanımlar. Pydantic AI bunu LLM için uygun JSON şemasına dönüştürür ve yanıtı buna göre doğrular. Her yerde kullanılan tek tanım. İkincisi, orada’ kodun ayrıştırılması yok. İşaretleme çitlerini kaldırmazsınız, json.loads’u çağırmazsınız veya JSONDecodeError’ı yakalamazsınız. Çerçeve bunların hepsini hallediyor.
Ayrıca doğrulama gerçektir. Güvenilirlik alanındaki Field(ge=0, le=1), 95 değerinin sessizce kabul edilmediği, reddedildiği anlamına gelir. Enum olarak Harcama Kategorisi, geri dönüş maskeleme olmadan yalnızca geçerli kategorilere izin verildiği anlamına gelir. Son olarak, yeniden deneme otomatiktir.
LLM, doğrulamayı geçemeyen bir çıktı döndürürse Pydantic AI, doğrulama hatasını modele geri gönderir ve kendisinden kendisini düzeltmesini ister. Elle yuvarlanan yeniden deneme döngüsü yoktur. İşlev bir ReceiptAnalytics nesnesi döndürür: yazılan, doğrulanan ve IDE otomatik tamamlama dostu. Doğru anahtarlara sahip olduğunu umduğunuz bir söz değil. Görünürde ne oluyor?
Output_type=ReceiptAnalytics’i tanımladığınızda Pydantic AI, her aracı çalıştırmasında birkaç önemli şey yapar. İçeri girerken Pydantic modelinizden bir JSON şeması oluşturur ve bunu LLM isteğine enjekte eder.
Model sağlayıcısına bağlı olarak bu, yerel yapılandırılmış çıktı/araç çağrısı mekanizmasını (OpenAI’nin yanıt_formatı, Anthropic’in araç kullanımı vb.) kullanır, böylece LLM tam olarak hangi yapıyı üreteceğini bilir. Dönüş yolunda, LLM’nin ham yanıtını alır, Pydantic modeline göre ayrıştırır ve tam doğrulamayı çalıştırır (tür zorlaması, alan kısıtlamaları ve numaralandırma üyeliği).
Doğrulama başarısız olursa, hata mesajını konuşmaya geri gönderir ve LLM’den hata mesajını düzeltmesini ister. ut (yapılandırılabilir yeniden deneme sınırına kadar otomatik olarak).
┌─────────────────────────────────── ───────────────────────────────────┐ │ Pydantic AI — Yapılandırılmış Çıkış Akışı │ │ │ │ ┌────────────────┐ ┌──────────────────────────────────┐ │ │ │ Kodunuz │ │ Pydantic AI Çerçevesi │ │ │ │ │ │ │ │ │ │ çıktı_tipi = │────────>│ 1. │ │’den JSON şeması oluşturun │ │ Fiş Analizi │ Fiş Analizi modeli │ │ │ │ │ │ │ │ │ └────────────────┘ │ 2.
Şemayı LLM’ye enjekte edin │ │ │ │ istek (yerel sağlayıcı │ │ │ │ biçimi: yanıt_biçimi, │ │ │ │ tool_call, vb.) │ │ │ │ │ │ │ │ └──────────────┼───────────────────┘ │ │ ▼ │ │ ┌──────────────────────────────────┐ │ │ │ Yüksek Lisans │ │ │ │ Şemayı görür → JSON üretir │ │ │ └──────────────┬───────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────┐ │ │ │ Pydantic Yapay Zeka Çerçevesi │ │ │ │ │ │ │ │ 3.
Ham LLM yanıtını ayrıştırın │ │ │ │ 4.
Modele göre doğrulama: │ │ │ │ – Tip kontrolleri │ │ │ │ – Alan kısıtlamaları (ge, le) │ │ │ │ – Enum üyeliği │ │ │ │ │ │ │ │ │ ┌────┴────┐ │ │ │ │ │ │ │ │ │ │ GEÇTİ ✓ KALDI ✗ │ │ │ │ │ │ │ │ │ │ ▼ ▼ │ │ │ │ Yazılan geri dönüş Gönderme doğrulaması │ │ │ │ Yüksek Lisans’a geri dönen nesne hatası │ │ │ │ kendi kendini düzeltmek için │ │ │ │ (otomatik yeniden deneme) │ │ │ └──────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────┐ │ │ │ Kodunuz şunları alır: │ │ │ │ sonuç.çıktı → Fiş Analizi │ │ │ │ (yazılan, doğrulanan, kullanıma hazır)│ │ │ └──── ──────────────────────────────┘ │ └─────────────────────────────────── ───────────────────────────────────┘ Sözleşmeyi bir kez Python sınıfı olarak tanımlarsınız.
Çerçeve, LLM sınırının her iki tarafını da ele alarak modele ne üreteceğini söyler ve ürettiğini doğrular. Sorun 2: Araç Tanımları Genel Olarak Ağırdır Makbuz acenteniz, satıcı kategorilerini aramasına, döviz kurlarını kontrol etmesine ve harcama geçmişini sorgulamasına olanak tanıyan araçlara ihtiyaç duyar.
Ham işlev çağrısında bunun nasıl görüneceği aşağıda açıklanmıştır: araçlar = [ { “tip”: “işlev”, “işlev”: { “name”: “aranan_tüccar_kategorisi”, “description”: “Bir satıcı adına ait harcama kategorisine bakın”, “parametreler”: { “tip”: “nesne”, “özellikler”: { “satıcı_adı”: { “tip”: “dize”, “description”: “Makbuzdaki satıcı adı” } }, “gerekli”: [“satıcı_adı”] } } }, { “tip”: “işlev”, “işlev”: { “name”: “get_exchange_rate”, “description”: “İki para birimi arasındaki güncel döviz kurunu alın”, “parametreler”: { “tip”: “nesne”, “özellikler”: { “para biriminden”: { “tip”: “dize”, “description”: “Kaynak para birimi kodu (ör.
EUR)” }, “to_currency”: { “tip”: “dize”, “description”: “Hedef para birimi kodu (ör. USD)” } }, “gerekli”: [“from_currency”, “to_currency”] } } }, { “tip”: “işlev”, “işlev”: { “name”: “get_spending_history”, “description”: “Bir tarih aralığı için harcama toplamlarını kategoriye göre alın”, “parametreler”: { “t
İlgili yazılar
- Yapay Zeka Yazılımcıların Yerini mi Alacak, Yoksa Gücünü mü Artıracak?
- 2026’da Yapay Zeka Chatbotları Nasıl Kurulur ve Kullanılır
Editörün Notu
Yapay zeka ajanları geliştirirken, yapılandırılmış çıktı ve sağlam hata yönetimi için Pydantic gibi doğrulama araçlarını entegre etmek, kodunuzu daha sürdürülebilir ve üretim ortamına uygun hale getirir. Böylece, karmaşık hata senaryolarını önceden yakalayarak bakım maliyetlerini azaltabilirsiniz.
“Pydantic AI ile Üretim Kalitesinde Yapay Zeka Ajanları Geliştirme” üzerine bir düşünce
Yorumlar kapalı.