Azure OpenAI toplu dağıtımlarını kullanmaya başlama

Azure OpenAI Batch API'si büyük ölçekli ve yüksek hacimli işleme görevlerini verimli bir şekilde işler. Ayrı bir kotaya tabi asenkron istek gruplarını işler ve küresel standarda göre %50 daha düşük maliyetle 24 saatlik hedef tamamlama süresi sunar. Toplu işlemle, tek seferde bir istek göndermek yerine tek bir dosyada çok sayıda istek gönderirsiniz. Genel toplu iş isteklerinin ayrı bir sıralanmış belirteç kotası vardır, bu nedenle çevrimiçi iş yükleriniz kesintiye uğramaz.

Önemli kullanım örnekleri şunlardır:

  • Large-Scale Veri İşleme: Kapsamlı veri kümelerini paralel olarak hızla analiz edin.

  • İçerik Oluşturma: Ürün açıklamaları veya makaleler gibi büyük hacimli metinler oluşturun.

  • Belge Gözden Geçirme ve Özetleme: Uzun belgeleri gözden geçirmeyi ve özetlemeyi otomatikleştirin.

  • Müşteri Desteği Otomasyonu: Daha hızlı yanıtlar için aynı anda çok sayıda sorgu işleyebilir.

  • Veri Ayıklama ve Çözümleme: Çok miktarda yapılandırılmamış veriden bilgi ayıklayın ve analiz edin.

  • Doğal Dil İşleme (NLP) Görevleri: Büyük veri kümelerinde yaklaşım analizi veya çeviri gibi görevler gerçekleştirin.

  • Pazarlama ve Kişiselleştirme: Büyük ölçekte kişiselleştirilmiş içerik ve öneriler oluşturun.

Ipucu

Toplu işleriniz, dağıtımınız için ayrılan kotayı en üst düzeye çıkarmanıza rağmen kuyruğa alınmış belirteç sınırına ulaşacak kadar büyükse, bazı bölgeler artık birden fazla toplu işi üstel geri çekilme ile kuyruğa almanıza olanak tanıyan yeni bir özelliği destekliyor.

Sıralanan belirteç kotanız kullanılabilir olduğunda, bir sonraki toplu iş otomatik olarak oluşturulabilir ve başlatılır. Daha fazla bilgi edinmek için bkz. Üstel geri alma ile büyük toplu işlerin yeniden denemelerini otomatikleştirme.

Önemli

Hizmet, toplu iş isteklerini 24 saat içinde işlemeyi amaçlar, ancak daha uzun sürecek işlerin süresi dolmaz. İşi istediğiniz zaman iptal edebilirsiniz. İşi iptal ettiğinizde, hizmet kalan tüm çalışmaları iptal eder ve zaten tamamlanmış olan işleri döndürür. Tamamlanan tüm çalışmalar için ödeme alırsınız.

Beklemede depolanan veriler belirlenen Azure coğrafyada kalırken, veriler herhangi bir Azure OpenAI konumunda çıkarım için işlenebilir.  Veri yerleşimi hakkında daha fazla bilgi edinin. 

Batch desteği

Genel toplu işlem modeli erişilebilirliği

Bölge gpt-5.4-mini, 2026-03-17 gpt-5.4, 2026-03-05 gpt-5.1, 2025-11-13 gpt-5, 2025-08-07 o3, 2025-04-16 o4-mini, 2025-04-16 gpt-4.1, 2025-04-14 gpt-4.1-nano, 2025-04-14 gpt-4.1-mini, 2025-04-14 o3-mini, 2025-01-31 gpt-4o, 2024-05-13 gpt-4o, 2024-08-06 gpt-4o, 2024-11-20 gpt-4o-mini, 2024-07-18
australiaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
brazilsouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
canadaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
centralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus2 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
francecentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
AlmanyaBatıMerkez ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
japaneast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Kore Merkez ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
northcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
norwayeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
polonyamerkezi ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southafricanorth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Güney Hindistan ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
swedencentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
İsviçre Kuzey ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
uksouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westeurope ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus3 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

Not

Genel Batch eski API sürümlerini desteklese de, bazı modeller daha yeni API sürümleri gerektirir. Örneğin, o3-mini bu tarihten sonra yayımlandığı için 2024-10-21 ile desteklenmez. Global Batch ile daha yeni modellere erişmek için v1 API'sini kullanın.

Özellik desteği

Aşağıdaki özellikler şu anda desteklenmiyor:

  • Yardımcılar API'siyle tümleştirme.
  • Verilerinizde OpenAI özelliğini Azure ile tümleştirme.

Toplu dağıtım

Not

Microsoft Dökümhane portalında toplu dağıtım türleri Global-Batch ve Data Zone Batch olarak görünür. Azure OpenAI dağıtım türleri hakkında daha fazla bilgi edinmek için deployment türleri kılavuzuna bakın.

Ipucu

Sıraya alınan belirteç kotasının yetersiz olması nedeniyle görev hatalarını önlemeye yardımcı olmak için tüm genel toplu model dağıtımlarında dinamik kotayı etkinleştirmenizi öneririz. Dinamik kota kullanmak, ek kapasite kullanılabilir olduğunda dağıtımınızın fırsatçı olarak daha fazla kotadan yararlanmasını sağlar. Dinamik kota kapalı olarak ayarlandığında, dağıtımınız yalnızca dağıtımı oluşturduğunuzda tanımlanan sıralanmış belirteç sınırına kadar olan istekleri işleyebilecektir.

Önkoşullar

  • Azure aboneliği - ücretsiz bir abonelik oluşturma.
  • GlobalBatch veya DataZoneBatch dağıtım türü modeline sahip bir kaynak dağıtıldı.

Toplu iş dosyanızı hazırlama

Hassas ayarlama gibi toplu işlem de dosyaları JSON satırları (.jsonl) biçiminde kullanır. Aşağıda desteklenen içerik türleri farklı olan bazı örnek dosyalar verilmişti:

Giriş biçimi

Yanıtlar API'si

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

Sohbet tamamlama API'si

