كيف تدمج OpenAI API في تطبيقك

لدمج OpenAI API، أنشئ مفتاح API داخل مشروع في OpenAI، وخزّنه كـسر على الخادم باسم OPENAI_API_KEY، واستدعِ الواجهة من مسار على خادمك باستخدام حزمة OpenAI الرسمية، وليس من كود المتصفح أبدًا. حسب دليل البدء السريع لدى OpenAI في سبتمبر 2026، تُقدَّم Responses API كنقطة البداية للمشاريع الجديدة. اضبط حد إنفاق قبل الإطلاق، وحدّد طول الرد، واحصر عدد مرات استخدام الميزة لكل مستخدم، وتعامل مع أخطاء حد المعدل بإعادة المحاولة.

يغطي هذا الدليل الإعداد، وتدفق الطلب، وتعليمات لأداة البناء بالذكاء الاصطناعي، والأخطاء التي تكشف المفاتيح أو تستنزف المال. تفاصيل OpenAI مأخوذة من وثائقها الرسمية حتى سبتمبر 2026. لفهم المفاهيم العامة (الرموز، ونوافذ السياق، والتسعير) اقرأ كيف تستخدم واجهات LLM البرمجية أولًا.

ما الذي يمكنك بناؤه به

• مساعد دردشة داخل تطبيقك (كيف تبني تطبيق دردشة بالذكاء الاصطناعي)
• أزرار «لخّص هذا» أو «أعد صياغة هذا» أو «اكتب ردًا»
• استخراج بيانات منظمة من نص حر: تحويل بريد إلكتروني إلى طلب، أو تصنيف تذاكر الدعم
• البحث والإجابة عن الأسئلة من محتواك الخاص
• ميزات الوسائط كتوليد الصور والكلام، حسب النماذج المتاحة

مزيد من الأفكار موجودة في كيف تضيف ميزات الذكاء الاصطناعي إلى تطبيقك.

إعداد حسابك في OpenAI

1. أنشئ حسابًا ومشروعًا في منصة OpenAI. توصي أفضل ممارسات الإنتاج لدى OpenAI بـمشاريع منفصلة للتجهيز (staging) والإنتاج، حتى يكون لكل منها مفاتيحه وحدوده الخاصة.
2. أنشئ مفتاح API للمشروع. توصي OpenAI بضبط تاريخ انتهاء وتدوير المفاتيح بانتظام.
3. اضبط تنبيهات الإنفاق وحدًا صارمًا للإنفاق من صفحة الحدود. يوضح دليل OpenAI أن التنبيهات تُرسل إليك عند تجاوز الاستخدام مبلغًا معينًا، وأن الحد الصارم يفرض سقفًا شهريًا.
4. أضف طريقة الدفع. تصف وثائق حدود المعدل لدى OpenAI مستويات استخدام: ترتفع حدودك تلقائيًا مع زيادة إنفاقك بمرور الوقت.

تدفق الطلب

المتصفح  ->  مسار خادمك  ->  OpenAI API
         <-  (رد مُبثّ)  <-

1. يضغط المستخدم على زر أو يرسل رسالة.
2. يستدعي المتصفح مسار خادمك أنت، مثل POST /api/summarise.
3. يتحقق خادمك من أن المستخدم مسجّل الدخول ومسموح له باستخدام الميزة.
4. يبني الخادم الطلب: التعليمات، ومدخلات المستخدم، وأي بيانات من قاعدة بياناتك تحتاجها المهمة.
5. يستدعي OpenAI بالمفتاح من متغيرات البيئة. وتقرأ حزم OpenAI الرسمية OPENAI_API_KEY تلقائيًا.
6. يبث الرد أو يعيده، ويسجّل استهلاك الرموز.

حزمة OpenAI الرسمية اسمها openai لكل من JavaScript/TypeScript (npm) وPython (pip).

اختيار النموذج

تقدم OpenAI عدة نماذج بأسعار وسرعات مختلفة، وتتغير التشكيلة كثيرًا. ابدأ بنموذج أصغر وأرخص، وقِس الجودة على أمثلة حقيقية، ولا تنتقل إلى نموذج أكبر إلا إذا احتجت إلى ذلك. احتفظ باسم النموذج في قيمة إعدادات أو سر حتى تستطيع تغييره دون إعادة كتابة الكود. راجع صفحة التسعير لدى OpenAI للاطلاع على الأسعار الحالية.

الخيارات والمفاضلات

