چک‌لیست تولید API OpenRouter

بررسی سازگاری API و نقاط پایانی

برای یک یکپارچه‌سازی قابل‌اعتماد، از اندپوینت‌های استاندارد سازگار با OpenAI استفاده کنید.

نقطه پایانی اصلی POST /v1/chat/completions. این تولید متن برای تاریخچه‌های چت را مدیریت می‌کند. یک نقطه پایایی ثانویه، GET /v1/models, مدل‌های موجود را فهرست می‌کند. شما برای وظایف فقط متنی به نقاط پایانی جاسازی یا تولید تصویر نیاز ندارید. بسیاری از توسعه‌دهندگان فرض می‌کنند که به لایه مسیریابی پیچیده‌ای نیاز دارند. OpenRouter این کار را با قرار دادن یک نقطه ورود واحد ساده می‌کند. شما یک بدنه JSON با شناسه مدل و پرامپت‌های سیستم خود ارسال می‌کنید. سرویس یک JSON ساختاریافته با محتوا و داده‌های استفاده برمی‌گرداند. این طراحی با انتظارات SDK رسمی OpenAI مطابقت دارد. می‌توانید مدل‌ها را بدون تغییر کد مشتری خود جابجا کنید. فقط شناسه مدل را در پیکربندی خود به‌روزرسانی کنید. مطمئن شوید که مشتری شما از آخرین طرحواره JSON پشتیبانی می‌کند. نسخه‌های قدیمی‌تر ممکن است پارامترهای جدید را رد کنند. اتصال خود را قبل از استقرار در محیط تولید آزمایش کنید. تأیید کنید که فرمت پاسخ با پارسر شما مطابقت دارد.

پیکربندی احراز هویت و کلیدها

کلید API خود را بلافاصله پس از تولید در متغیرهای محیطی امن کنید.

کلید را از طریق داشبورد ارائه‌دهنده تولید کنید. آن را در مکانی امن ذخیره کنید. هرگز آن را در مخزن منبع خود هاردکد نکنید. آن را از طریق ارسال کنید Authorization: Bearer <key> هدر. هر کلید به یک حساب کاربری خاص متصل است. اگر نشت کلید را مشکوک می‌دانید، می‌توانید کلیدها را بچرخانید. برخی از ارائه‌دهندگان اجازه چندین کلید برای هر حساب کاربری را می‌دهند. این به شما امکان می‌دهد ترافیک توسعه و تولید را جدا کنید. مصرف را به ازای هر کلید پایش کنید تا ناهنجاری‌ها را تشخیص دهید. کلیدهای استفاده نشده را به طور منظم لغو کنید. از کلیدهای عمر کوتاه برای اسکریپ‌های موقت استفاده کنید. این خطر انفجار ناشی از نفوذ را کاهش می‌دهد. اطمینان حاصل کنید که نسخه SDK شما از احراز هویت توکن bearer پشتیبانی می‌کند. کتابخانه‌های قدیمی‌تر ممکن است به فرمت هدر متفاوتی نیاز داشته باشند. مستندات SDK خاص خود را بررسی کنید. بررسی کنید که کلید موجودی کافی دارد. کلید منقضی شده خطای 401 برمی‌گرداند. کلیدی با موجودی صفر خطای 402 برمی‌گرداند. این دو حالت را در منطق خود متمایز کنید.

مدیریت پخش زنده و استفاده از توکن

برای کاهش تأخیر و بازخورد کاربر بلادرنگ، جریان‌یابی را فعال کنید.

تنظیم stream: true در پیکربندی درخواست. سرز یک سری رویدادهای ارسال‌شده توسط سرور (SSE) ارسال می‌کند. هر رویداد حاوی یک قطعه جزئی از متن است. باید این قطعات را برای تشکیل پاسخ کامل مونتاژ کنید. قطعه نهایی اغلب شامل آمار مصرف توکن است. این به شما امکان می‌دهد هزینه‌ها را به صورت بلادرنگ ردیابی کنید. بدون پخش، شما منتظر پاسخ کامل می‌مانید. این تاخیر ادراک‌شده را به طور قابل توجهی افزایش می‌دهد. پخش برای رابط‌های چت ضروری است. این یک افکت تایپ ایجاد می‌کند که پاسخگو به نظر می‌رسد. در مدیریت خطاها هنگام پخش مراقب باشید. اگر اتصال قطع شود، قطعه فعلی را از دست می‌دهید. منطق اتصال مجدد باید وضعیت مکالمه را حفظ کند. برخی از SDKها پخش را به صورت خودکار مدیریت می‌کنند. برخی دیگر به شنوندگان رویداد دستی نیاز دارند. رویکردی را انتخاب کنید که با معماری شما سازگار است. مطمئن شوید تجزیه‌کننده شما قطعات JSON ناقص را مدیریت می‌کند. فرض نکنید هر رویداد یک شیء کامل است. داده‌ها را بافر کنید تا زمانی که یک ساختار معتبر داشته باشید.

