رفع اشکالات
بیشتر Notemd مشکلات در چهار دسته قرار میگیرند: مشکلات کلیدی API، اتصال شبکه، خطاهای احراز هویت (401/403) و محدودیتهای نرخ (429). آزمون اتصال داخلی و پنل تشخیصی به سرعت علت اصلی را شناسایی میکنند. این صفحه تمام پیامهای خطای رایج، علت آنها و راهحلهای مربوطه را پوشش میدهد. برای مشکلاتی که در اینجا فهرست نشدهاند، آنها را همراه با خروجی تشخیصی در GitHub Issues گزارش دهید.
این بخشی از Obsidian راهنمای مدیریت دانش هوش مصنوعی است.
مرور کلی
Notemd به سرویسهای خارجی – ارائهدهندگان LLM و موتورهای جستجو API – وابسته است؛ بنابراین اکثر مشکلات از خارج از خود پلاگین نشأت میگیرند. پنل تشخیصی در تنظیمات، نمای ساختاریافتهای از آخرین API فراخوانی را ارائه میدهد که شامل درخواست URL، وضعیت پاسخ و بدنه خطا است. همیشه قبل از بررسی بیشتر، ابتدا آن را بررسی کنید.
نحوه کارکرد: تشخیصات
آزمون اتصال
هر بخش پیکربندی ارائهدهنده دارای دکمهای به نام "آزمون اتصال" است. با کلیک بر روی آن، یک درخواست حداقلی API ارسال میشود (معمولاً فهرست مدلها یا یک پاسخ کوتاه) و موفقیت یا خطای خاص HTTP گزارش میشود. این سریعترین روش برای بررسی صحت کلید API و پایه URL شماست.
پنل تشخیصی
تنظیمات --> Notemd --> تشخیصات نمایش میدهد:
| فیلد | محتوا |
|---|---|
| آخرین ارائهدهنده | کدام ارائهدهنده آخرین بار فراخوانی شده است |
| آخرین مدل | کدام مدل آخرین بار فراخوانی شده است |
| آخرین وضعیت | کد وضعیت HTTP یا خطای انتقال |
| آخرین خطا | پیام خطا خام از API |
| آخرین درخواست URL | محتوای کامل URL درخواست قبلی (کلید API حذف شده است) |
| محتوای پاسخ آخر | بدنه پاسخ کوتاه شده (۵۰۰ کاراکتر اول) |
هنگام گزارش مشکلات در GitHub، خروجی کامل تشخیص اختلالات را کپی کنید.
خطاهای رایج
API کلید نامعتبر یا وجود ندارد
علامتها: HTTP خطا ۴۰۱ یا «کلید API نادرست ارائه شده است»
دلیل: کلید API وجود ندارد، حاوی فضای خالی است، یا متعلق به یک ارائهدهنده دیگر میباشد.
راهحل:
- بررسی کنید که کلید فاقد فضای ابتدایی/پایانی باشد.
- تأیید کنید که کلید با ارائهدهنده انتخابشده مطابقت دارد (یک کلید OpenAI نمیتواند با Anthropic کار کند).
- بررسی کنید که حساب شما دارای اعتبار یا اشتراک فعال است
- برای تأیید، روی "Test Connection" کلیک کنید
خطاهای شبکه / اتصال
علائم: ERR_CONNECTION_REFUSED, ERR_TIMED_OUT, Socket hang up, Network request failed
دلیل: پایانه API از روی دستگاه شما قابل دسترسی نیست.
راهحل:
- اتصال اینترنت خود را بررسی کنید
- در صورت استفاده از پروکسی یا فایروال، تأیید کنید که دامنه API مسدود نشده است
- برای Ollama: تأیید کنید که
ollama serveدر حال اجراست (ollama listباید مدلها را برگرداند) - برای LMStudio: تأیید کنید که سرور روی
localhost:1234در حال اجراست - از روش انتقال داده متفاوتی استفاده کنید – کاربران موبایل باید اطمینان حاصل کنند که روش انتقال
requestUrlفعال است enableStableApiCallرا برای تلاش خودکار مجدد در صورت خطاهای موقت فعال کنید
403 Forbidden
علائم: HTTP 403
دلیل: کلید API شما معتبر است اما دسترسی لازم برای منبع درخواستی را ندارد.
راهحل:
- برخی مدلها نیاز به دسترسی ویژه دارند (مثلاً GPT-4 از طریق Azure نیازمند یک نام پیادهسازی است)
- برخی ارائهدهندگان مدلها را بر اساس سطح منوال محدود میکنند – حساب خود را بررسی کنید
- ممکن است محدودیتهای منطقهای وجود داشته باشد (برخی ارائهدهندگان چینی IPهای بینالمللی را مسدود میکنند و برعکس)
- بررسی کنید که نام مدل به درستی نوشته شده است (مثلاً
gpt-4oنهgpt-4o-miniزمانی که مدل کوچک تنها چیزی است که منوال شما اجازه میدهد)
محدودیت نرخ درخواست (429)
علائم: HTTP 429 یا "محدودیت نرخ درخواست رخ داد"
دلیل: تعداد زیادی درخواست در یک بازه زمانی کوتاه.
راهحل:
batchConcurrencyرا به1یا2کاهش دهید- چند دقیقه صبر کنید و سپس دوباره امتحان کنید
- مستندات مربوط به محدودیت نرخ درخواست ارائهدهنده خود را برای سطح منوال خود بررسی کنید
enableStableApiCallرا برای تلاش خودکار با تأخیر فعال کنید- در نظر بگیرید به ارائهدهندهای با محدودیتهای بالاتر (DeepSeek، Ollama) منتقل شوید
مدل پیدا نشد
علائم: "مدل پیدا نشد" یا HTTP 404
دلیل: نام مدل در ارائهدهنده انتخابشده وجود ندارد.
راهحل:
- برای مشاهده تمام مدلهای موجود برای ارائهدهنده خود، روی "Get Model List" کلیک کنید
- برخی از نامهای مدلها با گذشت زمان تغییر میکنند – نام فعلی را در مستندات ارائهدهنده بررسی کنید
- برای Ollama:
ollama listرا اجرا کنید تا مدلهای بارگذاریشده را مشاهده کنید؛ تنها مدلهای دانلودشده در دسترس هستند
هیچ لینکی/هیچ مفهومی تولید نشده است
علامتها: دستور اجرا میشود اما خروجیای تولید نمیکند
دلیل: LLM پاسخ خالی یا غیرقابل تحلیلی را برگردانده است.
راهحل:
- برای مشاهده پاسخ واقعی LLM، به پنل تشخیصی نگاه کنید
- مدلی قویتر را امتحان کنید (برخی مدلهای کوچک در خروجی ساختاریافته مشکل دارند)
- مطمئن شوید یادداشت حاوی محتوای کافی (بیش از ۵۰ کلمه) است
- دستورالعملهای متضاد در پرامپت سفارشی خود را بررسی کنید
- برای بررسی اینکه آیا فیلترینگ بیش از حد است یا خیر، سرکوب مترادفات را موقتاً غیرفعال کنید
شناسه پایانه Doubao ناپدید شده است
علامتها: هنگام استفاده از ارائهدهنده ByteDance Doubao خطا رخ میدهد
دلیل: Doubao به جای نام مدل، به یک شناسه پایانه Ark (فرمت: ep-xxxxxxxx-xxxx-xxxx) نیاز دارد.
تعمیر: جایگزین مدل جایگزین پیشفرض با شناسه انتهایی واقعی خود از کنسول Volcengine کنید.
پیکربندی
| تنظیمات تشخیصی | موقعیت | هدف |
|---|---|---|
| آزمایش اتصال | بخش Settings --> Provider | بررسی کلید API و قابلیت اتصال |
| لیست گرفتن مدلها | بخش Settings --> Provider | تأیید اینکه کدام مدلها در دسترس هستند |
enableStableApiCall | بخش Settings --> Advanced | فعالسازی تلاش مجدد با تأخیر زمانی |
batchConcurrency | بخش Settings --> Batch | کنترل موازیسازی برای جلوگیری از محدودیتهای نرخ |
نحوه گزارش مشکلات
اگر مشکل شما در بالا پوشش داده نشده است:
- باز کردن Settings --> Notemd --> Diagnostics
- کپی کردن خروجی کامل تشخیصات
- افتتاح یک مسئله در GitHub در آدرس github.com/Jacobinwwey/obsidian-NotEMD/issues
- شامل: نسخه Obsidian، نسخه Notemd، ارائهدهنده، مدل، خروجی تشخیصات و مراحل تکرار مشکل
- پنهان کردن کلید API خود از هر گونه لاگ مشترک
گامهای بعدی
- LLM Providers -- منبع کامل پیکربندی ارائهدهندگان
- Batch Processing -- تنظیمات همزمانی و تلاش مجدد برای عملیاتهای بزرگ
- Custom Prompts -- رفع رفتار غیرمنتظره LLM با تنظیم پرامپتها