استكشاف الأخطاء وإصلاحها
طابق أي عَرَض في 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_FOUND | voice_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؛ راجع أدوات العميل. |
يعيد طلب الجلسة 403 | Voice Agent غير مفعّل لحسابك بعد. | تواصل مع الدعم. |
يعيد طلب الجلسة 429 | كل المكالمات المتزامنة في خطتك جارية، أو نفدت الدقائق اليومية. | انتظر Retry-After؛ راجع حدود الخطة. |
تواصل مع الدعم
أرسل إلى جهة اتصالك في HUMAIN:
- وقت الفشل مع المنطقة الزمنية.
API_URLللبيئة.- معرّف الطلب أو المهمة أو التدفق.
codeالخطأ ورمز حالة HTTP.- SDK وإصداره، مثل
@humain-voice/[email protected]. - أصغر مثال برمجي يعيد إنتاج المشكلة.
لا ترسل مفتاح API أبدًا. ولا ترسل صوت العميل أو نصه إلا إذا طلبه الدعم.