Skip to content

Latest commit

 

History

History
219 lines (139 loc) · 14.1 KB

TROUBLESHOOTING.md

File metadata and controls

219 lines (139 loc) · 14.1 KB

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

🌐 Languages: 🇺🇸 English | 🇧🇷 Português (Brasil) | 🇪🇸 Español | 🇫🇷 Français | 🇮🇹 Italiano | 🇷🇺 Русский | 🇨🇳 中文 (简体) | 🇩🇪 Deutsch | 🇮🇳 हिन्दी | 🇹🇭 ไทย | 🇺🇦 Українська | 🇸🇦 العربية | 🇯🇵 日本語 | 🇻🇳 Tiếng Việt | 🇧🇬 Български | 🇩🇰 Dansk | 🇫🇮 Suomi | 🇮🇱 עברית | 🇭🇺 Magyar | 🇮🇩 Bahasa Indonesia | 🇰🇷 한국어 | 🇲🇾 Bahasa Melayu | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇵🇹 Português (Portugal) | 🇷🇴 Română | 🇵🇱 Polski | 🇸🇰 Slovenčina | 🇸🇪 Svenska | 🇵🇭 Filipino

المشاكل والحلول الشائعة لـ OmniRoute.

إصلاحات سريعة

مشكلة الحل
تسجيل الدخول الأول لا يعمل تحقق من INITIAL_PASSWORD في .env (الافتراضي: 123456)
تفتح لوحة المعلومات على منفذ خاطئ اضبط PORT=20128 وNEXT_PUBLIC_BASE_URL=http://localhost:20128
لا توجد سجلات للطلب ضمن logs/ تعيين ENABLE_REQUEST_LOGS=true
EACCES: تم رفض الإذن اضبط DATA_DIR=/path/to/writable/dir لتجاوز ~/.omniroute
استراتيجية التوجيه لا تنقذ التحديث إلى الإصدار 1.4.11+ (إصلاح مخطط Zod لاستمرارية الإعدادات)

مشكلات المزود

"نموذج اللغة لم يقدم رسائل"

السبب: استنفدت حصة الموفر.

الإصلاح:

  1. تحقق من تعقب الحصص في لوحة القيادة
  2. استخدم مجموعة من المستويات الاحتياطية
  3. قم بالتبديل إلى الطبقة الأرخص/المجانية

تحديد المعدل

السبب: استنفدت حصة الاشتراك.

الإصلاح:

  • إضافة احتياطي: cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking
  • استخدم GLM/MiniMax كنسخة احتياطية رخيصة الثمن

انتهت صلاحية رمز OAuth

يقوم OmniRoute بتحديث الرموز المميزة تلقائيًا. إذا استمرت المشكلات:

  1. لوحة المعلومات → الموفر → إعادة الاتصال
  2. قم بحذف وإعادة إضافة اتصال الموفر

مشكلات السحابة

