ابن سير عمل متعدد الوسائط باستخدام Rivya API

تكامل Rivya API الجيد ليس مجرد طلب واحد إلى نموذج واحد.

معظم سير العمل الحقيقي في المنتجات يتكون من سلسلة صغيرة: اختر النموذج المناسب، حضر المدخل، ارفع ملفات مرجعية عند الحاجة، أرسل مهمة، راقب الحالة، عالج الأرصدة، ونبه المنتج عندما تصبح النتيجة جاهزة.

تعرض هذه المقالة شكل التخطيط. استخدم البدء السريع مع Rivya API لأقصر مسار قابل للتشغيل، واستخدم وثائق API للحقول الدقيقة في الطلب.

يصف سير العمل أدناه عقد API العام المنفذ. قبل البناء، تأكد من أن الوصول إلى API العام مفعل للنشر والحساب، وأن النموذج المختار جاهز للاستخدام عبر API، وأن الميزات الاختيارية مثل Webhook متاحة فعلا.

ابدأ بلحظة المنتج

قبل اختيار نقاط النهاية، صف لحظة المنتج في جملة واحدة.

أمثلة:

• أنشئ مسودة صورة منتج عندما يرسل بائع موجز قائمة.

• ولّد مفهوم فيديو قصير بعد أن يوافق مدير الحملة على اتجاه صورة ثابتة.

• أرسل جولة محادثة داخل أداة بحث داخلية وابث الاستجابة إلى المستخدم.

• ارفع صورة مرجعية، وأرسل طلب نموذج مدعوما، ونبه المستخدم عندما تصبح النتيجة جاهزة.

هذه الجملة تمنع التكامل من التحول إلى مجموعة فضفاضة من استدعاءات API.

ارسم سير العمل قبل كتابة الكود

استخدم هذا الجدول قبل فتح مخطط الطلب.

يجب أن يكون سير العمل واضحا بما يكفي ليكون لكل منطقة API سبب للوجود.

الخطوة 1: أنشئ مفتاحا لهذا التكامل

أنشئ مفتاح API للتطبيق أو البيئة أو سير العمل المحدد الذي سيستخدمه.

تجنب استخدام مفتاح واحد لكل شيء. تسمية المفاتيح بحسب الغرض تجعل المراجعة اللاحقة أسهل:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

اقرأ مصادقة API قبل تخزين المفتاح. يظهر السر الكامل مرة واحدة فقط، لذلك يجب أن يحفظه فريقك فورا في مخزن أسرار مناسب من جهة الخادم.

الخطوة 2: اختر النماذج من قائمة API العامة

لا تثبت نموذجا في الكود فقط لأنه نجح في اختبار يدوي.

استخدم نماذج API ومرجع API للنماذج لتأكيد:

• معرف النموذج العام

• هل هو متاح عبر API

• وضع الإدخال المدعوم

• توقعات المطالبة والمعلمات

• هل تحتاج إلى واجهة API للملفات

• سلوك الأرصدة وملاحظات الجاهزية

هنا تصبح كثير من التكاملات أنظف. قد يكون النموذج مثاليا لاختبار Studio يدوي، لكنه ليس بالضرورة النموذج الأول الصحيح لتدفق منتج مؤتمت.

الخطوة 3: قرر هل تكون واجهة API للملفات جزءا من النسخة الأولى

إذا كان النموذج يستطيع العمل من إدخال نصي، فأبق النسخة الأولى نصية فقط.

أضف واجهة API للملفات فقط عندما يحتاج سير العمل فعلا إلى وسائط مرجعية.

عندما تحتاجه، عرف:

• أنواع الملفات التي يقبلها المنتج

• من يملك خطوة تنظيف الملفات

• ماذا يحدث عند فشل الرفع

• كيف تمرر بيانات الملف المرتجعة إلى معلمات النموذج

• هل يجب إعادة استخدام الملف نفسه أم رفعه مرة أخرى

هذا يمنع إخفاء تجربة ملفات هشة خلف زر توليد يبدو نظيفا.

الخطوة 4: أرسل مهمة توليد واحدة

لتوليد الصور والفيديو والصوت، النمط المعتاد هو:

1. حضر معرف النموذج، والمطالبة، والمعلمات المدعومة

2. أضف مفتاح عدم التكرار لإعادة المحاولة بأمان

3. أرسل عبر نقطة نهاية التوليد

4. احفظ معرف المهمة العام

5. استعلم عن الحالة حتى تصل المهمة إلى حالة نهائية

استخدم إنشاء عملية توليد لشكل الطلب وحالة التوليد لمعالجة النتائج.

يجب أن يعامل المنتج حالات queued وprocessing وsucceeded وfailed كحالات مفهومة للمستخدم. لا تجعل المستخدمين يقرؤون تفاصيل النظام أو يخمنون لماذا تكون المهمة بطيئة.

الخطوة 5: استخدم واجهة API للمحادثة لنماذج المحادثة

يجب أن تستخدم نماذج المحادثة واجهة API للمحادثة، لا نقطة نهاية التوليد.

هذا مهم لأن عمل المحادثة له سلوك مختلف:

• يمكن أن تنتمي جولات المحادثة إلى جلسات أنشأها API