{"custom_id": "task-0", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id, belirli bir yanıtla hangi toplu iş isteğinin eşleştiğini belirlemenize olanak tanımak için gereklidir. Yanıtlar, toplu iş dosyasında tanımlanan .jsonl siparişle aynı sırada döndürülemez.

model özniteliği, çıkarım yanıtları için hedeflemek istediğiniz Genel Batch dağıtımının adıyla eşleşecek şekilde ayarlanmalıdır.

Önemli

Öznitelik, model çıkarım yanıtları için hedeflemek istediğiniz Genel Batch dağıtımının adıyla eşleşecek şekilde ayarlanmalıdır. Toplu iş dosyasının her satırında aynı Genel Batch modeli dağıtım adı bulunmalıdır. Farklı bir dağıtımı hedeflemek istiyorsanız, bunu ayrı bir toplu iş dosyasında/işinde yapmanız gerekir.

En iyi performans için, her dosyada yalnızca birkaç satır bulunan çok sayıda küçük dosya yerine toplu işlem için büyük dosyalar göndermenizi öneririz.

Giriş dosyası oluşturma

Bu makale için adlı test.jsonl bir dosya oluşturacağız ve yukarıdaki standart giriş kodu bloğundaki içeriği dosyaya kopyalayacağız. Genel toplu dağıtım adınızı değiştirmeniz ve dosyanın her satırına eklemeniz gerekir.

Toplu iş oluştur

Giriş dosyanız hazırlandıktan sonra bir toplu iş başlatabilmek için önce dosyayı karşıya yüklemeniz gerekir. Dosya yükleme işlemi hem program aracılığıyla hem de Microsoft Foundry portalı üzerinden yapılabilir. Bu örnekte, bir dosyanın doğrudan Azure OpenAI kaynağınıza yüklenmesi gösterilmektedir. Alternatif olarak, Azure OpenAI Batch için Azure Blob Depolama'ı yapılandırabilirsiniz.

  1. Microsoft Foundry oturum açın. Yeni Dökümhane anahtarının açık olduğundan emin olun. Bu adımlar Foundry (yeni)'ye atıfta bulunur.

  2. Sağ üst köşede Derle seçin

  3. Sol bölmeden Modeller'i seçin

  4. Toplu İşler'i> seçerektoplu iş oluşturun

    Yeni Foundry toplu oluşturma deneyiminin ekran görüntüsü.

Toplu iş ilerleme durumunu izleme

İşiniz oluşturulduktan sonra, en son oluşturulan işin İş Kimliğini seçerek işin ilerleme durumunu izleyebilirsiniz. Varsayılan olarak, en son oluşturduğunuz toplu işin durum sayfasına yönlendirilirsiniz.

İşinizin durumunu sağ bölmeden izleyebilirsiniz:

Toplu iş çıktı dosyasını alma

İşiniz tamamlandıktan veya terminal durumuna ulaştıktan sonra, aşağı ok simgesiyle ilgili düğme seçilerek gözden geçirilme amacıyla indirilebilen bir hata dosyası ve bir çıkış dosyası oluşturur.

Toplu işlemi iptal et

Devam eden toplu işlemi iptal eder. Toplu işlem, cancelling durumunda 10 dakikaya kadar kalacak, ardından cancelled durumuna geçecek, bu noktada çıktı dosyasında kısmi sonuçlar (varsa) bulunabilir.

Önkoşullar

Bu makaledeki adımların Jupyter Notebooks'ta sıralı olarak çalıştırılması amaçlanmıştır. Bu nedenle, örneklerin başında Azure OpenAI istemcisinin örneğini yalnızca bir kez oluşturacağız. Sıra dışı bir adım çalıştırmak istiyorsanız, genellikle bu çağrının bir parçası olarak bir Azure OpenAI istemcisi ayarlamanız gerekir.

OpenAI Python kitaplığı zaten yüklü olsa bile yüklemenizi en son sürüme yükseltmeniz gerekebilir:

!pip install openai --upgrade

Toplu iş dosyanızı hazırlama

Genel toplu işlem, ince ayarlama gibi dosyaları da JSON satırları (.jsonl) biçiminde kullanır. Aşağıda desteklenen içerik türleri farklı olan bazı örnek dosyalar verilmişti:

Giriş biçimi

Yanıtlar API'si

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

Sohbet tamamlama API'si

{"custom_id": "task-0", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id, belirli bir yanıtla hangi toplu iş isteğinin eşleştiğini belirlemenize olanak tanımak için gereklidir. Yanıtlar, toplu iş dosyasında tanımlanan .jsonl siparişle aynı sırada döndürülemez.

model özniteliği, çıkarım yanıtları için hedeflemek istediğiniz Genel Batch dağıtımının adıyla eşleşecek şekilde ayarlanmalıdır.

Önemli

Öznitelik, model çıkarım yanıtları için hedeflemek istediğiniz Genel Batch dağıtımının adıyla eşleşecek şekilde ayarlanmalıdır. Toplu iş dosyasının her satırında aynı Genel Batch modeli dağıtım adı bulunmalıdır. Farklı bir dağıtımı hedeflemek istiyorsanız, bunu ayrı bir toplu iş dosyasında/işinde yapmanız gerekir.

En iyi performans için, her dosyada yalnızca birkaç satır bulunan çok sayıda küçük dosya yerine toplu işlem için büyük dosyalar göndermenizi öneririz.

Giriş dosyası oluşturma

Bu makale için adlı test.jsonl bir dosya oluşturacağız ve yukarıdaki standart giriş kodu bloğundaki içerikleri dosyaya kopyalayacağız. Genel toplu dağıtım adınızı değiştirmeniz ve dosyanın her satırına eklemeniz gerekir. Bu dosyayı Jupyter Notebook yürüttüğünüz dizine kaydedin.

Toplu iş dosyasını karşıya yükleme

Giriş dosyanız hazırlandıktan sonra bir toplu iş başlatabilmek için önce dosyayı karşıya yüklemeniz gerekir. Dosya yükleme işlemi hem program aracılığıyla hem de Microsoft Foundry portalı üzerinden yapılabilir. Bu örnekte, bir dosyanın doğrudan Azure OpenAI kaynağınıza yüklenmesi gösterilmektedir. Alternatif olarak, Azure OpenAI Batch için Azure Blob Depolama'ı yapılandırabilirsiniz.

import os
from datetime import datetime
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

# Upload a file with a purpose of "batch"
file = client.files.create(
  file=open("test.jsonl", "rb"), 
  purpose="batch",
  extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}} # Optional you can set to a number between 1209600-2592000. This is equivalent to 14-30 days
)

print(file.model_dump_json(indent=2))

print(f"File expiration: {datetime.fromtimestamp(file.expires_at) if file.expires_at is not None else 'Not set'}")

file_id = file.id

expires_after nesnesi, giriş dosyasının siz oluşturduktan 14 gün sonra süresinin dolmasını sağlar. 14 ila 30 gün arasında bir sona erme süresi seçmek için 1209600 değerini 2592000 ile seconds arasında bir değere ayarlayın. Süre sonu ayarlamak, giriş dosyası sınırını da artırır. Ayrıntılar için bkz. Batch sınırları.

Çıkış:

{
  "id": "file-655111ec9cfc44489d9af078f08116ef",
  "bytes": 176064,
  "created_at": 1743391067,
  "filename": "test.jsonl",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "expires_at": 1744600667,
  "status_details": null
}
File expiration: 2025-04-13 23:17:47

