Batch API؛ اجرای انبوه درخواستهای گفتگو با یک فایل JSONL
برای کارهای بزرگ، مثل دستهبندی حجم زیادی متن یا خلاصه کردن یک آرشیو، باز نگه داشتن اتصالها و مدیریت همزمانی و تلاش دوباره کار سختی است. مسیرهای POST /v1/files و POST /v1/batches در وان ای آی (1ai) همان روال آشنای OpenAI را دارند: فایل JSONL را بارگذاری میکنید، کار را میسازید، وضعیت را میپرسید و فایل نتیجه را برمیدارید. اجرا غیرهمزمان است و میتواند ساعتها طول بکشد. قیمت هر مدل همان قیمت معمولی آن است و سطرهای ناموفق هزینهای ندارند.
چرا با 1ai
بدون اتصال باز
درخواستها را یکجا میفرستید؛ لازم نیست اتصالها را باز نگه دارید یا همزمانی و تلاش دوباره را خودتان مدیریت کنید.
روال آشنای OpenAI
بارگذاری فایل با purpose=batch، ساخت کار با POST /v1/batches و دریافت نتیجه با GET /v1/files/{id}/content.
فقط مصرف واقعی
بدترین حالت هر سطر هنگام ساخت کار رزرو میشود و بخش مصرفنشده در پایان برمیگردد. سطرهای ناموفق هزینهای ندارند.
نتیجه با شناسهی خودتان
هر سطر نتیجه custom_id شما را دارد، پس ترتیب مهم نیست و هر پاسخ را به رکورد خودش وصل میکنید.
در چند قدم
- ۱
فایل JSONL را بسازید
هر سطر یک درخواست است با custom_id، method، url و body؛ همهی سطرها یک مدل، و max_tokens در هر سطر.
- ۲
فایل را بارگذاری کنید
فایل را با purpose=batch به POST /v1/files بفرستید و id آن را بردارید.
- ۳
کار را بسازید
POST /v1/batches را با input_file_id، endpoint و completion_window صدا بزنید؛ اعتبار همینجا رزرو میشود.
- ۴
نتیجه را بردارید
با GET /v1/batches/{id} وضعیت را بپرسید و بعد output_file_id و error_file_id را دانلود کنید.
مدلهای گفتگو در API
همهی مدلهاGPT-6 Luna
سریع و بسیار ارزان؛ مدل پیشفرض و در نسخهی رایگان
شروع پاسخ ۲٫۶ ثانیه و سرعت ۷۴ توکن در ثانیه
GPT-6.1 Sol
پرچمدار اوپنایآی برای کارهای دقیق، تحلیلی و چندمرحلهای
شروع پاسخ ۵٫۶ ثانیه و سرعت ۵۷ توکن در ثانیه
Claude Haiku 5.5
سریعترین کلود؛ در نسخهی رایگان
شروع پاسخ ۴٫۶ ثانیه و سرعت ۲۹۸ توکن در ثانیه
۱. ساختن فایل JSONL
هر سطر فایل requests.jsonl یک درخواست کامل است:
{"custom_id": "q-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-6.1-sol", "max_tokens": 300, "messages": [{"role": "user", "content": "این نظر مثبت است یا منفی؟ خیلی راضی بودم."}]}}
{"custom_id": "q-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "openai/gpt-6.1-sol", "max_tokens": 300, "messages": [{"role": "user", "content": "این نظر مثبت است یا منفی؟ بسته دیر رسید."}]}}custom_idدر هر فایل باید یکتا باشد و تا ۶۴ نویسه.modelدر همهی سطرها یکی است: هر فایل یک مدل.max_tokensرا در همهی سطرها بگذارید؛ بخش رزرو اعتبار را ببینید.- شناسهی مدل بالا فقط نمونه است و همهی مدلها به صورت Batch اجرا نمیشوند؛ بخش «محدودیتها» را ببینید.
۲. بارگذاری فایل و ساختن کار
curl https://1ai.ir/v1/files \
-H "Authorization: Bearer $ONEAI_API_KEY" \
-F purpose=batch \
-F file=@requests.jsonlپاسخ یک id به شکل fil_… دارد. با آن کار را بسازید:
curl https://1ai.ir/v1/batches \
-H "Authorization: Bearer $ONEAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "fil_...",
"endpoint": "/v1/chat/completions",
"completion_window": "24h"
}'completion_window باید 24h باشد تا با قالب OpenAI یکی بماند، ولی پایان کار را در این زمان تضمین نمیکند. موعد نهایی کار در expires_at میآید.
۳. پیگیری وضعیت و دریافت نتیجه
curl https://1ai.ir/v1/batches/bat_... -H "Authorization: Bearer $ONEAI_API_KEY"{
"id": "bat_…",
"object": "batch",
"endpoint": "/v1/chat/completions",
"model": "openai/gpt-6.1-sol",
"status": "completed",
"input_file_id": "fil_…",
"output_file_id": "fil_…",
"error_file_id": null,
"request_counts": { "total": 2, "completed": 2, "failed": 0 },
"estimated_credits": …,
"credits": …
}status | معنی |
|---|---|
validating | در حال ارسال برای اجرا |
in_progress | در حال اجرا |
completed | تمام شده؛ فایلهای نتیجه آمادهاند |
failed | اجرا نشد؛ علت در errors است |
expired | تا موعد تمام نشد و اعتبار رزروشده برگشت |
وقتی کار تمام شد، فایلها را بردارید:
curl -L -o output.jsonl https://1ai.ir/v1/files/fil_.../content -H "Authorization: Bearer $ONEAI_API_KEY"این مسیر به یک لینک امضاشده هدایت میکند که یک ساعت اعتبار دارد. سطرهای موفق در output_file_id و سطرهای ناموفق در error_file_id هستند:
{"id": "batch_req_…", "custom_id": "q-1", "response": {"status_code": 200, "request_id": "…", "body": {"object": "chat.completion", "choices": […], "usage": {…}}}, "error": null}
{"id": "batch_req_…", "custom_id": "q-2", "response": null, "error": {"code": "request_failed", "message": "This request failed, and no credits were charged."}}نتیجهها را با custom_id به رکوردهای خودتان وصل کنید.
نمونه کامل با Python
# pip install requests
import os, time, requests
API = "https://1ai.ir/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ONEAI_API_KEY']}"}
with open("requests.jsonl", "rb") as f:
file = requests.post(f"{API}/files", headers=HEADERS, data={"purpose": "batch"}, files={"file": f}, timeout=120).json()
batch = requests.post(f"{API}/batches", headers=HEADERS, json={
"input_file_id": file["id"],
"endpoint": "/v1/chat/completions",
"completion_window": "24h",
}, timeout=120).json()
while batch["status"] in ("validating", "in_progress"):
time.sleep(300)
batch = requests.get(f"{API}/batches/{batch['id']}", headers=HEADERS, timeout=60).json()
for name in ("output_file_id", "error_file_id"):
if batch[name]:
res = requests.get(f"{API}/files/{batch[name]}/content", headers=HEADERS, timeout=600)
open(f"{name}.jsonl", "wb").write(res.content)چون کار ممکن است ساعتها طول بکشد، به جای یک حلقهی بلند میتوانید id کار را ذخیره کنید و وضعیت را با یک زمانبند بپرسید.
رزرو اعتبار و هزینه
هنگام ساختن کار، اعتبارِ بدترین حالت همهی سطرها یکجا رزرو میشود و بخش مصرفنشده وقتی کار تمام شد برمیگردد. پس موجودی شما باید برای کل فایل کافی باشد؛ وگرنه ساختن کار با 402 insufficient_credits رد میشود.
در هر سطر max_tokens بگذارید. سطری که آن را ندارد، به اندازهی کل سقف خروجی مدل رزرو میکند و در یک فایل بزرگ رزرو خیلی بالا میرود.
هر سطر به قیمت معمولی مدل حساب میشود و Batch تخفیف جداگانهای ندارد؛ مزیتش این است که اتصال و همزمانی را شما مدیریت نمیکنید. سطرهای ناموفق هزینهای ندارند و به فایل خطا میروند. تخمین رزرو در estimated_credits و مبلغ نهایی در credits میآید.
محدودیتها
- فقط گفتگو: تنها مسیر مجاز
/v1/chat/completionsاست. - یک مدل در هر فایل. همهی مدلها به صورت Batch اجرا نمیشوند و بقیه خطای
400 batch_not_availableمیگیرند. کلیدی که گاردریل دارد هم همین خطا را میگیرد. - بدون استریم:
streamپذیرفته نمیشود وnباید ۱ باشد. - فیلدهای مجاز
body:model،messages،max_tokens،max_completion_tokens،temperature،top_p،stop،seed،presence_penalty،frequency_penalty،tools،tool_choice،parallel_tool_calls،response_formatوreasoning_effort. - فقط ابزارهای function: ابزارهای دیگر پذیرفته نمیشوند.
- فقط متن و تصویر در پیامها؛ فایلهای دیگر پذیرفته نمیشوند.
- یک سطر بد، کل فایل را رد میکند. خطای
400 invalid_batch_fileشمارهی همان سطر را میگوید؛ سطر را درست کنید و فایل را دوباره بفرستید. - حجم فایل: تا ۲۵ مگابایت. تعداد سطرها و حجم کل فایلهای هر حساب هم سقف دارد و فایلها پس از مدتی حذف میشوند.
- بدون لغو: کاری که شروع شده لغو نمیشود و
POST /v1/batches/{id}/cancelخطای409 batch_not_cancellableمیدهد.
مدیریت فایلها و خطاها
فهرست فایلها و کارها با GET /v1/files و GET /v1/batches میآید و با after و limit صفحهبندی میشود. DELETE /v1/files/{id} فایل را حذف میکند.
| کد | معنی |
|---|---|
400 invalid_batch_file | سطری از فایل نادرست است؛ پیام شمارهی سطر را میگوید |
400 batch_not_available | این مدل یا این کلید به صورت Batch اجرا نمیشود |
402 insufficient_credits | موجودی برای رزرو کل فایل کافی نیست |
404 file_not_found و 404 batch_not_found | فایل یا کاری با این شناسه برای این حساب نیست |
409 file_in_use | کاری در حال اجرا این فایل را میخواند و حذف نمیشود |
409 batch_not_cancellable | کاری که شروع شده لغو نمیشود |
413 file_quota_exceeded | حجم فایلهای حساب از سقف گذشته؛ چند فایل را حذف کنید |
سوالات متداول
Batch از درخواست معمولی ارزانتر است؟
خیر. هر سطر به قیمت معمولی همان مدل حساب میشود. فایدهی Batch این است که برای کارهای بزرگ لازم نیست اتصالها را باز نگه دارید یا همزمانی و تلاش دوباره را خودتان مدیریت کنید.
یک کار Batch چقدر طول میکشد؟
اجرا غیرهمزمان است و میتواند ساعتها طول بکشد؛ زمان مشخصی را قول نمیدهیم. برای کاری که پاسخ فوری میخواهد، همان POST /v1/chat/completions مناسبتر است.
کدام مدلها به صورت Batch اجرا میشوند؟
همهی مدلها این امکان را ندارند و فهرست آن ممکن است تغییر کند. اگر مدلی نشود، ساختن کار با 400 batch_not_available رد میشود و اعتباری رزرو نمیشود؛ مدل دیگری را امتحان کنید.
چرا باید در هر سطر max_tokens بگذارم؟
چون اعتبارِ بدترین حالت هر سطر هنگام ساختن کار رزرو میشود. سطر بدون max_tokens کل سقف خروجی مدل را رزرو میکند و ممکن است موجودی کافی نباشد. بخش مصرفنشده در پایان برمیگردد.
اگر بعضی سطرها شکست بخورند چه میشود؟
هزینهای برایشان حساب نمیشود و با همان custom_id به فایل error_file_id میروند. میتوانید همان سطرها را در یک فایل تازه دوباره بفرستید.
میتوانم کار را وسط اجرا لغو کنم؟
خیر. کاری که شروع شده لغو نمیشود، پس پیش از ساختن کار فایل را با چند سطر امتحان کنید.
چه فرقی با POST /v1/batch دارد؟
POST /v1/batch چند درخواست را در یک فراخوانی و همان لحظه اجرا میکند و پاسخ را همانجا میدهد. POST /v1/batches برای فایلهای بزرگ است، غیرهمزمان اجرا میشود و نتیجه را در فایل میدهد.
مطالب مرتبط

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
چطور پروژهای را که با کتابخانهی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدلها و مدیریت خطا.

کلید API در 1ai: امنیت، محدودیتها و کنترل هزینه
چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدلهای مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.
صفحههای مرتبط
همهی امکاناتOpenAI SDK
کتابخانهی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.
Rerank API
یک پرسش و فهرستی از متنها بفرستید و همان متنها را مرتبشده بر اساس ارتباط با پرسش، همراه با امتیاز هر کدام، پس بگیرید.
Extraction API
فیلدهایی را که لازم دارید با نوعشان تعریف کنید و از متن یا تصویر، مقدار هر فیلد را با اطمینان آن بگیرید؛ فیلدی که در متن نیست null برمیگردد.
Batch API؛ اجرای انبوه درخواستهای گفتگو با یک فایل JSONL
حجم زیادی از درخواستهای گفتگو را لازم نیست یکییکی بفرستید: آنها را در یک فایل JSONL بگذارید، کار را بسازید و وقتی تمام شد فایل نتیجه را بردارید.
ساخت کلید API