• التجربة غير المتدفقة وتجربة بث SSE مختلفتان للمستخدم

• تستخدم مرفقات الصور معرفات ملفات من واجهة API للملفات

• تسوية الأرصدة تتبع جولة المحادثة بدلا من مهمة وسائط غير متزامنة عادية

إذا كان منتجك يحتاج إلى إجابة من المساعد داخل واجهته، فقد تكون واجهة API للمحادثة هي المسار الصحيح. أما إذا كان المستخدم لا يزال يستكشف الأفكار، فقد تكون المحادثة في Rivya أو Studio أنسب.

الخطوة 6: ابدأ بالاستعلام، ثم أضف إشعارات Webhook

في النسخة الأولى، يكون الاستعلام الدوري أسهل في الفهم.

إذا كانت ميزة Webhook مفعلة للنشر، فأضف إشعارات Webhook عبر API عندما:

• يكون لدى المنتج كثير من المهام غير المتزامنة

• لا ينبغي للعملاء المنتظرين أن يستعلموا مباشرة

• تحتاج الأنظمة اللاحقة إلى أحداث اكتمال موقعة

• يكون تصميم إعادة المحاولة والتعامل مع التكرارات جاهزا

يجب أن يكون مستقبل الويبهوك بسيطا وصارما: تحقق من التوقيع، واقبل الأحداث الآمنة عند التكرار، وحدث سجل منتج واحدا، وسجل فقط ما يمكن تسجيله بأمان.

الخطوة 7: اجعل الأرصدة مرئية في المنتج

يستخدم Rivya API أرصدة الحساب نفسها التي يستخدمها Studio.

يجب أن يقرر تكاملك مقدار ما سيعرضه من ذلك. على الأقل، يجب أن يعرف الفريق:

• أي حساب يملك مفتاح API

• أي سير عمل يمكن أن يستهلك الأرصدة

• ماذا يحدث عندما تكون الأرصدة منخفضة جدا

• كيف تشرح حالات فشل التوليد

• أين ترسل شخصا لأسئلة الأرصدة والفوترة

استخدم أرصدة API، والأرصدة والفوترة في Rivya، وكيفية فهم أرصدة Rivya وحزمها وخططها لنموذج المحفظة المرئي للمستخدم.

نسخة أولى صغيرة

النسخة الأولى الجيدة تكون محدودة عمدا.

مثلا:

1. مفتاح API واحد

2. نموذج صورة واحد محدد

3. لا رفع ملفات بعد

4. طلب توليد واحد

5. مسار استعلام دوري واحد للحالة

6. معاينة نتيجة بسيطة واحدة داخل منتجك

7. رسالة خطأ أرصدة واضحة واحدة

هذه النسخة تثبت الاتصال قبل إضافة مزيد من الأجزاء المتحركة.

نسخة أكثر اكتمالا

بعد أن تعمل النسخة الأولى، يمكن لسير عمل أكمل أن يضيف:

• واجهة API للملفات للصور أو الفيديوهات المرجعية

• عناصر تحكم خاصة بمعلمات النموذج

• عدم التكرار مرتبطا بسجل منتجك

• إشعارات Webhook موقعة عند الاكتمال عندما تكون هذه الميزة مفعلة

• واجهة API للمحادثة لجولات المساعد

• تدفق أحداث من الخادم عندما تحتاج المحادثة إلى إخراج حي

• عروض إدارية أو دعم للمهام الفاشلة

يجب أن يجيب كل إضافة عن حاجة منتج حقيقية. إذا كانت تجعل العرض التجريبي يبدو أكبر فقط، فاتركها خارج النسخة.

أخطاء التكامل الشائعة

تجنب هذه الأنماط:

• البدء بكل ميزات API في وقت واحد

• إخفاء استخدام الأرصدة عن مالك الحساب

• استخدام افتراضات خاصة بـ Studio داخل تدفق API

• التعامل مع رفع الملفات كفكرة لاحقة

• إعادة محاولة طلبات التوليد من دون عدم تكرار

• استخدام واجهة API للمحادثة لوظائف يجب أن تكون توليدا غير متزامن

• استخدام نقاط نهاية التوليد لجولات المحادثة

• تسجيل مفاتيح API كاملة، أو أسرار الويبهوك، أو تفاصيل ملفات مؤقتة

أكثر سير عمل API أمانا يكون واضحا بشأن الملكية، والحالة، ومعالجة الفشل.

إلى أين تنتقل بعد ذلك

• ابدأ من المطورون لمركز API العام.

• استخدم البدء السريع مع Rivya API لتشغيل أول طلب.

• استخدم نماذج API قبل اختيار معرّفات النماذج.

• استخدم واجهة API للملفات فقط عندما يحتاج النموذج فعلا إلى وسائط مرجعية.

• استخدم واجهة API للمحادثة لجولات المحادثة واستجابات المحادثة المتدفقة.

• استخدم إشعارات Webhook عبر API عندما لا يعود الاستعلام الدوري كافيا وتكون الميزة مفعلة.

• إذا كان سير العمل لا يزال يحتاج إلى استكشاف بشري، فاقرأ متى تستخدم Rivya API بدلا من Studio قبل أتمتته.