Pi Agent: Troubleshooting & AI Providers

آخر تحديث: 2026-08-31

--- title: "حل المشكلات ومزوّدو الذكاء الاصطناعي" description: "دليل حل المشكلات الشائعة في Pi Agent ومرجع التكوين التفصيلي لجميع مزوّدي الذكاء الاصطناعي المدعومين." order: 20 lang: ar

لا تهلع عند حدوث مشاكل — 90% من المشاكل يمكن حلها في هذه الصفحة.


1. حل المشكلات الشائعة

(1) مشاكل التثبيت

المشكلة السبب الحل
فشل pip install إصدار pip قديم pip install --upgrade pip
انتهاء مهلة الشبكة مشاكل شبكة استخدم مرآة: -i https://pypi.tuna.tsinghua.edu.cn/simple
خطأ تجميع أدوات بناء مفقودة ثبّت build-essential (Linux) أو VS Build Tools (Windows)
خطأ صلاحيات التثبيت العام يحتاج root استخدم --user أو virtualenv

(2) مشاكل استدعاء API

رمز الخطأ المعنى الحل
401 فشل المصادقة تحقق من مفتاح API
429 حد المعدل قلّل تكرار الطلبات أو ارقِ خطتك
500 خطأ في الخادم حاول لاحقاً
503 الخدمة غير متاحة تحقق من صفحة حالة المزوّد

(3) مشاكل استدعاء الأدوات

المشكلة السبب الحل
الأداة لا تستجيب صلاحيات غير كافية تحقق من مستوى الثقة وصلاحيات الأداة
انتهت مهلة الأداة التنفيذ طويل جداً زِد max_execution_time
نتيجة فارغة معلمات إدخال سيئة تحقق من أنواع المعلمات وتنسيقها
ملف غير موجود مسار خاطئ استخدم مسارات مطلقة

2. نصائح التصحيح

(1) تفعيل وضع التصحيح

BASH
pi-agent chat --debug
PYTHON
agent = Agent(name="debug", debug=True)

(2) تسجيل مفصّل

PYTHON
import logging
logging.basicConfig(level=logging.DEBUG)

agent = Agent(name="debug")
agent.chat("Test message")

(3) تتبع الأحداث

PYTHON
@agent.on("*")
def trace(event):
    print(f"[{event.timestamp}] {event.name}: {event.data}")

3. مرجع مزوّدي الذكاء الاصطناعي

(1) DeepSeek

YAML
providers:
  deepseek:
    api_key: "sk-xxxxxxxx"
    base_url: "https://api.deepseek.com"
    models:
      - name: deepseek-chat
        context: 64000
        input_price: 1.0
        output_price: 2.0
      - name: deepseek-reasoner
        context: 64000
        input_price: 4.0
        output_price: 16.0

(2) OpenAI

YAML
providers:
  openai:
    api_key: "sk-xxxxxxxx"
    base_url: "https://api.openai.com/v1"
    models:
      - name: gpt-4o
        context: 128000
        input_price: 2.5
        output_price: 10.0
      - name: gpt-4o-mini
        context: 128000
        input_price: 0.15
        output_price: 0.6

(3) Anthropic

YAML
providers:
  anthropic:
    api_key: "sk-ant-xxxxxxxx"
    base_url: "https://api.anthropic.com"
    models:
      - name: claude-sonnet-4-20250514
        context: 200000
        input_price: 3.0
        output_price: 15.0
      - name: claude-3-5-haiku-20241022
        context: 200000
        input_price: 0.8
        output_price: 4.0

(4) Google Gemini

YAML
providers:
  gemini:
    api_key: "AIzaxxxxxxxx"
    base_url: "https://generativelanguage.googleapis.com/v1beta"
    models:
      - name: gemini-2.0-flash
        context: 1048576
        input_price: 0.1
        output_price: 0.4

(5) llama.cpp

YAML
providers:
  local:
    type: llama_cpp
    model_path: "./models/qwen2.5-7b-instruct-q4_k_m.gguf"
    n_gpu_layers: -1
    n_ctx: 4096

(6) Ollama

YAML
providers:
  ollama:
    type: ollama
    base_url: "http://localhost:11434"
    model: "qwen2.5:7b"

4. تحسين الأداء

PYTHON
agent = Agent(
    max_tokens=2048,
    temperature=0.3,
    context_window=4096,
    provider="deepseek",
    auto_summarize=True
)

5. فحص الصحة

مثال 1: سكريبت تشخيصي (الصعوبة: ⭐)

PYTHON
from pi_agent import Config, Agent

print("=== Pi Agent Diagnostics ===")

config = Config.load()
print(f"Config: {'OK' if config else 'Not found'}")

for name, provider in config.providers.items():
    try:
        agent = Agent(provider=name)
        agent.chat("ping")
        print(f"Provider {name}: OK")
    except Exception as e:
        print(f"Provider {name}: FAIL ({e})")

print("=== Diagnostics Complete ===")

❓ أسئلة شائعة

س الوكيل لا يستجيب أبداً؟
ج تحقق من الشبكة وصلاحية مفتاح API وحالة خدمة المزوّد. فعّل وضع التصحيح لسجلات طلبات مفصلة.
س صلاحية استدعاء الأداة مرفوضة؟
ج تحقق من مستوى ثقة المشروع. shell وfile_write يحتاجان مستوى trusted أو restricted.
س التبديل إلى نموذج أرخص؟
ج تفاعلي: /model gpt-4o-mini. كود: Agent(model="deepseek-chat"). تكوين: غيّر default_model.

📖 ملخص


📝 تمارين

  1. أساسي (الصعوبة: ⭐): شغّل سكريبت فحص الصحة، تأكد أن بيئتك مُعدة بشكل صحيح.
  2. متوسط (الصعوبة: ⭐⭐): أعد مزوّدين، اكتب كوداً للتحول التلقائي إلى المزوّد الاحتياطي عند الفشل.
  3. متقدم (الصعوبة: ⭐⭐⭐): نفّذ حل مراقبة كامل: فحص دوري للمزوّدين، تتبع زمن استجابة، اتجاهات استخدام الرموز، تنبيه عند الشذوذ.
Web-Tutorial.com

فريق Web-Tutorial التقني

منصة دروس برمجية يديرها عدة مطورين. كل درس يتم كتابته ومراجعته بواسطة مطورين متخصصين في المجال. نعمل على ضمان دقة وموثوقية المحتوى — إذا لاحظت أي مشكلة، فيرجى إخبارنا.

100%