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.📖 ملخص
- ثلاث فئات مشاكل: التثبيت، API، الأدوات — لكل منها مسارات حل
- مجموعة أدوات التصحيح: --debug، logging، تتبع الأحداث
- 6 مزوّدي ذكاء اصطناعي بمرجع تكوين كامل
- تحسين الأداء: تقليل زمن الاستجابة، تقليل التكلفة، التحكم في التزامن
- سكريبت فحص الصحة لتشخيص سريع للمشاكل
📝 تمارين
- أساسي (الصعوبة: ⭐): شغّل سكريبت فحص الصحة، تأكد أن بيئتك مُعدة بشكل صحيح.
- متوسط (الصعوبة: ⭐⭐): أعد مزوّدين، اكتب كوداً للتحول التلقائي إلى المزوّد الاحتياطي عند الفشل.
- متقدم (الصعوبة: ⭐⭐⭐): نفّذ حل مراقبة كامل: فحص دوري للمزوّدين، تتبع زمن استجابة، اتجاهات استخدام الرموز، تنبيه عند الشذوذ.