قائمة مراجعة إنتاج OpenRouter API

تحقق من توافق واجهة برمجة التطبيقات والنقاط النهائية

استخدم نقاط النهاية القياسية المتوافقة مع OpenAI لدمج موثوق.

النقطة النهائية الأساسية هي POST /v1/chat/completions. يتعامل هذا مع توليد النص لسجلات الدردشة. نقطة نهاية ثانوية، GET /v1/models, يعرض النماذج المتاحة. لا تحتاج إلى نقاط نهاية للتضميم أو توليد الصور للمهام التي تعتمد على النص فقط. يفترض العديد من المطورين أنهم بحاجة إلى طبقة توجيه معقدة. تبسط OpenRouter هذا من خلال كشف نقطة دخول واحدة. ترسل حمولة JSON مع معرف النموذج ورسائل النظام. تُرجع الخدمة JSON منظمًا يحتوي على المحتوى وبيانات الاستخدام. يتوافق هذا التصميم مع توقعات SDK الرسمي لـ OpenAI. يمكنك تبديل النماذج دون تغيير كود العميل الخاص بك. فقط قم بتحديث معرف النموذج في تكوينك. تأكد من أن عميلك يدعم أحدث مخطط JSON. قد ترفض الإصدارات القديمة المعلمات الجديدة. اختبر اتصالك قبل النشر في بيئة الإنتاج. تحقق من أن تنسيق الاستجابة يتوافق مع المفسر الخاص بك.

تكوين المصادقة والمفاتيح

احمِ مفتاح واجهة برمجة الخاص بك في متغيرات البيئة فورًا بعد إنشائه.

أنشئ مفتاحاً من خلال لوحة تحكم المزود. احفظه في مكان آمن. لا تقم بتضمينه بشكل ثابت في مستودع الكود الخاص بك. مرره عبر Authorization: Bearer <key> رأس. يرتبط كل مفتاح بحساب معين. يمكنك تدوير المفاتيح إذا اشتبهت في حدوث تسرب. يسمح بعض المزودين بمفاتيح متعددة لكل حساب. يتيح لك ذلك فصل حركة تطوير وإنتاج البيانات. راقب الاستخدام لكل مفتاح للكشف عن الشذوذ. ألغِ صلاحية المفاتيح غير المستخدمة بانتظام. استخدم مفاتيح قصيرة العمر للبرامج النصية المؤقتة. يقلل هذا من حجم الضرر في حالة حدوث اختراق. تأكد من أن إصدار واجهة برمجة التطبيقات (SDK) الخاص بك يدعم مصادقة رمز bearer. قد تتطلب المكتبات القديمة تنسيق رأس مختلف. تحقق من الوثائق الخاصة بواجهة برمجة التطبيقات (SDK) المحددة الخاصة بك. تحقق من أن المفتاح يحتوي على رصيد كافٍ. يعيد المفتاح المنتهي صلاحيته خطأ 401. يعيد المفتاح الذي يحتوي على رصيد صفر خطأ 402. ميز بين هاتين الحالتين في منطقك.

التعامل مع التدفق واستخدام الرموز

فعّل التدفق لملاحظات المستخدم في الوقت الفعلي وانخفاض زمن الانتظار.

تعيين stream: true في حمولة الطلب الخاصة بك. يرسل الخادم سلسلة من أحداث مُرسلة من الخادم (SSE). تحتوي كل حدث على شريحة نصية جزئية. يجب عليك تجميع هذه الشرائح لتشكيل الرد الكامل. غالباً ما تتضمن الشريحة الأخيرة إحصائيات استخدام الرموز. يتيح لك ذلك تتبع التكاليف في الوقت الفعلي. بدون التدفق، تنتظر الرد بأكمله. يزيد هذا من زمن الاستجابة المُدرَك بشكل كبير. التدفق ضروري لواجهات الدردشة. يخلق تأثير كتابة يشعر بالاستجابة. كن حذراً مع معالجة الأخطاء أثناء التدفق. إذا انقطع الاتصال، تفقد الشريحة الحالية. يجب أن يحافظ منطق إعادة الاتصال على حالة المحادثة. تتعامل بعض مكتبات التطوير (SDKs) مع التدفق تلقائياً. يتطلب البعض الآخر مستمعي أحداث يدويين. اختر النهج الذي يناسب بنية نظامك. تأكد من أن المفسر الخاص بك يتعامل مع شرائح JSON غير المكتملة. لا تفترض أن كل حدث هو كائن كامل. قم بتخزين البيانات مؤقتاً حتى تحصل على هيكل صالح.

مراقبة حدود المعدل والتزامن

تتبع عدد طلباتك في الدقيقة لتجنب انقطاع الخدمة.

