OpenAI Batch API Nasıl Kullanılır

Bu kılavuzun sonunda, OpenAI Toplu İş API'sini kullanarak binlerce model isteğini tek bir eşzamansız iş olarak çalıştırabilecek, sonuçları indirebilecek ve token maliyetinde %50 indirimden yararlanabileceksiniz. Akış şu şekilde: istekleri JSONL dosyasına paketleyin, dosyayı yükleyin, toplu işi oluşturun, tamamlanana kadar yoklayın ve çıktıyı indirin. Üretime almadan önce her adımı Apidog üzerinde test edebilirsiniz. İşiniz kullanıcı bekleyen etkileşimli bir akışsa, toplu iş yerine eşzamanlı API kullanın ve ChatGPT API'sini Apidog ile test edin.

Apidog'u bugün deneyin

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 kayıt için ayrı HTTP isteği göndermek yerine, tüm istekleri bir JSONL dosyasına koyar, tek bir iş olarak gönderir ve tamamlanana kadar durumu yoklarsınız. OpenAI işi arka planda çalıştırır ve sonuçları bir çıktı dosyasında döndürür.

Pratikte iki avantaj sağlar:

• Eşzamanlı API'ye kıyasla girdi ve çıktı tokenlarında %50 indirim.
• Toplu işler ayrı bir hız sınırı havuzu kullandığı için canlı trafiğinizle rekabet etmeyen daha yüksek verim.

Dezavantaj gecikmedir. OpenAI, işin 24 saat içinde tamamlanmasını taahhüt eder. Birçok iş daha erken bitebilir, ancak sistem tasarımınızı buna göre yapmamalısınız.

Toplu işlemeyi şu işler için tercih edin:

• Birikmiş kayıtları sınıflandırma veya etiketleme
• Tüm metin kümesi için embedding oluşturma
• Ürün açıklaması, özet veya çeviri gibi toplu içerik üretimi
• Veri kümesi üzerinde değerlendirme paketleri veya model karşılaştırmaları çalıştırma

Kullanıcının yanıt beklediği sohbet arayüzleri, otomatik tamamlama ve canlı aracı senaryolarında bunu kullanmayın. Aynı anda çok sayıda model veya aracı yapılandırması oluşturuyorsanız, toplu işlemeyle 100'den fazla aracı yapılandırması oluşturma rehberine de bakabilirsiniz.

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

Akış iki ana uç nokta üzerinden ilerler:

• /v1/files
• /v1/batches

Adım	Uç Nokta	Ne Olur
1. Yükle	POST /v1/files	.jsonl dosyanızı purpose: "batch" ile gönderir, dosya kimliği alırsınız
2. Oluştur	POST /v1/batches	Dosya kimliğini hedef uç nokta ve tamamlama penceresiyle gönderirsiniz
3. Yokla	GET /v1/batches/{id}	status değeri completed olana kadar kontrol edersiniz
4. Al	GET /v1/files/{id}/content	output_file_id ile sonuçları indirirsiniz

Devam etmek için şunlara ihtiyacınız var:

• OPENAI_API_KEY olarak dışa aktarılmış OpenAI API anahtarı
• JSONL formatında istek dosyası
• HTTP çağrılarını çalıştırmak ve yanıtları incelemek için curl, Apidog veya benzeri bir API aracı

Adım 1: JSONL Dosyasını Oluşturun ve Yükleyin

Girdi dosyanız JSONL olmalıdır. Her satır bağımsız bir istektir.

Her satırda şu alanlar bulunur:

• custom_id: Sonucu kaynak satırla eşleştirmek için benzersiz kimlik
• method: Genellikle POST
• url: Hedef uç nokta, örneğin /v1/chat/completions
• body: Gerçek model isteği

Örnek requests.jsonl:

{"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'"}]}}

Dikkat edilmesi gerekenler:

