OpenAI Batch API Nasıl Kullanılır

Bu kılavuzun sonunda, OpenAI Toplu İş API'sini çağırarak binlerce model isteğini tek bir eşzamansız iş olarak çalıştırabilecek ve her sonucu %50 indirimle geri alabileceksiniz. İsteklerinizi bir JSONL dosyasına paketleyecek, tek bir toplu iş gönderecek, tamamlanana kadar yoklayacak ve çıktıyı indireceksiniz, ardından üretime bağlamadan önce her adımı Apidog'da test edeceksiniz. İşiniz daha etkileşimliyse, eşzamanlı yol daha uygun olacaktır ve bunun yerine ChatGPT API'sini Apidog ile test edebilirsiniz.

Toplu İş API'si Nedir ve Ne Zaman Kullanılmalıdır?

Toplu İş API'si, gecikmeye tolerans gösterebilen yüksek hacimli model çağrıları için eşzamansız bir uç noktadır. Her istek için bir HTTP isteği yapmak yerine, birçok isteği tek bir JSONL dosyasına paketler, tek bir iş olarak gönderir ve tamamlanması için yoklarsınız. OpenAI, işi yoğun olmayan zamanlarda çalıştırır ve her sonucu bir çıktı dosyasında döndürür.

İki somut fayda elde edersiniz. Birincisi, eşzamanlı API'ye kıyasla hem girdi hem de çıktı tokenlarında %50 sabit bir indirim. İkincisi, toplu işler ayrı bir hız sınırı havuzu kullandığından ve canlı trafiğinizle rekabet etmediğinden daha yüksek verim. Dezavantajı ise gecikmedir. OpenAI, 24 saat içinde tamamlanmayı taahhüt eder; birçok iş daha erken biter, ancak buna güvenemezsiniz.

İş çevrimdışı ve toplu nitelikte olduğunda toplu işlemeyi tercih edin:

• Birikmiş kayıtları sınıflandırma veya etiketleme
• Tüm bir metin kümesi için gömme (embedding) oluşturma
• Toplu içerik oluşturma (ürün açıklamaları, özetler, çeviriler)
• Bir veri kümesi üzerinde değerlendirme paketleri veya model karşılaştırmaları çalıştırma

Bir kullanıcının beklediği herhangi bir şey için bunu atlayın. Sohbet kullanıcı arayüzleri, otomatik tamamlama ve canlı aracılar eşzamanlı uç noktalara ihtiyaç duyar. Aynı anda birçok model veya aracı yapılandırması oluşturuyorsanız, toplu işleme bu iş yüküyle iyi uyum sağlar; toplu işlemeyle 100'den fazla aracı yapılandırması oluşturma hakkındaki rehberimize bakın.

Başlamadan Önce İhtiyaç Duyduklarınız

Tüm akış, iki uç nokta olan /v1/files ve /v1/batches ile dört adımdan oluşur. Çağrılara bakmadan önce şeması aşağıdadır.

Devam etmek için OPENAI_API_KEY olarak dışa aktarılmış bir OpenAI API anahtarına, bir istek JSONL dosyasına ve çağrıları tetikleyip incelemek için bir araca ihtiyacınız var. Her adım, üzerinde doğrulama yapabileceğiniz bir nesne döndürür, bu da tüm yaşam döngüsünü test etmeyi kolaylaştırır.

Adım 1: JSONL dosyasını oluşturun ve yükleyin

Girdiniz, her satırın kendi içinde bir istek olduğu bir JSONL dosyasıdır. Her satır dört alana ihtiyaç duyar: seçtiğiniz bir custom_id (sonuçları girdilerle eşleştirebilmek için), method (POST), url (/v1/chat/completions gibi hedef uç nokta) ve gerçek istek parametrelerini tutan bir body.

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'shipping was slow but the product is great'"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'returned it the same day'"}]}}

custom_id dosya içinde benzersiz olmalıdır. Sonuçlar belirli bir sırada gelmez, bu nedenle her yanıtı kaynak satırına yeniden bağlamak için bu kimliği kullanırsınız. Tek bir toplu iş 50.000 adede kadar istek içerebilir ve dosya 200 MB'a kadar olabilir.

batch amacı ile Dosyalar API'ye yükleyin:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@requests.jsonl"

Yanıt bir dosya id'si (file-abc123 gibi bir şey) taşır. Bu, bir sonraki adım için input_file_id'nizdir.

Adım 2: Toplu işi oluşturun

Şimdi işi oluşturun. input_file_id, hedeflediğiniz endpoint ve completion_window'u geçirirsiniz. Bugün completion_window tek bir değer, "24h" kabul eder.

curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {"job": "sentiment-backfill"}
  }'

endpoint alanı, JSONL satırlarınızda kullanılan url ile eşleşmelidir. Desteklenen hedefler arasında /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions ve /v1/moderations bulunur. İsteğe bağlı metadata nesnesi, daha sonra filtrelemek isteyeceğiniz işleri etiketlemek için kullanışlı olan 16 adede kadar anahtar-değer çifti tutar.

Çağrı bir toplu iş nesnesi döndürür. En çok önemseyeceğiniz alanlar:

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "request_counts": { "total": 0, "completed": 0, "failed": 0 },
  "created_at": 1733452800,
  "metadata": { "job": "sentiment-backfill" }
}

Adım 3: Toplu işin durumunu yoklayın

Yeni bir toplu iş validating durumunda başlar. Buradan bir dizi belgelenmiş duruma geçer. GET /v1/batches/{batch_id} adresini yoklayın ve status alanını okuyun.

request_counts nesnesi (total, completed, failed), durum in_progress iken size canlı ilerleme sağlar. Burada bekleyecek bir webhook yoktur, bu nedenle makul aralıklarla yoklama (her birkaç dakikada bir, her saniye değil) doğru yöntemdir. Yanlışlıkla gönderdiyseniz, POST /v1/batches/{batch_id}/cancel ile çalışan bir işi de iptal edebilirsiniz.

Adım 4: Çıktıyı alın

status completed olarak okunduğunda, toplu iş nesnesi bir output_file_id taşır. Bu dosyanın içeriğini Dosyalar API'si aracılığıyla indirin:

curl https://api.openai.com/v1/files/file-output456/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > results.jsonl

Çıktı yine JSONL'dir, istek başına bir satır. Her satır, belirlediğiniz custom_id'yi ve durum kodunu ve gövdeyi içeren bir response nesnesini yansıtır. Hata veren istekler error_file_id ile referans verilen dosyada görünür, bu yüzden her ikisini de kontrol edin. Sonuçları girdilerle custom_id üzerinden eşleştirin, satır sırasına göre değil.

Maliyet ve Süre Değişimlerini Göz Önünde Bulundurun

Matematik basit: tokenlarda %50 tasarruf edersiniz ve 24 saate kadar bir geri dönüş süresini kabul edersiniz. Tek seferlik bir veri doldurma veya gece çalışan bir iş için bu kolay bir karardır. Ürününüzün kritik yolundaki bir özellik için ise öyle değildir.

Birkaç pratik not:

• İndirim, desteklenen modeller genelinde hem girdi hem de çıktı tokenları için geçerlidir.
• 24 saatlik süre bir tavan olup, bir hedef değildir. En kötü senaryoyu planlayın; bir iş expired durumuna düşerse, tamamlanan istekler yine de faturalandırılır ve döndürülür, geri kalanı ise döndürülmez.
• Toplu işler ayrı bir sıraya alınmış token limitinden yararlanır, bu nedenle büyük bir toplu iş canlı trafiğinizin bağımlı olduğu hız limitlerini tüketmez. Zaten limitlere takılıyorsanız, GPT API hız limitleri ve bunları nasıl test edeceğinize dair kılavuzumuz eşzamanlı tarafı kapsar.
• Yarı fiyatına tokenlar hacim arttıkça yine de birikir. Daha sonra maliyeti ilişkilendirebilmek için metadata etiketini kullanarak iş başına harcamayı takip edin; işte OpenAI harcaması için bir maliyet atfetme kılavuzu.

Apidog'da Nasıl Test Edilir?

Toplu İş API'si, tek bir sohbet çağrısından daha hataya açıktır, çünkü hata modları dosyalar, JSONL biçimlendirmesi ve bir yoklama döngüsüne yayılmıştır. 50.000 istekli bir dosyadaki hatalı biçimlendirilmiş bir satır, tüm yüklemeyi başarısız kılar ve doğrulama çalışana kadar bunu bilemezsiniz. Yaşam döngüsü uç noktalarını otomatikleştirmeden önce test etmek, bu gidiş-dönüş süresinden sizi kurtarır.

Apidog, her adımı bir istek olarak çalıştırabileceğiniz, bunları zincirleyebileceğiniz ve yanıtlarda doğrulama yapabileceğiniz bir API platformudur. Uç noktaları test eder ve taklit eder; bir OpenAI SDK'sı değildir. Gerçekçi bir kurulum şöyle görünür:

• Önce JSONL biçimini doğrulayın. Herhangi bir şey yüklemeden önce, her satırın custom_id, method, url ve body taşıdığını ve body.model ile mesajların mevcut olduğunu doğrulayın. Eksik bir alanı yerel olarak yakalamak, başarısız bir toplu işten daha ucuzdur.
• Multipart yüklemeyi çalıştırın. purpose=batch ve dosyanızla birlikte POST /v1/files gönderin, ardından döndürülen id'yi bir ortam değişkenine kaydedin.
• Toplu işi oluşturun ve nesne üzerinde doğrulama yapın. POST /v1/batches'i tetikleyin, ardından status'un validating olduğunu ve endpoint'in gönderdiğinizle eşleştiğini doğrulayın. Apidog'un görsel doğrulama araçları, betik yazmadan bu alanları kontrol etmenizi sağlar.
• Yoklayın ve alın. Bir döngüde GET /v1/batches/{id}'yi çağırın, status completed olduğunda doğrulama yapın, ardından output_file_id'yi çekin ve sonuçları indirin.
• İptal ve hata yollarını deneyin. Kasıtlı olarak bozuk bir dosya gönderin ve failed durumu aldığınızı onaylayın, ayrıca POST /v1/batches/{id}/cancel'ı test edin, böylece hata yönetiminiz varsayılan değil, gerçek olur.

Çıktı dosyası daha sonra geldiği için, örnek bir tamamlanmış toplu iş nesnesi ve önceden hazırlanmış bir sonuç dosyası döndüren bir sahte API de kurabilirsiniz. Bu, gerçek bir 24 saatlik işi beklemeden ve geliştirme sırasında token harcamadan alma ve ayrıştırma mantığınızı oluşturmanıza ve test etmenize olanak tanır. Ekibiniz önce spesifikasyonla çalıştığında, doğrudan bir OpenAPI spesifikasyonundan bir test koleksiyonu oluşturabilir ve toplu iş uç noktalarını CI'da regresyon kapsamı altında tutabilirsiniz.

Sıkça Sorulan Sorular

Bir toplu iş aslında ne kadar sürer?

OpenAI, bir toplu işi 24 saat içinde tamamlamayı taahhüt eder. Pratikte birçok iş daha hızlı biter, ancak garanti 24 saatlik tavandır, bu yüzden sisteminizi buna göre kurun. Süreç tamamlanmadan kapanırsa, toplu iş expired durumuna geçer ve yalnızca tamamlanan istekler döndürülür ve faturalandırılır.

Gerçek indirim nedir ve birleşir mi?

Toplu İş API'si, eşzamanlı uç noktalara kıyasla hem girdi hem de çıktı tokenlarında %50 sabit bir indirim sağlar. OpenAI'ın çevrimdışı iş yükleri için sunduğu en büyük maliyet kaldıracıdır. Bu harcamayı özelliklere veya işlere geri atfetmeye çalışıyorsanız, maliyet atfetme kılavuzu bunu nasıl dilimleyeceğinizi gösterir.

Bir toplu işte hangi uç noktaları çalıştırabilirim?

Hedefi hem JSONL url'sinde hem de toplu işin endpoint alanında ayarlarsınız ve bunların eşleşmesi gerekir. Desteklenen hedefler arasında /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions ve /v1/moderations ile görüntü ve video uç noktaları bulunur. OpenAI zamanla bu listeyi genişlettiği için tam liste için güncel belgelere bakın.

Sonuçlarım neden sırasız?

Tasarıma göre sıralı değillerdir. Çıktı JSONL, girdi satırı sırasını korumaz; bu da her isteğin neden benzersiz bir custom_id'ye ihtiyaç duyduğunu açıklar. Sonuçları bu kimlik üzerinden girdilerle eşleştirin. İki satır aynı custom_id'yi paylaşıyorsa, yanıtlarını güvenilir bir şekilde ayırt edemezsiniz.

Sonuç

Artık tüm akışa sahipsiniz: isteklerinizi bir JSONL dosyasına paketleyin, yükleyin, toplu işi oluşturun, durumu yoklayın ve çıktıyı alın; tüm bunlar 24 saatlik bir pencerede token maliyetinin yarısına. Her adım, doğrulayabileceğiniz bir nesne döndürür, bu nedenle JSONL biçimi ve yoklama döngüsü doğru olduğunda, gerisi mekaniktir.

Otomatikleştirmeden önce yaşam döngüsünü elle çalıştırın. İstek dosyanızı doğrulamak, yükleme, oluşturma, yoklama ve iptal uç noktalarını denemek ve toplu iş nesnesi alanlarını doğrulamak için Apidog'u indirin, böylece hatalı biçimlendirilmiş bir satır size asla 24 saatlik bir gidiş-dönüşe mal olmaz.