تفرض OpenRouter حدوداً صارمة لمعدل الطلبات لكل مفتاح API. يؤدي تجاوز هذه الحدود إلى تشغيل خطأ 429 Too Many Requests. يجب عليك تنفيذ استراتيجية إعادة المحايل مع زيادة أسية في منطق إعادة المحاولة. تحسب الطلبات المتزامنة أيضاً ضمن حدودك. تحقق من رؤوس الاستجابة لمعرفة الرصيد المتبقي. تكشف بعض المزودين عن هذه الرؤوس مباشرة. تتطلب أخرى منك استنتاج الحدود من الأخطاء. يمكن أن يستنفد الازدواجية العالية مجموعة الاتصالات الخاصة بك. تأكد من إدارة عميلك للاتصالات بكفاءة. استخدم تجزئة الاتصالات لتقليل الحمل. راقب عمق الطابور أثناء أحمال الذروة. إذا وصلت إلى الحد، انتظر قبل إعادة المحاولة. قم بتغيير وقت الانتظار عشوائياً لتجنب مشاكل القطيع الرعدية. سجل جميع أحداث حد المعدل لاستكشاف الأخطاء وإصلاحها. يساعد ذلك في تحديد الأنماط في استخدامك. اضبط إعدادات الازدواجية بناءً على هذه السجلات. لا تفترض أن مفتاحاً واحداً يمكنه التعامل مع حركة مرور غير محدودة. وزع الحمل عبر مفاتيح متعددة إذا لزم الأمر. يتطلب ذلك إدارة حالة دقيقة. تأكد من أن كل مفتاح يحافظ على سياقه الخاص إذا لزم الأمر.

إدارة الفواتير بالعملات المشفرة والإضافات

استخدم الرصيد المسبق لتغطية استخدام الرموز دون رسوم شهرية.

قم بزيادة رصيد حسابك بالعملات المشفرة. الشبكات المدعومة تشمل USDT على TRC20 وUSDC على Base. تبدأ الزيادة الدنيا من $20. تنطبق المكافآت على المبالغ الأكبر. تتلقى 5% إضافية لـ $50، و10% لـ $100، و15% لـ $200. الرصيد لا ينتهي. هذا مثالي للمشاريع طويلة الأجل. تدفع فقط مقابل الرموز المميزة المستخدمة فعلياً. الأخطاء والرفض مجاني. هذا يحمي ميزانيتك من التكاليف غير المتوقعة. تحصل الحسابات الجديدة على $0.50 للاختبار. لا يتم إصدار استرداد للشراءات القياسية. يتم تصحيح الشحنات المزدوجة عبر الدعم. تأكد من أن محفظتك تدعم الشبكات المطلوبة. تحقق من عنوان العقد قبل الإرسال. قد تؤدي الشبكات غير الصحيحة إلى فقدان الأموال. تحقق من رصيدك بانتظام. يمكن أن تعطل الأرصدة المنخفضة الخدمة بشكل غير متوقع. قم بأتمتة الزيادة إذا أمكن. هذا يضمن الاستمرارية في التوفر للمهام الحرجة.

اختبار مرشحات المحتوى والرفض

تحقق من أن النموذج يتصرف كما هو متوقع مع المطالبات غير الخاضعة للرقابة.

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

تنفيذ معالجة الأخطاء للطلبات المجانية

عالج الأخطاء بسلاسة للحفاظ على تجربة مستخدم سلسة.

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

وسع الاستخدام باستخدام وضع JSON واستدعاء الأدوات

استخدم المخرجات المهيكلة لاستخراج البيانات الموثوق وتنفيذ الوظائف.

تفعيل وضع JSON عن طريق تعيين response_format: {type: "json_object"}. يفرض هذا على النموذج إخراج JSON صالح. استخدم هذا لتحليل البيانات أو إنشاء ملفات التكوين. يسمح استدعاء الأدوات للنموذج بتنفيذ الوظائف. عرّف أدواتك في حمولة الطلب. يقرر النموذج متى يستدعيها. مرر النتائج مرة أخرى إلى النموذج. يمكنه إنشاء استجابة نهائية بناءً على المخرج. هذا يخلق حلقة للمهام المعقدة. تأكد من أن تعريفات أدواتك واضحة. تؤدي الأدوات الغامضة إلى استدعاءات غير صحيحة. تحقق من إخراج JSON قبل التحليل. هذا يمنع أخطاء وقت التشغيل في كودك. استخدم استدعاء الأدوات لمهام استخراج البيانات. يحسن الدقة بشكل كبير. اختبر بتنسيقات إدخال متنوعة. تأكد من أن النموذج يتعامل مع الحالات الحدية. وثّق الأدوات المتاحة لفريقك. يضمن هذا الاستخدام المتسق عبر المشاريع.

مراجعة سياسات الخصوصية واستخدام البيانات

فهم كيفية تخزين بياناتك واستخدامها من قبل المزود.

تحقق من سياسة الخصوصية لتفاصيل الاحتفاظ بالبيانات. يستخدم بعض المزودين بياناتك في التدريب، بينما يحافظ آخرون على خصوصيتها. تأكد من عدم استخدام بياناتك لتحسين النموذج إذا كان ذلك مهماً لك. تحقق من معايير التشفير. يجب تشفير البيانات أثناء النقل وعند التخزين. تحقق مما إذا كانت السجلات (Logs) تُحفظ. قد تحتوي السجلات على طلباتك. تأكد من أمان هذه السجلات. راجع شروط الخدمة لفهم بنود المسؤولية. افهم من يملك المحتوى المولد. يدعي بعض المزودين حقوقاً على ناتجك. تأكد من توافق ذلك مع احتياجاتك. احذف حسابك إذا لم تعد تستخدم الخدمة. تحقق من إزالة بياناتك. تواصل مع الدعم إذا كانت لديك استفسارات. وثّق إعدادات الخصوصية لأغراض التدقيق. يضمن ذلك الامتثال للسياسات الداخلية.