مشاركة عبر

Getting started مع نشر دفعات Azure OpenAI

تم تصميم واجهة برمجة تطبيقات Azure OpenAI Batch للتعامل مع مهام المعالجة واسعة النطاق وعالية الحجم بكفاءة. معالجة مجموعات غير متزامنة من الطلبات بحصص منفصلة، مع استجابة مستهدفة خلال 24 ساعة، عند 50% تكلفة أقل من المعيار العالمي . مع معالجة الدفعات، بدلا من إرسال طلب واحد في كل مرة ترسل عددا كبيرا من الطلبات في ملف واحد. تحتوي طلبات الدفعات العمومية على حصة منفصلة من الرمز المميز في قائمة الانتظار لتجنب أي تعطيل لأحمال العمل عبر الإنترنت.

تتضمن حالات الاستخدام الرئيسية ما يلي:

  • Large-Scale معالجة البيانات: تحليل مجموعات البيانات الشاملة بسرعة بالتوازي.

  • إنشاء المحتوى: إنشاء كميات كبيرة من النص، مثل أوصاف المنتج أو المقالات.

  • مراجعة المستند وتلخيصه: أتمتة مراجعة المستندات المطولة وتلخيصها.

  • أتمتة دعم العملاء: معالجة العديد من الاستعلامات في وقت واحد للحصول على استجابات أسرع.

  • استخراج البيانات وتحليلها: استخراج المعلومات وتحليلها من كميات هائلة من البيانات غير المنظمة.

  • مهام معالجة اللغة الطبيعية (NLP): تنفيذ مهام مثل تحليل المشاعر أو الترجمة على مجموعات البيانات الكبيرة.

  • التسويق والتخصيص: إنشاء محتوى وتوصيات مخصصة على نطاق واسع.

نصيحة

إذا كانت مهام الدفعات الخاصة بك كبيرة جدا بحيث تصل إلى حد الرمز المميز المحدد في قائمة الانتظار حتى بعد الحد الأقصى للحصة النسبية للتوزيع الخاص بك، تدعم مناطق معينة الآن ميزة جديدة تسمح لك بقائمة انتظار مهام دفعية متعددة مع التراجع الأسي.

بمجرد توفر الحصة النسبية للرمز المميز المدرج في قائمة الانتظار، يمكن إنشاء مهمة الدفعة التالية وبدءها تلقائيا. لمعرفة المزيد، راجع أتمتة عمليات إعادة المحاولة لوظائف الدفعات الكبيرة مع التراجع الأسي.

مهم

نهدف إلى معالجة طلبات الدفعات في غضون 24 ساعة؛ لا تنتهي صلاحية الوظائف التي تستغرق وقتا أطول. يمكنك إلغاء المهمة في أي وقت. عند إلغاء المهمة، يتم إلغاء أي عمل متبق ويتم إرجاع أي عمل مكتمل بالفعل. سيتم تحصيل رسوم منك مقابل أي عمل مكتمل.

البيانات المخزنة في حالة السكون تبقى في الجغرافيا المخصصة ل Azure، بينما يمكن معالجة البيانات للاستنتاج في أي موقع Azure OpenAI.  تعرف أكثر على الإقامة في البيانات. 

دعم الدفعة

توفر نموذج الدفعة العمومي

Region جي بي تي -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 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
البرازيل الجنوبية ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
canadaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
centralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus2 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
francecentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
مركز ألمانيا ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
japaneast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
مركز كوريا ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
شمال وسط الولايات المتحدة ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
norwayeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
polandcentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
جنوب أفريقيا ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
مركز جنوبي ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southindia ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
swedencentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
switzerlandnorth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
uksouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
غرب أوروبا ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus3 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

التسجيل مطلوب لل access إلى gpt-5 وo3. لمزيد من المعلومات ، راجع دليل نماذج التفكير.

‏‫ملاحظة‬

بينما يدعم جلوبال باتش إصدارات واجهات برمجة التطبيقات القديمة، تتطلب بعض النماذج إصدارات API أحدث. على سبيل المثال، o3-mini غير مدعوم مع 2024-10-21 لأنه تم إصداره بعد هذا التاريخ. access النماذج الأحدث مع Global Batch، استخدم واجهة برمجة التطبيقات v1.

دعم الميزات

ما يلي غير مدعوم حاليا:

  • التكامل مع واجهة برمجة تطبيقات المساعدين.
  • التكامل مع ميزة Azure OpenAI على بياناتك.

نشر الدفعة

‏‫ملاحظة‬

في بوابة Microsoft Foundry تظهر أنواع النشر الدفعي ك Global-Batch و Data Zone Batch. لمعرفة المزيد عن أنواع نشر OpenAI Azure، راجع دليل أنواع النشر.

نصيحة

