المفاهيم
اختر مسار الكلام المناسب حسب حالة الإدخال وتوقيت النتيجة ونوع الخرج.
ابدأ بسؤالين: هل الإدخال صوت أم نص؟ وإذا كان صوتًا، فهل الوحدة كاملة متاحة بالفعل؟ تحدد الإجابتان نموذج المعالجة. تأتي وسيلة النقل وعميل SDK بعد ذلك.
اختر نموذج المعالجة
| نقطة البداية | اختر | السلوك | الحد الفاصل للقرار |
|---|---|---|---|
| تسجيل طويل أو كبير مكتمل | النسخ الدفعي | ارفع مرة واحدة، واستلم jobId، ثم استعلم عن عمل | استخدمه للاجتماعات والبودكاست والأرشيفات وغيرها عندما يكون الاكتمال غير المتزامن مقبولاً. |
| وحدة صوت مكتملة يهم كمونها | النسخ السريع | أرسل وحدة الصوت المشفرة كاملة عبر Socket.IO، ثم استلم أحداث النتائج | استخدمه لعمل كامل الصوت ومحدود النطاق، مثل دور واحد لوكيل أو محادثة. وهو ليس بث صوت مباشر ولا مسار التسجيلات الطويلة. |
| صوت لا يزال يصل | النسخ الفوري | أرسل مقاطع PCM16 واستلم نصًا مؤقتًا ونهائيًا ما دام البث مفتوحًا | استخدمه للمكالمات والترجمات والميكروفونات وخطوط الوسائط المباشرة. |
| حاجة إلى معرفة من تكلم ومتى | تمييز المتحدثين | أنشئ مقاطع زمنية للمتحدثين إلى جانب صوت Batch أو من بث PCM مباشر | أضفه إلى مسار Batch أو Live المطابق؛ فهو لا ينتج النص المنسوخ بنفسه. |
| نص يجب أن يصبح صوتًا | تحويل النص إلى كلام (TTS) | أرسل النص واستلم عينات PCM خام متدفقة | استخدمه عندما يكون الكلام هو الخرج لا الإدخال. |
الحد الحاسم هو حدود الإدخال. يبدأ Batch والنسخ السريع كلاهما بصوت مكتمل؛ ولا تجعل أحداث نتائج Fast الإدخال Realtime. إذا كان الصوت لا يزال يُنتج، فاختر Realtime.
Batch عمل
يعيد إرسال Batch القيمة jobId. استعلم من مسار النتيجة حتى حالة طرفية أو
حتى انتهاء المهلة الكلية للتطبيق.
| الحالة | النوع | قرار التطبيق |
|---|---|---|
queued | غير طرفية | انتظر ثم استعلم مجددًا ضمن المهلة. |
processing | غير طرفية | استمر في الانتظار ضمن المهلة نفسها. |
done | نجاح طرفي | اقرأ النتيجة المكتملة. |
failed | فشل طرفي | أوقف الاستعلام وأظهر فشل العمل. |
cleared | طرفية بلا نتيجة مخزنة | أوقف الاستعلام وعامل النتيجة على أنها غير متاحة. |
لا تعرّف API المنشورة مدة احتفاظ، لذلك لا تصمم اعتمادًا على نافذة مضمونة
لتوفر النتائج. ينجح SDK 0.18.0 عند done، ويرفع خطأ عند failed، ويتوقف
فيما عدا ذلك عند مهلته المضبوطة؛ ويجب على المستعلم المباشر معالجة cleared
بنفسه.
تستخدم قراءة النتيجة القيمة الافتراضية save_result=false. قد تمسح قراءة
done أو failed النهائية الحقول المخزنة بعد بناء استجابتها، ولذلك قد تتبع
الاستجابة المفقودة حالة cleared. اضبط save_result=true قبل الاستعلام عندما
يجب أن يكون تسليم النتيجة النهائية قابلاً للتكرار؛ ولا يحدد ذلك مدة احتفاظ.
نتائج الأحداث حالة وليست سجل نص
تتطور استجابات Fast وRealtime والتمييز. وفّقها حسب معرّف الطلب أو البث بدلاً من إلحاق كل حدث.
| السطح | علامات النتيجة | قاعدة الحالة |
|---|---|---|
| النسخ السريع | id، seq، is_final | عامل الاستجابات غير النهائية كمؤقتة وثبت الاستجابة النهائية مرة واحدة. |
| النسخ الفوري | id، seq، is_final، is_speech_final | استبدل النص المؤقت ما دام علما النهاية false؛ وثبته عندما يصبح أحدهما true. |
| التمييز المباشر | id، final_segments، active_segments، is_final | اجمع الإضافات النهائية غير المشاهدة واستبدل الذيل النشط القابل للمراجعة. |
تتضمن استجابات Fast وRealtime القيمة seq، لكن عقديهما العامين الحاليين لا
يعرّفان لها دلالات ترتيب أو تفرّد. وجّه الأحداث حسب id وعالجها بترتيب الوصول
المرصود، وعامل نص كل حدث وكلماته كحالة ذلك الحدث. لا تنهِ الانتظار إلا عند
إشارة النهاية الخاصة بالقدرة أو خطأ أو مهلة.
يتجاهل RealtimeSubtitles الاستجابات المؤقتة عمدًا ويزيل تكرار الاستجابات
النهائية حسب معرّف البث وseq. ولأن عقد Realtime السلكي الحالي لا يضمن قيم
seq متميزة، فلا تستخدم هذا المساعد لجمع عدة أحداث نهائية. اجمع الكلمات
النهائية بترتيب الوصول المرصود واعرضها باستخدام Subtitles بدلًا منه.
أنهِ الإدخال المباشر بإطار النهاية الموثق، وانتظر إلى مهلة التطبيق فقط، ونظف العميل دائمًا. لا يثبت انتهاء انتظار الإغلاق وصول نتيجة نهائية؛ افحص الحالة التي سجلتها الاستدعاءات.
التمييز خط زمني
ينتج التمييز تسميات متحدثين نسبية عبر الزمن، لا هوية حقيقية. تعرض تحديثات SDK
المباشرة الخط الزمني الموفق في update.segments والإضافات النهائية الجديدة في
update.newlyFinalized / update.newly_finalized. ينتظر إغلاق بث SDK مدة تصل
إلى خمس ثوان، ويعيد أفضل خط زمني معروف إذا لم يصل تحديث نهائي خلالها.
في استجابة Batch V2، تكون final_word_segments وdiarization_segments
منفصلة. إذا احتاج التطبيق كلمات منسوبة إلى متحدثين، فاختر قاعدة تداخل ووثقها
بدلاً من افتراض أن كل كلمة تحتوي speaker بالفعل.
عقود الصوت والنقل
| السطح | عقد الصوت | نقل SDK 0.18.0 |
|---|---|---|
| النسخ الدفعي | حاوية ملف صوت مكتملة ومدعومة | REST |
| النسخ السريع | ملف AAC أو FLAC أو MP3 أو MP4 أو WAV كامل واحد | Socket.IO |
| النسخ الفوري والتمييز المباشر | PCM16 little-endian، بتردد 16 kHz وأحادي القناة | Socket.IO |
| TTS عبر SDK | خرج PCM16 خام little-endian، بتردد 24 kHz وأحادي القناة | Socket.IO |
| TTS المباشر عبر HTTP | تسجيل بروتوكول بلا فواصل مع إطارات خدمة نظرية تحمل PCM16 بتردد 16 kHz؛ وليس صوتًا قابلاً للفك عمومًا | لا غلاف SDK عامًا |
PCM الخام ليس حاوية ملف وسائط. يحتاج مشغل معتاد إلى ترويسة WAV بمعدل العينات
المطابق. يمكن للتكاملات المباشرة أيضًا استخدام عمليات Realtime HTTP المتحقق
منها؛ ولا يغلفها عميل SDK عام في 0.18.0.
الخطوات التالية
تشرح المفاهيم ما الذي تختاره. تعرّف أدلة SDK سلوك العملاء المنشور، وتجمع الوصفات مهام كاملة، وتعرّف OpenAPI وAsyncAPI عقود البروتوكول المباشر.
نفّذ أول طلب
شغّل مسار Batch أو Realtime مختبرًا بعد اختيار نموذج المعالجة.
استخدم عميل SDK
راجع الدوال والخيارات وحقول الاستجابة والمهل وسلوك التنظيف بدقة.
أكمل مهمة
أنشئ نصوصًا منسوبة إلى متحدثين أو ترجمات نهائية أو خرج TTS قابلاً للتشغيل.
تكامل مباشرة
استخدم أدلة النقل، ثم أكد الحقول والإطارات الدقيقة في مراجع API المولدة.