Toplu iş oluştur

Dosyanız başarıyla karşıya yüklendikten sonra dosyayı toplu işlem için gönderebilirsiniz.

# Submit a batch job with the file
batch_response = client.batches.create(
    input_file_id=file_id,
    endpoint="/chat/completions", # While passing this parameter is required, the system will read your input file to determine if the chat completions or responses API is needed.  
    completion_window="24h",
    # extra_body={"output_expires_after":{"seconds": 1209600, "anchor": "created_at"}} # Optional you can set to a number between 1209600-2592000. This is equivalent to 14-30 days
)

# Save batch ID for later use
batch_id = batch_response.id

print(batch_response.model_dump_json(indent=2))

Not

Şu anda tamamlanma penceresi olarak 24hayarlanmalıdır. Başka bir değer ayarlarsanız 24h başarısız olur. 24 saatten uzun süren işler iptal edilene kadar yürütülmeye devam eder.

Çıkış:

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-655111ec9cfc44489d9af078f08116ef",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": null,
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": null,
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

Toplu işleriniz, dağıtımınızın kotasını tamamen kullandıktan sonra dahi sıraya alınan belirteç sınırına ulaşacak kadar büyükse, bazı bölgeler artık yeni bir erken hata verme özelliğini destekliyor. Bu özellik, üstel geri çekilme ile birden çok toplu işi kuyruğa almanıza olanak tanıyor ki, böylece bir büyük toplu iş tamamlandıktan sonra bir sonraki otomatik olarak başlatılabilir. Bu özelliği hangi bölgelerin desteklediği hakkında daha fazla bilgi edinmek ve kodunuzu bundan yararlanmak için uyarlamak için bkz. toplu işleri sıraya alma.

Toplu iş ilerleme durumunu izleme

Toplu işi başarıyla oluşturduktan sonra, ilerleme durumunu Studio'da veya program aracılığıyla izleyebilirsiniz. Toplu iş ilerleme durumunu denetlerken her durum çağrısı arasında en az 60 saniye beklemenizi öneririz.

import time
import datetime 

status = "validating"
while status not in ("completed", "failed", "canceled"):
    time.sleep(60)
    batch_response = client.batches.retrieve(batch_id)
    status = batch_response.status
    print(f"{datetime.datetime.now()} Batch Id: {batch_id},  Status: {status}")

if batch_response.status == "failed":
    for error in batch_response.errors.data:  
        print(f"Error code {error.code} Message {error.message}")

Çıkış:

2024-07-31 21:48:32.556488 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: validating
2024-07-31 21:49:39.221560 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:50:53.383138 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:52:07.274570 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:53:21.149501 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:54:34.572508 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:55:35.304713 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:56:36.531816 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:57:37.414105 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: completed

Aşağıdaki durum değerleri mümkündür:

Durum Açıklama
validating Toplu işlem başlamadan önce giriş dosyası doğrulanıyor.
failed Giriş dosyası doğrulama işlemi başarısız oldu.
in_progress Giriş dosyası başarıyla doğrulandı ve toplu iş şu anda çalışıyor.
finalizing Toplu işlem tamamlandı ve sonuçlar hazırlanıyor.
completed Toplu iş tamamlandı ve sonuçlar hazır.
expired Toplu işlem 24 saatlik zaman diliminde tamamlanamadı.
cancelling Toplu işlem yapılıyor cancelled (Bu işlem 10 dakika kadar sürebilir.)
cancelled parti cancelled idi

İş durumu ayrıntılarını incelemek için şunu çalıştırabilirsiniz:

print(batch_response.model_dump_json(indent=2))

Çıkış:

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-9f3a81d899b4442f98b640e4bc3535dd",
  "object": "batch",
  "status": "completed",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": 1722477429,
  "error_file_id": "file-c795ae52-3ba7-417d-86ec-07eebca57d0b",
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": 1722477177,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "file-3304e310-3b39-4e34-9f1c-e1c1504b2b2a",
  "request_counts": {
    "completed": 3,
    "failed": 0,
    "total": 3
  }
}

Hem error_file_id hem de ayrı bir output_file_id olduğunu gözlemleyin. error_file_id kullanarak toplu işinizde oluşan sorunları ayıklayabilirsiniz.

Toplu iş çıktı dosyasını alma

import json

output_file_id = batch_response.output_file_id

if not output_file_id:
    output_file_id = batch_response.error_file_id

if output_file_id:
    file_response = client.files.content(output_file_id)
    raw_responses = file_response.text.strip().split('\n')  

    for raw_response in raw_responses:  
        json_response = json.loads(raw_response)  
        formatted_json = json.dumps(json_response, indent=2)  
        print(formatted_json)

Çıkış:

Kısalık adına yalnızca tek bir sohbet tamamlama yanıtı dahil ediyoruz. Bu makaledeki adımları izlerseniz aşağıdakine benzer üç yanıtınız olmalıdır:

Sohbet tamamlanması

{
  "custom_id": "task-0",
  "response": {
    "body": {
      "choices": [
        {
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          },
          "finish_reason": "stop",
          "index": 0,
          "logprobs": null,
          "message": {
            "content": "Microsoft was founded on April 4, 1975, by Bill Gates and Paul Allen in Albuquerque, New Mexico.",
            "role": "assistant"
          }
        }
      ],
      "created": 1722477079,
      "id": "chatcmpl-9rFGJ9dh08Tw9WRKqaEHwrkqRa4DJ",
      "model": "gpt-4o-2024-05-13",
      "object": "chat.completion",
      "prompt_filter_results": [
        {
          "prompt_index": 0,
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "jailbreak": {
              "filtered": false,
              "detected": false
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          }
        }
      ],
      "system_fingerprint": "fp_a9bfe9d51d",
      "usage": {
        "completion_tokens": 24,
        "prompt_tokens": 27,
        "total_tokens": 51
      }
    },
    "request_id": "660b7424-b648-4b67-addc-862ba067d442",
    "status_code": 200
  },
  "error": null
}

Yanıtlar API'si