نوصي بتمكين الحصة النسبية الديناميكية لجميع عمليات نشر نموذج الدفعات العمومية للمساعدة في تجنب فشل المهمة بسبب الحصة النسبية غير الكافية للرمز المميز في قائمة الانتظار. يسمح استخدام الحصة النسبية الديناميكية للتوزيع الخاص بك بالاستفادة بشكل انتهازي من المزيد من الحصة النسبية عند توفر سعة إضافية. عند تعيين الحصة النسبية الديناميكية إلى إيقاف التشغيل، سيتمكن التوزيع الخاص بك فقط من معالجة الطلبات حتى حد الرمز المميز المحدد في قائمة الانتظار الذي تم تعريفه عند إنشاء النشر.

المتطلبات المسبقه

  • اشتراك Azure - إنشاء واحد مجانا.
  • مورد يحتوي على نموذج من نوع GlobalBatch النشر أو DataZoneBatch النشر.

إعداد ملف الدفعة

مثل الضبط الدقيق ، تستخدم الدفعة الملفات بتنسيق خطوط JSON (.jsonl). فيما يلي بعض الأمثلة على الملفات ذات أنواع مختلفة من المحتوى المدعوم:

تنسيق الإدخال

واجهة برمجة تطبيقات الاستجابات

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

واجهة برمجة تطبيقات إكمال الدردشة

{"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 مطلوب للسماح لك بتحديد طلب الدفعة الفردي الذي يتوافق مع استجابة معينة. لن يتم إرجاع الاستجابات بترتيب متطابق مع الترتيب المحدد في ملف الدفعة .jsonl .

model يجب تعيين السمة لمطابقة اسم توزيع الدفعة العمومية الذي ترغب في استهدافه لاستجابات الاستدلال.

مهم

model يجب تعيين السمة لمطابقة اسم توزيع الدفعة العمومية الذي ترغب في استهدافه للاستجابات الاستدلالية. يجب أن يكون نفس اسم نشر نموذج الدفعة العمومية موجودا على كل سطر من ملف الدفعة. إذا كنت ترغب في استهداف توزيع مختلف، فيجب عليك القيام بذلك في ملف/مهمة دفعية منفصلة.

للحصول على أفضل أداء، نوصي بإرسال ملفات كبيرة لمعالجة الدفعات، بدلا من عدد كبير من الملفات الصغيرة مع بضعة أسطر فقط في كل ملف.

إنشاء ملف إدخال

بالنسبة لهذه المقالة، سنقوم بإنشاء ملف باسم test.jsonl وسننسخ المحتويات من كتلة التعليمات البرمجية للإدخال القياسية أعلاه إلى الملف. ستحتاج إلى تعديل وإضافة اسم نشر الدفعة العمومية إلى كل سطر من الملف.

إنشاء مهمة دفعية

بمجرد إعداد ملف الإدخال الخاص بك، تحتاج أولا إلى تحميل الملف حتى تتمكن من بدء مهمة دفعية. يمكن رفع الملفات بشكل برمجي أو عبر بوابة Microsoft Foundry. هذا المثال يوضح رفع ملف مباشرة إلى مورد Azure OpenAI الخاص بك. بدلا من ذلك، يمكنك configure Azure Blob Storage ل Azure OpenAI Batch.

  1. تسجيل الدخول إلى Microsoft Foundry. تأكد من تفعيل مفتاح New Foundry . تشير هذه الخطوات إلى Foundry (جديد).

  2. في أعلى اليمين اختر البناء

  3. من اللوحة اليسرى اختر النماذج

  4. اختيار وظائف دفعية لإنشاء>وظيفة دفعية

    لقطة شاشة لتجربة جديدة في إنشاء دفعة Foundry.

تعقب تقدم مهمة الدفعة

بمجرد إنشاء وظيفتك، يمكنك مراقبة تقدم المهمة عن طريق تحديد معرف الوظيفة للوظيفة التي تم إنشاؤها مؤخرا. بشكل افتراضي، سيتم نقلك إلى صفحة الحالة لوظيفة الدفعة التي تم إنشاؤها مؤخرا.

يمكنك تعقب حالة الوظيفة لمهمتك في الجزء الأيمن:

استرداد ملف إخراج وظيفة الدفعة

بمجرد اكتمال مهمتك أو الوصول إلى حالة طرفية، ستنشئ ملف خطأ وملف إخراج يمكن تنزيله للمراجعة عن طريق تحديد الزر المعني مع أيقونة السهم لأسفل.

إلغاء الدفعة

إلغاء دفعة قيد التقدم. ستكون الدفعة في حالة cancelling تصل إلى 10 دقائق، قبل التغيير إلى cancelled، حيث سيكون لها نتائج جزئية (إن وجدت) متوفرة في ملف الإخراج.

المتطلبات المسبقه

تهدف الخطوات الواردة في هذه المقالة إلى التشغيل بشكل تسلسلي في Jupyter Notebooks. لهذا السبب سنقوم بتجسيد عميل Azure OpenAI مرة واحدة فقط في بداية الأمثلة. إذا أردت تشغيل خطوة خارج الترتيب، غالبا ستحتاج إلى إعداد عميل Azure OpenAI كجزء من تلك المكالمة.

حتى إذا كان لديك بالفعل مكتبة OpenAI Python مثبتة، فقد تحتاج إلى ترقية التثبيت إلى أحدث إصدار:

!pip install openai --upgrade

إعداد ملف الدفعة

مثل الضبط الدقيق، تستخدم الدفعة العمومية الملفات بتنسيق خطوط JSON (.jsonl). فيما يلي بعض الأمثلة على الملفات ذات أنواع مختلفة من المحتوى المدعوم:

تنسيق الإدخال

واجهة برمجة تطبيقات الاستجابات

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

واجهة برمجة تطبيقات إكمال الدردشة

{"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 مطلوب للسماح لك بتحديد طلب الدفعة الفردي الذي يتوافق مع استجابة معينة. لن يتم إرجاع الاستجابات بترتيب متطابق مع الترتيب المحدد في ملف الدفعة .jsonl .

model يجب تعيين السمة لمطابقة اسم توزيع الدفعة العمومية الذي ترغب في استهدافه لاستجابات الاستدلال.

مهم

model يجب تعيين السمة لمطابقة اسم توزيع الدفعة العمومية الذي ترغب في استهدافه للاستجابات الاستدلالية. يجب أن يكون نفس اسم نشر نموذج الدفعة العمومية موجودا على كل سطر من ملف الدفعة. إذا كنت ترغب في استهداف توزيع مختلف، فيجب عليك القيام بذلك في ملف/مهمة دفعية منفصلة.

للحصول على أفضل أداء، نوصي بإرسال ملفات كبيرة لمعالجة الدفعات، بدلا من عدد كبير من الملفات الصغيرة مع بضعة أسطر فقط في كل ملف.

إنشاء ملف إدخال

بالنسبة لهذه المقالة، سنقوم بإنشاء ملف باسم test.jsonl وسننسخ المحتويات من كتلة التعليمات البرمجية للإدخال القياسية أعلاه إلى الملف. ستحتاج إلى تعديل وإضافة اسم نشر الدفعة العمومية إلى كل سطر من الملف. احفظ هذا الملف في نفس المجلد الذي تقوم فيه بتشغيل Jupyter Notebook الخاص بك.

تحميل ملف الدفعة

بمجرد إعداد ملف الإدخال الخاص بك، تحتاج أولا إلى تحميل الملف حتى تتمكن من بدء مهمة دفعية. يمكن رفع الملفات بشكل برمجي أو عبر بوابة Microsoft Foundry. هذا المثال يوضح رفع ملف مباشرة إلى مورد Azure OpenAI الخاص بك. بدلا من ذلك، يمكنك configure Azure Blob Storage ل Azure OpenAI Batch.

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

من خلال إلغاء التعليق وإضافته extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}} ، تقوم بإعداد ملف التحميل الخاص بنا لتنتهي صلاحيته في غضون 14 يوما. هناك حد أقصى يبلغ 500 ملف دفعة لكل مورد عندما لا يكون هناك صلاحية محددة. بتعيين قيمة للانتهاء الصلاحية، يزداد عدد ملفات الدفعة المدخلة لكل مورد إلى 10,000 ملف لكل مورد. لإزالة حدود ملفات إدخال الدفعات استخدم Batch مع Azure Blob Storage.

