پایداری: مدل جایگزین و تلاش دوباره

مدل‌ها گاهی جواب نمی‌دهند. برنامهٔ شما نباید با آن‌ها بخوابد.

۵ دقیقهدرس ۴ از ۹۰ از ۲ قدم

هر مدلی گاهی جواب نمی‌دهد، به خاطر فشار زیاد، تعمیرات یا یک خطای موقت. برنامهٔ خوب از قبل برای این لحظه آماده است و ایران‌روتر چند ابزار ساده برایش دارد.

مدل‌های جایگزین

کنار model می‌توانید فهرست models را هم بفرستید. اگر مدل اول نتواند جواب بدهد و هنوز چیزی از جواب برایتان فرستاده نشده باشد، مدل بعدی امتحان می‌شود.

JSON
{
  "model": "anthropic/claude-sonnet-4.6",
  "models": ["deepseek/deepseek-v4-flash"],
  "messages": [{"role": "user", "content": "سلام"}]
}

کل زنجیره حداکثر سه مدل است و خود model هم یکی از آن‌هاست. عوض شدن مدل را از شما پنهان نمی‌کنیم: لاگ نشان می‌دهد چه مدل‌هایی امتحان شدند و کدام جواب داد، و فقط پول همان مدل را می‌دهید.

بعد از رسیدن اولین بایت جواب، مدل دیگر عوض نمی‌شود؛ جوابی که نصفش از یک مدل و نصفش از مدل دیگر باشد، به درد کسی نمی‌خورد.

تلاش دوبارهٔ بی‌خطر

فرض کنید درخواستی فرستادید و اینترنت قطع شد. نمی‌دانید رسیده یا نه. اگر دوباره بفرستید ممکن است دو بار پول بدهید. هدر Idempotency-Key این مشکل را حل می‌کند:

Shell
curl https://iranrouter.com/v1/chat/completions \
  -H "Authorization: Bearer ir-..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4-flash", "messages": [{"role": "user", "content": "سلام"}]}'

اگر با همین Idempotency-Key دوباره بفرستید، همان جواب قبلی برمی‌گردد و دوباره پولی کم نمی‌شود. اگر درخواست اول هنوز در حال اجرا باشد، خطای ۴۰۹ می‌گیرید. این هدر فقط برای درخواست‌های بدون stream کار می‌کند.

کارهای طولانی

برای کاری که چند دقیقه طول می‌کشد، به جای باز نگه داشتن اتصال از مسیر async استفاده کنید. همان بدنه را به /v1/async/ و نام مسیر می‌فرستید، بلافاصله یک شناسهٔ کار می‌گیرید و نتیجه را بعداً می‌خوانید.

Shell
curl https://iranrouter.com/v1/async/chat/completions \
  -H "Authorization: Bearer ir-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4-flash", "messages": [{"role": "user", "content": "گزارش بنویس"}]}'

برای کارهای انبوه هم POST /v1/batches هست. یک فایل JSONL از درخواست‌ها می‌دهید، در پس‌زمینه اجرا می‌شود و نتیجه هم به شکل فایل برمی‌گردد. batch تخفیف ندارد و هر خط با همان قیمت یک درخواست معمولی حساب می‌شود. فایده‌اش راحتی است، نه ارزانی.

الگوی پیشنهادی

  1. برای هر مدل حیاتی یک جایگزین بگذارید.
  2. روی ۴۲۹ و ۵۰۳ با فاصلهٔ افزایشی دوباره تلاش کنید و retry-after را رعایت کنید.
  3. برای درخواست‌هایی که نباید دو بار اجرا شوند Idempotency-Key بفرستید.
  4. برای مدل‌های قدیمی هدر Deprecation و X-IranRouter-Successor را نگاه کنید.
صفحهٔ وضعیت نشان می‌دهد کدام مدل‌ها پایدارند و منبع هر عدد را هم نوشته است.

زنجیره را امتحان کنید۰ از ۲ قدم

  1. یک درخواست با فهرست models بفرستید و جواب را ببینید.
  2. ردیف همین درخواست را در لاگ باز کنید و بخش زنجیره را بخوانید.

خلاصهٔ درس

  • models جایگزین می‌دهد و فقط مدلی که جواب داده هزینه دارد.
  • Idempotency-Key تلاش دوباره را بی‌خطر می‌کند.
  • کار طولانی را به مسیر async بفرستید.
تصویر، صدا، ویدئو، OCR و embeddingبا همان کلید و کیف پول، کارهایی جز متن هم می‌شود کرد که شاید هنوز به فکرتان نرسیده باشد.تمام کردم، درس بعد