{
  "custom_id": "task-0",
  "response": {
    "body": {
      "id": "resp_0e5c78eb05ee70cf00690cc6d988e4819587556df17436a206",
      "created_at": 1762445017.0,
      "error": null,
      "incomplete_details": null,
      "instructions": null,
      "metadata": {},
      "model": "gpt-4.1-batch",
      "object": "response",
      "output": [
        {
          "id": "msg_0e5c78eb05ee70cf00690cc6da3c548195aae483031113df16",
          "content": [
            {
              "annotations": [],
              "text": "Microsoft was founded on **April 4, 1975** by **Bill Gates** and **Paul Allen**.",
              "type": "output_text",
              "logprobs": []
            }
          ],
          "role": "assistant",
          "status": "completed",
          "type": "message"
        }
      ],
      "parallel_tool_calls": true,
      "temperature": 1.0,
      "tool_choice": "auto",
      "tools": [],
      "top_p": 1.0,
      "background": false,
      "max_output_tokens": null,
      "max_tool_calls": null,
      "previous_response_id": null,
      "prompt_cache_key": null,
      "reasoning": {
        "effort": null,
        "summary": null
      },
      "safety_identifier": null,
      "service_tier": "default",
      "status": "completed",
      "text": {
        "format": {
          "type": "text"
        },
        "verbosity": "medium"
      },
      "top_logprobs": 0,
      "truncation": "disabled",
      "usage": {
        "input_tokens": 16,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 25,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 41
      },
      "user": null,
      "content_filters": null,
      "store": true
    },
    "request_id": "809b30c2-fa0b-4613-b5cc-c30f6b780c9a",
    "status_code": 200
  },
  "error": null
}

Ek toplu iş komutları

Toplu işlemi iptal et

Devam eden toplu işlemi iptal eder. Toplu işlem, cancelling durumunda 10 dakikaya kadar kalacak, ardından cancelled durumuna geçecek, bu noktada çıktı dosyasında kısmi sonuçlar (varsa) bulunabilir.

client.batches.cancel("batch_abc123") # set to your batch_id for the job you want to cancel

Toplu işlemi listeleme

Belirli bir Azure OpenAI kaynağı için toplu işleri listeleyin.

client.batches.list()

Python kitaplığındaki liste yöntemleri sayfalandırılmıştır.

Tüm işleri listelemek için:

all_jobs = []
# Automatically fetches more pages as needed.
for job in client.batches.list(
    limit=20,
):
    # Do something with job here
    all_jobs.append(job)
print(all_jobs)

Toplu işlemi listeleme (Önizleme)

Tüm toplu işleri ek sıralama/filtreleme seçenekleriyle listelemek için REST API'sini kullanın.

Aşağıdaki örneklerde, filtre oluşturmayı kolaylaştırmak için generate_time_filter işlevini sağlıyoruz. Bu işlevi kullanmak istemiyorsanız, filtre dizesinin biçimi created_at gt 1728860560 and status eq 'Completed' gibi görünür.

import requests
import json
from datetime import datetime, timedelta
from azure.identity import DefaultAzureCredential

token_credential = DefaultAzureCredential()
token = token_credential.get_token('https://ai.azure.com/.default')

endpoint = "https://{YOUR_RESOURCE_NAME}.openai.azure.com/"
api_version = "2025-03-01-preview"
url = f"{endpoint}openai/batches"
order = "created_at asc"
time_filter =  lambda: generate_time_filter("past 8 hours")

# Additional filter examples:
#time_filter =  lambda: generate_time_filter("past 1 day")
#time_filter =  lambda: generate_time_filter("past 3 days", status="Completed")

def generate_time_filter(time_range, status=None):
    now = datetime.now()
    
    if 'day' in time_range:
        days = int(time_range.split()[1])
        start_time = now - timedelta(days=days)
    elif 'hour' in time_range:
        hours = int(time_range.split()[1])
        start_time = now - timedelta(hours=hours)
    else:
        raise ValueError("Invalid time range format. Use 'past X day(s)' or 'past X hour(s)'")
    
    start_timestamp = int(start_time.timestamp())
    
    filter_string = f"created_at gt {start_timestamp}"
    
    if status:
        filter_string += f" and status eq '{status}'"
    
    return filter_string

filter = time_filter()

headers = {'Authorization': 'Bearer ' + token.token}

params = {
    "api-version": api_version,
    "$filter": filter,
    "$orderby": order
}

response = requests.get(url, headers=headers, params=params)

json_data = response.json()

if response.status_code == 200:
    print(json.dumps(json_data, indent=2))
else:
    print(f"Request failed with status code: {response.status_code}")
    print(response.text)

Çıkış:

{
  "data": [
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729011896,
      "completion_window": "24h",
      "created_at": 1729011128,
      "error_file_id": "file-472c0626-4561-4327-9e4e-f41afbfb30e6",
      "expired_at": null,
      "expires_at": 1729097528,
      "failed_at": null,
      "finalizing_at": 1729011805,
      "id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
      "in_progress_at": 1729011493,
      "input_file_id": "file-f89384af0082485da43cb26b49dc25ce",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-62bebde8-e767-4cd3-a0a1-28b214dc8974",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    },
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729016366,
      "completion_window": "24h",
      "created_at": 1729015829,
      "error_file_id": "file-85ae1971-9957-4511-9eb4-4cc9f708b904",
      "expired_at": null,
      "expires_at": 1729102229,
      "failed_at": null,
      "finalizing_at": 1729016272,
      "id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43",
      "in_progress_at": 1729016126,
      "input_file_id": "file-686746fcb6bc47f495250191ffa8a28e",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-04399828-ae0b-4825-9b49-8976778918cb",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    }
  ],
  "first_id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
  "has_more": false,
  "last_id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43"
}

Toplu işleri kuyruğa alma

Toplu işleriniz, dağıtımınız için kotayı maksimum düzeye çıkardıktan sonra bile sıraya alınan belirteç sınırına ulaşacak kadar büyükse, bazı bölgeler artık üstel geri dönüş ile birden çok toplu işi kuyruğa almanıza olanak tanıyan yeni bir hızlı başarısızlık özelliğini destekliyor. Bir büyük toplu iş tamamlandıktan ve kuyruğa alınan token kotanız yeniden kullanılabilir hale geldikten sonra, bir sonraki toplu iş otomatik olarak oluşturulup başlatılabilir.

Eski davranış:

  1. Dağıtımınız için kullanılabilir tüm belirteçleri kullanan ve halihazırda çalışan büyük Batch işleri var.
  2. Yeni toplu iş gönderildi.
  3. Yeni toplu iş doğrulama aşamasına geçer ve bu işlem birkaç dakikaya kadar sürebilir.
  4. Yeni iş için belirteç sayısı şu anda kullanılabilir olan kotaya göre denetleniyor.
  5. Yeni toplu iş, hata raporu belirteci eşik seviyesi aşıldığı için başarısız oluyor.

Yeni davranış:

  1. Dağıtımınız için kullanılabilir tüm belirteçleri çalıştıran ve kullanan büyük Batch işleri
  2. Yeni toplu iş gönderildi
  3. Yeni işin yaklaşık belirteç sayısı, mevcut toplu kota ile hemen karşılaştırılır ve hızlı şekilde başarısız olur, bu da yeniden denemeleri program aracılığıyla daha kolay yönetmenizi sağlar.

Bölge desteği