مانیتور محدودیت‌های نرخ و همزمانی

تعداد درخواست‌های در دقیقه خود را ردیابی کنید تا از اختلال در سرویس جلوگیری شود.

OpenRouter محدودیت‌های نرخ سخت‌گیرانه‌ای را برای هر کلید API اعمال می‌کند. تجاوز از این محدودیت‌ها منجر به خطای 429 Too Many Requests می‌شود. شما باید در منطق تلاش مجدد خود از بازگشت نمایی (exponential backoff) استفاده کنید. درخواست‌های همزمان نیز در محدودیت‌های شما محاسبه می‌شوند. برای بررسی سهمیه باقی‌مانده، به هدرهای پاسخ نگاه کنید. برخی از ارائه‌دهندگان این هدرها را مستقیماً در اختیار قرار می‌دهند. برخی دیگر نیاز دارند که محدودیت‌ها را از خطاها استنتاج کنید. همزمانی بالا می‌تواند مخزن اتصال شما را مستهلک کند. مطمئن شوید که کلاینت شما اتصالات را به طور کارآمد مدیریت می‌کند. از پویش اتصال (connection pooling) برای کاهش سربار استفاده کنید. عمق صف خود را در زمان‌های اوج بار نظارت کنید. اگر به محدودیت برسید، قبل از تلاش مجدد صبر کنید. زمان انتظار خود را تصادفی کنید تا از مشکلات گله‌ای (thundering herd) جلوگیری کنید. تمام رویدادهای محدودیت نرخ را برای اشکال‌زدایی ثبت کنید. این به شناسایی الگوها در استفاده شما کمک می‌کند. تنظیمات همزمانی خود را بر اساس این گزارش‌ها تنظیم کنید. فرض نکنید که یک کلید واحد می‌تواند ترافیک نامحدود را مدیریت کند. اگر لازم است، بار را بین چند کلید توزیع کنید. این نیاز به مدیریت وضعیت دقیق دارد. مطمئن شوید که هر کلید زمینه خود را حفظ می‌کند، اگر نیاز است.

مدیریت پرداخت‌های کریپتو و شارژ حساب

از اعتبار پیش‌پرداخت برای پوشش استفاده توکن بدون هزینه ماهانه استفاده کنید.

حساب خود را با ارز دیجیتال شارژ کنید. شبکه‌های پشتیبانی شده شامل USDT روی TRC20 و USDC روی Base است. حداقل شارژ‌ها از $20 شروع می‌شوند. پاداش‌ها برای مبالغ بزرگ‌تر اعمال می‌شوند. شما 5% اضافی برای $50، 10% برای $100 و 15% برای $200 دریافت می‌کنید. اعتبار هرگز منقضی نمی‌شود. این برای پروژه‌های بلندمدت ایده‌آل است. شما فقط برای توکن‌های واقعی مصرف شده پرداخت می‌کنید. خطاها و رد شدن درخواست‌ها رایگان هستند. این از بودجه شما در برابر هزینه‌های غیرمنتظره محافظت می‌کند. حساب‌های جدید $0.50 برای آزمایش دریافت می‌کنند. برای خریدهای استاندارد بازگشت وجه صادر نمی‌شود. پرداخت‌های دوتایی از طریق پشتیبانی اصلاح می‌شوند. اطمینان حاصل کنید که کیف پول شما شبکه‌های مورد نیاز را پشتیبانی می‌کند. آدرس قرارداد را قبل از ارسال بررسی کنید. شبکه‌های نادرست ممکن است منجر به از دست رفتن وجوه شود. موجودی خود را به طور منظم بررسی کنید. موجودی‌های کم می‌توانند به طور غیرمنتظره خدمات را قطع کنند. اگر امکان دارد شارژهای خود را خودکار کنید. این برای اطمینان از دسترسی مداوم برای وظایف حیاتی است.

بررسی فیلترها و رد کردن محتوا

بررسی کنید که مدل با پرامپت‌های بدون سانسور همان‌طور که انتظار می‌رود رفتار می‌کند.

