عیب‌یابی: ارائه‌دهندگان LLM

أخطاء ارائه‌دهندهين الشائعة

401 Unauthorized / 403 Forbidden

مفتاح API الخاص بك غير صالح یا ازتهي الصخیرحية یا خیر يملك أذونات كادرة.

الحل:

# أعد ذخیره‌سازی مفتاح API
triggerfish config set-secret provider:<name>:apiKey <your-key>

# أعد تشغيل الخدمة الخلدرة
triggerfish stop && triggerfish start

مخیرحظات خاصة بارائه‌دهندهين:

ارائه‌دهنده	تنسيق المفتاح	کجا تحصل عليه
Anthropic	sk-ant-...	console.anthropic.com
OpenAI	sk-...	platform.openai.com
Google	AIza...	aistudio.google.com
Fireworks	fw_...	fireworks.ai
OpenRouter	sk-or-...	openrouter.ai

429 Rate Limited

لقد تجاوزت حد بادل ارائه‌دهنده. خیر يُعيد Triggerfish المحاولة به‌صورت خودکار عند 429 لباظم ارائه‌دهندهين (باستثناء Notion الذي يحتوي روی تمراجعه کنید مدمج).

الحل: انتظر وحاول مرة أخرى. إذا وصلت لحدود البادل باستمرار، فكّر در:

• ترقية خطة API الخاصة بك لحدود أروی
• plugin ارائه‌دهنده احتياطي ليمرّر درخواستات عند تقييد ارائه‌دهنده الأساسي
• تقليل تكرار المُنشّطات إذا كانت وظایف زمان‌بندی‌شده هي السبب

500 / 502 / 503 خطأ خادم

خوادم ارائه‌دهنده تواجه مشاهر. این عادة مؤقتة.

إذا كان لديك سلسلة تبديل خودکار مكوّنة، يحاول Triggerfish ارائه‌دهنده التالي به‌صورت خودکار. بدون تبديل خودکار، ينتقل الخطأ به المستخدم.

"No response body for streaming"

قبل ارائه‌دهنده درخواست لكنه أرجع جسم پاسخ فارغ لفراخوانی بث. يمكن أن يحدث این عندما:

• بنية ارائه‌دهنده التحتية محمّلة بشهر زائد
• عامل یا جدار حماية يزيل جسم پاسخ
• مدل غير متوفر مؤقتاً

يؤثر این روی: OpenRouter، Local (Ollama/LM Studio)، ZenMux، Z.AI، Fireworks.

---

مشاهر خاصة بارائه‌دهندهين

Anthropic

تحويل تنسيق ابزارها. يحوّل Triggerfish بین تنسيق ابزارها الداخلي وتنسيق ابزارها Anthropic الأصلي. إذا رهرت أخطاء متعلقة بابزارها، تحقق از أن تعريفات ابزارهاك تحتوي روی JSON Schema صالح.

باالجة موجّه النظام. يتدرخواست Anthropic موجّه النظام كحقل ازفصل وليس كپیام. این التحويل خودکار، لكن إذا رهرت پیام‌ها "system" تظهر در مکالمه، آنجا خطأ در تنسيق الپیام‌ها.

OpenAI

عقوبة التكرار. يطبّق Triggerfish عقوبة تكرار 0.3 روی تمام درخواستات OpenAI لتثبيط المخرجات المتكررة. این مُثبّت در الكود ونمی‌توان تغييره از طریق پیکربندی.

دعم الصور. پشتیبانی می‌کند OpenAI الصور المشفرة بـ base64 در محتوى پیام. إذا لم کار می‌کند بینایی، تأكد از أن لديك مدخیرً پشتیبانی می‌کند بینایی مكوّناً (مثل gpt-4o، وليس gpt-4o-mini).

Google Gemini

المفتاح در سلسلة اخیرستعخیرم. روی عكس ارائه‌دهندهين الآخرين، يستخدم Google مفتاح API كباامل استعخیرم وليس رأساً. يُعالج این به‌صورت خودکار، لكنه يعني أن المفتاح قد يظهر در سجخیرت عامل/الوصول إذا وجّهت از طریق عامل مؤسسي.

Ollama / LM Studio (محلی)

باید أن يكون الخادم کار می‌کند. تتدرخواست ارائه‌دهندهات المحلیة أن يكون خادم مدل کار می‌کند قبل بدء Triggerfish. إذا لم يكن Ollama یا LM Studio کار می‌کند:

Local LLM request failed (connection refused)

ابدأ الخادم:

# Ollama
ollama serve

# LM Studio
# افتح LM Studio وابدأ الخادم المحلی

مدل غير محمّل. با Ollama، باید سحب مدل یاخیرً:

ollama pull llama3.3:70b

تجاوز نقطة النهاية. إذا لم يكن خادمك المحلی روی الازفذ پیش‌فرض:

models:
  providers:
    local:
      model: llama3.3:70b
      endpoint: "http://localhost:11434"   # پیش‌فرض Ollama
      # endpoint: "http://localhost:1234"  # پیش‌فرض LM Studio

Fireworks

API أصلي. يستخدم Triggerfish واجهة API الأصلية لـ Fireworks، وليس نقطة النهاية المتوافقة با OpenAI. قد تختلف بارّفات المدل‌ها عما تراه در وثائق التوافقية با OpenAI.

تنسيقات بارّف مدل. يقبل Fireworks عدة أنماط لبارّف مدل. يُعادل الباالج التنسيقات الشائعة، لكن إذا فشل التحقق، تحقق از مكتبة مدل‌ها Fireworks للبارّف الدقيق.

OpenRouter

توجيه مدل. يوجّه OpenRouter درخواستات به ارائه‌دهندهين متعددين. تُغلَّف الأخطاء از ارائه‌دهنده الأساسي بتنسيق خطأ OpenRouter. يُستخرج پیام الخطأ الفعلية وتُعرض.

تنسيق خطأ API. يُرجع OpenRouter الأخطاء ككائنات JSON. إذا بدت پیام الخطأ عامة، يُسجَّل الخطأ الخام روی مستوى DEBUG.

ZenMux / Z.AI

دعم البث. كخیر ارائه‌دهندهين پشتیبانی می‌کندان البث. إذا فشل البث:

ZenMux stream failed (status): error text

تحقق از أن مفتاح API الخاص بك لديه أذونات البث (بعض طبقات API تقيّد الوصول للبث).

---

التبديل الخودکار

چگونه کار می‌کند التبديل الخودکار

عندما يفشل ارائه‌دهنده الأساسي، يحاول Triggerfish هر مدل در قائمة failover بالترتيب:

models:
  failover:
    - openai/gpt-4o
    - google/gemini-2.5-pro

إذا نجح ارائه‌دهنده احتياطي، تُسجَّل پاسخ با ارائه‌دهنده الذي استُخدم. إذا فشل تمام ارائه‌دهندهين، يُرجع الخطأ الأخير للمستخدم.

"All providers exhausted"

فشل هر ارائه‌دهنده در السلسلة. تحقق از:

1. هل تمام مفاتيح API صالحة؟ اختبر هر ارائه‌دهنده روی حدة.
2. هل تمام ارائه‌دهندهين يعانون از انقطاعات؟ تحقق از صفحات حالتهم.
3. هل شبكتك تحظر HTTPS الصادر لهر از نقاط نهاية ارائه‌دهندهين؟

تكوين التبديل الخودکار

models:
  failover_config:
    max_retries: 3          # المحاوخیرت لهر ارائه‌دهنده قبل اخیرنتقال للتالي
    retry_delay_ms: 1000    # التأخير الأساسي بین المحاوخیرت
    conditions:             # ظروف الخطأ التي تُفعّل التبديل
      - timeout
      - server_error
      - rate_limited

"Primary provider not found in registry"

اسم ارائه‌دهنده در models.primary.provider خیر يطابق هر ارائه‌دهنده مكوّن در models.providers. تحقق از الأخطاء المطبعية.

"Classification model provider not configured"

ضبطت تجاوز classification_models يشير به ارائه‌دهنده غير موجود در models.providers:

models:
  classification_models:
    RESTRICTED:
      provider: local        # باید أن يكون این ارائه‌دهنده موجوداً در models.providers
      model: llama3.3:70b
  providers:
    # باید تعريف "local" اینجا
    local:
      model: llama3.3:70b
      endpoint: "http://localhost:11434"

---

سلوك إعادة المحاولة

يُعيد Triggerfish محاولة درخواستات ارائه‌دهنده عند الأخطاء المؤقتة (مهخیرت الشبكة، استجابات 5xx). ازطق إعادة المحاولة:

1. ينتظر بتمراجعه کنید أسي بین المحاوخیرت
2. يسجّل هر محاولة إعادة روی مستوى WARN
3. بعد استنفاد المحاوخیرت خیررائه‌دهنده واحد، ينتقل به التالي در سلسلة التبديل
4. اتصاخیرت البث لها ازطق إعادة محاولة ازفصل لإنشاء اخیرتصال مقابل الفشل أثناء البث

می‌توانید رؤية محاوخیرت إعادة المحاولة در السجخیرت:

Provider request failed with retryable error, retrying
Provider stream connection failed, retrying