Aşağıdaki bölgeler yeni hızlı başarısız davranışı destekler:

  • australiaeast
  • eastus
  • AlmanyaBatıMerkez
  • italynorth
  • northcentralus
  • polonyamerkezi
  • swedencentral
  • İsviçre Kuzey
  • eastus2
  • westus

Aşağıdaki kod, hızlı başarısız olma davranışını ele almanın temel mekaniklerini, yeniden denemelerin otomatikleştirilmesi ve toplu işlerin üstel geri çekilmeyle kuyruğa alınmasına izin verecek şekilde gösterir.

Toplu işlerinizin boyutuna bağlı olarak, max_retries değerini büyük ölçüde artırmanız veya bu örneği daha fazla değiştirmeniz gerekebilir.

import time
from openai import BadRequestError

max_retries = 10
retries = 0
initial_delay = 5
delay = initial_delay

while True:
    try:
        batch_response = client.batches.create(
            input_file_id=file_id,
            endpoint="/chat/completions",
            completion_window="24h",
        )
        
        # Save batch ID for later use
        batch_id = batch_response.id
        
        print(f"✅ Batch created successfully after {retries} retries")
        print(batch_response.model_dump_json(indent=2))
        break  
        
    except BadRequestError as e:
        error_message = str(e)
        
        # Check if it's a token limit error
        if 'token_limit_exceeded' in error_message:
            retries += 1
            if retries >= max_retries:
                print(f"❌ Maximum retries ({max_retries}) reached. Giving up.")
                raise
            
            print(f"⏳ Token limit exceeded. Waiting {delay} seconds before retry {retries}/{max_retries}...")
            time.sleep(delay)
            
            # Exponential backoff - increase delay for next attempt
            delay *= 2
        else:
            # If it's a different error, raise it immediately
            print(f"❌ Encountered non-token limit error: {error_message}")
            raise

Çıkış:

⏳ Token limit exceeded. Waiting 5 seconds before retry 1/10...
⏳ Token limit exceeded. Waiting 10 seconds before retry 2/10...
⏳ Token limit exceeded. Waiting 20 seconds before retry 3/10...
⏳ Token limit exceeded. Waiting 40 seconds before retry 4/10...
⏳ Token limit exceeded. Waiting 80 seconds before retry 5/10...
⏳ Token limit exceeded. Waiting 160 seconds before retry 6/10...
⏳ Token limit exceeded. Waiting 320 seconds before retry 7/10...
✅ Batch created successfully after 7 retries
{
  "id": "batch_1e1e7b9f-d4b4-41fa-bd2e-8d2ec50fb8cc",
  "completion_window": "24h",
  "created_at": 1744402048,
  "endpoint": "/chat/completions",
  "input_file_id": "file-e2ba4ccaa4a348e0976c6fe3c018ea92",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": "",
  "errors": null,
  "expired_at": null,
  "expires_at": 1744488444,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

Önkoşullar

Toplu iş dosyanızı hazırlama

Genel toplu işlem, ince ayarlama gibi dosyaları da JSON satırları (.jsonl) biçiminde kullanır. Aşağıda desteklenen içerik türleri farklı olan bazı örnek dosyalar verilmişti:

Giriş biçimi

Yanıtlar API'si

{"custom_id": "task-0", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was Microsoft founded, and by whom?"}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "When was XBOX merged into Microsoft?"}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/responses", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "input": "What is Visual Basic?"}}

Sohbet tamamlama API'si

{"custom_id": "task-0", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id, belirli bir yanıtla hangi toplu iş isteğinin eşleştiğini belirlemenize olanak tanımak için gereklidir. Yanıtlar, toplu iş dosyasında tanımlanan .jsonl siparişle aynı sırada döndürülemez.

model özniteliği, çıkarım yanıtları için hedeflemek istediğiniz Genel Batch dağıtımının adıyla eşleşecek şekilde ayarlanmalıdır.

Önemli

Öznitelik, model çıkarım yanıtları için hedeflemek istediğiniz Genel Batch dağıtımının adıyla eşleşecek şekilde ayarlanmalıdır. Toplu iş dosyasının her satırında aynı Genel Batch modeli dağıtım adı bulunmalıdır. Farklı bir dağıtımı hedeflemek istiyorsanız, bunu ayrı bir toplu iş dosyasında/işinde yapmanız gerekir.

En iyi performans için, her dosyada yalnızca birkaç satır bulunan çok sayıda küçük dosya yerine toplu işlem için büyük dosyalar göndermenizi öneririz.

Giriş dosyası oluşturma

Bu makale için adlı test.jsonl bir dosya oluşturacağız ve yukarıdaki standart giriş kodu bloğundaki içerikleri dosyaya kopyalayacağız. Genel toplu dağıtım adınızı değiştirmeniz ve dosyanın her satırına eklemeniz gerekir.

Toplu iş dosyasını karşıya yükleme

Giriş dosyanız hazırlandıktan sonra bir toplu iş başlatabilmek için önce dosyayı karşıya yüklemeniz gerekir. Dosya yükleme işlemi hem program aracılığıyla hem de Microsoft Foundry portalı üzerinden yapılabilir. Bu örnekte, bir dosyanın doğrudan Azure OpenAI kaynağınıza yüklenmesi gösterilmektedir. Alternatif olarak, Azure OpenAI Batch için Azure Blob Depolama'ı yapılandırabilirsiniz.

Önemli

API anahtarlarını dikkatli kullanın. API anahtarını doğrudan kodunuzla eklemeyin ve hiçbir zaman herkese açık olarak göndermeyin. API anahtarı kullanıyorsanız, Azure Key Vault güvenli bir şekilde depolayın. Uygulamalarınızda API anahtarlarını güvenli bir şekilde kullanma hakkında daha fazla bilgi için bkz. Azure Key Vault ile API anahtarları.

Yapay zeka hizmetleri güvenliği hakkında daha fazla bilgi için bkz. Azure Yapay Zeka Hizmetleri istekleri doğrulama.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -F "purpose=batch" \
  -F "file=@C:\\batch\\test.jsonl;type=application/json" \
  -F "expires_after.seconds=1209600" \
  -F "expires_after.anchor=created_at"

Yukarıdaki kod, test.jsonl dosyanız için belirli bir dosya yolu olduğunu varsayar. Bu dosya yolunu yerel sisteminiz için gerektiği gibi ayarlayın.

İsteğe bağlı expires_after.seconds ve expires_after.anchor parametreleri giriş dosyasının süresi oluşturulduktan 14 gün sonra dolacak şekilde ayarlanır. 14 ila 30 gün arasında bir sona erme süresi seçmek için 1209600 değerini 2592000 ile expires_after.seconds arasında bir değere ayarlayın. Son kullanma tarihi ayarlamak, giriş dosyası sınırını da artırır. Ayrıntılar için bkz. Batch sınırları.

Çıkış:

{
  "status": "processed",
  "bytes": 817,
  "purpose": "batch",
  "filename": "test.jsonl",
  "expires_at": 1744607747,
  "id": "file-7733bc35e32841e297a62a9ee50b3461",
  "created_at": 1743398147,
  "object": "file"
}

Dosya yüklemesinin durumunu izleme

Dosya boyutunuza bağlı olarak, dosyanın tamamen yüklenmesi ve işlenmesi biraz zaman alabilir. Dosya karşıya yükleme durumunuzu denetlemek için şu komutu çalıştırın:

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files/{file-id} \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Çıkış:

{
  "status": "processed",
  "bytes": 686,
  "purpose": "batch",
  "filename": "test.jsonl",
  "expires_at": 1744607747,
  "id": "file-7733bc35e32841e297a62a9ee50b3461",
  "created_at": 1721408291,
  "object": "file"
}

Toplu iş oluştur

Dosyanız başarıyla karşıya yüklendikten sonra dosyayı toplu işlem için gönderebilirsiniz.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/chat/completions",
    "completion_window": "24h",
    "output_expires_after": {
      "anchor": "created_at",
      "seconds": 1209600
    }
  }'

