Skip to content

Latest commit

 

History

History
219 lines (139 loc) · 12 KB

TROUBLESHOOTING.md

File metadata and controls

219 lines (139 loc) · 12 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'... בנקודת קצה בענן עבור שיחות שאינן זורמות.

סיבה: Upstream מחזיר מטען SSE בזמן שהלקוח מצפה ל-JSON.

פתרון לעקיפת הבעיה: השתמש ב-stream=true לשיחות ישירות בענן. זמן ריצה מקומי כולל SSE → JSON fallback.

ענן אומר מחובר אבל "מפתח API לא חוקי"

  1. צור מפתח חדש מלוח המחוונים המקומי (/api/keys)
  2. הפעל סנכרון ענן: הפעל ענן ← סנכרן עכשיו
  3. מפתחות ישנים/לא מסונכרנים עדיין יכולים להחזיר 401 בענן

בעיות דוקר

כלי CLI מציג לא מותקן

  1. בדוק את שדות זמן הריצה: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. עבור מצב נייד: השתמש ביעד תמונה runner-cli (CLI מצרפים)
  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. הגדר תקציבי עלויות לכל מפתח API: לוח מחוונים ← מפתחות API ← תקציב

איתור באגים

אפשר יומני בקשות

הגדר את 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)

בעיות מפסקים

הספק תקוע במצב OPEN

כאשר מפסק החשמל של ספק פתוח, הבקשות נחסמות עד לפקיעת הקירור.

תיקון:

  1. עבור אל לוח מחוונים ← הגדרות ← חוסן
  2. בדוק את כרטיס המפסק עבור הספק המושפע
  3. לחץ על אפס הכל כדי לנקות את כל המפסקים, או המתן עד שתוקף הקירור יפוג
  4. ודא שהספק אכן זמין לפני האיפוס

הספק ממשיך להדליק את המפסק

אם ספק נכנס שוב ושוב למצב OPEN:

  1. סמן את לוח המחוונים ← תקינות ← תקינות הספק עבור דפוס הכשל
  2. עבור אל הגדרות ← חוסן ← פרופילי ספקים והגדל את סף הכשל
  3. בדוק אם הספק שינה מגבלות API או שהוא דורש אימות מחדש
  4. סקירת טלמטריית חביון - זמן אחזור גבוה עלול לגרום לכשלים מבוססי זמן קצוב

בעיות בתמלול אודיו

שגיאה "מודל לא נתמך".

  • ודא שאתה משתמש בקידומת הנכונה: deepgram/nova-3 או assemblyai/best
  • ודא שהספק מחובר ב-לוח מחוונים → ספקים

התמלול מחזיר ריק או נכשל

  • בדוק פורמטי שמע נתמכים: mp3, wav, m4a, flac, ogg, webm
  • ודא שגודל הקובץ נמצא בגבולות הספק (בדרך כלל < 25MB)
  • בדוק את תוקף מפתח ה-API של ספק בכרטיס הספק

ניפוי באגים של מתרגם

השתמש בלוח המחוונים ← מתרגם כדי לנפות באגים בבעיות תרגום בפורמט:

מצב מתי להשתמש
מגרש משחקים השווה פורמטים של קלט/פלט זה לצד זה - הדבק בקשה נכשלת כדי לראות איך היא מתורגמת
בודק צ'אט שלח הודעות חיות ובדוק את מטען הבקשה/תגובה המלא כולל כותרות
ספסל מבחן הפעל בדיקות אצווה על פני שילובי פורמטים כדי למצוא אילו תרגומים מקולקלים
שידור חי צפה בזרם הבקשות בזמן אמת כדי לתפוס בעיות תרגום לסירוגין

בעיות פורמט נפוצות

  • תגי חשיבה לא מופיעים — בדוק אם ספק היעד תומך בחשיבה ובהגדרת תקציב החשיבה
  • הורדת שיחות הכלים - תרגומי פורמט מסוימים עשויים להסיר שדות שאינם נתמכים; לאמת במצב Playground
  • הנחיית מערכת חסרה - קלוד וג'מיני מטפלים בהנחיות המערכת בצורה שונה; בדוק את פלט התרגום
  • 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

הגדרות חוסן

מגבלת שיעור אוטומטי לא מופעלת

  • הגבלת תעריף אוטומטי חלה רק על ספקי מפתח API (לא OAuth/מינוי)
  • ודא של הגדרות ← חוסן ← פרופילי ספקים מופעלת הגבלת תעריף אוטומטי
  • בדוק אם הספק מחזיר 429 קודי סטטוס או כותרות Retry-After

כוונון גיבוי אקספוננציאלי

פרופילי ספקים תומכים בהגדרות הבאות:

  • השהיית בסיס - זמן המתנה ראשוני לאחר הכשל הראשון (ברירת מחדל: 1 שניות)
  • עיכוב מרבי - מכסת זמן המתנה מקסימלית (ברירת מחדל: 30 שניות)
  • מכפיל - כמה להגדיל את העיכוב לכל כשל רצוף (ברירת מחדל: פי 2)

עדר נגד רעמים

כאשר בקשות בו-זמניות רבות פוגעות בספק מוגבל בקצב, OmniRoute משתמשת ב-mutex + הגבלת קצב אוטומטית כדי להדגיש בקשות ולמנוע כשלים מדורגים. זה אוטומטי עבור ספקי מפתחות API.

עדיין תקוע?

  • בעיות GitHub: github.com/diegosouzapw/OmniRoute/issues
  • אדריכלות: ראה link לפרטים פנימיים
  • הפניה ל-API: ראה link עבור כל נקודות הקצה
  • לוח מחוונים לבריאות: בדוק את לוח מחוונים ← בריאות למצב מערכת בזמן אמת
  • מתרגם: השתמש ב-לוח מחוונים ← מתרגם כדי לנפות באגים בפורמט