إخراج:

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

إنشاء مهمة دفعية

بمجرد تحميل الملف بنجاح، يمكنك إرسال الملف لمعالجة الدفعات.

# 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))

‏‫ملاحظة‬

حاليا يجب تعيين نافذة الإكمال إلى 24h. إذا قمت بتعيين أي قيمة أخرى غير 24h وظيفتك ستفشل. ستستمر المهام التي تستغرق أكثر من 24 ساعة في التنفيذ حتى يتم إلغاؤها.

إخراج:

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

إذا كانت مهام الدفعات الخاصة بك كبيرة جدا لدرجة أنك تصل إلى حد الرمز المميز المدرج في قائمة الانتظار حتى بعد الحد الأقصى للحصة النسبية للتوزيع الخاص بك، فإن بعض المناطق تدعم الآن ميزة جديدة سريعة الفشل تسمح لك بقائمة انتظار مهام دفعية متعددة مع تراجع أسي بحيث يمكن بدء مهمة دفعية كبيرة واحدة تلقائيا. لمعرفة المزيد حول المناطق التي تدعم هذه الميزة وكيفية تكييف التعليمات البرمجية للاستفادة منها، راجع وضع مهام الدفعات في قائمة الانتظار.

تعقب تقدم مهمة الدفعة

بمجرد إنشاء وظيفة دفعية بنجاح، يمكنك مراقبة تقدمها إما في Studio أو برمجيا. عند التحقق من تقدم مهمة الدفعة، نوصي بالانتظار لمدة 60 ثانية على الأقل بين كل استدعاء حالة.

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

إخراج:

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

قيم الحالة التالية ممكنة:

Status الوصف
validating يتم التحقق من صحة ملف الإدخال قبل بدء معالجة الدفعة.
failed فشل ملف الإدخال في عملية التحقق من الصحة.
in_progress تم التحقق من صحة ملف الإدخال بنجاح والدفعة قيد التشغيل حاليا.
finalizing اكتملت الدفعة ويتم إعداد النتائج.
completed تم إكمال الدفعة والنتائج جاهزة.
expired لم تتمكن الدفعة من إكمالها خلال النافذة الزمنية التي تبلغ 24 ساعة.
cancelling يتم تنفيذ cancelled الدفعة (قد يستغرق هذا الأمر ما يصل إلى 10 دقائق حتى يدخل حيز التنفيذ.)
cancelled كانت cancelledالدفعة .

لفحص تفاصيل حالة الوظيفة، يمكنك تشغيل:

print(batch_response.model_dump_json(indent=2))

إخراج:

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

لاحظ أن هناك كل من error_file_id و منفصل output_file_id. استخدم للمساعدة error_file_id في تصحيح أي مشكلات تحدث في وظيفة الدفعة.

استرداد ملف إخراج وظيفة الدفعة

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)

إخراج:

للإيجاز، نحن نتضمن فقط استجابة واحدة لإكمال الدردشة للإخراج. إذا اتبعت الخطوات الواردة في هذه المقالة، فيجب أن يكون لديك ثلاثة استجابات مشابهة لتلك التالية:

إكمال الدردشة

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

واجهة برمجة تطبيقات الاستجابات

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

أوامر دفعية إضافية

إلغاء الدفعة

إلغاء دفعة قيد التقدم. ستكون الدفعة في حالة cancelling تصل إلى 10 دقائق، قبل التغيير إلى cancelled، حيث سيكون لها نتائج جزئية (إن وجدت) متوفرة في ملف الإخراج.

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

دفعة القائمة

قم بإدراج مهام الدفعات لمورد معين من Azure OpenAI.

client.batches.list()

يتم ترقيم طرق القائمة في مكتبة Python.

لسرد جميع الوظائف:

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)

دفعة القائمة (معاينة)

استخدم واجهة برمجة تطبيقات REST لسرد جميع مهام الدفعات مع خيارات فرز/تصفية إضافية.

في الأمثلة أدناه، نقدم الدالة generate_time_filter لتسهيل إنشاء عامل التصفية. إذا كنت لا ترغب في استخدام هذه الدالة، فسيبدو تنسيق سلسلة التصفية مثل created_at gt 1728860560 and status eq 'Completed'.

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)

إخراج:

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

وضع مهام الدفعة في قائمة الانتظار

إذا كانت مهام الدفعات كبيرة جدا لدرجة أنك تصل إلى حد الرمز المميز المحدد في قائمة الانتظار حتى بعد الحد الأقصى للحصة النسبية للتوزيع الخاص بك، تدعم بعض المناطق الآن ميزة جديدة سريعة الفشل تسمح لك بقائمة انتظار مهام دفعية متعددة مع التراجع الأسي. بمجرد اكتمال مهمة دفعية كبيرة واحدة وإتاحة حصة الرمز المميز المدرجة في قائمة الانتظار مرة أخرى، يمكن إنشاء مهمة الدفعة التالية وبدء تشغيلها تلقائيا.

السلوك القديم:

  1. وظيفة/مهام Batch الكبيرة قيد التشغيل بالفعل وتستخدم جميع الرموز المميزة المتوفرة للتوزيع الخاص بك.
  2. تم إرسال مهمة دفعية جديدة.
  3. تنتقل مهمة الدفعة الجديدة إلى مرحلة التحقق من الصحة التي يمكن أن تستمر حتى بضع دقائق.
  4. يتم التحقق من عدد الرموز المميزة للمهمة الجديدة مقابل الحصة النسبية المتوفرة حاليا.
  5. فشلت مهمة الدفعة الجديدة مع تجاوز حد الرمز المميز للإبلاغ عن الخطأ.

سلوك جديد:

  1. وظيفة/مهام Batch الكبيرة قيد التشغيل بالفعل وتستخدم جميع الرموز المميزة المتوفرة للتوزيع الخاص بك
  2. تم إرسال مهمة دفعية جديدة
  3. يفشل عدد الرموز المميزة التقريبية للوظيفة الجديدة على الفور مقارنة بوظيفة الحصة النسبية الدفعية المتوفرة حاليا بسرعة مما يسمح لك بمعالجة عمليات إعادة المحاولة برمجيا بسهولة أكبر.

دعم المنطقة

تدعم المناطق التالية السلوك السريع للفشل الجديد:

  • australiaeast
  • eastus
  • مركز ألمانيا
  • رقم إيطاليا
  • شمال وسط الولايات المتحدة
  • polandcentral
  • swedencentral
  • switzerlandnorth
  • eastus2
  • westus

توضح التعليمات البرمجية أدناه الميكانيكا الأساسية للتعامل مع السلوك السريع للفشل للسماح بإعادة المحاولة التلقائية ووضع مهمة الدفعة في قائمة الانتظار مع التراجع الأسي.

اعتمادا على حجم وظائف الدفعة الخاصة بك قد تحتاج إلى زيادة كبيرة في max_retries أو تغيير هذا المثال بشكل أكبر.

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