İsteğe bağlı output_expires_after nesne, çıktı dosyalarının süresi oluşturulduktan 14 gün sonra dolacak şekilde ayarlar. 14 ile 30 gün arasında bir sona erme süresi seçmek için 1209600 değerini 2592000 ile seconds arasında bir değere ayarlayın. anchor değeri created_at olmalıdır.

Not

Şu anda tamamlanma penceresi olarak 24hayarlanmalıdır. Başka bir değer ayarlarsanız 24h başarısız olur. 24 saatten uzun süren işler iptal edilene kadar yürütülmeye devam eder.

Çıkış:

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:13:57.2491382+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:13:57.1918498+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_fe3f047a-de39-4068-9008-346795bfc1db",
  "in_progress_at": null,
  "input_file_id": "file-21006e70789246658b86a1fc205899a4",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

Toplu iş ilerleme durumunu izleme

Toplu işi başarıyla oluşturduktan sonra, ilerleme durumunu Studio'da veya program aracılığıyla izleyebilirsiniz. Toplu iş ilerleme durumunu denetlerken her durum çağrısı arasında en az 60 saniye beklemenizi öneririz.

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches/{batch_id} \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Çıkış:

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:33:29.1619286+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:33:29.1578141+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_e0a7ee28-82c4-46a2-a3a0-c13b3c4e390b",
  "in_progress_at": null,
  "input_file_id": "file-c55ec4e859d54738a313d767718a2ac5",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

Aşağıdaki durum değerleri mümkündür:

Durum Açıklama
validating Toplu işlem başlamadan önce giriş dosyası doğrulanıyor.
failed Giriş dosyası doğrulama işlemi başarısız oldu.
in_progress Giriş dosyası başarıyla doğrulandı ve toplu iş şu anda çalışıyor.
finalizing Toplu işlem tamamlandı ve sonuçlar hazırlanıyor.
completed Toplu iş tamamlandı ve sonuçlar hazır.
expired Toplu işlem 24 saatlik zaman diliminde tamamlanamadı.
cancelling Toplu işlem şu anda yapılıyor cancelled (Bu işlem 10 dakika kadar sürebilir.)
cancelled parti cancelled idi

Toplu iş çıktı dosyasını alma

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/files/{output_file_id}/content \
  -H "api-key: $AZURE_OPENAI_API_KEY" > batch_output.jsonl

Ek toplu iş komutları

Toplu işlemi iptal et

Devam eden toplu işlemi iptal eder. Toplu işlem, cancelling durumunda 10 dakikaya kadar kalacak, ardından cancelled durumuna geçecek, bu noktada çıktı dosyasında kısmi sonuçlar (varsa) bulunabilir.

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches/{batch_id}/cancel \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Toplu işlemi listeleme

Belirli bir Azure OpenAI kaynağı için mevcut toplu işleri listeleyin.

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/batches \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Liste API çağrısı sayfalandırılmıştır. Yanıt, yinelemek için daha fazla sonuç olduğunda göstermek için bir boole has_more değeri içerir.

Toplu işlemi listeleme (Önizleme)

Tüm toplu işleri ek sıralama/filtreleme seçenekleriyle listelemek için REST API'sini kullanın.

curl "YOUR_RESOURCE_NAME.openai.azure.com/batches?api-version=2025-04-01-preview&$filter=created_at%20gt%201728773533%20and%20created_at%20lt%201729032733%20and%20status%20eq%20'Completed'&$orderby=created_at%20asc" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Hata URL rejected: Malformed input to a URL function alanlarının ile %20değiştirilmesini önlemek için.

Toplu işlem sınırları

Sınır adı Sınır değeri
En fazla toplu giriş dosyası (süre sonu yok) 500
Maksimum toplu girdi dosyaları (sona erme süresi ayarlı) 10,000
En büyük giriş dosyası boyutu 200 MB
Maksimum giriş dosyası boyutu - Kendi depolama alanınızı getirin (BYOS) 1GB
Dosya başına en fazla istek sayısı 100,000

Not

Kaynak başına sınırı artırmak ve depolanan dosyaları yönetmek için giriş dosyaları için süre sonu ayarlayın. Toplu giriş dosyası sınırları, error.jsonl ve result.jsonl gibi çıkış dosyaları için geçerli değildir. Dosya API'si giriş dosyası sınırlarını önlemek için Azure Blob Depolama ile Batch kullanın.

Batch kotası

Tabloda toplu iş kotası sınırı gösterilir. Global toplu iş için kota değerleri, kuyruklanmış jetonlar şeklinde temsil edilir. Toplu işlem için bir dosya gönderdiğinizde, dosyadaki belirteç sayısı sayılır. Toplu iş terminal durumuna ulaşana kadar, bu belirteçler toplam sıralanmış belirteç sınırınıza göre sayılır.

Genel toplu işlem

