Batch API
Batch API برای پردازش دستهای و ناهمزمان طراحی میشود؛ یعنی بهجای اینکه تعداد زیادی درخواست را همزمان و برخط بفرستید، آنها را به شکل یک کار دستهای ثبت میکنید و بعداً نتیجه را دریافت میکنید.
این الگو برای کارهایی مناسب است که کاربر منتظر پاسخ لحظهای نیست:
- خلاصهسازی تعداد زیادی سند
- تولید Embedding برای ورود اولیه دادهها
- برچسبگذاری رکوردها
- ارزیابی مجموعهای از پرامپتها
- پردازش شبانه یا زمانبندیشده
جایگاه در گدارAI
فعالبودن Batch API به نسخه و تنظیمات محیط شما بستگی دارد. اگر این قابلیت در فضای کاری شما فعال باشد، معمولاً با مسیرهایی از این خانواده کار میکنید:
POST /v1/batches
GET /v1/batches/{batch_id}
POST /v1/files
GET /v1/files/{file_id}
GET /v1/files/{file_id}/content
اگر این مسیرها در محیط شما فعال نیستند، برای پردازش انبوه فعلاً orchestration را در سرویس خودتان نگه دارید و از APIهای آماده مثل Chat Completions و Embeddings استفاده کنید.
Batch API چه مسئلهای را حل میکند؟
در درخواستهای عادی:
- درخواست را میفرستید.
- همان لحظه پاسخ میگیرید.
- زمان پاسخ برای تجربه کاربر مهم است.
در پردازش دستهای:
- یک کار ناهمزمان ثبت میکنید.
- پردازش در پسزمینه انجام میشود.
- وضعیت کار را پیگیری میکنید.
- خروجی را بعداً دریافت میکنید.
این تفاوت برای کنترل هزینه، مدیریت خطا و اجرای پردازشهای بزرگ بسیار مهم است.
چه زمانی استفاده نکنیم؟
Batch API انتخاب خوبی نیست برای:
- چت زنده با کاربر
- رابط تعاملی که پاسخ فوری میخواهد
- عاملهایی که باید در چند ثانیه ابزار صدا بزنند
- مسیرهایی که هر درخواست به تصمیم کاربر وابسته است
برای این سناریوها، Chat Completions، Responses API یا Embeddings به شکل مستقیم مناسبترند.
الگوی موقت تا زمان فعالسازی
اگر امروز به رفتار نزدیک به Batch نیاز دارید:
- داده را در storage خودتان نگه دارید.
- آن را به دستههای کوچکتر تقسیم کنید.
- برای هر دسته، درخواستهای کنترلشده به گدارAI بفرستید.
- نتیجه هر درخواست را ذخیره کنید.
- خطاها را با شناسه رکورد و شناسه رد درخواست نگه دارید.
- در پایان گزارش مصرف، خطا و خروجی را بسازید.
برای تولید بردار، Embeddings از آرایه رشتهها پشتیبانی میکند و میتواند بخشی از این الگوی موقت باشد.
نکتههای طراحی
- اندازه دستهها را محدود نگه دارید تا خطاها قابل بازیابی باشند.
- سیاست تلاش دوباره را صریح طراحی کنید؛ همه خطاها نباید بیدرنگ دوباره اجرا شوند.
- قبل از اجرای گسترده، بودجه و سقف نرخ را بررسی کنید.
- برای هر آیتم، شناسه داخلی خودتان را نگه دارید تا نتیجه نهایی قابل تطبیق باشد.
- اگر داده حساس دارید، سیاست نگهداری فایل ورودی و خروجی را از ابتدا روشن کنید.
وقتی Batch API فعال باشد چه انتظاری داریم؟
در یک قرارداد کامل، معمولاً این قابلیتها لازم میشوند:
- ساخت کار دستهای با
POST /v1/batches - مشاهده وضعیت کار
- دریافت فایل نتیجه
- مشاهده خطاهای آیتمبهآیتم
- اتصال به Files API
- ثبت مصرف و هزینه برای کل کار و آیتمهای آن
جزئیات قطعی را همیشه از مستندات همان محیط و نسخهای که برای شما فعال شده است بردارید.
جمعبندی
Batch API برای پردازشهای بزرگ، غیرتعاملی و قابل زمانبندی مناسب است. تا زمانی که در محیط شما فعال نشده، همان معماری را در سرویس خودتان شبیهسازی کنید: دستهبندی کنترلشده، ثبت نتیجه، مدیریت خطا، و بررسی دقیق مصرف در گدارAI.