حل المشكلات

💡TL;DR

تندرج معظم Notemd المشكلات في أربع فئات: المشكلات الرئيسية API، واتصال الشبكة، وأخطاء المصادقة (401/403)، وقيود المعدل (429). يقوم اختبار الاتصال المدمج ولوحة التشخيص بتحديد السبب الجذري بسرعة. تغطي هذه الصفحة كل رسالة خطأ شائعة، وسببها، وطريقة إصلاحها. بالنسبة للمشكلات غير المدرجة هنا، قم بالإبلاغ عنها في GitHub Issues مع نتائج التشخيص.

هذا جزء من Obsidian دليل إدارة المعرفة الذكية.

نظرة عامة

Notemd يعتمد على خدمات خارجية -- مزودي LLM ومحركات البحث API -- لذلك تنشأ معظم المشكلات خارج الإضافة نفسها. توفر لوحة التشخيص في الإعدادات عرضًا منظمًا لآخر استدعاء API، بما في ذلك طلب URL، وحالة الاستجابة، وجسم الخطأ. يجب دائمًا التحقق منها أولاً قبل المضي قدمًا في التحقيق.

كيفية عملها: التشخيص

اختبار الاتصال

يحتوي كل قسم لإعدادات المزود على زر "اختبر الاتصال". عند النقر عليه يتم إرسال طلب API بسيط (عادةً قائمة بالنماذج أو استكمال قصير) ويتم الإبلاغ عن النجاح أو الخطأ المحدد HTTP. هذه هي أسرع طريقة للتحقق من صحة مفتاح API والقاعدة URL الخاصة بك.

لوحة التشخيص

الإعدادات --> Notemd --> التشخيص تعرض ما يلي:

الحقل	المحتوى
آخر مزود	أي مزود تم استدعاؤه آخر مرة
آخر نموذج	أي نموذج تم استدعاؤه آخر مرة
آخر حالة	رمز حالة HTTP أو خطأ نقل
آخر خطأ	رسالة الخطأ الأصلية من API
طلب آخر URL	نسخة كاملة URL من الطلب الأخير (تم حجب مفتاح API)
جسم الاستجابة الأخير	جزء مقتطع من جسم الاستجابة (أول 500 حرف)

قم بنسخ ناتج التشخيص الكامل عند الإبلاغ عن المشاكل على GitHub.

الأخطاء الشائعة

مفتاح API غير صالح أو مفقود

الأعراض: HTTP 401 أو "تم تقديم مفتاح API غير صحيح"

السبب: مفتاح API مفقود أو يحتوي على مسافات بيضاء أو يخص مزودًا مختلفًا.

الحل:

1. تحقق من عدم وجود مسافات في بداية أو نهاية المفتاح
2. تأكد من أن المفتاح يتطابق مع المزود المختار (مفتاح OpenAI لن يعمل مع Anthropic)
3. تحقق من أن حسابك يحتوي على ائتمانات أو اشتراك نشط
4. انقر على "اختبار الاتصال" للتحقق

أخطاء الشبكة / الاتصال

الأعراض: ERR_CONNECTION_REFUSED، ERR_TIMED_OUT، Socket hang up، Network request failed

السبب: لا يمكن الوصول إلى نقطة النهاية API من جهازك.

الحل:

1. تحقق من اتصال الإنترنت الخاص بك
2. إذا كنت خلف بروكسي أو جدار حماية، تأكد من أن نطاق API غير محظور
3. بالنسبة لـ Ollama: تأكد من أن ollama serve يعمل (يجب أن يُرجع ollama list النماذج)
4. بالنسبة لـ LMStudio: تأكد من أن الخادم يعمل على localhost:1234
5. جرب وسيلة نقل مختلفة -- يجب على المستخدمين المحمولين التأكد من أن وسيلة النقل requestUrl نشطة
6. قم بتفعيل enableStableApiCall لإعادة المحاولة تلقائيًا في حالة الأخطاء المؤقتة

403 ممنوع

الأعراض: HTTP 403

السبب: مفتاح API الخاص بك صالح ولكنه لا يمتلك صلاحيات الوصول إلى المورد المطلوب.

الحل:

1. بعض النماذج تتطلب وصولًا خاصًا (مثلاً، GPT-4 عبر Azure يتطلب اسم نشر)
2. يقوم بعض المزودين بتقييد النماذج حسب مستوى الخطة -- تحقق من حسابك
3. قد تُطبق قيود إقليمية (بعض مزودي الصين يحظرون عناوين IP الدولية والعكس صحيح)
4. تأكد من أن اسم النموذج مكتوب بشكل صحيح (مثلاً، gpt-4o وليس gpt-4o-mini عندما يكون النموذج المصغر هو كل ما تسمح به خطتك)

حد السرعة (429)

الأعراض: HTTP 429 أو "تم تجاوز حد السرعة"

السبب: عدد كبير من الطلبات في فترة زمنية قصيرة.

الحل:

1. قلّل batchConcurrency إلى 1 أو 2
2. انتظر بضع دقائق قبل المحاولة مجددًا
3. راجع وثائق حد السرعة الخاصة بمزودك لمستوى خطتك
4. قم بتفعيل enableStableApiCall لإعادة المحاولة التلقائية مع تأخير
5. فكر في التحويل إلى مزود يوفر حدودًا أعلى (DeepSeek، Ollama)

النموذج غير موجود

الأعراض: "النموذج غير موجود" أو HTTP 404

السبب: اسم النموذج غير موجود لدى المزود المختار.

الحل:

1. انقر على "Get Model List" لعرض جميع النماذج المتاحة لمزودك
2. تتغير أسماء بعض النماذج مع مرور الوقت -- تحقق من الاسم الحالي في وثائق المزود
3. بالنسبة لـ Ollama: قم بتشغيل ollama list لعرض النماذج التي تم سحبها؛ فقط النماذج المُنزلة متاحة

لا توجد روابط / لم يتم إنشاء أي مفاهيم

الأعراض: يتم تشغيل الأمر ولكن لا يتم إنتاج أي ناتج

السبب: عاد LLM برد فعل فارغ أو غير قابل للتحليل.

الحل:

1. تحقق من لوحة التشخيص لمعرفة رد LLM الفعلي
2. جرب نموذجًا أكثر قدرة (بعض النماذج الصغيرة تواجه صعوبات في إنتاج مخرجات منظمة)
3. تأكد من أن الملاحظة تحتوي على محتوى كافٍ (>50 كلمة)
4. راجع نص الطلب المخصص الخاص بك للبحث عن تعليمات متعارضة
5. أوقف تعطيل الكلمات المرادفة مؤقتًا لمعرفة ما إذا كان يتم تصفية النتائج بشكل مفرط

غياب معرف نقطة نهاية Doubao

الأعراض: حدوث خطأ عند استخدام مزود ByteDance Doubao

السبب: يتطلب Doubao معرف نقطة نهاية Ark (التنسيق: ep-xxxxxxxx-xxxx-xxxx) بدلاً من اسم النموذج.

الإصلاح: استبدل النموذج الافتراضي بمعرف نقطة النهاية الفعلية الخاصة بك من واجهة تحكم Volcengine.

التكوين

إعداد التشخيص	الموقع	الغرض
اختبار الاتصال	قسم المزود في الإعدادات	تحقق من مفتاح API وجودة الاتصال
استرجاع قائمة النماذج	قسم المزود في الإعدادات	تأكد من النماذج التي يمكن الوصول إليها
enableStableApiCall	الإعدادات --> المتقدمة	تفعيل إعادة المحاولة مع تأخير زمني
batchConcurrency	الإعدادات --> المجموعات	التحكم في التوازي لتجنب قيود المعدلات

كيفية الإبلاغ عن المشكلات

إذا لم تكن مشكلتك مذكورة أعلاه:

1. افتح الإعدادات --> Notemd --> التشخيص
2. انسخ نتائج التشخيص الكاملة
3. افتح قضية في GitHub على github.com/Jacobinwwey/obsidian-NotEMD/issues
4. أدرج: إصدار Obsidian، إصدار Notemd، المزود، النموذج، نتائج التشخيص، وخطوات تكرار المشكلة
5. احذف مفتاح API الخاص بك من أي سجلات مشتركة

---

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

• LLM المزودون -- مرجع كامل لإعدادات المزود
• المعالجة الدفعية -- إعدادات التزامن وإعادة المحاولة للعمليات الكبيرة
• الطلبات المخصصة -- تصحيح السلوك غير المتوقع لـ LLM عن طريق تعديل الطلبات