
Teknik not
Yapay Zekâ Araçlarında Idempotency: Çift İşlemi Önleme

Bir yapay zekâ asistanı randevu oluşturma aracını çağırdı. Sunucu randevuyu kaydetti, ancak yanıt uygulamaya ulaşmadan bağlantı koptu. Asistan aynı isteği yeniden gönderdi ve ikinci bir randevu oluştu. Bu tür çift işlemler, araca yeniden deneme eklediğinizde kolayca ortaya çıkar.
Idempotency (aynı isteğin tekrarlanmasının tek bir sonuca bağlanması), aynı mantıksal işlemin güvenle yeniden denenmesini sağlar. Bu yazıda, yapay zekâ araç çağrılarında bunun nasıl kurulacağını ve nerede sınırlarının başladığını göreceğiz.

Yapay zekâ aracında tekrar deneme neden çift işlem oluşturur?
Model bir araç çağrısı üretir; uygulamanız bu çağrıyı çalıştırıp dış servise istek gönderir. Dış servis işlemi tamamlayabilir, fakat yanıt ağda kaybolabilir veya uygulamanın zaman aşımına uğramasına neden olabilir. Uygulama işlemin gerçekleşip gerçekleşmediğini bilemez ve çağrıyı yeniden deneyebilir.
Bu, özellikle ödeme alma, rezervasyon, sipariş oluşturma, e-posta gönderme veya kayıt açma gibi yan etkili işlemlerde önemlidir. Aynı isteği iki kere göndermek iki ayrı sonuç doğurabilir.
Idempotency anahtarı nasıl çalışır?
Uygulama, kullanıcının tek bir niyetini tanımlayan kararlı bir idempotency anahtarı üretir. Aynı mantıksal işlem yeniden denenirse aynı anahtar kullanılır. Sunucu bu anahtarı daha önce tamamlanmış bir işlemle eşleştirirse yeni bir yan etki yaratmak yerine önceki sonucu döndürür.
Bu anahtar, modelin araç çağrısı için verdiği call_id ile aynı şey değildir. OpenAI belgelerinde call_id, araç çıktısını ilgili çağrıyla eşleştirmek içindir. Kalıcı işlem tekilleştirmesini uygulamanız veya işlemi yapan servis tasarlamalıdır.
Güvenli bir akış için beş adım
- İşlem niyetini belirleyin. Örneğin “bu kullanıcı için 14 Mayıs saat 10.00 randevusu oluştur” bir mantıksal işlemdir.
- Anahtarı uygulama tarafında oluşturun. Anahtar, kullanıcı/hesap ve işlem türü kapsamında benzersiz olsun. Yeniden denemelerde aynı niyet için anahtarı koruyun; kullanıcının daha sonra bilerek istediği yeni randevuya yeni anahtar verin.
- Anahtarı kalıcı olarak kaydedin. Veritabanında benzersizlik kısıtı veya atomik kayıt işlemi kullanın. Böylece aynı anda gelen iki tekrar da tek bir işlem kaydına bağlanır.
- İşlem durumunu ve isteğin parmak izini tutun. Örneğin
IN_PROGRESSveCOMPLETEDdurumlarıyla birlikte, anahtarla gönderilen önemli parametrelerin özetini saklayın. Aynı anahtar farklı içerikle gelirse sessizce yeni işlem açmayın; çakışma olarak ele alın. - Anahtarı aşağı akış servisine iletin. Ödeme veya rezervasyon sağlayıcısı idempotency destekliyorsa aynı anahtarla isteği tekrarlayın ve dönen sonucu kaydedin. Tekrar geldiğinde tamamlanan sonucu geri verin.
Örnek: randevu oluşturma aracını güvenle yinelemek
Asistanın “randevu oluştur” çağrısı zaman aşımına uğradığında, yeni bir randevu isteği üretmek yerine ilk kullanıcı niyetine ait işlem kaydını arayın. Kayıt tamamlandıysa saklanan randevu kimliğini ve sonucu araca döndürün. Kayıt sürüyorsa ikinci bir dış çağrı başlatmayın; ilk işlemi bekleyin veya durumunu sorgulayın. Kayıt yoksa anahtarı benzersiz biçimde kaydedip işlemi başlatın.
Uygulama mantığı kabaca şöyledir:
key = stable_key(user_intent_id, "create_appointment")
record = get_or_create_unique(key, request_fingerprint)
if record.is_complete:
return record.saved_result
if record.is_in_progress:
return wait_or_check_status(record)
result = booking_service.create(..., idempotency_key=key)
save_result_and_mark_complete(key, result)
return result
Buradaki kritik nokta, anahtarı her denemede yeniden üretmemektir. Yeni bir kullanıcı niyeti içinse yeni bir işlem kimliği gerekir. Anahtarı yalnızca istek gövdesinden türetmek, kullanıcının aynı ayrıntılarla bilerek ikinci bir işlem yapmasını engelleyebilir.
Zaman aşımında hangi durumlar düşünülmeli?
Aynı anahtar, aynı parametreler
Bu, güvenli tekrar denemesidir. İşlem tamamlandıysa önceki yanıtı döndürün; sürüyorsa ikinci yan etkiyi başlatmayın.
Aynı anahtar, değişmiş parametreler
Bu bir çakışmadır. Örneğin aynı anahtar önce 10.00, sonra 11.00 randevusu için kullanılırsa isteği reddedin veya uygulamanızın açıkça tanımladığı düzeltme akışına yönlendirin. Anahtarı yeni içerikle kullanmak belirsiz sonuçlar doğurur.
Dış işlem tamamlandı, yerel yanıt kaydedilemedi
En zor durum budur: sağlayıcı işlemi yapmış olabilir, fakat uygulamanız sonucu yazamadan durmuş olabilir. Sağlayıcının aynı anahtarla tekrar sorgulama/yeniden gönderme desteğini kullanın; yoksa işlem kimliği, rezervasyon kaydı veya sağlayıcı sorgusu üzerinden sonucu uzlaştırın. Körlemesine yeni bir anahtar üretmeyin.
Kontrol listesi
- Tekrar denemede aynı mantıksal işleme aynı anahtar mı veriliyor?
- Anahtar için veritabanında atomik benzersizlik ve eşzamanlı istek koruması var mı?
- Aynı anahtar farklı parametrelerle gelirse davranış açık mı?
- Tamamlanan işlem sonucu tekrar geldiğinde yeniden kullanılabiliyor mu?
- Anahtarın geçerlilik süresi sona erdiğinde belirsiz işlemler nasıl uzlaştırılıyor?
- Aynı kullanıcı yeni bir işlem istediğinde yeni anahtar üretildiği test ediliyor mu?
Idempotency, dağıtık sistemlerde her koşulda “tam olarak bir kez” çalıştırma garantisi değildir. Doğru anahtar kapsamı, kalıcı kayıt, eşzamanlılık kontrolü ve belirsiz sonuçları uzlaştırma birlikte gerekir. Stripe’ın API belgesi de anahtarların saklanma süresi ve aynı anahtarla farklı parametre gönderme davranışını açıkça ele alır; bu nedenle kullandığınız servisin kurallarını kontrol edin.