Aracı, video dönüştürme uç noktanızı çağırır. Uç nokta, 202 Accepted ve bir iş kimliği döndürür. Sisteminizde 202'nin ne anlama geldiği hakkında hiçbir fikri olmayan aracı, dönüştürmenin tamamlandığını bildirir ve henüz var olmayan bir dosyayı okuyan bir sonraki adıma geçer.
Uzun süren işlemler, aracılar üzerinde belirli bir şekilde sorunlara yol açar. Senkron bir çağrının açık bir sözleşmesi vardır: gönderirsiniz, beklersiniz, bir yanıt alırsınız. Asenkron bir çağrı bunu bir başlangıç ve bir bitişe böler ve aralarındaki boşluk, aracıların kafasının karıştığı yerdir. Başarıyı erken ilan ederler, sıkı bir döngüde binlerce kez sorgularlar veya bir konuşma sırasını açık tutarak altı dakika boyunca engellenmiş otururlar.
Bu kılavuz, bir aracının takip edebileceği asenkron sözleşmenin nasıl tasarlanacağını, ne zaman sorgulanacağını ve ne zaman devredileceğini, modelin düzgün çalışması için araçların nasıl yazılacağını ve yavaş ve başarısız durumlar dahil olmak üzere tüm yolun nasıl test edileceğini kapsar. Aracı hata kurtarma hakkındaki yazımız API çağrılarının hata tarafını ele alırken; bu yazı, yavaşça başarılı olanları kapsar.
Apidog, bir aracının dört dakika süren ve ardından başarısız olan bir işi ele aldığını kanıtlamanız gereken noktada devreye girer; bu, üretimde keşfetmek isteyeceğiniz bir şey değildir.
Aracılar neden asenkron işlemleri yanlış yönetir?
Çoğu soruna üç alışkanlık neden olur.
Modeller, bir 2xx'i tamamlanmış olarak kabul eder. Bir 202, isteğin işlenmek üzere kabul edildiğini belirtir ve HTTP semantik spesifikasyonu, işlemin tamamlanmamış olabileceğini açıkça belirtir. Sıradan istek/yanıt trafiği üzerinde eğitilmiş modeller, yanıt aksi belirtmedikçe herhangi bir 2xx'i tamamlanma olarak okuma eğilimindedir.
Döngüler maliyetlidir. Bir aracı, kendi muhakeme döngüsü içinde sorgulama yaparsa, her kontrol bir model sırası ve önceki konuşmanın belirteçleri kadar maliyetlidir. Dört dakikalık bir iş için her iki saniyede bir sorgulama yapmak 120 sıra demektir ve çalışma ya bağlamı ya da bütçeyi tüketir. Araç yanıtlarını bağlam penceresinin dışında tutma hakkındaki yazımız, bunun neden insanların beklediğinden daha hızlı biriktiğini açıklar.
Aracılar işleri takip edemez. Bir iş başlatan ve bir iş kimliği döndüren bir araç, aracının ileriye taşıması gereken bir durum yaratmıştır. Eğer kimlik uzun bir konuşmanın ortasına düşerse, sıkıştırılarak kaybolabilir ve aracı devam eden bir işi olduğunu unutur.
Modelin yanlış okuyamayacağı bir yanıt tasarlayın
En etkili çözüm mimari değil, ifadelendirmedir. Durum kodunuz ne olursa olsun, gövdenin açıkça ne olduğunu ve sonra ne yapılacağını belirtmesini sağlayın.
{
"status": "processing",
"job_id": "job_7f21c",
"message": "The transcode has STARTED and is NOT complete. Do not report success. Check status with getJobStatus(job_id) after at least 30 seconds.",
"poll_after_seconds": 30,
"estimated_duration_seconds": 240,
"status_url": "/v1/jobs/job_7f21c"
}
Bu, bir insan API tüketicisi için kaba gelebilir. Bir modele yöneliktir ve modeller, bir durum kodundan anlam çıkarmaktansa, bir yanıt gövdesindeki açık talimatları çok daha güvenilir bir şekilde takip eder. Üç ayrıntı işi yapar: “tamamlanmadı” kelimesi, adlandırılmış sonraki araç ve minimum bekleme süresi.
Google'ın uzun süreli işlemlerle ilgili AIP-151'i, bunun için tek bir Operation nesnesinin done, error ve response alanlarını taşıdığı temiz bir kaynak şekli açıklar. Bu yapıyı kopyalamak, her yavaş uç nokta arasında tutarlı bir yüzey sağlar; bu önemlidir çünkü bir sorgulama düzenini öğrenen bir aracı, hepsini yönetebilir.
Durum yanıtını da aynı derecede açık tutun:
{
"job_id": "job_7f21c",
"status": "processing",
"done": false,
"progress_percent": 45,
"elapsed_seconds": 108,
"poll_after_seconds": 45,
"message": "Still processing. Do not proceed to the next step."
}
Ve tamamlandığında, sonuç küçükse satır içi olarak döndürün, böylece aracının üçüncü bir çağrıya ihtiyacı olmaz:
{
"job_id": "job_7f21c",
"status": "succeeded",
"done": true,
"result": { "output_url": "https://cdn.example.com/out/7f21c.mp4", "duration_seconds": 372 }
}
Modelin içinde değil, dışında sorgulama yapın
En önemli uygulama seçimi: beklemeyi aracının muhakeme döngüsüne değil, araç sarmalayıcınıza koyun.
import time
def start_and_await_transcode(client, source_url, max_wait=600):
job = client.post("/v1/transcode", json={"source_url": source_url}).json()
job_id = job["job_id"]
delay = job.get("poll_after_seconds", 5)
waited = 0
while waited < max_wait:
time.sleep(delay)
waited += delay
status = client.get(f"/v1/jobs/{job_id}").json()
if status.get("done"):
if status["status"] == "succeeded":
return {"status": "succeeded", "result": status["result"]}
return {"status": "failed", "error": status.get("error")}
delay = min(int(delay * 1.5), 60)
return {
"status": "timed_out",
"job_id": job_id,
"message": f"Still running after {max_wait}s. Job {job_id} continues in the background.",
}
Model tarafından bakıldığında bu, biraz zaman alan ve nihai bir yanıt döndüren tek bir araç çağrısıdır. Bağlamda sorgulama döngüsü yok, unutulmuş iş kimlikleri yok, 120 sıra yok. Geri çekilme (backoff), istek sayısını makul tutar ve üst sınır, takılı kalan bir işin sonsuza dek çalışmayı askıya almasını engeller. Amazon'un jitter ile zaman aşımları, yeniden denemeler ve geri çekilme hakkındaki yazısı, bu sayıları ayarlamadan önce okunmaya değer bir referanstır.
İki kural bunu güvenli kılar. Bekleme süresini her zaman sınırlayın ve zaman aşımında her zaman iş kimliğini döndürün, böylece aracı veya bir insan daha sonra kontrol edebilir. Asla belirsiz bir sonuç döndürmeyin: succeeded, failed ve timed_out üç farklı sonuçtur ve modelin üç farklı kelime görmesi gerekir.
Dakikalar yerine saatlerle ölçülen işler için sarmalayıcı içi sorgulama mantıksız hale gelir. O zaman doğru şekil, biri başlatmak diğeri kontrol etmek için iki araç, ayrıca devam eden işlerin konuşma dışında kalıcı bir kaydıdır, böylece hiçbir şey sıkıştırma nedeniyle kaybolmaz. job_id'yi, ait olduğu görevi ve başlangıç zamanını saklayın ve aracının her çalıştırmanın başında bu listeyi okumasını sağlayın.
Webhook'lar ne zaman daha iyi bir yanıt olur?
Sorgulama basittir ve her yerde çalışır. Geri aramalar (callback'ler) daha verimlidir ve çalıştırması daha fazla iş gerektirir. Takas, webhook'lar ve sorgulama karşılaştırmamızda iyi bir şekilde ele alınmıştır ve aracıya özel sürümü daha dardır.
İş saniyelerden dakikalara sürdüğünde, aracı devam etmek için sonucu beklediğinde veya herkese açık bir uç nokta barındıramadığınızda sorgulama kullanın. Çoğu aracı iş yükü buraya düşer.
İşler saatler sürdüğünde, aracı bir işi başlatıp devam ettiğinde veya birçok iş eşzamanlı çalıştığında ve her birini sorgulamak israf olduğunda webhook'ları kullanın. Maliyet gerçektir: herkese açık bir alıcıya, imza doğrulamasına, yeniden deneme işlemine ve geri arama geldiğinde aracıyı uyandırmanın bir yoluna ihtiyacınız vardır. Güvenilir webhook'lar tasarlama ve webhook imza doğrulama kılavuzlarımız bu temel çalışmayı kapsar.
Ortadaki bir seçeneği bilmekte fayda var. İşin ilerlemesini sunucu tarafından gönderilen olaylar üzerinden akışla sağlamak, istemci bağlantıyı tuttuğu için herkese açık bir uç noktaya ihtiyaç duymadan size push semantiği verir. İnsan gözlemlerken interaktif aracılar için uygundur ve SSE ile API yanıtlarını akışla gönderme kılavuzumuz uygulamayı kapsar.
Hangisini seçerseniz seçin, tamamlama yolu idempotent olmalıdır. Webhook'lar yeniden dener, sorgulamalar yarışır ve "başarılı" kelimesini iki kez gören bir aracı, sonraki adımı iki kez başlatmamalıdır. Yapay zeka aracıları için idempotentlik hakkındaki yazımız, bunu güvenli kılan anahtarları kapsar.
Sadece hızlı yolu değil, yavaş yolu da test edin
Asenkron hatalar, test ortamları hızlı olduğu için gizlenir. Üretimde dört dakika süren bir iş, yerel bir saplama (stub) üzerinde 200 milisaniyede biter, bu yüzden aracı gerçekte karşılaşacağı durumu asla deneyimlemez.
Dört senaryoyu bilerek inşa etmeye değerdir.
Gerçekten yavaş iş. Durum uç noktasını, ilk birkaç çağrı için processing ve ardından succeeded döndürecek şekilde taklit edin. Bu, sarmalayıcının sorgulama yaptığını, geri çekildiğini ve sonunda döndüğünü kanıtlar. Apidog'da bunu, istek sayısına veya bir kontrol parametresine göre değişen bir taklitle yürütebilirsiniz, böylece aynı test her seferinde aynı şekilde çalışır.
Geç başarısız olan iş. Üç kez processing döndürün, ardından bir hata gövdesiyle birlikte failed döndürün. Aracı, tamamlanmış bir sorgulamayı tamamlanmış bir iş olarak ele almak yerine hatayı bildirmelidir. Bu, yanlış olduğunda sessiz veri kaybına neden olan durumdur.
Zaman aşımı. Taklidin, sarmalayıcının üst sınırını aşarak processing döndürmeye devam etmesini sağlayın ve aracın bir istisna veya sahte bir başarı değil, iş kimliği sağlam kalacak şekilde timed_out döndürdüğünü doğrulayın.
Yinelenen tamamlama. Başarıyı iki kez, bir webhook yeniden denemesiyle veya bir yarışan sorgulama ile teslim edin ve aşağı akış adımının bir kez çalıştığını doğrulayın.
Dördünü de senaryo olarak kaydedin, böylece CI'da çalışsınlar. Yeniden çalıştırmak hiçbir maliyet gerektirmez ve birinin bir zaman aşımını kısalttığı veya bir hatayı yuttuğu gerilemeleri yakalarlar. Daha geniş yaklaşım, API sözleşme testi kılavuzumuzdadır.
Sorunu ortaya çıkaran üç iş
Rapor oluşturma. Bir finans aracı üç aylık bir dışa aktarım talep eder. Bu 90 saniye sürer. Saf bir araçla aracı bir iş kimliği alır, raporun hazır olduğunu duyurur ve ardından kullanıcıya bozuk bir indirme bağlantısı sunar. Engelleme yapan bir sarmalayıcı ile 90 saniye bekler ve gerçek URL'yi döndürür. Aynı API, zıt sonuçlar ve tek fark, beklemenin nerede gerçekleştiğidir.
Toplu içe aktarımlar. Bir operasyon aracı 20.000 kayıt yükler. İçe aktarma sekiz dakika sürer ve 14.000. satırda kısmen başarısız olur. Bu, saf bir başarı kontrolünü cezalandıran durumdur: iş bitti, bu yüzden done durumu doğrudur, ancak sonuç reddedilen satırların bir listesini içerir. Kısmi sonuçları açıkça, sayılarla döndürün ve aracı ilerlemeden önce bunları okumasını sağlayın.
Model ve derleme işlem hatları. Bir aracı, 40 dakika süren bir eğitim çalıştırmasını veya bir CI derlemesini tetikler. Sarmalayıcı içi sorgulama burada yanlış bir şekildir; çalışma, bir sırayı çok uzun süre açık tutardı. İşi başlatın, kimliği kalıcı depolamaya kaydedin, sırayı sonlandırın ve planlanmış bir kontrol veya geri aramanın takibi uyandırmasına izin verin. Çoklu aracı devri ve bağlam geçişi hakkındaki yazımız, bu durumu çalıştırmalar arasında kaybetmeden taşıyabilmeyi kapsar.
Kısmi sonuçlara bir şekil verin
Uzun işler genellikle başarı ve başarısızlık arasında bir yerde biter ve iki durumlu bir model sizi bu konuda yalan söylemeye zorlar. Üçüncü durumu açıkça belirtin:
{
"job_id": "job_a11f",
"status": "completed_with_errors",
"done": true,
"summary": { "processed": 20000, "succeeded": 19860, "failed": 140 },
"errors_url": "/v1/jobs/job_a11f/errors?limit=50",
"message": "Import finished. 140 rows failed and were not written. Review errors before reporting success."
}
Bu yükte iki şey önemlidir. Sayılar satır içidir, böylece aracı başka bir çağrıya ihtiyaç duymadan karar verebilir. Başarısız olan satırlar, bir sınırlama ile bir URL'nin arkasındadır, bu yüzden 140 hata nesnesi bağlama davetsizce düşmez.
Duraklayan işi birinin görmesi gerekiyor
Zaman aşımı yolu, bir iş kimliği ve işin hala devam ettiğini belirten bir mesajla sona erer. Bu doğru dönüş değeridir ve yalnızca bir kişiye ulaştığında faydalıdır.
Aracının kendi hizmetiniz olduğu durumlarda, ekibinizin zaten izlediği herhangi bir kuyruğa yönlendirin. Aracının atanmış görevleri yerine getiren bir kodlama çalışma zamanı olduğu durumlarda, onu çalıştıran platform genellikle bunun için bir yere sahiptir. Sharkly'de, engellenmiş olarak biten bir çalıştırma, yürütme durumu ve sonucuyla görevinin üzerinde kalır ve Gelen Kutusu, insan yanıtı veya incelemesi gerektiren öğeleri sıradan güncellemelerden ayırır. Önemli olan belirli araç değildir. Önemli olan "hala çalışıyor, daha sonra kontrol et" ifadesinin bir sahibinin olması gerektiğidir, aksi takdirde "kimse kontrol etmedi" olur.
Kısa bir kontrol listesi
- Her yavaş uç nokta, bir iş kimliği, bir durum URL'si ve işin bitmediğini belirten açık dilde bir mesaj döndürür.
- Durum yanıtları, modelin yorumlaması gereken bir dize yerine, boole bir
donealanı taşır. - Sorgulama, üstel geri çekilme (exponential backoff) ve katı bir üst sınır ile araç sarmalayıcısında yer alır.
- Zaman aşımları, işin kaybolmak yerine devam ettirilebilmesi için iş kimliğini döndürür.
- Başarı, başarısızlık ve zaman aşımı üç farklı dönüş değeridir.
- Birkaç dakikadan uzun süren herhangi bir iş için devam eden işler, konuşmanın dışında kaydedilir.
- Sinyal sorgulama yoluyla veya geri arama yoluyla gelse de tamamlama işlemi idempotenttir.
- Yavaş, geç başarısız olan, zaman aşımına uğrayan ve yinelenen tüm tamamlamalar kaydedilmiş testlere sahiptir.
Yanıtı ve sarmalayıcıyı doğru şekilde ayarlayın; uzun süreli işlemler aracı için özel bir durum olmaktan çıkar. Bir aracı çağırır, bekler ve en iyi şekilde ele aldığı sözleşme olan bir yanıt alır. Yavaş iş taklitlerini testlerle birlikte oluşturmak için Apidog'u indirin.
Sıkça sorulan sorular
API, asenkron bir başlangıç için 202 mi yoksa 200 mü döndürmeli? 202 Accepted dürüst koddur ve standart istemcilere işlemin bitmediğini işaret eder. Modeli en güvenilir şekilde gövde okuduğu için aracılar için buna tek başına güvenmeyin. İkisini de kullanın.
Araç sarmalayıcısı pes etmeden önce ne kadar beklemeli? Üst sınırı, uç noktanın gerçekçi en kötü durumunun biraz üzerine ayarlayın, genellikle iki ila on dakika. Bunun ötesinde sarmalayıcı, bir konuşma sırasını çok uzun süre engeller ve daha sonra kontrol etme aracı daha iyi bir şekildir.
Hangi sorgulama aralığını kullanmalıyım? Sunucunun kendi poll_after_seconds ipucunu (eğer veriyorsa) kullanarak başlayın, ardından yaklaşık 1.5 faktörüyle geri çekilin ve 60 saniye civarında bir üst sınır belirleyin. Sabit bir saniyelik sorgulama istekleri boşa harcar ve oran limiti aşıldı kılavuzumuzda belirtildiği gibi oran limitlerini tetikleyebilir.
Aracı beklerken yararlı bir şey yapabilir mi? Yalnızca düzenleyiciniz eşzamanlı araç çağrılarını destekliyorsa. Desteklediği yerlerde işi başlatın, bağımsız işi yapın, ardından durumu kontrol edin. Desteklemediği yerlerde, engelleme yapan sarmalayıcı, elle yazılmış bir zamanlayıcıdan daha basit ve daha az hataya açıktır.
Aracının başarıyı erken iddia etmesini nasıl engellerim? Yanıt gövdesinde bunu kelimelerle belirtin, boole bir done alanı gösterin ve tamamlama aracını bir sonucun görüneceği tek yer haline getirin. Başlangıç yanıtı bir sonuç içermiyorsa, modelin bir sonuç olarak bildireceği hiçbir şey yoktur.
Webhook'lar dizüstü bilgisayarda çalışan aracılar için çalışır mı? Doğrudan çalışmaz, çünkü herkese açık bir uç nokta yoktur. Webhook hizmetleriyle localhost API'lerini test etme kılavuzumuzda olduğu gibi geliştirme için bir tünel kullanın veya aracı adreslenebilir bir yerde çalışana kadar sorgulamaya bağlı kalın.