Çok Modelli API Ağ Geçidinde Yapılandırılmış Çıktılar: JSON Şeması, Araç Çağrıları ve Anlamsal Korumalar

Bu matrisin sürümü oluşturulmalı ve test edilmelidir. Bir sağlayıcı davranışını değiştirdiğinde veya yeni bir model eklendiğinde, üretim yönlendirmeden önce yapısal çıktı uyumluluğu doğrulanmalıdır.

3. En güçlü sağlayıcı-yerel sözleşmeye çevirin

Bağdaştırıcı net bir tercih sırasını takip etmelidir:

1. Seçili model ve şema tarafından desteklendiğinde, sağlayıcıya özgü katı yapılandırılmış çıktılar kullanın.
2. Eylemler ve işlev benzeri görevler için sağlayıcıya özgü araç çağrısını kullanın.
3. Katı mod kullanılamadığında doğrulama ve yeniden denemelerle katı olmayan yapılandırılmış çıktıyı veya JSON modunu kullanın.
4. İsteği reddedin, uyumlu bir yedek modele yönlendirin veya yüksek riskli iş akışları için eylem dışı yanıt döndürün.

Yüksek riskli bir işlemin düzeyini katı şema modundan "en iyi çaba JSON'una" sessizce düşürmeyin. Uygulama katı davranış talep ettiyse ve seçilen sağlayıcı bunu destekleyemiyorsa ağ geçidi bunu bir hata, yönlendirme kararı veya açık sürüm düşürme işareti aracılığıyla görünür hale getirmelidir.

Yürütmeden önce üç doğrulama katmanı

Katman 1: ayrıştırma doğrulaması

Öncelikle yanıtın beklenen zarfa ayrıştırılıp ayrıştırılamayacağını belirleyin. Hatalı biçimlendirilmiş JSON, eksik araç çağrısı blokları, kısaltılmış yanıtlar veya sözleşmenin yasakladığı doğal dil ile JSON karışımı durumlarda hızlı başarısız olun.