إخراج:

⏳ 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
  }
}

المتطلبات المسبقه

إعداد ملف الدفعة

مثل الضبط الدقيق، تستخدم الدفعة العمومية الملفات بتنسيق خطوط JSON (.jsonl). فيما يلي بعض الأمثلة على الملفات ذات أنواع مختلفة من المحتوى المدعوم:

تنسيق الإدخال

واجهة برمجة تطبيقات الاستجابات

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

واجهة برمجة تطبيقات إكمال الدردشة

{"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 مطلوب للسماح لك بتحديد طلب الدفعة الفردي الذي يتوافق مع استجابة معينة. لن يتم إرجاع الاستجابات بترتيب متطابق مع الترتيب المحدد في ملف الدفعة .jsonl .

model يجب تعيين السمة لمطابقة اسم توزيع الدفعة العمومية الذي ترغب في استهدافه لاستجابات الاستدلال.

مهم

model يجب تعيين السمة لمطابقة اسم توزيع الدفعة العمومية الذي ترغب في استهدافه للاستجابات الاستدلالية. يجب أن يكون نفس اسم نشر نموذج الدفعة العمومية موجودا على كل سطر من ملف الدفعة. إذا كنت ترغب في استهداف توزيع مختلف، فيجب عليك القيام بذلك في ملف/مهمة دفعية منفصلة.

للحصول على أفضل أداء، نوصي بإرسال ملفات كبيرة لمعالجة الدفعات، بدلا من عدد كبير من الملفات الصغيرة مع بضعة أسطر فقط في كل ملف.

إنشاء ملف إدخال

بالنسبة لهذه المقالة، سنقوم بإنشاء ملف باسم test.jsonl وسننسخ المحتويات من كتلة التعليمات البرمجية للإدخال القياسية أعلاه إلى الملف. ستحتاج إلى تعديل وإضافة اسم نشر الدفعة العمومية إلى كل سطر من الملف.

تحميل ملف الدفعة

بمجرد إعداد ملف الإدخال الخاص بك، تحتاج أولا إلى تحميل الملف حتى تتمكن من بدء مهمة دفعية. يمكن رفع الملفات بشكل برمجي أو عبر بوابة Microsoft Foundry. هذا المثال يوضح رفع ملف مباشرة إلى مورد Azure OpenAI الخاص بك. بدلا من ذلك، يمكنك configure Azure Blob Storage ل Azure OpenAI Batch.

مهم

استخدم مفاتيح واجهة برمجة التطبيقات بحذر. لا تقم بتضمين مفتاح API مباشرة في التعليمات البرمجية الخاصة بك، ولا تنشره بشكل عام. إذا كنت تستخدم مفتاح API، خزنه بأمان في Azure Key Vault. لمزيد من المعلومات حول استخدام مفاتيح API بأمان في تطبيقاتك، راجع <مفاتيح ال c0>API مع Azure Key Vault.

لمزيد من المعلومات حول أمان خدمات الذكاء الاصطناعي، راجع التحقق من الطلبات إلى Azure AI services.

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"

تفترض التعليمات البرمجية أعلاه مسار ملف معين لملف test.jsonl الخاص بك. اضبط مسار الملف هذا حسب الضرورة للنظام المحلي.

بإضافة المعلمات الاختيارية "expires_after.seconds=1209600" والمعلمات "expires_after.anchor=created_at" التي تقوم بإعداد ملف التحميل الخاص بك لتنتهي صلاحيته في غضون 14 يوما. هناك حد أقصى يبلغ 500 ملف إدخال دفعي لكل مورد عندما لا يكون هناك صلاحية محددة. من خلال تعيين قيمة لانتهاء الصلاحية، تتم زيادة عدد ملفات الدفعات لكل مورد إلى 10000 ملف لكل مورد. يمكنك تعيين إلى رقم بين 1209600-2592000. وهذا يعادل 14-30 يوما. لإزالة حدود ملفات إدخال الدفعات استخدم Batch مع Azure Blob Storage.

إخراج:

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

تعقب حالة تحميل الملف

اعتمادا على حجم ملف التحميل الخاص بك، قد يستغرق الأمر بعض الوقت قبل تحميله ومعالجته بالكامل. للتحقق من حالة تحميل الملف، قم بتشغيل:

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

إخراج:

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

إنشاء مهمة دفعية

بمجرد تحميل الملف بنجاح، يمكنك إرسال الملف لمعالجة الدفعات.

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": {
        "seconds": 1209600
    },
    "anchor": "created_at"
  }'

هنا يمكنك إضافة "output_expires_after":{"seconds": 1209600}, و "anchor": "created_at" اختياريا بحيث تنتهي صلاحية ملفات الإخراج الخاصة بك في 14 يوما.

‏‫ملاحظة‬

حاليا يجب تعيين نافذة الإكمال إلى 24h. إذا قمت بتعيين أي قيمة أخرى غير 24h وظيفتك ستفشل. ستستمر المهام التي تستغرق أكثر من 24 ساعة في التنفيذ حتى يتم إلغاؤها.