تعليمات لأداة البناء بالذكاء الاصطناعي

ميزة أولى:

أضف زر «لخّص» في صفحة التذكرة. يستدعي مسار خادم POST /api/summarise يتحقق من أن المستخدم مسجّل الدخول، ويحمّل التذكرة، ويستدعي OpenAI Responses API باستخدام حزمة openai الرسمية والسر OPENAI_API_KEY. اقرأ اسم النموذج من السر OPENAI_MODEL. التعليمات: «لخّص في 3 نقاط، ثم اقترح ردًا قصيرًا. لا تخترع أرقام طلبات.» حدد طول المخرجات، وابث الرد إلى الصفحة، ولا ترسل المفتاح إلى المتصفح أبدًا.

الضوابط:

حدّد كل مستخدم بـ30 طلب ذكاء اصطناعي في الساعة، مخزنًا في قاعدة البيانات. سجّل رموز الإدخال والإخراج لكل طلب مع معرّف المستخدم واسم الميزة. إذا أعادت OpenAI الخطأ 429، فاحترم ترويسة Retry-After، وأعد المحاولة بتأخير متزايد وعشوائية (jitter) حتى 3 مرات؛ وبعد ذلك اعرض «الذكاء الاصطناعي مشغول، حاول مرة أخرى بعد دقيقة». اعرض رسالة خطأ ودية لأي فشل آخر، وأبقِ بقية الصفحة تعمل.

التعامل مع الأخطاء والحدود

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

خطط أيضًا لـ:

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

أخطاء شائعة

• المفتاح في الواجهة الأمامية أو في المستودع. كود المتصفح عام، ويمكن إساءة استخدام المفتاح المسرّب خلال دقائق. انظر كيف تحافظ على أمان مفاتيح API.
• عدم وجود حد للإنفاق. حلقة تكرار أو مستخدم مسيء يمكن أن يشغّل فاتورة كبيرة بسرعة.
• عدم وجود حدود لكل مستخدم. حد المزود يحمي محفظتك، لا بقية مستخدميك.
• الثقة بالتعليمات للأمان. يستطيع المستخدمون كتابة «تجاهل التعليمات السابقة». الصلاحيات تنتمي إلى كود الخادم.
• إرسال أكثر مما يلزم. المستندات الكاملة والمحادثات الطويلة تضاعف التكلفة. أرسل ما تحتاجه المهمة فقط.
• تثبيت اسم النموذج في الكود. النماذج تُحدَّث وتُسحب؛ اجعله إعدادًا.
• إرسال بيانات شخصية دون تفكير. اقرأ شروط استخدام البيانات لدى OpenAI، وأرسل ما تحتاجه الميزة فقط.

قائمة التحقق

• مشاريع OpenAI منفصلة (أو مفاتيح منفصلة) للاختبار والإنتاج
• المفتاح مخزّن كسر على الخادم، وليس في كود المتصفح أو المستودع
• تنبيهات الإنفاق وحد صارم للإنفاق مضبوطان
• كل الاستدعاءات تمر عبر خادمك وتتحقق من صلاحيات المستخدم
• طول المخرجات محدود، واسم النموذج قابل للضبط
• حد معدل لكل مستخدم في تطبيقك
• التعامل مع 429 باستخدام Retry-After والتأخير المتزايد والعشوائية
• حالة خطأ ودية؛ والصفحة تعمل بدون الذكاء الاصطناعي
• تسجيل استهلاك الرموز لكل ميزة
• تم الاختبار بمدخلات طويلة وفارغة ومعادية

استخدام OpenAI API في Mythex

ميزات الذكاء الاصطناعي في التطبيقات التي تبنيها على Mythex تستخدم مفتاح OpenAI الخاص بك، وتُحتسب على حساب OpenAI الخاص بك، لا على أرصدة بناء Mythex. أضف OPENAI_API_KEY كسر للمشروع عبر /secrets أو إعدادات المشروع أو بطاقة الأسرار التي يعرضها الوكيل عندما يحتاج إلى مفتاح، ثم صف الميزة بتعليمات مشابهة لما سبق. بعد تغيير الأسرار في تطبيق منشور، أعد النشر حتى يلتقطها. يقدم دليل إضافة ميزات الذكاء الاصطناعي بمفاتيح API الخاصة بك تعليمات بداية، ويشرح الأسرار في المحادثة بطاقة الأسرار. وإذا كنت تقارن بين المزودين؟ راجع كيف تدمج Claude API.

الأسئلة