
Teknik not
OpenAI Batch API: Toplu Yapay Zekâ İşleri Nasıl Çalışır?

Her yapay zekâ isteğinin sonucunu anında almak zorunda değilseniz, istekleri tek tek göndermek yerine bir grup halinde işletebilirsiniz. OpenAI Batch API; sınıflandırma, değerlendirme ve embedding üretimi gibi bekleyebilen işleri sıraya alır. Böylece uygulamanın kullanıcıya anlık yanıt verme yükü ile arka plandaki büyük işleri birbirinden ayırırsınız.
Bu rehberde Batch API’nin ne zaman işe yaradığını, istek dosyasının nasıl hazırlandığını ve sonuçların doğru kayıtlarla nasıl eşleştirileceğini adım adım göreceğiz.

OpenAI Batch API ne işe yarar?
Batch API, çok sayıda bağımsız API isteğini bir .jsonl dosyasında toplar ve bunları asenkron biçimde işler. Her satır tek bir istektir. Dosyayı yükler, hangi API uç noktasında çalışacağını belirterek bir batch oluşturur, durumunu takip eder ve tamamlanınca çıktı dosyasını indirirsiniz.
OpenAI belgeleri Batch API için standart eşzamanlı isteklere kıyasla yüzde 50 maliyet indirimi, daha geniş ayrı hız limitleri ve 24 saatlik tamamlanma penceresi bildiriyor. Bu özellikler, yanıtı hemen gerekmeyen işler içindir; sohbet ekranında kullanıcı beklerken cevap üretmek için uygun değildir. Desteklenen kullanım örnekleri arasında büyük veri kümelerini sınıflandırmak, değerlendirme çalıştırmak ve içeriklere embedding üretmek yer alır. OpenAI Batch API belgeleri
Batch API kullanımı: beş adım
1. İstekleri JSONL dosyasına yazın
Her satıra bir istek koyun. Sonuçları kaynak kayıtla eşleştirmek için her satıra kendinize ait, benzersiz bir custom_id verin. Örneğin destek kayıtlarını sınıflandıran iki satır şöyle olabilir:
{"custom_id":"destek-1001","method":"POST","url":"/v1/responses","body":{"model":"MODEL_ADI","input":"Bu destek mesajını fatura, teknik sorun veya hesap erişimi olarak sınıflandır: Ödeme iki kez çekilmiş."}}
{"custom_id":"destek-1002","method":"POST","url":"/v1/responses","body":{"model":"MODEL_ADI","input":"Bu destek mesajını fatura, teknik sorun veya hesap erişimi olarak sınıflandır: Uygulamaya giriş yapamıyorum."}}
MODEL_ADI yerine hesabınızda kullanabildiğiniz bir modeli yazın. Her satır geçerli JSON olmalı; satır sonları kayıtları ayırır.
2. Dosyayı batch amacıyla yükleyin
Hazırladığınız dosyayı Files API üzerinden purpose: "batch" ile yükleyin. Yanıttaki dosya kimliğini saklayın; bir sonraki adım bu kimliği kullanır.
3. Batch işini oluşturun
Yüklenen dosyanın kimliğini, kullanılacak uç noktayı ve tamamlanma penceresini verin. Örneğin Responses API için yapı şu şekildedir:
const batch = await client.batches.create({
input_file_id: "file-...",
endpoint: "/v1/responses",
completion_window: "24h"
});
OpenAI belgelerindeki mevcut batch tamamlanma penceresi 24h değeridir. Batch oluşturma isteği, işin hemen tamamlandığı anlamına gelmez; dönen batch kimliğini kayıt altına alın.
4. Durumu takip edin
Batch’in durumunu kimliğiyle sorgulayın. Doğrulama ve işleme aşamalarından sonra tamamlandı, başarısız oldu veya süresi doldu gibi bir son durum görürsünüz. Uygulamanız bu duruma göre devam etmeli; yalnızca dosyanın yüklenmiş olmasını başarılı sonuç kabul etmemelidir.
5. Çıktı ve hata dosyalarını indirin
İş tamamlandığında batch nesnesindeki çıktı dosyası kimliğini kullanarak sonuçları indirin. Başarısız istekler için ayrı bir hata dosyası bulunabilir. Çıktı satırlarının girişteki sırayı koruyacağı varsayılmamalıdır: yanıtları, her satırda geri gelen custom_id değerine göre kendi verinizle birleştirin.
Pratik örnek: destek kayıtlarını topluca sınıflandırma
Bir destek ekibinin arşivindeki 8.000 eski mesajı üç kategoriye ayırdığını düşünün. Uygulanabilir akış şöyle olur:
- Her mesaj için değişmeyen bir kayıt kimliği seçin ve bunu
custom_idolarak yazın. - Mesajları JSONL satırlarına dönüştürün; gizli müşteri bilgilerini gereksiz yere göndermeyin.
- Dosyayı yükleyip batch’i oluşturun ve dönen batch kimliğini iş kaydınıza yazın.
- Durumu belli aralıklarla kontrol edin; geçici bir kontrol hatasında yeni bir batch açmak yerine mevcut kimliğin durumunu tekrar sorgulayın.
- Sonuç ve hata dosyalarını indirin,
custom_idile kaynak kayıtlarla eşleştirin ve hatalı satırları ayrı ele alın.
Bu yöntem, arşiv işleme gibi gecikmeye dayanıklı görevlerde yararlıdır. Anlık kullanıcı yanıtı, canlı moderasyon kararı ya da sonucu saniyeler içinde kullanılması gereken bir akış için eşzamanlı API çağrısı daha uygundur.
Üretime geçmeden önce kontrol edin
- Her isteğe benzersiz ve kalıcı bir
custom_idverin. - Batch kimliğini, oluşturulma zamanını ve son durumu saklayın; zaman aşımını otomatik olarak yeni iş başlatma nedeni saymayın.
- Mevcut belgelerde tek bir batch için üst sınır 50.000 istek ve giriş dosyası için 200 MB olarak belirtiliyor. İşinizi bu sınırlar içinde parçalara ayırın.
- Çıktı sırasına güvenmeyin; eşleştirmeyi
custom_idile yapın. - Başarı ve hata dosyalarını birlikte inceleyin; başarısız istekleri kontrollü biçimde yeniden işleyin.
Kısa özet
OpenAI Batch API, acil olmayan çok sayıdaki yapay zekâ isteğini dosyadan çalıştırıp sonuçları sonradan almanızı sağlar. Temel akış basittir: JSONL oluşturun, dosyayı yükleyin, batch’i başlatın, durumu izleyin ve sonuçları custom_id üzerinden eşleştirin. Doğru kullanıldığında arka plan işlerini çevrimiçi kullanıcı trafiğinden ayırmaya ve toplu işleme maliyetini azaltmaya yardımcı olur.