توفر مجموعة تطوير البرمجيات (SDK) الخاصة بـ AKOOL للبث المباشر للصور الرمزية (Avatar) الأساس اللازم للتفاعل الفوري عبر الفيديو والصوت والنص والميكروفون. وتتمثل الخطوة التالية في جعل هذه الصورة الرمزية مفيدة لعملك من خلال ربطها بوثائق المنتجات الموثوقة، أو السياسات، أو المواد التدريبية، أو محتوى الدعم.
يركز هذا الدليل على طبقة المعرفة هذه. ستقوم بإنشاء قاعدة معرفية من AKOOL، وربطها بجلسة بث للصور الرمزية باستخدام knowledge_id، والتحقق من أن الصورة الرمزية تقدم إجابات دقيقة ومستندة إلى الحقائق داخل تطبيقك الخاص.
توضح لك وثائق SDK الرسمية كيفية بث صورة رمزية. بينما يوضح لك هذا الدليل كيفية جعل تلك الصورة الرمزية تفهم طبيعة عملك.
ما الذي تقوم ببنائه
تجمع التجربة النهائية بين ثلاثة أجزاء: مصادر المعرفة المعتمدة الخاصة بك، وقاعدة معرفية من AKOOL تجهز تلك المصادر للمحادثة، وصورة رمزية للبث المباشر مدمجة في تطبيقك. عندما يطرح المستخدم سؤالاً، تستخدم الصورة الرمزية قاعدة المعرفة المتصلة كمرجع سياقي وتعود بالإجابة من خلال صوت وفيديو متزامنين.
الرابط بين طبقة المعرفة والجلسة المباشرة هو حقل knowledge_id . يتم إضافته عند إنشاء جلسة بث الصورة الرمزية، قبل أن ينضم المتصفح إلى القناة المباشرة.
تتم معالجة مصادر المعرفة داخل AKOOL ويتم تمثيلها بواسطة knowledge_id. يقوم نظامك الخلفي بتضمين هذا المعرف عند إنشاء جلسة بث الصورة الرمزية. بعد ذلك، ينضم المتصفح إلى الجلسة التي تم إرجاعها من خلال AKOOL SDK، مما يسمح للصورة الرمزية بالإجابة بناءً على المعرفة المعتمدة مع الحفاظ على بيانات الاعتماد على الخادم.
اختر مسار البناء الخاص بك
إذا كنت ترغب في الحصول على نموذج أولي فعال بسرعة، انسخ المطالبة أدناه إلى وكيل برمجة يعمل بالذكاء الاصطناعي. إذا كان لديك بالفعل تكامل لـ AKOOL Streaming Avatar—أو كنت تفضل تهيئة سير العمل بنفسك—فتابع مع "البدء السريع". كلا المسارين يؤديان إلى نفس النتيجة: صورة رمزية مباشرة تكون إجاباتها مستندة إلى المحتوى الخاص بك.
الخيار 1: البناء باستخدام وكيل ذكاء اصطناعي
انسخ هذه المطالبة إلى وكيل البرمجة المفضل لديك الذي يعمل بالذكاء الاصطناعي وقدم تكوين AKOOL الخاص بك عند الطلب.
مطالبة بناء وكيل الذكاء الاصطناعي
Build a knowledge-powered AKOOL Streaming Avatar application.
Use AKOOL’s official Streaming Avatar SDK Quick Start as the implementation reference:
https://docs.akool.com/sdk/jssdk-start
Start from the official SDK workflow instead of recreating a generic streaming demo. Add the following knowledge-base workflow:
1. Create the avatar session from a backend endpoint.
2. Read the Avatar ID, Knowledge Base ID, optional Voice ID, language, and duration from server-side configuration.
3. Include knowledge_id and mode_type: 2 in the session-creation request.
4. Return only the temporary session credentials required by the browser.
5. Use the official AKOOL JavaScript SDK for video, audio, text, microphone, and interruption controls.
6. Add an explicit End Session action.
7. Provide a small test panel for an exact-source question, a paraphrased question, and an out-of-scope question.
Keep the interface simple and use the linked AKOOL documentation as the source of truth.الخيار 2: اتباع دليل البدء السريع
استخدم هذا المسار عندما ترغب في إضافة طبقة المعرفة إلى تطبيق موجود أو فهم عملية التكامل قبل تسليمها إلى وكيل ذكاء اصطناعي.
قبل أن تبدأ
أنت بحاجة إلى حساب AKOOL مع إمكانية الوصول إلى واجهة برمجة التطبيقات (API)، ومعرف بث الصورة الرمزية (Streaming Avatar ID)، وتطبيق بث صور رمزية يعمل بناءً على حزمة تطوير البرمجيات (SDK) الرسمية بلغة JavaScript. يمكنك إنشاء أو إدارة صورة رمزية للبث (Streaming Avatar) في AKOOL. جهّز المستندات أو روابط URL العامة التي يجب أن تستخدمها الصورة الرمزية. معرف الصوت (Voice ID) اختياري.
إذا لم تقم بالاتصال بـ Streaming Avatar بعد، أكمل دليل البدء السريع لـ Streaming Avatar SDK أولاً. لا تكرر هذه المقالة عمداً خطوات التثبيت أو الاتصال بالقناة أو معالجة الوسائط.
الخطوة 1: تجهيز مصادر المعرفة
قم بتحميل المستندات المدعومة أو أضف روابط URL عامة. لإجراء اختبار أولي بسيط، يُعد ملف DOCX منظم وبسيط نقطة بداية عملية. اجعل كل مصدر يركز على موضوع واحد حتى تتمكن قاعدة المعرفة من استرجاع المقطع الصحيح بشكل موثوق.
ابدأ بمجموعة مصادر صغيرة وموثوقة ونطاق اختبار محدود. بعد أن تقدم الأسئلة الأولى إجابات دقيقة، أضف المزيد من المستندات أو الروابط في دفعات محكومة وأعد الاختبار.
الخطوة 2: إنشاء قاعدة معرفة AKOOL
أكمل حقول الإعداد الأساسية: اسم واضح، وعبارة افتتاحية (المقدمة في واجهة برمجة التطبيقات)، ومطالبة توجيهية، والمستندات المدعومة أو روابط URL العامة التي تريد من AKOOL استخدامها كمصادر.
العبارة الافتتاحية (المقدمة): اكتب الرسالة الأولى التي يجب أن تقولها الصورة الرمزية عند بدء الجلسة. اجعلها قصيرة ومرحبة ومتوافقة مع نطاق قاعدة المعرفة.
المطالبة (Prompt): "أجب على الأسئلة باستخدام مصادر المعرفة المعتمدة. كن موجزاً ومفيداً. إذا كانت المعلومات غير متوفرة، اذكر ذلك بوضوح واقترح خطوة الدعم التالية."
انتظر حتى تنتهي المصادر من المعالجة، ثم انسخ معرف قاعدة المعرفة (Knowledge Base ID). يستخدم AKOOL هذه القيمة كـ knowledge_id للجلسة المباشرة.
الخطوة 3: ربط قاعدة المعرفة بالجلسة
عندما يقوم نظامك الخلفي (Backend) بإنشاء جلسة الصورة الرمزية المتدفقة (Streaming Avatar)، أضف معرف قاعدة المعرفة (Knowledge Base ID) إلى الطلب. استخدم وضع الحوار حتى يتمكن الصورة الرمزية من الإجابة على الأسئلة ومواصلة المحادثة.
مثال على إعداد الجلسة
{
"avatar_id": "your_avatar_id",
"voice_id": "your_voice_id",
"knowledge_id": "your_knowledge_id",
"mode_type": 2
}التفصيل المهم هو متى يحدث هذا: knowledge_id ينتمي إلى مرحلة إنشاء الجلسة، وليس إلى joinChat() في المتصفح. بمجرد إنشاء الجلسة، يمكن للمتصفح الاتصال باستخدام بيانات الاعتماد المؤقتة التي تعيدها AKOOL واستخدام تدفق التفاعل القياسي الخاص بـ SDK.
قم بإنشاء الجلسة من نظامك الخلفي، وليس مباشرة في المتصفح، لضمان بقاء مفتاح واجهة برمجة التطبيقات (API key) خاصاً. يرسل مثال cURL هذا معرف قاعدة المعرفة عند إنشاء الجلسة ويُفعّل وضع الحوار باستخدام mode_type: 2.
إنشاء جلسة صورة رمزية متدفقة مدعومة بقاعدة معرفة
curl --request POST \
--url https://openapi.akool.com/api/open/v4/liveAvatar/session/create \
--header "Content-Type: application/json" \
--header "x-api-key: <api-key>" \
--data '{
"avatar_id": "<avatar-id>",
"voice_id": "<voice-id>",
"language": "en",
"duration": 600,
"mode_type": 2,
"knowledge_id": "<knowledge-id>",
"stream_type": "agora"
}'قم بتخزين بيانات اعتماد الجلسة التي تم إرجاعها على الخادم، ومرر فقط قيم الانضمام المطلوبة إلى عميلك، واستخدمها لتهيئة SDK الخاص بـ AKOOL Streaming Avatar.
الخطوة 4: إضافة الصورة الرمزية إلى تطبيقك
استخدم JavaScript SDK الخاص بـ AKOOL للانضمام إلى القناة في الوقت الفعلي، وبدء الدردشة في وضع الحوار، وعرض الفيديو والصوت عن بُعد، وإرسال النصوص أو مدخلات الميكروفون. هذا الجزء مطابق تماماً لدليل البدء السريع الرسمي لـ SDK؛ أما عملك الخاص بالتطبيق فيتمثل في تحديد مكان ظهور الصورة الرمزية وكيفية بدء المستخدمين للمحادثة ومقاطعتها وإنهائها.
احتفظ بإعدادات المعرفة في مسار إنشاء الجلسة. يتيح ذلك لنفس الواجهة الأمامية دعم منتجات أو مناطق أو جماهير مختلفة عن طريق اختيار معرف قاعدة معرفة معتمد مختلف على النظام الخلفي.
الخطوة 5: التحقق من الإجابات المستندة إلى المعرفة
لا تتوقف بعد اتصال الصورة الرمزية بنجاح. تأكد من أنها تستخدم المعرفة المقصودة بالفعل وتستجيب بشكل مناسب عندما تكون الإجابة غير متوفرة.
استكشاف أخطاء قاعدة المعرفة الشائعة وإصلاحها
الصورة الرمزية تتجاهل قاعدة المعرفة. تأكد من تضمين knowledge_id الصحيح في طلب إنشاء الجلسة. يمكن أن توجد قاعدة المعرفة في لوحة التحكم دون أن تكون مرتبطة بجلسة الصورة الرمزية المتدفقة النشطة.
لم يتم العثور على محتوى قاعدة المعرفة. تأكد من اكتمال معالجة جميع الملفات المرفوعة أو روابط URL العامة قبل البدء بالاختبار. إذا كانت المعالجة لا تزال معلقة أو فشلت، فلن يكون المحتوى متاحاً للاسترجاع بعد.
الإجابات غير متسقة. احذف المواد المصدرية القديمة أو المكررة أو المتضاربة. احتفظ بنسخة مرجعية واحدة لكل معلومة، واستخدم عناوين واضحة، وأعد الاختبار بأسئلة مباشرة تظهر إجاباتها بوضوح في المصادر.
الجلسة تعمل، لكن الحوار لا يعمل. تحقق من إنشاء الجلسة باستخدام mode_type: 2. ثم تأكد من أن حزمة تطوير البرمجيات (SDK) تنضم إلى نفس الجلسة التي أرجعها نظامك الخلفي، وأن إعدادات الصورة الرمزية (Avatar) والصوت واللغة والجلسة صالحة. إذا قمت بإنشاء جلسة بديلة أثناء تصحيح الأخطاء، فتأكد من أن العميل لا يزال يستخدم بيانات اعتماد منتهية الصلاحية من استجابة سابقة.
حالات الاستخدام
دعم العملاء. اسمح للزوار بطرح أسئلة حول المنتجات، أو الإعداد، أو الضمان، أو السياسات من خلال واجهة أكثر طبيعية من بحث مركز المساعدة التقليدي.
اكتشاف المنتجات. وجه العملاء المحتملين عبر الميزات والخطط وسير العمل الموصى به باستخدام محتوى المبيعات والمنتجات المعتمد.
تدريب الموظفين. حول أدلة التوجيه والإجراءات الداخلية إلى مساعد تدريب تفاعلي.
التعليم والفعاليات. امنح المتعلمين أو الحضور مقدم عرض حي يمكنه الإجابة على الأسئلة من مواد الدورة التدريبية، أو ملاحظات المتحدث، أو موارد الفعالية.
قائمة التحقق للإطلاق
☐ مصادر المعرفة محدثة وموثوقة وتمت معالجتها بالكامل.
☐ تم تضمين knowledge_id المقصود عند إنشاء الجلسة.
☐ تم اختبار الأسئلة المباشرة، وإعادة الصياغة، والأسئلة الخارجة عن النطاق، وأسئلة المتابعة.
☐ يوفر التطبيق عناصر تحكم واضحة لبدء الجلسة، وإيقافها مؤقتاً، وإنهاؤها.
☐ تم اختبار التجربة النهائية باستخدام كل من المدخلات النصية ومدخلات الميكروفون.
الموارد
- قاعدة معرفة AKOOL
- إنشاء جلسة أفاتار للبث المباشر
- دليل البدء السريع لـ Streaming Avatar SDK
- أفضل الممارسات لاستخدام حزمة تطوير برمجيات (SDK) الأفاتار للبث المباشر
الأسئلة الشائعة
ما هو knowledge_id في AKOOL Streaming Avatar؟
knowledge_id هو المعرف الخاص بقاعدة معرفة AKOOL. تؤدي إضافته إلى جلسة Streaming Avatar إلى إخبار AKOOL بالمستندات وعناوين URL التي تمت معالجتها والتي يجب أن يستخدمها الأفاتار عند الإجابة على الأسئلة المستندة إلى المعرفة.
متى يجب أن أضيف knowledge_id إلى جلسة Streaming Avatar؟
أضفه أثناء إنشاء الجلسة على الواجهة الخلفية (backend) الخاصة بك، قبل أن ينضم المتصفح إلى الجلسة. يضمن هذا ربط قاعدة المعرفة منذ البداية ويجنبك كشف مفتاح واجهة برمجة تطبيقات AKOOL الخاص بك في كود جانب العميل.
ما هي أنواع الملفات التي يمكن لقاعدة معرفة AKOOL استخدامها؟
تدعم مستندات AKOOL ملفات PDF وDOC وDOCX وTXT وMD وJSON وXML وCSV. يمكنك أيضاً إضافة عناوين URL عامة. استخدم مصادر نظيفة وحديثة ذات عناوين وصفية، وانتظر حتى تنتهي المعالجة قبل اختبار الاسترجاع.
هل يمكنني توصيل نموذج لغوي كبير (LLM) خارجي أو قاعدة معرفة RAG مباشرة؟
تستخدم سير عمل Streaming Avatar الموثق قاعدة معرفة AKOOL: أضف المستندات أو عناوين URL، واحصل على الـ knowledge_idالخاص بها، وقم بتضمين ذلك المعرف عند إنشاء الجلسة. لا تفترض أنه يمكن ربط قاعدة بيانات متجهة خارجية أو خدمة RAG بشكل مباشر ما لم تقم بتصميم والتحقق من صحة تكامل منفصل على مستوى التطبيق.