Modeli Kurumsal ve MCA-E Varsayılan Aylık kredi kartı tabanlı abonelikler MSDN abonelikleri Öğrenciler için Azure, ücretsiz denemeler
gpt-4.1 5B 200M 50M 90 bin Uygulanamaz
gpt-4.1 mini 15B 1B 50M 90 bin Uygulanamaz
gpt-4.1-nano 15B 1B 50M 90 bin Uygulanamaz
gpt-4o 5B 200M 50M 90 bin Uygulanamaz
gpt-4o-mini 15B 1B 50M 90 bin Uygulanamaz
gpt-4-turbo 300 Milyon 80M 40M 90 bin Uygulanamaz
gpt-4 150 milyon 30 milyon 5 milyon 100 bin Uygulanamaz
o3-mini 15B 1B 50M 90 bin Uygulanamaz
o4-mini 15B 1B 50M 90 bin Uygulanamaz
gpt-5 5B 200M 50M 90 bin Uygulanamaz
gpt-5.1 5B 200M 50M 90 bin Uygulanamaz
gpt-5.2 5B 200M 50M Uygulanamaz Uygulanamaz
gpt-5.4 5B 200M 50M Uygulanamaz Uygulanamaz
gpt-5.4-mini 5B 200M 50M Uygulanamaz Uygulanamaz
gpt-5.4-nano 5B 200M 50M Uygulanamaz Uygulanamaz
gpt-5.5 5B 200M 50M 90 bin Uygulanamaz

B = milyar | M = milyon | K = bin

Veri bölgesi yığını

Modeli Kurumsal ve MCA-E Varsayılan Aylık kredi kartı tabanlı abonelikler MSDN abonelikleri Öğrenciler için Azure, ücretsiz denemeler
gpt-4.1 500M 30 milyon 30 milyon 90 bin Uygulanamaz
gpt-4.1-mini 1,5B 100M 50M 90 bin Uygulanamaz
gpt-4o 500M 30 milyon 30 milyon 90 bin Uygulanamaz
gpt-4o-mini 1,5B 100M 50M 90 bin Uygulanamaz
o3-mini 1,5B 100M 50M 90 bin Uygulanamaz
gpt-5 5B 200M 50M 90 bin Uygulanamaz
gpt-5.1 5B 200M 50M 90 bin Uygulanamaz
gpt-5.4 5B 200M 50M Uygulanamaz Uygulanamaz
gpt-5.4-mini 5B 200M 50M Uygulanamaz Uygulanamaz
gpt-5.5 5B 200M 50M 90 bin Uygulanamaz

Toplu iş kaydı saklama

Toplu iş kayıtları, iş failed, expired, cancelled veya completed gibi bir son duruma ulaştıktan sonra en fazla 365 gün boyunca saklanır. Bu süre boyunca, işi listeleyip alabilir ve hala iptal edilebilir durumdaysa iptal edebilirsiniz.

Oluşturulan çıkış ve hata dosyalarının varsayılan süre sonu yoktur. Siz silene veya açık bir süre sonu ayarlayana kadar bunlar kullanılabilir durumda kalır. Giriş dosyasını karşıya yüklerken expires_after ayarlayın veya bir toplu iş oluştururken output_expires_after ayarlayın. Her iki açık sona erme ayarı da 14 ila 30 gün aralığını kabul eder ve referans noktası olarak created_at kullanır. Örnekler için Python veya REST API sekmesindeki Toplu iş dosyasını karşıya yükleme ve Toplu iş oluşturma bölümlerine bakın.

Batch nesnesi

Özellik Türü Tanımı
id Dize Toplu işlem tanımlayıcısı.
object Dize batch
endpoint Dize Toplu işlemin kullandığı API uç noktası.
errors Nesne Varsa toplu iş için hata bilgileri.
input_file_id Dize Toplu işleme ait girdi dosyasının kimliği.
completion_window Dize Toplu işlemi işlemek için hedef zaman çerçevesi. Şu anda bu değeri olarak 24hayarlamanız gerekir. 24 saat içinde tamamlanması garanti değildir ve bir iş bitene veya siz iptal edene kadar devam edebilir.
status Dize Toplu işlemin mevcut durumu. Olası değerler: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled.
output_file_id Dize Başarıyla yürütülen isteklerin çıkışlarını içeren dosyanın kimliği.
error_file_id Dize Hata içeren isteklerin çıkışlarını içeren dosyanın kimliği.
created_at Tamsayı Bu toplu işin oluşturulma zamanı için bir zaman damgası (Unix zamanı saniye cinsinden).
in_progress_at Tamsayı Bu toplu işin ilerlemeye başlama zamanını gösteren bir zaman damgası (Unix dönem saniyelerinde).
expires_at Tamsayı Bu kümenin süresinin dolacağı zamana damgası (Unix dönem saniye cinsinden).
finalizing_at Tamsayı Zaman damgası, bu işlem grubunun sonlandırmaya başladığı anı gösterir (Unix epoch saniye cinsinden).
completed_at Tamsayı Bu toplu işin tamamlandığı zamanın damgası (Unix dönemi saniyesi cinsinden).
failed_at Tamsayı Bu toplu iş başarısız olduğunda bir zaman damgası (Unix dönem saniye cinsinden).
expired_at Tamsayı Bu partinin süresinin dolduğu zaman damgası (Unix zamanı saniye cinsinden).
cancelling_at Tamsayı Bu toplu iş başlatıldığında cancelling bir zaman damgası (Unix dönem saniye cinsinden).
cancelled_at Tamsayı Bu toplu iş cancelled olduğu zaman damgası (Unix dönem saniye cinsinden).
request_counts Nesne Nesne yapısı:

total Tamsayı
Toplu iş içindeki toplam istek sayısı.
completed Tamsayı
Toplu işlemdeki başarıyla tamamlanan isteklerin sayısı.
failed Tamsayı
Toplu işlemdeki başarısız olan istek sayısı.
metadata Harita Toplu işe ekleyebileceğiniz anahtar-değer çiftleri kümesi. Bu özellik, toplu iş hakkındaki ek bilgileri yapılandırılmış biçimde depolamak için yararlı olabilir.

Sık sorulan sorular (SSS)

Görüntüler toplu iş API'siyle kullanılabilir mi?

Bu özellik belirli çok modüllü modellerde sınırlıdır. Görüntüleri bir görüntü URL'si veya görüntünün base64 kodlanmış gösterimi aracılığıyla giriş olarak sağlayabilirsiniz.

Batch API'sini ince ayarlı modellerle kullanabilir miyim?

Toplu API şu anda ince ayarlı modelleri desteklemiyor.

Ekleme modelleri için toplu iş API'sini kullanabilir miyim?

Toplu API şu anda ince ayarlı modelleri desteklemiyor.

İçerik filtreleme Genel Batch dağıtımıyla çalışır mı?

Evet. Diğer dağıtım türlerine benzer şekilde, içerik filtreleri oluşturabilir ve bunları Genel Batch dağıtım türüyle ilişkilendirebilirsiniz.

Ek kota isteyebilir miyim?

Evet, Dökümhane portalındaki kota sayfasından. Varsayılan kota ayırma, kota ve sınırlar makalesinde bulunabilir.

API isteğimi 24 saat içinde tamamlamazsa ne olur?

