Pi Agent: Configuration Deep Dive
آخر تحديث: 2026-08-31
--- title: "تفاصيل التكوين" description: "دليل شامل لنظام تكوين Pi Agent، بما في ذلك بنية الملفات وتجاوز الطبقات ومتغيرات البيئة والتكوين الديناميكي." order: 12 lang: ar
التكوين هو "لوحة التحكم" لـ Pi Agent — افهمه لضبط كل معلمة بدقة.
1. طبقات التكوين
أولوية تكوين Pi Agent من الأقل إلى الأعلى:
TEXT
📖 للعرض فقط
الافتراضيات → التكوين العام → تكوين المشروع → متغيرات البيئة → معلمات الكود → معلمات CLI
(الأقل) (الأعلى)
الأولوية الأعلى تتجاوز الأقل.
2. التكوين العام
الموقع: ~/.pi-agent/config.yaml
YAML
default_provider: deepseek
default_model: deepseek-chat
providers:
deepseek:
api_key: "sk-xxxxxxxx"
base_url: "https://api.deepseek.com"
model: "deepseek-chat"
temperature: 0.7
max_tokens: 4096
openai:
api_key: "sk-xxxxxxxx"
model: "gpt-4o"
display:
theme: dark
code_highlight: true
show_token_count: true
session:
auto_save: true
save_dir: "~/.pi-agent/sessions"
templates_dir: "~/.pi-agent/templates"
skills_dir: "~/.pi-agent/skills"
3. تكوين المشروع
الموقع: .pi-agent.yaml في جذر المشروع
YAML
project:
name: "my_fastapi_app"
description: "مشروع FastAPI"
agent:
system_prompt: "أنت المساعد المخصص لهذا المشروع FastAPI"
tools:
- file_reader
- shell
- search
context:
inject:
- "README.md"
- "requirements.txt"
providers:
deepseek:
temperature: 0.3
4. متغيرات البيئة
جميع عناصر التكوين لها متغيرات بيئة مقابلة ببادئة PI_:
| عنصر التكوين | متغير البيئة |
|---|---|
| providers.deepseek.api_key | PI_DEEPSEEK_API_KEY |
| default_provider | PI_DEFAULT_PROVIDER |
| display.theme | PI_DISPLAY_THEME |
| session.auto_save | PI_SESSION_AUTO_SAVE |
| agent.temperature | PI_AGENT_TEMPERATURE |
5. التكوين في الكود
PYTHON
from pi_agent import Agent
agent = Agent(
name="custom",
provider="deepseek",
model="deepseek-chat",
temperature=0.5,
max_tokens=2048,
tools=["search", "calculator"],
system_prompt="أنت مساعد رياضيات",
context_window=8192,
truncation_strategy="summarize",
auto_save=True
)
6. التكوين الديناميكي
تعديل التكوين في وقت التشغيل:
PYTHON
agent.configure(model="deepseek-reasoner", temperature=0.2)
agent.enable_tool("shell")
agent.disable_tool("search")
agent.set_system_prompt("أنت الآن مراجع أمان صارم")
7. مرجع التكوين
| الفئة | العنصر | الافتراضي | الوصف |
|---|---|---|---|
| Agent | name | "agent" | اسم الوكيل |
| Agent | system_prompt | "" | موجه النظام |
| Agent | temperature | 0.7 | درجة الحرارة |
| Agent | max_tokens | 4096 | الحد الأقصى لرموز المخرجات |
| Agent | context_window | 8192 | نافذة السياق |
| Agent | truncation_strategy | "remove_oldest" | استراتيجية الاقتطاع |
| Provider | api_key | "" | مفتاح API |
| Provider | base_url | "" | URL الأساسي لـ API |
| Provider | model | "" | اسم النموذج |
| Display | theme | "dark" | سمة الواجهة |
| Session | auto_save | false | حفظ تلقائي للجلسات |
❓ أسئلة شائعة
س ما الذي يجب تكوينه؟
ج فقط مفتاح API (
providers.<name>.api_key). كل شيء آخر له قيم افتراضية. النماذج المحلية لا تحتاج حتى إلى مفتاح.س تعارض تكوين المشروع مع التكوين العام؟
ج تكوين المشروع يفوز — "مبدأ القرب": المشروع > المستخدم > الافتراضيات العامة.
س هل يمكنني إيداع التكوين في Git؟
ج تكوين المشروع (.pi-agent.yaml) نعم، لكن لا تضمّن مفاتيح API. استخدم متغيرات البيئة للأسرار.
📖 ملخص
- الأولوية: الافتراضات < عام < مشروع < متغيرات البيئة < كود < CLI
- العام:
~/.pi-agent/config.yaml؛ المشروع:.pi-agent.yaml - متغيرات البيئة:
PI_+ اسم المفتاح بالأحرف الكبيرة - التكوين الديناميكي في وقت التشغيل مدعوم
- مفاتيح API عبر متغيرات البيئة، لا تُودع أبداً في Git
📝 تمارين
- أساسي (الصعوبة: ⭐): أنشئ ملف تكوين عام بمزوّد LLM واحد على الأقل.
- متوسط (الصعوبة: ⭐⭐): أنشئ
.pi-agent.yamlلمشروعك بموجه نظام مخصص وأدوات. - متقدم (الصعوبة: ⭐⭐⭐): اكتب سكريبت تحقق من التكوين يفحص الاكتمال والاتساق.