استكشاف الأخطاء وإصلاحها

طابق أي عَرَض في HUMAIN Voice مع سببه المرجح وإصلاحه في مشكلات الاتصال والصوت والنسخ الدفعي والبث وتحويل النص إلى كلام وVoice Agent.

الاتصال والمصادقة

العَرَضالسبب المرجحالإصلاح
401 AUTH_UNAUTHORIZEDالمفتاح مفقود أو به خطأ إملائي أو مُلغى أو منتهي الصلاحية.أرسل API_KEY كـx-api-key؛ راجع أخطاء المصادقة.
401 مع مفتاح يعمل في مكان آخرالمفتاح صادر لبيئة أخرى.استخدم المفتاح مع API_URL الخاص ببيئته؛ راجع الحصول على مفتاح API.
403 AUTH_FORBIDDENينقص المفتاح النطاق المطلوب لهذه العملية.افحص Scopes للمفتاح؛ راجع أخطاء المصادقة.
403 دون جسم ErrorResponseرفضت بوابة الطلب.افحص API_URL والمسار والترويسات، وفي Socket.IO ترويسة Origin؛ راجع أخطاء المصادقة.
connect_error في Socket.IO أو غياب حدث connectمسار خاطئ، أو Origin مفقود، أو نقل بالاستعلام الدوري.استخدم /socket.io وOrigin وWebSocket؛ راجع إرسال المفتاح: Socket.IO.
لا تنتهي عملية JavaScript بعد رفض المفتاحيواصل SDK 0.18.1 إعادة الاتصال بعد رفض connect().التقط الخطأ واخرج صراحةً بـprocess.exit(1)؛ راجع إعداد العميل.

تنسيق الصوت

العَرَضالسبب المرجحالإصلاح
نص النسخ الفوري فارغ أو مشوش أو سريع جدًا أو بطيء جدًاأُرسلت بايتات WAV/MP3 أو بتردد خاطئ على أنها PCM.حوّل إلى PCM16 LE بتردد 16 kHz أحادي القناة؛ راجع تجهيز الصوت.
صوت الهاتف بتردد 8 kHz يُنسخ بجودة ضعيفة في النسخ الفورييتوقع النسخ الفوري تردد 16 kHz.حوّله بأمر تجهيز الصوت.
نتائج ضعيفة في تسجيلات المكالمات العربية بتردد 8 kHz في النسخ الدفعيالنموذج ليس نموذج الاتصالات الهاتفية.استخدم nida_8k_ar؛ راجع اختيار النموذج بحسب حالة الاستخدام.
ASR_UNSUPPORTED_CODEC في النسخ السريع، أو فشل MP4حاوية غير مدعومة، أو ذرة moov في MP4 في آخر الملف.أعد الترميز إلى صيغة مدرجة مع moov في البداية؛ راجع صيغ الصوت.
422 VALIDATION_FILE_CORRUPT في النسخ الدفعيملف تالف أو فارغ أو غير مدعوم.تحقق من أن ffmpeg يفك ترميز الملف، ثم أعد الإرسال.

مهام النسخ الدفعي

العَرَضالسبب المرجحالإصلاح
تبقى المهمة queued أو processingصوت طويل أو سعة مشغولة.استعلم دوريًا ضمن موعد نهائي إجمالي واحد؛ راجع النسخ الدفعي مهمة.
BatchTranscribeTimeoutErrorتجاوز الاستعلام الدوري timeout في SDK.ارفع المهلة أو استعلم بمعرّف المهمة؛ راجع التعامل مع الإخفاقات.
القراءة الثانية تعيد clearedمسحت القراءة الأولى النتيجة.استعلم مع save_result=true؛ راجع قراءة النتيجة مرة أخرى.
وصول المهمة إلى failedفشلت المعالجة.أعد الإرسال مرة واحدة؛ وإذا فشلت ثانية فـتواصل مع الدعم مع معرّف المهمة.
429 RATE_LIMIT_EXCEEDED عند الإرسالاستُنفدت سعة الصوت الدفعي.تراجع؛ راجع استجابات السعة.
422 AUDIO_DURATION_EXCEEDEDمدة الصوت تتجاوز سقف الأربع ساعات عند تقديم الطلب.قسّم التسجيل؛ راجع حدود النسخ الدفعي.
انتهت مهلة الإرسال أو أعاد 500قد تكون المهمة أُنشئت.لا تعد الإرسال تلقائيًا؛ راجع إعادة المحاولة والتكرار.

نتائج البث