مدل‌های بدون سانسور ممکن است همچنان محدودیت‌های سختی اعمال کنند. محدودیت‌ها را روی انواع خاص محتوا بررسی کنید. با عبارات محرک شناخته‌شده آزمایش کنید. اطمینان حاصل کنید که مدل به درستی پاسخ می‌دهد. برخی از ارائه‌دهندگان فیلترهایی را به دلایل قانونی حفظ می‌کنند. قبل از تکیه بر مدل برای داده‌های حساس، این‌ها را بررسی کنید. موارد مرزی در حوزه خود را آزمایش کنید. پرامپت‌هایی را ارسال کنید که معمولاً منجر به رد می‌شوند. قالب پاسخ را مشاهده کنید. آیا دلیل رد را برمی‌گرداند؟ یا آیا محتوا را به صورت خام تولید می‌کند؟ این رفتارها را در تست‌های یکپارچه‌سازی خود مستند کنید. این کار از سورپرایز شدن در محیط تولید جلوگیری می‌کند. اگر مدل رفتار خود را تغییر داد، تست‌های خود را به‌روزرسانی کنید. تیم خود را از هرگونه تغییر قابل توجهی مطلع کنید. ثبات کلید اعتماد کاربر است. اطمینان حاصل کنید که برنامه شما رد کردن‌ها را به صورت شستشوده مدیریت می‌کند. فرض نکنید که هر پاسخی معتبر است. ساختار خروجی را اعتبارسنجی کنید. توهم‌ها یا خطاهای قالب‌بندی را بررسی کنید. این یک تجربه کاربری قابل اعتماد را تضمین می‌کند.

پیاده‌سازی مدیریت خطا برای درخواست‌های رایگان

خطاها را به شیوه‌ای مناسب مدیریت کنید تا تجربه کاربری روانی حفظ شود.

خطاهای شبکه، زمان‌های انتظار و خطاهای سرور ممکن است رخ دهند. منطق تلاش مجدد را با بازگشت نمایی پیاده‌سازی کنید. بین خطاهای موقت و دائمی تمایز قائل شوید. خطای ۴۲۹ موقت است. صبر کنید و مجدداً تلاش کنید. خطای ۴۰۰ دائمی است. داده‌های ورودی خود را بررسی کنید. خطای ۵۰۰ مربوط به سمت سرور است. با احتیاط مجدداً تلاش کنید. تمام خطاها را برای اشکال‌زدایی ثبت کنید. پیکربندی درخواست و بدنه پاسخ را شامل کنید. این به بازتولید سریع مشکلات کمک می‌کند. خطاهای خام را به کاربران نشان ندهید. آن‌ها را به پیام‌های قابل‌فهم برای کاربر تبدیل کنید. خطاهای استریم را با دقت مدیریت کنید. از جریان رویداد قطع شوید. منابع را پاکسازی کنید. مطمئن شوید برنامه شما نشت حافظه ندارد. سناریوهای خطا را به‌خوبی تست کنید. افت شبکه را شبیه‌سازی کنید. زمان‌های انتظار سرور را شبیه‌سازی کنید. تأیید کنید که منطق بازیابی شما کار می‌کند. این امر قابلیت اطمینان را در شرایط نامساعد تضمین می‌کند.

با حالت JSON و فراخوانی ابزار مقیاس دهید

از خروجی‌های ساختاریافته برای استخراج داده‌های قابل‌اعتماد و اجرای تابع استفاده کنید.

حالت JSON را با تنظیم response_format: {type: "json_object"}. این موضوع مدل را مجبور می‌کند تا JSON معتبر خروجی دهد. این را برای تجزیه داده یا تولید پیکربندی‌ها استفاده کنید. فراخوانی ابزار به مدل اجازه می‌دهد توابع را اجرا کند. ابزارهای خود را در بدنه درخواست تعریف کنید. مدل تصمیم می‌گیرد که چه زمانی آن‌ها را فراخوانی کند. نتایج را به مدل بازگردانید. مدل می‌تواند بر اساس خروجی یک پاسخ نهایی تولید کند. این یک حلقه برای وظایف پیچیده ایجاد می‌کند. مطمئن شوید تعاریف ابزار شما واضح هستند. ابزارهای مبهم منجر به فراخوانی‌های نادرست می‌شوند. خروجی JSON را قبل از تجزیه اعتبارسنجی کنید. این از خطاهای زمان اجرا در کد شما جلوگیری می‌کند. فراخوانی ابزار را برای وظایف استخراج داده استفاده کنید. دقت را به طور قابل توجهی بهبود می‌بخشد. با فرمت‌های ورودی مختلف آزمایش کنید. مطمئن شوید که مدل موارد حاشیه‌ای را مدیریت می‌کند. ابزارهای موجود را برای تیم خود مستند کنید. این استفاده یکسان در سراسر پروژه‌ها را تضمین می‌کند.

مرور سیاست‌های حریم خصوصی و استفاده از داده‌ها

درک کنید داده‌های شما توسط ارائه‌دهنده چگونه ذخیره و استفاده می‌شوند.

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