• custom_id dosya içinde benzersiz olmalıdır.
• Sonuçlar girdi sırasıyla dönmeyebilir.
• Yanıtları satır sırasına göre değil, custom_id ile eşleştirin.
• Tek bir toplu iş 50.000 adede kadar istek içerebilir.
• Dosya boyutu 200 MB'a kadar olabilir.

Dosyayı batch amacıyla yükleyin:

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

Yanıtta bir dosya id değeri döner:

{
  "id": "file-abc123",
  "object": "file",
  "purpose": "batch"
}

Bu değer bir sonraki adımda input_file_id olarak kullanılır.

Adım 2: Toplu İşi Oluşturun

Dosya yüklendikten sonra toplu işi oluşturun. Bunun için şunları gönderirsiniz:

• input_file_id
• endpoint
• completion_window

Bugün completion_window için kabul edilen değer "24h" şeklindedir.

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ındaki url alanıyla eşleşmelidir.

Desteklenen hedefler arasında şunlar bulunur:

• /v1/chat/completions
• /v1/responses
• /v1/embeddings
• /v1/completions
• /v1/moderations

İsteğe bağlı metadata alanı, işleri daha sonra filtrelemek veya maliyeti ilişkilendirmek için kullanışlıdır. En fazla 16 anahtar-değer çifti tutabilir.

Örnek toplu iş yanıtı:

{
  "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"
  }
}

Bu yanıttaki id değerini saklayın. Sonraki adımda toplu iş durumunu bu kimlikle yoklayacaksınız.

Adım 3: Toplu İşin Durumunu Yoklayın

Yeni bir toplu iş genellikle validating durumunda başlar. Durumu kontrol etmek için:

curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY"

İzlemeniz gereken ana alan status değeridir.

Durum	Anlamı
validating	Girdi dosyası çalıştırmadan önce kontrol ediliyor
in_progress	İstekler işleniyor
finalizing	Çalıştırma tamamlandı, çıktı dosyası hazırlanıyor
completed	İş tamamlandı, sonuçlar indirilmeye hazır
failed	Doğrulama başarısız oldu, hiçbir istek çalıştırılmadı
expired	24 saatlik süre tüm istekler tamamlanmadan sona erdi
cancelling / cancelled	İptal talebi işlendi veya tamamlandı

request_counts nesnesi, iş ilerlerken canlı ilerleme sağlar:

{
  "request_counts": {
    "total": 50000,
    "completed": 42000,
    "failed": 10
  }
}

Yoklama için makul aralıklar kullanın. Her saniye yoklamak yerine birkaç dakikada bir kontrol etmek genellikle yeterlidir.

Yanlış bir iş gönderdiyseniz iptal edebilirsiniz:

curl -X POST https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY"

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

status değeri completed olduğunda toplu iş nesnesinde output_file_id bulunur.

Sonuç dosyasını indirin:

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

Çıktı yine JSONL formatındadır. Her satır genellikle şunları içerir:

• custom_id
• response
• HTTP durum kodu
• Yanıt gövdesi

Örnek yapı:

{
  "custom_id": "req-1",
  "response": {
    "status_code": 200,
    "body": {
      "id": "chatcmpl-...",
      "object": "chat.completion"
    }
  }
}

Hata veren istekler error_file_id ile referans verilen dosyada yer alabilir. Bu yüzden yalnızca output_file_id değil, error_file_id alanını da kontrol edin.

Sonuçları işlerken temel kural:

custom_id -> kaynak kayıt
custom_id -> model sonucu

Satır sırasına güvenmeyin.

Maliyet ve Süre Değişimlerini Planlayın

Toplu İş API'sinde temel takas şudur:

• Token maliyetinde %50 indirim
• 24 saate kadar gecikme

Bu nedenle toplu işlemeyi şu işler için kullanmak mantıklıdır:

• Gece çalışan veri işleme görevleri
• Tek seferlik backfill işlemleri
• Büyük ölçekli sınıflandırma veya embedding işleri
• Çevrimdışı değerlendirme paketleri