أخطاء المزامنة السحابية

  1. تحقق من نقاط BASE_URL لمثيلك قيد التشغيل (على سبيل المثال، http://localhost:20128)
  2. تحقق من نقاط CLOUD_URL إلى نقطة نهاية السحابة الخاصة بك (على سبيل المثال، https://omniroute.dev)
  3. حافظ على محاذاة قيم NEXT_PUBLIC_* مع القيم من جانب الخادم

السحابة stream=false تُرجع 500

العَرَض: Unexpected token 'd'... على نقطة نهاية السحابة للمكالمات غير المتدفقة.

السبب: يقوم المنبع بإرجاع حمولة SSE بينما يتوقع العميل JSON.

الحل البديل: استخدم stream=true للمكالمات السحابية المباشرة. يتضمن وقت التشغيل المحلي SSE → JSON الاحتياطي.

تقول السحابة إنها متصلة ولكن "مفتاح واجهة برمجة التطبيقات غير صالح"

  1. قم بإنشاء مفتاح جديد من لوحة المعلومات المحلية (/api/keys)
  2. قم بتشغيل المزامنة السحابية: قم بتمكين السحابة → المزامنة الآن
  3. لا يزال بإمكان المفاتيح القديمة/غير المتزامنة إرجاع 401 على السحابة

مشكلات عامل الميناء

تظهر أداة CLI غير مثبتة

  1. تحقق من حقول وقت التشغيل: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. بالنسبة للوضع المحمول: استخدم هدف الصورة runner-cli (CLIs المجمعة)
  3. بالنسبة لوضع تثبيت المضيف: قم بتعيين CLI_EXTRA_PATHS وتثبيت دليل حاوية المضيف للقراءة فقط
  4. إذا تم العثور على installed=true وrunnable=false: ثنائي ولكن فشل التحقق من الصحة

التحقق السريع من وقت التشغيل

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

قضايا التكلفة

ارتفاع التكاليف

  1. تحقق من إحصائيات الاستخدام في لوحة المعلومات → الاستخدام
  2. قم بتبديل النموذج الأساسي إلى GLM/MiniMax
  3. استخدم الطبقة المجانية (Gemini CLI، iFlow) للمهام غير الحرجة
  4. قم بتعيين ميزانيات التكلفة لكل مفتاح واجهة برمجة التطبيقات: لوحة المعلومات ← مفاتيح واجهة برمجة التطبيقات ← الميزانية

التصحيح

تمكين سجلات الطلبات

قم بتعيين ENABLE_REQUEST_LOGS=true في ملف .env الخاص بك. تظهر السجلات ضمن الدليل logs/.

التحقق من صحة مقدم الخدمة

# Health dashboard
http://localhost:20128/dashboard/health

# API health check
curl http://localhost:20128/api/monitoring/health

تخزين وقت التشغيل

  • الحالة الرئيسية: ${DATA_DIR}/db.json (المزودون، المجموعات، الأسماء المستعارة، المفاتيح، الإعدادات)
  • الاستخدام: ${DATA_DIR}/usage.json، ${DATA_DIR}/log.txt، ${DATA_DIR}/call_logs/
  • سجلات الطلب: <repo>/logs/... (عندما ENABLE_REQUEST_LOGS=true)

مشكلات قواطع الدائرة

الموفر عالق في الحالة المفتوحة

عندما يكون قاطع دائرة الموفر مفتوحًا، يتم حظر الطلبات حتى تنتهي فترة التهدئة.

الإصلاح:

  1. انتقل إلى لوحة التحكم ← الإعدادات ← المرونة
  2. تحقق من بطاقة قاطع الدائرة الكهربائية الخاصة بالمزود المتأثر
  3. انقر فوق إعادة تعيين الكل لمسح جميع القواطع، أو انتظر حتى تنتهي فترة التهدئة
  4. تحقق من أن الموفر متاح فعليًا قبل إعادة التعيين

يستمر المزود في تعطيل قاطع الدائرة

إذا دخل مقدم الخدمة بشكل متكرر في الحالة المفتوحة:

  1. تحقق من Dashboard → Health → Provider Health لمعرفة نمط الفشل
  2. انتقل إلى الإعدادات → المرونة → ملفات تعريف الموفر وقم بزيادة حد الفشل
  3. تحقق مما إذا كان الموفر قد قام بتغيير حدود واجهة برمجة التطبيقات (API) أو طلب إعادة المصادقة
  4. قم بمراجعة القياس عن بعد لزمن الاستجابة - قد يتسبب زمن الاستجابة العالي في حدوث أعطال بسبب انتهاء المهلة

مشكلات النسخ الصوتي

خطأ "نموذج غير مدعوم".

  • تأكد من أنك تستخدم البادئة الصحيحة: deepgram/nova-3 أو assemblyai/best
  • تحقق من أن الموفر متصل في لوحة التحكم ← الموفرون

يعود النسخ فارغًا أو يفشل

  • تحقق من تنسيقات الصوت المدعومة: mp3، wav، m4a، flac، ogg، webm
  • التحقق من أن حجم الملف يقع ضمن حدود الموفر (عادةً أقل من 25 ميجابايت)
  • التحقق من صلاحية مفتاح API الخاص بالموفر في بطاقة المزود

تصحيح أخطاء المترجم

استخدم لوحة المعلومات → المترجم لتصحيح مشكلات ترجمة التنسيق:

الوضع متى تستخدم
ساحة اللعب قارن تنسيقات الإدخال/الإخراج جنبًا إلى جنب — الصق طلبًا فاشلاً لترى كيف تتم ترجمته
** اختبار الدردشة ** أرسل رسائل مباشرة وافحص حمولة الطلب/الاستجابة الكاملة بما في ذلك الرؤوس
** مقعد الاختبار ** قم بإجراء اختبارات مجمعة عبر مجموعات التنسيق للعثور على الترجمات المعطلة
مراقبة حية شاهد تدفق الطلبات في الوقت الفعلي للتعرف على مشكلات الترجمة المتقطعة

مشكلات التنسيق الشائعة

  • لا تظهر علامات التفكير — تحقق مما إذا كان الموفر المستهدف يدعم التفكير وإعداد ميزانية التفكير
  • استدعاءات الأداة — قد تؤدي بعض ترجمات التنسيق إلى إزالة الحقول غير المدعومة؛ تحقق في وضع الملعب
  • مطالبة النظام مفقودة — يتعامل نظام Claude وGemini مع المطالبات بشكل مختلف؛ التحقق من إخراج الترجمة
  • ** تقوم SDK بإرجاع سلسلة أولية بدلاً من الكائن ** - تم الإصلاح في الإصدار 1.1.0: تقوم أداة معالجة الاستجابة الآن بإزالة الحقول غير القياسية (x_groq، usage_breakdown، وما إلى ذلك) التي تتسبب في فشل التحقق من صحة OpenAI SDK Pydantic
  • GLM/ERNIE يرفض دور system — تم إصلاحه في الإصدار 1.1.0: يقوم مُطبيع الدور تلقائيًا بدمج رسائل النظام في رسائل المستخدم للنماذج غير المتوافقة
  • developer لم يتم التعرف على الدور — تم إصلاحه في الإصدار 1.1.0: تم تحويله تلقائيًا إلى system لمقدمي الخدمات غير التابعين لـ OpenAI
  • json_schema لا يعمل مع Gemini — تم إصلاحه في الإصدار 1.1.0: response_format تم تحويله الآن إلى responseMimeType + responseSchema الخاص بـ Gemini__

إعدادات المرونة

لا يتم تشغيل حد المعدل التلقائي

  • ينطبق حد المعدل التلقائي فقط على موفري مفاتيح واجهة برمجة التطبيقات (وليس OAuth/الاشتراك)
  • تحقق من أن الإعدادات → المرونة → ملفات تعريف الموفر تم تمكين حد المعدل التلقائي
  • تحقق مما إذا كان الموفر يعرض 429 رموز الحالة أو رؤوس Retry-After

ضبط التراجع الأسي

تدعم ملفات تعريف الموفر هذه الإعدادات:

  • التأخير الأساسي — وقت الانتظار الأولي بعد الفشل الأول (الافتراضي: 1 ثانية)
  • الحد الأقصى للتأخير — الحد الأقصى لوقت الانتظار (الافتراضي: 30 ثانية)
  • المضاعف — مقدار زيادة التأخير لكل فشل متتالي (الافتراضي: 2x)

قطيع مضاد للرعد

عندما تصل العديد من الطلبات المتزامنة إلى موفر محدود السعر، يستخدم OmniRoute تحديد المعدل التلقائي + mutex لإجراء تسلسل للطلبات ومنع حالات الفشل المتتالية. وهذا تلقائي لموفري مفاتيح API.

هل مازلت عالقًا؟

  • مشكلات GitHub: github.com/diegosouzapw/OmniRoute/issues
  • الهندسة المعمارية: راجع link للحصول على التفاصيل الداخلية
  • مرجع واجهة برمجة التطبيقات: راجع link لجميع نقاط النهاية
  • لوحة معلومات الصحة: تحقق من لوحة المعلومات ← الصحة لمعرفة حالة النظام في الوقت الفعلي
  • المترجم: استخدم لوحة المعلومات ← المترجم لتصحيح مشكلات التنسيق