المفاهيم
اختر سير عمل HUMAIN Voice وتنسيق الصوت المناسبين لمدخلاتك، وتعرّف على سلوك مهام النسخ الدفعي ونتائج البث والخطوط الزمنية للمتحدثين وخرج الكلام.
اختر سير العمل
| سير العمل | استخدمه عندما | الإدخال | كيف تصل النتائج |
|---|---|---|---|
| النسخ الدفعي | يكون التسجيل موجودًا بالفعل: اجتماعات ومكالمات وبودكاست وأرشيفات. | ملف صوت كامل واحد عبر REST. | يعيد الإرسال jobId؛ استعلم دوريًا حتى تبلغ المهمة حالة طرفية. |
| النسخ السريع | لديك مقطع قصير كامل واحد وتحتاج النص بسرعة، مثل أمر صوتي منتهٍ أو دور محادثة. | ملف صوت كامل واحد عبر Socket.IO أو بث HTTP. | صفر نتيجة مؤقتة أو أكثر، ثم نتيجة واحدة بـis_final: true. |
| النسخ الفوري | لا يزال الصوت يصل: ميكروفون أو مكالمة هاتفية أو تسميات توضيحية مباشرة. | قطع PCM خام عبر Socket.IO أو بث HTTP. | نص مؤقت يُستبدل أثناء الكلام، ونتيجة نهائية عند كل نهاية كلام، وis_final: true عند انتهاء التدفق. |
| التمييز المباشر | تحتاج معرفة من يتحدث بينما لا يزال الصوت يصل. يعيد مقاطع المتحدثين لا النص. | قطع PCM خام عبر Socket.IO أو بث HTTP. | قائمة متنامية من مقاطع المتحدثين النهائية مع ذيل نشط قابل للمراجعة، حتى is_final: true. |
| تحويل النص إلى كلام (TTS) | الكلام هو الخرج والنص هو الإدخال. | نص ونموذج وصوت عبر Socket.IO أو بث HTTP أو POST مخزَّن واحد (واجهة OpenAI المتوافقة). | قطع صوت؛ وتُعلَّم القطعة الأخيرة بأنها نهائية. ويعيد POST المخزَّن ملفًا كاملًا واحدًا. |
| Voice Agent | تريد محادثة منطوقة: يتحدث المستخدم ويجيبه وكيل مستضاف. | ميكروفون المستخدم، من متصفح أو تطبيق عبر WebRTC. | ردود منطوقة ونصوص منسوخة مباشرة واستدعاءات أدوات حتى تنتهي المكالمة؛ راجع Voice Agent. |
إذا كان الصوت موجودًا بالفعل فاستخدم النسخ الدفعي؛ واستخدم النسخ السريع فقط لمقطع قصير كامل واحد يهمك فيه زمن الاستجابة (يقبل النسخ السريع حتى 30 دقيقة، لكن استخدمه لدور واحد؛ راجع الحدود). حدود الحجم والمدة لكل سير عمل في الحدود، وقيم اللغة والنموذج والصوت لكل سير عمل في النماذج والأصوات.
للحصول على النص والمتحدثين معًا مباشرة، فعّل علامة التمييز (البت 2 في بايت العلامات في الإطار) على تدفق نسخ فوري مباشر عبر Socket.IO؛ لا يعرض SDK 0.18.1 هذه العلامة (راجع واجهة Socket.IO). أو شغّل النسخ الفوري والتمييز المباشر على الصوت نفسه وطابق بينهما بالزمن.
تنسيقات الصوت حسب سير العمل
| سير العمل | تنسيق الصوت |
|---|---|
| النسخ الدفعي | ملف صوت كامل واحد بأي تنسيق يستطيع ffmpeg فك ترميزه. تعيد الملفات غير المدعومة أو التالفة أو الفارغة الخطأ 422. |
| النسخ السريع | ملف AAC (ADTS) أو FLAC أو MP3 أو MP4 أو WAV كامل واحد. تكتشف الخدمة التنسيق من البايتات لا من اسم الملف. ضع عنصر MP4 المسمى moov في بداية الملف. |
| النسخ الفوري والتمييز المباشر | PCM16 خام little-endian بتردد 16 kHz وأحادي القناة، بلا ترويسة WAV. |
| خرج TTS من SDK | PCM16 خام little-endian بتردد 24 kHz وأحادي القناة، بلا ترويسة WAV. |
| خرج TTS عبر بث HTTP | PCM16 بتردد 16 kHz ملفوف في إطارات الخدمة التي لا يستطيع العميل تقسيمها بموثوقية. استخدم SDK أو POST /v1/audio/speech لملف كامل واحد عندما تحتاج صوتًا قابلًا للتشغيل. |
لتحويل تسجيل إلى PCM للنسخ الفوري، بما في ذلك صوت الهاتف بتردد 8 kHz الذي يجب أن يصبح 16 kHz،
استخدم أمر ffmpeg في النسخ الفوري. ولتشغيل خرج TTS أو
مشاركته، أضف ترويسة WAV بمعدل العينات المطابق؛ راجع
تحويل النص إلى كلام: الحفظ أو البث.
النسخ الدفعي مهمة
يُنشئ إرسال ملف مهمة. استعلم عنها دوريًا بمهلة لكل طلب وموعد نهائي واحد للمهمة كلها.
| الحالة | طرفية | الإجراء |
|---|---|---|
queued | لا | انتظر ثم استعلم مرة أخرى. |
processing | لا | واصل الاستعلام ضمن الموعد النهائي نفسه. |
done | نعم | اقرأ النص المنسوخ وأي نتائج للمتحدثين. |
failed | نعم | توقف عن الاستعلام وأبلغ عن الفشل. |
cleared | نعم | توقف عن الاستعلام. النتيجة المخزنة اختفت ولا يمكن قراءتها مرة أخرى. |
تعيد الحالات الخمس كلها HTTP 200؛ والاستجابة غير 2xx خطأ في الطلب أو المصادقة أو الخادم،
وتجدها في رموز الأخطاء. افتراضيًا قد تحذف القراءة
الطرفية النتيجة المخزنة، فتعيد القراءة الثانية cleared؛ اضبط
save_result=true إذا قد تحتاج إلى قراءتها مرة أخرى. راجع واجهة REST للنسخ الدفعي.
نتائج البث حالة وليست سجلاً
يرسل النسخ السريع والنسخ الفوري والتمييز المباشر نتائج تتغير. تعامل مع كل نتيجة على أنها الحالة الحالية لطلب أو تدفق، واستبدل الحالة السابقة بدل إلحاق كل حدث.
| العلامة | المعنى | الإجراء |
|---|---|---|
is_final يساوي false (في النسخ الفوري: وis_speech_final يساوي false) | مؤقتة. قد يتغير النص. | استبدل النص المؤقت السابق لذلك id. |
is_speech_final: true وis_final يساوي false | توقف المتحدث؛ نص هذا المقطع نهائي. في النسخ الفوري فقط. | ثبّت النص وأبقِ التدفق مفتوحًا. |
is_final: true | آخر نتيجة للطلب أو التدفق. | ثبّت أي نص متبقٍ وتوقف عن انتظار ذلك id. |
للتمييز المباشر راجع الخطوط الزمنية للمتحدثين.
اتبع هذه القواعد في كل سير عمل متدفق:
- وجّه كل نتيجة بحسب
idالخاص بها. يمكن للاتصال الواحد أن يحمل عدة طلبات أو تدفقات. - طبّق النتائج بترتيب وصولها.
- لا تستخدم
seqلترتيب النتائج أو إزالة المكرر منها. - أنهِ عند وصول
is_final: trueأو وصول خطأ أو انقضاء موعدك النهائي. إنهاء إدخالك لا يعني أن النتيجة النهائية وصلت؛ وطريقة إغلاق تدفق النسخ الفوري والانتظار في النسخ الفوري.
الخطوط الزمنية للمتحدثين
يعيد التمييز الدفعي (خيار في مهمة نسخ دفعي) والتمييز المباشر تسميات المتحدثين مع أوقات البداية والنهاية. تعلّم التسمية متحدثًا نسبةً إلى نتيجة واحدة؛ ولا تحدد هوية شخص.
- يرسل التمييز المباشر
final_segmentsالتي لن تتغير، وactive_segmentsالتي قد تتغير. أضف كل مقطع نهائي جديد إلى خطك الزمني مرة واحدة، واستبدل المقاطع النشطة عند كل نتيجة. يجري SDK هذا الدمج بالفعل:update.segmentsهو الخط الزمني الحالي وnewlyFinalized/newly_finalizedيحمل المقاطع النهائية الجديدة، فلا تدمجها مرة أخرى. - التسميات سلاسل معتمة نسبية إلى النتيجة. يصيغها النسخ الدفعي مثل
SPEAKER_1والبث مثلSPEAKER_01، فلا تحللها ولا تقارنها بين النتائج. - قد يقسم التمييز المباشر شخصًا واحدًا إلى تسميتين. ادمج التسميات بنفسك إذا احتاج تطبيقك إلى تسمية واحدة لكل شخص.
كيف تنسب استجابة النسخ الدفعي الكلمات إلى المتحدثين في نسخ تسجيل.
خرج الكلام
يعيد TTS الصوت في قطع. يوفر SDK طريقتين لاستهلاكها:
| الوضع | دالة SDK | استخدمه عندما |
|---|---|---|
| دفعة واحدة | synthesize() | تريد المقطع كاملًا دفعة واحدة: كتابة ملف أو إرفاق صوت برسالة أو تخزين مطالبة مؤقتًا. |
| متدفق | synthesizeStream() / synthesize_stream() | تريد بدء التشغيل قبل انتهاء التوليف، مثل رد وكيل صوتي. |
لا تعيد synthesize() شيئًا إلا بعد القطعة الأخيرة؛ ومع البث يكتمل المقطع عند القطعة
المعلَّمة بأنها نهائية. إذا فشل الطلب في منتصفه فتخلص من الصوت الجزئي. يظهر الوضعان في
تحويل النص إلى كلام: الحفظ أو البث.