Ancak ürününüzün kritik kullanıcı yolunda kullanmayın.

Pratik notlar:

• İndirim, desteklenen modellerde hem girdi hem de çıktı tokenları için geçerlidir.
• 24 saatlik süre hedef değil, üst sınırdır.
• İş expired durumuna düşerse, tamamlanan istekler döndürülür ve faturalandırılır; tamamlanmayanlar dönmez.
• Toplu işler ayrı bir sıraya alınmış token limitinden yararlanır, bu nedenle canlı trafiğinizin hız limitlerini tüketmez.
• Eşzamanlı tarafta limitlere takılıyorsanız, GPT API hız limitleri ve bunları nasıl test edeceğinize dair kılavuza bakın.
• İş başına maliyeti izlemek için metadata kullanın. Maliyet takibi için OpenAI harcaması maliyet atfetme kılavuzu yardımcı olabilir.

Apidog'da Nasıl Test Edilir?

Toplu İş API'si tek bir sohbet çağrısından daha fazla hata yüzeyi içerir:

• JSONL biçimi hatalı olabilir.
• Bir satırda eksik alan bulunabilir.
• Dosya yükleme başarısız olabilir.
• Toplu iş doğrulamada kalabilir veya failed durumuna düşebilir.
• Yoklama ve çıktı indirme mantığı yanlış kurulabilir.

Bu yüzden otomasyon yazmadan önce tüm yaşam döngüsünü manuel olarak test etmek faydalıdır.

Apidog, API isteklerini çalıştırabileceğiniz, zincirleyebileceğiniz ve yanıt alanlarını doğrulayabileceğiniz bir API platformudur. OpenAI SDK'sı değildir; uç noktaları test etmek, belgelemek ve taklit etmek için kullanılır.

1. JSONL Formatını Önce Yerelde Doğrulayın

Yüklemeden önce her satırda şu alanların olduğundan emin olun:

{
  "custom_id": "req-1",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {}
}

Kontrol edilmesi gerekenler:

• custom_id var mı?
• custom_id benzersiz mi?
• method POST mu?
• url, toplu iş endpoint değeriyle eşleşiyor mu?
• body.model var mı?
• Mesaj veya input alanları hedef uç nokta için geçerli mi?

Eksik bir alanı yerelde yakalamak, başarısız bir 24 saatlik iş döngüsünden daha ucuzdur.

2. Multipart Dosya Yüklemeyi Test Edin

Apidog'da POST /v1/files isteği oluşturun.

Form alanları:

Alan	Değer
purpose	batch
file	requests.jsonl

Yanıttan dönen id değerini ortam değişkeni olarak kaydedin:

input_file_id = file-abc123

3. Toplu İşi Oluşturun ve Yanıtı Doğrulayın

POST /v1/batches isteğini oluşturun:

{
  "input_file_id": "{{input_file_id}}",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "job": "sentiment-backfill"
  }
}

Yanıtta şu alanları doğrulayın:

• status değeri validating veya beklenen başka bir durum mu?
• endpoint, gönderdiğiniz değerle aynı mı?
• input_file_id, yüklediğiniz dosya kimliğiyle eşleşiyor mu?
• id alanı mevcut mu?

Dönen id değerini ortam değişkeni olarak saklayın:

batch_id = batch_abc123

4. Yoklama Akışını Test Edin

GET /v1/batches/{id} isteğini oluşturun:

GET /v1/batches/{{batch_id}}

Kontrol etmeniz gereken alanlar:

• status
• request_counts.total
• request_counts.completed
• request_counts.failed
• output_file_id
• error_file_id

status değeri completed olduğunda output_file_id değerini kaydedin.

5. Çıktı Dosyasını İndirin

GET /v1/files/{id}/content isteğini çalıştırın:

GET /v1/files/{{output_file_id}}/content

Sonuçları indirip ayrıştırma kodunuzda custom_id üzerinden eşleştirin.

6. Hata ve İptal Senaryolarını Deneyin