işlev ayrıştırmaStructuredResponse(raw) {
  dene {
    return { ok: true, değer: JSON.parse(raw) };
  } yakalamak (hata) {
    return { ok: false, Failure_type: "parse_failure", error: String(error) };
  }

Sağlayıcıya özgü araç çağrıları ham metin bloğunun ayrıştırılmasını gerektirmeyebilir ancak yine de zarf doğrulaması gerektirir: Model bilinen bir aracı seçti mi, bağımsız değişkenler sağladı mı ve beklendiği gibi araç yürütmeyi durdurdu mu?

Katman 2: JSON Şeması doğrulaması

Sonra, sunucu tarafı doğrulayıcı kullanarak nesneyi bildirilen şemaya göre doğrulayın. Sağlayıcı katı şema desteği talep ettiğinde bile bunu yapın. Ağ geçidi tarafı doğrulama, hataların tutarlı bir şekilde günlüğe kaydedilmesini sağlar, entegrasyon hatalarına karşı koruma sağlar ve aşağı yöndeki uyumsuzlukları yakalar.

const validate = schemaValidator.compile(schema);
const geçerli = validate(nesne);
eğer (!geçerli) {
  dönüş {
    tamam: yanlış,
    başarısızlık_türü: "şema_başarısızlığı",
    hatalar: validate.errors
  };

Taşınabilirlik için şemaları ortak alt kümeyi göz önünde bulundurarak tasarlayın:

• Açık type, required, properties, enum ve additionalProperties: false'u tercih edin.
• Hedef sağlayıcının bunları desteklediğini bilmediğiniz sürece derinlemesine yuvalanmış oneOf, anyOf ve koşullu şemalar gibi karmaşık kombinasyonlardan kaçının.
• Eylem argümanlarını küçük ve somut tutun.
• Aşağı yönlü sistemler başka bir tür gerektirmediği sürece kimlikler, tarihler ve kodlar için dizeleri kullanın.
• confidence, missing_fields veya requires_human_review gibi alanlarla belirsizliği açık bir şekilde temsil edin.

3. Katman: anlamsal ve iş doğrulama

Son olarak, yapılandırılmış sonucun görev için doğru olup olmadığını doğrulayın. Bu katman alana özeldir ve yalnızca JSON Schema'ya dış kaynak olarak verilemez.

Fatura çıkarma için anlamsal kontroller şunları içerebilir:

• Toplam negatif değildir ve satır öğeleriyle tolerans dahilinde eşleşir.
• Para birimi kaynak belgede görünüyor.
• Son tarih inanılmayacak kadar geçmişte veya gelecekte değil.
• Satıcı, onaylanmış bir satıcı listesinde mevcut.
• Güven, otomatik giriş için yeterince yüksektir.

Potansiyel müşteri yeterliliği için kontroller şunları içerebilir:

• Seçilen segment, satış ekibinin aktif segmentlerinden biridir.
• İstenen bütçe, kullanıcı bütçe sağlamadığında icat edilmemiş demektir.
• Kullanıcı açıkça istemediği sürece "kitap demosu" işlemi yürütülmez.

İş Ortağı API otomasyonu için kontroller şunları içerebilir:

• Bayi hesabı, istenen müşteriyi veya anahtarı oluşturma yetkisine sahiptir.
• İstenen harcama sınırı iş ortağı politikası dahilindedir.
• İşlemin bir önemsizlik anahtarı var.
• Eylem, yürütülmeden önce bir denetim günlüğüne kaydedilir.

Araç çağrıları: model çıktısını bir yürütme olarak değil, istek olarak ele alın

Modelin uygulamadan bir şey yapmasını istemesi gerektiğinde araç çağırma doğru modeldir: destek bildirimi oluşturmak, Telegram bot komutu göndermek, fiyatlandırmaya bakmak, müşteri kaydını güncellemek veya bir iş akışı başlatmak.

Güvenli bir araç döngüsü şuna benzer:

1. Uygulama mevcut araçları ve bunların giriş şemalarını bildirir.
2. Model, yapılandırılmış bağımsız değişkenlere sahip bir araç çağrısı döndürür.
3. Ağ geçidi, araç adını ve bağımsız değişkenleri doğrular.
4. Uygulama yetkilendirmeyi, politikayı, geçiciliği ve kullanıcı onayı gereksinimlerini kontrol eder.
5. Ancak o zaman uygulama aracı çalıştırır.
6. Konuşmanın devam etmesi gerekiyorsa araç sonucu modele geri gönderilir.

Bir araç çağrısını hiçbir zaman eylemin gerçekleşmesi gerektiğinin kanıtı olarak görmeyin. Bunu yapılandırılmış bir teklif olarak ele alın. Uygulama, yan etkiler konusunda otorite olmaya devam ediyor.

Çok modelli iş akışları için güvenli geri dönüş merdiveni

Bir ağ geçidi, olaylar meydana gelmeden önce geri dönüş davranışını tanımlamalıdır. Pratik bir merdiven:

1. Birincil: tercih edilen modelde sıkı yapılandırılmış çıktı.
2. Uyumlu geri dönüş: aynı katı şema gereksinimlerini destekleyen başka bir model.
3. Doğrulama ve yeniden deneme: sıkı desteği olmayan ve yalnızca risk izin verdiğinde kullanılan bir sağlayıcı.
4. İnsan incelemesi: Yapılandırılmış sonucu ve kaynak içeriği onay için sıraya koyun.
5. Eylem dışı yanıt: sistemin işlemi güvenli bir şekilde tamamlayamayacağını açıklayın.

Yeniden denemeler, biçimlendirme veya küçük şema hataları için faydalıdır ancak bir güvenlik stratejisi değildir. Nesne anlamsal olarak güvensizse, tekrarlanan istem, doğru reddetmeyi tehlikeli bir yürütülebilir nesneye dönüştürebilir. Yüksek riskli işlemlerde, tekrarlanan başarıyı zorlama girişimleri yerine incelemeyi veya reddetmeyi tercih edin.

Gözlemlenebilirlik: her yapılandırılmış çıktı kararını günlüğe kaydedin

Yapılandırılmış çıkış arızaları operasyonel sinyallerdir. Gereksiz hassas içeriği açığa çıkarmadan yönlendirmeyi, şemaları ve istemleri iyileştirmek için bunları yeterli ayrıntıyla günlüğe kaydedin.

Önerilen alanlar:

• schema_id ve schema_version.
• Sağlayıcı ve model.
• İstenen mod ve kullanılan gerçek mod.
• Ayrıştırma hatası durumu.
• Şema hatası durumu ve doğrulama hataları.
• Anlamsal doğrulama başarısızlığının nedeni.
• Sayımı yeniden dene.
• Gecikme.
• Jeton kullanımı ve maliyeti.
• Nihai eylem durumu: yürütüldü, sıraya alındı, reddedildi veya kullanıcıya iade edildi.
• Uygun olduğu yerde ekip, proje, API anahtarı veya iş ortağı hesabı tanımlayıcısı.

Bu günlükler hata ayıklamayı, maliyet analizini, sağlayıcı karşılaştırmasını ve ekip API yönetimini destekler. Ayrıca şu tür soruların yanıtlanmasına da yardımcı olurlar: "En çok yeniden denemeye hangi şema sürümü neden oluyor?" ve "Hangi yedek model sözdizimini geçiyor ancak iş doğrulamasında başarısız oluyor?"

Şema sürüm oluşturma kuralları

Şemalar üretim arayüzleridir. Onlara API sözleşmeleri gibi davranın.

• İstek meta verilerine ve günlüklerine schema_id ve schema_version'u ekleyin.
• Mevcut otomasyonlar için gerekli alanları sessizce değiştirmeyin.
• İstemciler taşınırken eski şemaları kullanılabilir durumda tutun.
• Yeni isteğe bağlı alanları zorunlu hale getirmeden önce ekleyin.
• Yönlendirme havuzundaki her sağlayıcı ve yedek modele karşı şemaları test edin.
• Yan etkili her eylem için hangi şema sürümünün kullanıldığını kaydedin.

Sürüm oluşturma, birçok alt müşterinin istikrarlı yapılandırılmış bir sözleşmeye bağlı olabileceği ajanslar, bayiler ve İş Ortağı API otomasyonu için özellikle önem kazanıyor.

Yapılandırılmış bir sonuç ne zaman yürütülmemelidir

Aşağıdaki koşullardan herhangi biri ortaya çıktığında ani durdurma kullanın:

• Yanıt ayrıştırılamaz.
• Nesne JSON Şeması doğrulamasında başarısız oldu.
• Bir numaralandırma değeri desteklenmiyor veya icat edilmiş.
• Bir miktar, fiyat, tarih veya para birimi imkansızdır.
• Sonuç, kullanıcının belirttiği amaçla çelişiyor.
• Model düşük güvenirliği veya eksik kanıtları ifade ediyor.
• Kullanıcı talimatı belirsiz.
• Eylemin yan etkileri var ve onayı yok.
• Hesap, ekip veya API anahtarı yetkili değil.
• Sağlayıcının yanıtı, ret veya güvenlikle ilgili yanıt vermemeyi içerir.

Öneriler ve tahminler

Öneriler: Mümkün olduğunda sağlayıcıya özgü yapılandırılmış çıktılar kullanın, her yanıt ağ geçidi tarafını doğrulayın, eylemler için araç çağrılarını tercih edin, bir yetenek matrisi, sürüm şemaları sürdürün ve anlamsal kontroller başarılı olana kadar yan etkileri engelleyin.

Tahminler: Yapılandırılmış çıktılar için sağlayıcı desteği muhtemelen daha güçlü ve daha tutarlı hale gelecektir, ancak model aileleri, şema alt kümeleri ve araç çağrısı döngüleri bir gecede aynı olmayacağından taşınabilirlik bir ağ geçidi endişesi olmaya devam edecektir. Doğrulama, gözlemlenebilirlik ve şema sürüm oluşturma özelliklerini geliştiren ekipler artık her iş akışını yeniden yazmaya gerek kalmadan yeni sağlayıcı özelliklerini benimseme konusunda daha iyi bir konumda olacak.

Harekete geçirilebilir uygulama kontrol listesi

1. Uygulamalarınız için normalleştirilmiş bir yapılandırılmış çıktı isteği biçimi tanımlayın.
2. Yönlendirme havuzunuzdaki her model için bir sağlayıcı yetenek matrisi oluşturun.
3. Taşınabilir bir JSON Şeması alt kümesi kullanarak şemalar tasarlayın.
4. Desteklendiğinde istekleri katı sağlayıcıya özgü mekanizmalara çevirin.
5. Oluşturma sonrasında ayrıştırılabilirliği, şema uyumluluğunu ve iş doğruluğunu doğrulayın.
6. Yan etkili işlemler için araç çağrılarını kullanın.
7. Model dışında yetkilendirme, yetkisizlik ve onay gerektirir.
8. Şema sürümünü, sağlayıcıyı, doğrulama hatalarını, yeniden denemeleri, gecikmeyi, maliyeti ve işlem durumunu günlüğe kaydedin.
9. İş akışı risk düzeyine göre geri dönüş davranışını tanımlayın.
10. Bağımlı otomasyonlar taşınana kadar eski şemaları kullanılabilir durumda tutun.

Pratik amaç, her modelin aynı şekilde davranmasını sağlamak değildir. Ağ geçidi sağlayıcı farklılıklarını dürüstçe ele alırken, uygulama geliştiricilerine istikrarlı bir sözleşme vermektir. Yapılandırılmış çıktılar, güvenilir yapay zeka otomasyonu için gerekli altyapıdır ancak üretim sınırı, bir nesnenin kullanımının güvenli olup olmadığına karar veren doğrulayıcı ve politika katmanıdır.

İlgili okuma

• anlam bilgisi olmadan geri dönüş yönlendirme regresyonlar
• API anahtarı yetkilendirmesi ve ekip kontrolleri
• yeniden denemeler için jeton maliyetini ve gecikmeyi izleme