العَرَضالسبب المرجحالإصلاح
تتكرر النصوص المؤقتة في التسميات التوضيحيةأُلحقت كل نتيجة بالنص.استبدل النص المؤقت بحسب id؛ راجع نتائج البث.
كلمات أخيرة مفقودة ولا is_finalعاد close() بعد مهلته الافتراضية البالغة ثانية واحدة.استدعِ close(5)؛ راجع إنهاء التدفق.
الجملة الأولى فقط في التسميات التوضيحيةأسقطت دالة مساعدة النتائج النهائية التي تشترك في seq.اجمع كلمات كل نتيجة نهائية بنفسك؛ راجع Subtitles.
تختلف تسميات المتحدثين بين النسخ الدفعي والبثالتسميات سلاسل معتمة نسبية إلى النتيجة.لا تحلل التسميات ولا تقارنها؛ راجع الخطوط الزمنية للمتحدثين.
شخص واحد يحصل على تسميتي متحدث مباشرتينقد يفرط التمييز المباشر في التقسيم.ادمج التسميات في تطبيقك؛ راجع الخطوط الزمنية للمتحدثين.
انقطع التدفق في منتصف الجلسةلا استئناف ولا إعادة تشغيل.احتفظ بالنص المثبّت وابدأ تدفقًا جديدًا؛ راجع التعافي.

تحويل النص إلى كلام

العَرَضالسبب المرجحالإصلاح
الملف المحفوظ لا يعملخرج SDK صوت PCM خام وليس WAV.أضف ترويسة WAV؛ راجع حفظ الكلام في ملف WAV.
الصوت المبثوث صامت أو مشوش في ffplayصيغة المشغّل خاطئة.مرر الصوت إلى ffplay -f s16le -ar 24000 -ch_layout mono -؛ راجع تشغيل الكلام.
خرج تحويل النص إلى كلام عبر HTTP غير قابل للتشغيلترويسات الإطارات داخل الصوت.استخدم SDK أو Socket.IO، أو استدعِ POST /v1/audio/speech لملف كامل قابل للتشغيل؛ راجع أيضًا تحويل النص إلى كلام عبر HTTP.
TTS_VOICE_NOT_FOUNDvoice_id من بيئة أخرى، أو تسمية.ابحث عن id الملف الشخصي للصوت؛ راجع قائمة الأصوات.
TTS_INPUT_NOT_ALLOWEDرفضت سياسة المحتوى النص.غيّر النص؛ راجع رموز تحويل النص إلى كلام.
TTS_MODERATION_UNAVAILABLEتعذر على الإشراف أن يقرر.تراجع وأعد المحاولة؛ راجع إعادة المحاولة بأمان.
CHARACTER_COUNT_EXCEEDEDالنص يتجاوز حد خطتك.قسّم النص؛ راجع حدود تحويل النص إلى كلام.

Voice Agent

العَرَضالسبب المرجحالإصلاح
يعيد طلب الجلسة 400حقل غير معروف، أو قيمة غير صالحة، أو متغير بلا قيمة.أصلح كل حقل في data.errors؛ راجع أخطاء التحقق.
تنتهي المكالمة بـuser_never_joinedاستُخدم رمز الدخول بعد expires_at، أي بعد نحو دقيقة من الطلب.ابدأ الجلسة عندما ينقر المستخدم، واتصل فورًا.
MIC_PERMISSION_DENIEDرفض المستخدم الميكروفون، أو الصفحة ليست على HTTPS أو localhost.قدّم الصفحة عبر HTTPS واطلب من المستخدم السماح بالميكروفون.
حالة الوكيل ready لكن لا يُسمعحجب المتصفح صوتًا لم يبدأ من نقرة.ابدأ المكالمة من نقرة، أو استدعِ startAudio() من onAudioBlocked؛ راجع SDK المتصفح.
CONNECTION_FAILED على شبكة مكتب أو فندق فقطتحجب الشبكة حركة WebRTC.اسمح بحركة UDP وTCP 443 الصادرة إلى مضيف server_url.
يقول الوكيل إنه لا يستطيع فعل شيء تعالجه أداتكلا معالج للأداة، أو أطلق المعالج خطأ.افحص onError بحثًا عن CLIENT_TOOL_NOT_HANDLED أو CLIENT_TOOL_FAILED؛ راجع أدوات العميل.
يعيد طلب الجلسة 403Voice Agent غير مفعّل لحسابك بعد.تواصل مع الدعم.
يعيد طلب الجلسة 429كل المكالمات المتزامنة في خطتك جارية، أو نفدت الدقائق اليومية.انتظر Retry-After؛ راجع حدود الخطة.

تواصل مع الدعم

أرسل إلى جهة اتصالك في HUMAIN:

  • وقت الفشل مع المنطقة الزمنية.
  • API_URL للبيئة.
  • معرّف الطلب أو المهمة أو التدفق.
  • code الخطأ ورمز حالة HTTP.
  • SDK وإصداره، مثل @humain-voice/[email protected].
  • أصغر مثال برمجي يعيد إنتاج المشكلة.

لا ترسل مفتاح API أبدًا. ولا ترسل صوت العميل أو نصه إلا إذا طلبه الدعم.

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

في هذه الصفحة