Bu istekleri 24 saat içinde işlemeyi hedefliyoruz; daha uzun sürecek işlerin süresi dolmaz. İşi istediğiniz zaman iptal edebilirsiniz. İşi iptal ettiğinizde, kalan tüm çalışmalar iptal edilir ve tamamlanmış tüm çalışmalar döndürülür. Tamamlanan tüm çalışmalar için ücretlendirilirsiniz.

Toplu işlem kullanarak kaç istek kuyruğa alabilirim?

Toplu işlem yapabileceğiniz istek sayısı üzerinde sabit bir sınır yoktur, ancak bu, kuyruğa alınan belirteç kotanıza bağlıdır. Sıralanan belirteç kotanız, bir kerede sıralayabileceğiniz en fazla giriş belirteci sayısını içerir.

Toplu iş isteğiniz tamamlandıktan sonra, giriş belirteçleriniz temizlendiğinden toplu iş hızı sınırınız sıfırlanır. Sınır, kuyruktaki genel isteklerin sayısına bağlıdır. Batch API kuyruğu toplu işlemlerinizi hızlı bir şekilde işlerse toplu iş hızı sınırınız daha hızlı sıfırlanır.

Sorun giderme

status completed olduğunda bir iş başarılı olur. Başarılı işler yine de bir error_file_idoluşturur, ancak sıfır bayt içeren boş bir dosyayla ilişkilendirilecektir.

bir iş hatası oluştuğunda, hatayla ilgili ayrıntıları özelliğinde errors bulabilirsiniz:

{
  "value": [
    {
      "id": "batch_80f5ad38-e05b-49bf-b2d6-a799db8466da",
      "completion_window": "24h",
      "created_at": 1725419394,
      "endpoint": "/chat/completions",
      "input_file_id": "file-c2d9a7881c8a466285e6f76f6321a681",
      "object": "batch",
      "status": "failed",
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1725419955,
      "error_file_id": "file-3b0f9beb-11ce-4796-bc31-d54e675f28fb",
      "errors": {
        "object": "list",
        "data": [
          {
            "code": "empty_file",
            "message": "The input file is empty. Please ensure that the batch contains at least one request."
          }
        ]
      },
      "expired_at": null,
      "expires_at": 1725505794,
      "failed_at": null,
      "finalizing_at": 1725419710,
      "in_progress_at": 1725419572,
      "metadata": null,
      "output_file_id": "file-ef12af98-dbbc-4d27-8309-2df57feed572",
      "request_counts": {
        "total": 10,
        "completed": null,
        "failed": null
      }
    }
  ]
}

Hata kodları

Hata kodu Tanımı
invalid_json_line Giriş dosyanızdaki bir satır (veya birden çok) geçerli json olarak ayrıştırılamadı.

Lütfen JSON standardına göre yazım hatası, düzgün açma ve kapatma köşeli ayraçları ve tırnak işaretleri olmadığından emin olun ve isteği yeniden gönderin.
too_many_tasks Giriş dosyasındaki istek sayısı izin verilen en fazla 100.000 değerini aşıyor.

Lütfen toplam isteklerinizin 100.000'in altında olduğundan emin olun ve işi yeniden gönderin.
url_mismatch Giriş dosyanızdaki bir satırın kalan satırlarla eşleşmeyen bir URL'si var veya giriş dosyasında belirtilen URL beklenen uç nokta URL'si ile eşleşmiyor.

Lütfen tüm istek URL'lerinin aynı olduğundan ve bunların Azure OpenAI dağıtımınızla ilişkili uç nokta URL'si ile eşleştiğinden emin olun.
model_not_found Giriş dosyasının model özelliğinde belirtilen Azure OpenAI modeli dağıtım adı bulunamadı.

Lütfen bu adın geçerli bir Azure OpenAI modeli dağıtımına işaret olduğundan emin olun.
duplicate_custom_id Bu isteğin özel kimliği, başka bir istekteki özel kimliğin bir kopyasıdır.
empty_file Giriş dosyası boş. Toplu işlemde en az bir istek bulunduğundan emin olun.
model_mismatch Giriş dosyasındaki bu isteğin model özelliğinde belirtilen Azure OpenAI modeli dağıtım adı, dosyanın geri kalanıyla eşleşmiyor.

Toplu işteki tüm isteklerin, isteğin model özelliğinde Aynı Azure OpenAI In Foundry Models model dağıtımına işaret etmesini sağlayın.
invalid_request Giriş satırının şeması geçersiz veya dağıtım SKU'su geçersiz.

Lütfen giriş dosyanızdaki isteğin özelliklerinin beklenen giriş özellikleriyle eşleştiğinden ve Azure OpenAI dağıtım SKU'sunun toplu API istekleri için globalbatch olduğundan emin olun.
input_modified Toplu iş gönderildikten sonra blob girdisi değiştirildi.
input_no_permissions Giriş blob'una erişmek mümkün değildir. Lütfen permissions ve Azure OpenAI hesabı ile Azure Depolama hesabı arasındaki ağ erişimini denetleyin.

Bilinen sorunlar

  • Azure CLI ile dağıtılan kaynaklar, varsayılan olarak Azure OpenAI küresel toplu işlemde çalışmaz. Bu sorun, bu yöntem kullanılarak dağıtılan kaynakların https://your-resource-name.openai.azure.com desenini izlemeyen uç nokta alt etki alanlarına sahip olması durumunda ortaya çıkar. Bu sorunun geçici çözümü, dağıtım işleminin bir parçası olarak alt etki alanı kurulumunu düzgün bir şekilde işleyecek diğer yaygın dağıtım yöntemlerinden birini kullanarak yeni bir Azure OpenAI kaynağı dağıtmaktır.

  • UTF-8-BOM kodlanmış jsonl dosyaları desteklenmez. JSON satır dosyaları UTF-8 kullanılarak kodlanmalıdır. Bayt-Order-Mark (BOM) kodlanmış dosyaların kullanımı JSON RFC belirtimi tarafından resmi olarak desteklenmez ve OpenAI Azure şu anda BOM ile kodlanmış dosyaları geçersiz olarak değerlendirecektir. UTF-8-BOM kodlanmış bir dosya şu anda genel hata iletisini döndürür: "Doğrulama başarısız oldu: Giriş dosyasından geçerli bir model dağıtım adı ayıklanamadı. Lütfen giriş dosyasındaki her satırın 'model' alanında belirtilen geçerli bir dağıtım adına sahip olduğundan ve dağıtım adının tüm satırlarda tutarlı olduğundan emin olun."

  • Toplu giriş verileri için kendi depolama alanınızı kullanırken, toplu iş gönderildikten sonra, giriş blobu değiştirilirse puanlama işi hizmet tarafından başarısız olur.

Ayrıca bkz.

  • Last updated on