Gerçek üretim akışına geçmeden önce şu yolları da test edin:

• Bilerek bozuk JSONL dosyası gönderin ve failed durumunu doğrulayın.
• Eksik body.model içeren satırla doğrulama sonucunu kontrol edin.
• Çalışan bir iş için POST /v1/batches/{id}/cancel çağrısını test edin.
• error_file_id dönmesi durumunda hata dosyasını indirme mantığını çalıştırın.

Çıktı dosyası daha sonra oluştuğu için, geliştirme sırasında örnek bir tamamlanmış toplu iş nesnesi ve hazırlanmış sonuç dosyası döndüren bir sahte API de kurabilirsiniz. Böylece gerçek bir 24 saatlik işi beklemeden çıktı ayrıştırma mantığını geliştirebilirsiniz.

Ekibiniz OpenAPI spesifikasyonuyla çalışıyorsa, doğrudan spesifikasyondan test koleksiyonu oluşturabilir ve toplu iş uç noktalarını CI içinde regresyon testine dahil edebilirsiniz.

Sıkça Sorulan Sorular

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

OpenAI, toplu işlerin 24 saat içinde tamamlanmasını taahhüt eder. Birçok iş daha hızlı bitebilir, ancak garanti edilen sınır 24 saattir. Sisteminiz bu en kötü senaryoya göre tasarlanmalıdır.

İş süre dolmadan tamamlanmazsa expired durumuna geçer. Bu durumda yalnızca tamamlanan istekler döndürülür ve faturalandırılır.

Gerçek indirim nedir?

Toplu İş API'si, eşzamanlı uç noktalara kıyasla hem girdi hem de çıktı tokenlarında %50 sabit indirim sağlar. Çevrimdışı iş yüklerinde en önemli maliyet avantajı budur.

Harcamayı özelliklere veya işlere göre ilişkilendirmek istiyorsanız, maliyet atfetme kılavuzu bu yapıyı kurmanıza yardımcı olur.

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

Hedef uç noktayı iki yerde belirtirsiniz:

• JSONL satırındaki url
• Toplu iş oluştururken gönderilen endpoint

Bu iki değer eşleşmelidir.

Desteklenen hedefler arasında şunlar bulunur:

• /v1/chat/completions
• /v1/responses
• /v1/embeddings
• /v1/completions
• /v1/moderations

OpenAI zamanla desteklenen uç nokta listesini genişletebildiği için güncel listeyi resmi belgelerden kontrol edin.

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

Bu beklenen davranıştır. Çıktı JSONL dosyası, girdi satır sırasını korumak zorunda değildir. Bu nedenle her istekte benzersiz bir custom_id kullanmanız gerekir.

Doğru eşleştirme yöntemi:

girdi.custom_id == çıktı.custom_id

İki satır aynı custom_id değerini paylaşırsa, yanıtları güvenilir şekilde ayırt edemezsiniz.

Sonuç

Toplu İş API'si için uygulanabilir akış şudur:

1. İstekleri JSONL dosyasına paketleyin.
2. Dosyayı purpose=batch ile yükleyin.
3. POST /v1/batches ile toplu işi oluşturun.
4. GET /v1/batches/{id} ile durumu yoklayın.
5. completed olduğunda output_file_id ile sonucu indirin.
6. Sonuçları custom_id üzerinden kaynak kayıtlarla eşleştirin.

Bu yapı, 24 saate kadar gecikmeyi kabul edebilen çevrimdışı işlerde token maliyetini yarıya indirir. Üretime almadan önce JSONL biçimini, dosya yüklemeyi, iş oluşturmayı, yoklamayı, iptali ve çıktı ayrıştırmayı manuel olarak test edin.

Bu yaşam döngüsünü daha güvenli doğrulamak için Apidog'u indirin ve hatalı biçimlendirilmiş tek bir satırın size gereksiz bir 24 saatlik geri dönüş süresi yaşatmasını önleyin.