أسهل خطأ هو التعامل مع Rivya API وRivya Studio كمسارين متنافسين.
الأدق أن تفهمهما كمرحلتين من المنتج نفسه. Studio هو المكان الذي يستكشف فيه الأشخاص، ويختارون، ويراجعون، ويتابعون العمل بصريا. أما API فهو المكان الذي يتحول فيه سير عمل مستقر إلى جزء من منتج آخر، أو سكربت، أو عملية خلفية.
إذا كنت ما زلت تتعرف إلى سطح API، فابدأ بقراءة ما هو Rivya API؟. هذه الصفحة أضيق نطاقا: كيف تقرر ما إذا كانت مهمة محددة تنتمي إلى Studio أم إلى API.
القرار في جدول واحد
| السؤال | استخدم Studio عندما... | استخدم API عندما... |
|---|---|---|
| هل ما زال الناتج استكشافيا؟ | نعم | لا، سير العمل أصبح قابلا للتكرار |
| هل يحتاج شخص إلى مقارنة النتائج؟ | نعم | فقط بعد أن يستقبل تطبيقك النتائج |
| هل اختيار النموذج مستقر؟ | ليس بعد | نعم، أو يتم اختياره من قائمة نماذج API |
| هل تحتاج المهمة إلى وسائط مرجعية؟ | ما زال شخص يجهزها | يستطيع تطبيقك رفعها عبر Files API |
| هل يجب أن تحدث النتيجة نظاما آخر؟ | ليس بعد | نعم، عبر polling أو webhooks |
| هل يجب أن يبقى استخدام الرصيد مرئيا؟ | نعم، أثناء الاختبار | نعم، لكن عبر ضوابط API على مستوى الحساب |
هذا لا يتعلق بأي واجهة أكثر تقدما. بل يتعلق بما إذا كانت المهمة جاهزة للأتمتة.
استخدم Studio بينما لا يزال العمل يتغير
Studio هو المكان الصحيح عندما يبقى القرار البشري هو العمل الأساسي.
يشمل ذلك:
- الاختيار بين نماذج الصورة أو الفيديو أو الصوت أو المحادثة
- اختبار ما إذا كان اتجاه المطالبة يستحق الاحتفاظ به
- مقارنة النتائج البصرية جنبا إلى جنب
- تقرير ما إذا كانت الوسائط المرجعية تساعد أم تضر
- استخدام السجل المحفوظ للمتابعة من نتيجة سابقة
هذا صحيح خصوصا في العمل الإبداعي. إذا لم يكن الموجز مستقرا، فإن أتمتة الطلب تجعل الارتباك أسرع غالبا، لا أصغر.
استخدم API عندما يكون سير العمل قابلا للتكرار
يصبح API المسار الأفضل عندما تكون المدخلات والخطوات التالية قابلة للتنبؤ بما يكفي.
علامات جيدة:
- منتجك يعرف مسبقا النموذج أو فئة النماذج التي يحتاجها
- يمكن تحويل مدخلات المستخدم إلى request body مستقر
- تستطيع مهمة خلفية polling للحالة دون أن يراقب شخص شاشة
- يستطيع webhook تحديث السجل الصحيح عند انتهاء المهمة
- يستطيع التطبيق شرح استخدام الرصيد للفريق أو مالك الحساب
عند هذه النقطة، قد يصبح استخدام Studio لكل تشغيل هو المسار الأبطأ. يسمح API لمنتجك ببدء المهمة مباشرة.
حد عملي: الاكتشاف مقابل التكامل
استخدم Studio للاكتشاف.
واستخدم API للتكامل.
الاكتشاف يعني:
- "أي نموذج يجب أن نستخدم؟"
- "ما شكل المطالبة الذي ينجح؟"
- "هل تحسن الوسائط المرجعية هذه المهمة؟"
- "هل جودة الناتج كافية لحالة الاستخدام هذه؟"
التكامل يعني:
- "يجب أن ينشئ هذا الإجراء من المستخدم مهمة توليد واحدة."
- "يجب إعادة محاولة هذه المهمة idempotently."
- "يجب رفع هذا الملف وإرفاقه بطلب النموذج."
- "يجب أن تحدث هذه المهمة المكتملة سجل المنتج لدينا."
هذا الحد يمنع API من التحول إلى سطح تجارب مخفي.
كيف يجب أن يؤثر الرصيد في القرار
يستخدم كل من Studio وAPI رصيد حساب Rivya نفسه.
يعني ذلك أن سلوك الرصيد يجب أن يكون جزءا من تصميم المنتج، لا فكرة لاحقة.
استخدم Studio أولا عندما لا يزال الفريق يحتاج إلى فهم شكل التكلفة. واستخدم API عندما تصبح المهمة مستقرة بما يكفي ليشرح المنتج متى قد يتم حجز الرصيد أو استهلاكه.
للقواعد العامة الحالية، اقرأ رصيد API. إذا كان سير العمل مكلفا إلى درجة يصعب شرحها لمالك الحساب، فهو ليس جاهزا بعد لأتمتة API.
أين تغير الملفات الاختيار
غالبا ما تكون الوسائط المرجعية هي النقطة التي يصبح فيها التكامل أكثر جدية.
في Studio، يمكن لشخص أن يرفع الملف، ويفحصه، ويعيد المحاولة، ويقرر ما إذا كان الملف جيدا بما يكفي. في API، يجب أن يتعامل منتجك مع مسار الملف بعناية عبر Files API.
استخدم Studio عندما:
- ما زالت الصورة أو الفيديو أو الصوت المرجعي يحتاج إلى تنظيف بشري
- لا يعرف الفريق أي مرجع يجب أن يوجه النموذج
- قواعد الملف ليست واضحة بعد للمستخدم
استخدم API عندما:
- يستطيع التطبيق جمع الملف بأمان
- متطلبات النموذج للمرجع معروفة
- يمكن رفع الملف قبل طلب التوليد أو المحادثة
- يمكن عرض الأخطاء داخل منتجك دون إخفاء ما حدث
Files API جسر مفيد، لكنه لا يزيل الحاجة إلى تصميم تجربة الملفات.
أين تغير المحادثة الاختيار
يمكن أن تكون المحادثة في أي من الجانبين.
استخدم Rivya Chat مباشرة عندما يستكشف شخص، أو يكتب، أو يراجع، أو يقرر.
واستخدم Chat API عندما يجب أن تعيش دورة المحادثة داخل منتجك أو سير عمل الخادم لديك. قد يشمل ذلك دورات غير متدفقة، أو تدفق SSE اختياريا، أو جلسات ينشئها API، أو مرفقات ملفات مدعومة.
السؤال الأساسي هو: أين يجب أن تعيش المحادثة؟ إذا كانت المحادثة جزءا من عمل Rivya، فاستخدم Rivya. وإذا كانت جزءا من تجربة منتجك، فاستخدم API.
متى تكون Webhooks إشارة
إذا كان سير العمل يحتاج إلى API Webhooks، فهو غالبا تجاوز مرحلة Studio اليدوية.
تفيد Webhooks عندما يحتاج نظام آخر إلى الاستجابة لمهام توليد مكتملة:
- وضع علامة أن الأصل جاهز
- إخطار مستخدم
- دفع خطوة مراجعة إلى الأمام
- نقل مهمة فاشلة إلى الدعم أو منطق إعادة المحاولة
هذا عمل تكامل. قد يبقى Studio مفيدا لاختبار مسار النموذج، لكن حلقة الإنتاج تنتمي إلى API.
نمط انتقال آمن
لا تنقل سير عمل كاملا إلى API دفعة واحدة.
استخدم هذا التسلسل:
- اختبر المهمة يدويا في Studio
- اكتب النموذج المستقر، وشكل المطالبة، وملفات الإدخال، والنتيجة المتوقعة
- اقرأ نماذج API ومرجع النموذج
- أرسل عملية توليد واحدة عبر دليل البدء السريع لـ API
- أضف Files API فقط إذا كان النموذج يتطلب وسائط مرجعية
- أضف Webhooks فقط بعد أن يعمل polling
- أضف Chat API فقط إذا كان المنتج يحتاج إلى دورات محادثة خارج Studio
يجب أن تجعل كل خطوة سير العمل أسهل في التشغيل، لا أكثر أتمتة فقط.
متى تبقى في Studio
ابق في Studio عندما ما زالت المهمة تحتاج إلى:
- مراجعة ذاتية الحكم
- تشكيل المطالبة
- مقارنة بصرية
- استكشاف النماذج
- سجل إبداعي محفوظ
- شخص يقرر هل الخطوة التالية صورة أم فيديو أم صوت أم محادثة
هذا ليس ضعفا. Studio مصمم لتلك المرحلة.
متى تنتقل إلى API
انتقل إلى API عندما:
- تتكرر المهمة نفسها كثيرا
- يمكن تنظيم المدخلات
- النموذج معروف
- يحتاج التطبيق إلى إنشاء مهام من واجهته الخاصة
- يمكن التعامل مع الحالة، والأخطاء، والرصيد بوضوح
- يناسب polling أو webhooks الواجهة الخلفية للمنتج
تكون API في أقوى حالاتها عندما تحول سير عمل Rivya مفهوما بالفعل إلى إجراء موثوق داخل المنتج.
الخطوة التالية في Rivya
- استخدم Developers لمعاينة سطح API.
- اقرأ دليل البدء السريع لـ Rivya API قبل كتابة كود الإنتاج.
- اقرأ مصادقة API قبل تخزين مفتاح API.
- اقرأ كيف تبني سير عمل AI متعدد الوسائط باستخدام Rivya API إذا كان السؤال التالي هو كيفية وصل النماذج، والملفات، والمحادثة، وwebhooks.
- استخدم نقل العمل عبر Rivya Chat وImage وVideo وAudio إذا كان المشروع ما زال ينتمي إلى عمل Studio بقيادة بشرية.