إخراج:

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

تعقب تقدم مهمة الدفعة

بمجرد إنشاء وظيفة دفعية بنجاح، يمكنك مراقبة تقدمها إما في Studio أو برمجيا. عند التحقق من تقدم مهمة الدفعة، نوصي بالانتظار لمدة 60 ثانية على الأقل بين كل استدعاء حالة.

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

إخراج:

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

قيم الحالة التالية ممكنة:

Status الوصف
validating يتم التحقق من صحة ملف الإدخال قبل بدء معالجة الدفعة.
failed فشل ملف الإدخال في عملية التحقق من الصحة.
in_progress تم التحقق من صحة ملف الإدخال بنجاح والدفعة قيد التشغيل حاليا.
finalizing اكتملت الدفعة ويتم إعداد النتائج.
completed تم إكمال الدفعة والنتائج جاهزة.
expired لم تتمكن الدفعة من إكمالها خلال النافذة الزمنية التي تبلغ 24 ساعة.
cancelling يتم تنفيذ cancelled الدفعة (قد يستغرق هذا الأمر ما يصل إلى 10 دقائق حتى يدخل حيز التنفيذ.)
cancelled كانت cancelledالدفعة .

استرداد ملف إخراج وظيفة الدفعة

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

أوامر دفعية إضافية

إلغاء الدفعة

إلغاء دفعة قيد التقدم. ستكون الدفعة في حالة cancelling تصل إلى 10 دقائق، قبل التغيير إلى cancelled، حيث سيكون لها نتائج جزئية (إن وجدت) متوفرة في ملف الإخراج.

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

دفعة القائمة

قم بإدراج مهام الدفعات الموجودة لمورد معين من Azure OpenAI.

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

استدعاء واجهة برمجة تطبيقات القائمة مرقم. تحتوي الاستجابة على قيمة منطقية has_more للإشارة إلى وقت وجود المزيد من النتائج للتكرار من خلالها.

دفعة القائمة (معاينة)

استخدم واجهة برمجة تطبيقات REST لسرد جميع مهام الدفعات مع خيارات فرز/تصفية إضافية.

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"

لتجنب استبدال مسافات الخطأ URL rejected: Malformed input to a URL function ب %20.

حدود الدفعات

اسم الحد القيمة الحدية
ملفات إدخال الدفعة القصوى - (بدون انتهاء صلاحية) 500
ملفات إدخال الدفعة القصوى - (مجموعة انتهاء الصلاحية) 10,000
الحد الأقصى لحجم ملف الإدخال 200 ميغابايت
الحد الأقصى لحجم ملف الإدخال - أحضر storage خاص بك (BYOS) 1 غيغابايت
الحد الأقصى للطلبات لكل ملف 100,000

‏‫ملاحظة‬

حدود ملفات الدفعات لا تنطبق على ملفات الإخراج (على سبيل المثال، result.jsonl، و error.jsonl). لإزالة حدود ملفات الإدخال الدفعية، استخدم Batch مع Azure Blob Storage.

الحصة النسبية للدفعة

يعرض الجدول حد الحصة النسبية للدفعة. يتم تمثيل قيم الحصة النسبية للدفعة العمومية من حيث الرموز المميزة المدرجة في قائمة الانتظار. عند إرسال ملف لمعالجة الدفعات، يتم حساب عدد الرموز المميزة في الملف. حتى تصل الوظيفة الدفعية إلى حالة طرفية، يتم احتساب هذه الرموز المميزة مقابل إجمالي حد الرمز المميز المدرج في قائمة الانتظار.

دفعة عمومية

Model Enterprise وMCA-E الإفتراضي اشتراكات شهرية قائمة على بطاقة الائتمان اشتراكات MSDN Azure للطلاب، تجارب مجانية
gpt-4.1 5 ب 200 م 50 م 90 كيلو غير متوفر
gpt-4.1 mini 15B 1B 50 م 90 كيلو غير متوفر
gpt-4.1-nano 15B 1B 50 م 90 كيلو غير متوفر
gpt-4o 5 ب 200 م 50 م 90 كيلو غير متوفر
gpt-4o-mini 15B 1B 50 م 90 كيلو غير متوفر
gpt-4-turbo 300 م 80 م 40 مليون 90 كيلو غير متوفر
gpt-4 150 م 30 م 5 م 100 ألف غير متوفر
o3-mini 15B 1B 50 م 90 كيلو غير متوفر
o4-mini 15B 1B 50 م 90 كيلو غير متوفر
gpt-5 5 ب 200 م 50 م 90 كيلو غير متوفر
gpt-5.1 5 ب 200 م 50 م 90 كيلو غير متوفر

ب = مليار | M = مليون | K = ألف

دفعة منطقة البيانات

