المفاهيم

اختر سير عمل 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 من SDKPCM16 خام little-endian بتردد 24 kHz وأحادي القناة، بلا ترويسة WAV.
خرج TTS عبر بث HTTPPCM16 بتردد 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() شيئًا إلا بعد القطعة الأخيرة؛ ومع البث يكتمل المقطع عند القطعة المعلَّمة بأنها نهائية. إذا فشل الطلب في منتصفه فتخلص من الصوت الجزئي. يظهر الوضعان في تحويل النص إلى كلام: الحفظ أو البث.

الخطوات التالية

في هذه الصفحة