Model Enterprise وMCA-E الإفتراضي اشتراكات شهرية قائمة على بطاقة الائتمان اشتراكات MSDN Azure للطلاب، تجارب مجانية
gpt-4.1 500 م 30 م 30 م 90 كيلو غير متوفر
gpt-4.1-mini 1.5 مليار 100 م 50 م 90 كيلو غير متوفر
gpt-4o 500 م 30 م 30 م 90 كيلو غير متوفر
gpt-4o-mini 1.5 مليار 100 م 50 م 90 كيلو غير متوفر
o3-mini 1.5 مليار 100 م 50 م 90 كيلو غير متوفر
gpt-5 5 ب 200 م 50 م 90 كيلو غير متوفر
gpt-5.1 5 ب 200 م 50 م 90 كيلو غير متوفر

كائن الدفعة

الخاصية النوع تعريف
id string معرف الدفعة.
object string batch
endpoint string نقطة نهاية واجهة برمجة التطبيقات المستخدمة من قبل الدفعة
errors object معلومات الخطأ الخاصة بالدفعة، إن وجدت.
input_file_id string معرف ملف الإدخال للدفعة
completion_window string الإطار الزمني الذي يجب معالجة الدفعة خلاله
status string الحالة الحالية للدفعة. القيم المحتملة: validating، failed، in_progress، finalizing، completed، expired، ، cancelling. cancelled
output_file_id string معرف الملف الذي يحتوي على مخرجات الطلبات التي تم تنفيذها بنجاح.
error_file_id string معرف الملف الذي يحتوي على مخرجات الطلبات ذات الأخطاء.
created_at integer طابع زمني عند إنشاء هذه الدفعة (بثوان عصر يونكس).
in_progress_at integer طابع زمني عندما بدأت هذه الدفعة في التقدم (بثوان عصر يونكس).
expires_at integer طابع زمني ينتهي فيه انتهاء صلاحية هذه الدفعة (بثوان عصر يونكس).
finalizing_at integer طابع زمني عندما بدأت هذه الدفعة في الانتهاء (بثوان عصر يونكس).
completed_at integer طابع زمني عند اكتمال هذه الدفعة (بثوان عصر يونكس).
failed_at integer طابع زمني عندما تفشل هذه الدفعة (بثوان عصر يونكس).
expired_at integer طابع زمني عندما انتهت صلاحية هذه الدفعة (بثوان عصر يونكس).
cancelling_at integer طابع زمني عندما بدأت cancelling هذه الدفعة (بثوان عصر يونكس).
cancelled_at integer طابع زمني عندما كانت هذه الدفعة ( cancelled بثوان عصر يونكس).
request_counts object بنية الكائن:

total العدد الصحيح
العدد الإجمالي للطلبات في الدفعة.
completed العدد الصحيح
عدد الطلبات في الدفعة التي تم إكمالها بنجاح.
failed العدد الصحيح
عدد الطلبات في الدفعة التي فشلت.
metadata خريطة مجموعة من أزواج قيم المفاتيح التي يمكن إرفاقها بالدفعة. يمكن أن تكون هذه الخاصية مفيدة لتخزين معلومات إضافية حول الدفعة بتنسيق منظم.

الأسئلة الشائعة (FAQ)

هل يمكن استخدام الصور مع واجهة برمجة التطبيقات الدفعية؟

تقتصر هذه القدرة على بعض النماذج متعددة الوسائط. يمكن توفير الصور كإدخال إما عبر عنوان URL للصورة أو تمثيل مشفر base64 للصورة.

هل يمكنني استخدام واجهة برمجة التطبيقات الدفعية مع نماذج دقيقة؟

هذا غير معتمد حاليا.

هل يمكنني استخدام واجهة برمجة التطبيقات الدفعية لنماذج التضمين؟

هذا غير معتمد حاليا.

هل تعمل تصفية المحتوى مع نشر Global Batch؟

نعم. على غرار أنواع التوزيع الأخرى، يمكنك إنشاء عوامل تصفية المحتوى وربطها بنوع توزيع الدفعة العمومية.

هل يمكنني طلب حصة إضافية؟

نعم، من صفحة الحصص في <بوابة c0>Foundry. يمكن العثور على تخصيص الحصة النسبية الافتراضي في مقالة الحصة النسبية والحدود.

ماذا يحدث إذا لم تكمل واجهة برمجة التطبيقات طلبي خلال الإطار الزمني لمدة 24 ساعة؟

ونهدف إلى معالجة هذه الطلبات في غضون 24 ساعة؛ لا تنتهي صلاحية الوظائف التي تستغرق وقتا أطول. يمكنك إلغاء المهمة في أي وقت. عند إلغاء المهمة، يتم إلغاء أي عمل متبق ويتم إرجاع أي عمل مكتمل بالفعل. سيتم تحصيل رسوم منك مقابل أي عمل مكتمل.

كم عدد الطلبات التي يمكنني وضعها في قائمة الانتظار باستخدام الدفعة؟

لا يوجد حد ثابت لعدد الطلبات التي يمكنك دفعها، ومع ذلك، سيعتمد ذلك على الحصة النسبية للرمز المميز الذي تم وضعه في قائمة الانتظار. تتضمن الحصة النسبية للرمز المميز في قائمة الانتظار الحد الأقصى لعدد رموز الإدخال المميزة التي يمكنك إدراجها في قائمة الانتظار في وقت واحد.

بمجرد اكتمال طلب الدفعة، تتم إعادة تعيين حد معدل الدفعة، حيث يتم مسح رموز الإدخال المميزة. يعتمد الحد على عدد الطلبات العمومية في قائمة الانتظار. إذا كانت قائمة انتظار Batch API تعالج دفعاتك بسرعة، تتم إعادة تعيين حد معدل الدفعة بسرعة أكبر.

استكشاف الأخطاء وإصلاحها

تكون الوظيفة ناجحة عندما status تكون completed. ستظل الوظائف الناجحة تولد ، error_file_idلكنها سترتبط بملف فارغ بدون بايت.

عند حدوث فشل في الوظيفة، ستجد تفاصيل حول الفشل في الخاصية errors :

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

رموز الخطأ

رمز الخطأ تعريف
invalid_json_line تعذر تحليل سطر (أو متعدد) في ملف الإدخال ك json صالح.

يرجى التأكد من عدم وجود أخطاء مطبعية، وأقواس فتح وإغلاق مناسبة، وعلامات اقتباس وفقا لمعيار JSON، وإعادة إرسال الطلب.
too_many_tasks يتجاوز عدد الطلبات في ملف الإدخال الحد الأقصى المسموح به وهو 100,000.

يرجى التأكد من أن إجمالي طلباتك أقل من 100,000 وإعادة إرسال المهمة.
url_mismatch إما أن الصف في ملف الإدخال يحتوي على عنوان URL لا يتطابق مع بقية الصفوف، أو أن عنوان URL المحدد في ملف الإدخال لا يتطابق مع عنوان URL المتوقع لنقطة النهاية.

يرجى التأكد من أن جميع عناوين الطلبات متطابقة، وأنها تطابق رابط نقطة النهاية المرتبط بنشر Azure OpenAI الخاص بك.
model_not_found لم يتم العثور على اسم نموذج نشر OpenAI Azure المحدد في خاصية model لملف الإدخال.

يرجى التأكد من أن هذا الاسم يشير إلى نشر نموذج Azure OpenAI صالح.
duplicate_custom_id المعرف المخصص لهذا الطلب هو تكرار للمعرف المخصص في طلب آخر.
empty_file ملف الإدخال فارغ. يرجى التأكد من أن الدفعة تحتوي على طلب واحد على الأنا.
model_mismatch اسم نموذج نشر OpenAI Azure الذي تم تحديده في خاصية model لهذا الطلب في ملف الإدخال لا يتطابق مع بقية الملف.

يرجى التأكد من أن جميع الطلبات في الدفعة تشير إلى نفس Azure OpenAI في نشر نموذج نماذج Foundry في خاصية model الخاصة بالطلب.
invalid_request مخطط سطر الإدخال غير صحيح أو نشر SKU غير صالح.

يرجى التأكد من أن خصائص الطلب في ملف الإدخال الخاص بك تطابق مع خصائص الإدخال المتوقعة، وأن وحدة نشر OpenAI Azure هي globalbatch لطلبات API الدفعية.
input_modified تم تعديل إدخال Blob بعد إرسال مهمة الدفعة.
input_no_permissions لا يمكن الوصول إلى access the input blob. يرجى التحقق من permissions و access الشبكة بين حساب OpenAI Azure وحساب Azure Storage.

المشكلات المعروفة

  • الموارد المنشورة مع Azure CLI لن تعمل بشكل خارج الصندوق مع دفعة Azure OpenAI العالمية. ويرجع ذلك إلى مشكلة حيث أن الموارد التي تم نشرها باستخدام هذه الطريقة تحتوي على نطاقات فرعية في نقاط النهاية لا تتبع نمط https://your-resource-name.openai.azure.com. حل حل لهذه المشكلة هو نشر مورد Azure OpenAI جديد باستخدام إحدى طرق النشر الشائعة الأخرى التي ستتعامل بشكل صحيح مع إعداد النطاق الفرعي كجزء من عملية النشر.

  • الملفات المشفرة jsonl UTF-8-BOM غير مدعومة. يجب ترميز ملفات خطوط JSON باستخدام UTF-8. استخدام ملفات البايت-Order-Mark (BOM) المشفرة غير مدعوم رسميا بمواصفة JSON RFC، و Azure OpenAI حاليا تعامل الملفات المشفرة على أنها غير صالحة. سيعيد الملف المشفر UTF-8-BOM حاليا رسالة الخطأ العامة: "فشل التحقق من الصحة: تعذر استخراج اسم نشر نموذج صالح من ملف الإدخال. الرجاء التأكد من أن كل صف في ملف الإدخال له اسم نشر صالح محدد في حقل "النموذج"، وأن اسم النشر متناسق عبر جميع الصفوف."

  • عند استخدام your own storage لبيانات إدخال الدفعات، بمجرد تقديم مهمة الدفعة، إذا تم تعديل كتلة الإدخال، ستفشل مهمة التسجيل من قبل الخدمة.

(راجع أيضًا)

  • Last updated on