المعمارية السداسية النظيفة (المنافذ والمحولات - Hexagonal Architecture)
تمت هندسة LocalPilot بالاعتماد على نموذج التصميم المقاد بالنطاق (Domain-Driven Design) مع حدود سداسية صارمة تفصل بين منطق العمليات الأساسي وقواعد التحقق وبين أدوات واجهة المستخدم أو محركات التشغيل الخارجية، بحيث تعمل النواة بنسبة 100% دون أي تبعيات خارجية أو مكتبات TUI أو أدوات تشغيل ثانوية.
احتساب تفريغ الذاكرة للـ GPU والـ RAM مع حجز مساحة أمان 512MB للنظام.
أوزان ترجيح متعددة العوامل: التوافق، السرعة، جودة التكميم، والتسريع العتادي.
ثلاثية التنفيذ غير القابلة للتغيير: (المحرك الحسابي × نوع الخدمة × نمط النشر).
آلة حالات صارمة تعتمد الإثبات الفعلي: UNTESTED ← DOWNLOADED ← TESTED_HERE.
- • فحص أنظمة Linux و macOS Darwin
- • تسريع Apple Metal والذاكرة الموحدة
- • فحص كروت NVIDIA CUDA و AMD ROCm
- • فاحص جهوزية منافذ Loopback المحلية
- • عميل مكتبة ومستودع Ollama Registry
- • منصة Hugging Face Hub (أوزان GGUF)
- • الفهرس المحلي المعتمد (Seed Catalog)
- • التحقق التشفيري من تجزئة SHA-256 والحجم
- • مشغل llama.cpp كعملية فرعية معزولة
- • عميل Ollama Local REST API المباشر
- • عميل واجهات LM Studio / llmster
- • التخزين المنظم مع احتساب المراجع و SQLite
📐 استعراض المخطط الهيكلي أحادي المسافة (ASCII Blueprint) فتح المخطط
┌────────────────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ Typer CLI (localpilot) │ Textual TUI (Visual Hub) │
└─────────────────────────────────┬──────────────────────────────────────┘
▼
┌────────────────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
│ SetupWorkflow │ UpdateWorkflow │ JobManager │ ActivityService │
└─────────────────────────────────┬──────────────────────────────────────┘
▼
┌────────────────────────────────────────────────────────────────────────┐
│ DOMAIN LAYER │
│ CompatibilityPolicy │ ScoringPolicy │ ExecutionPlan │ VerifiedState │
└──────────────┬──────────────────┬──────────────────────┬───────────────┘
▼ ▼ ▼
┌──────────────────────┐ ┌──────────────────┐ ┌─────────────────────────┐
│ PLATFORM ADAPTERS │ │ SOURCE ADAPTERS │ │ RUNTIME ADAPTERS │
│ Linux / Darwin │ │ Ollama Registry │ │ llama.cpp runner │
│ Hardware Inspector │ │ HuggingFace Hub │ │ Ollama API Client │
│ Metal / CUDA check │ │ Local Seed DB │ │ LM Studio Client │
└──────────────────────┘ └──────────────────┘ └─────────────────────────┘
معمارية المحاور الثلاثة للتنفيذ (3-Axis Architecture)
يقوم LocalPilot بفصل عملية تشغيل نماذج اللغة إلى ثلاثة محاور متعامدة ومستقلة تماماً:
محركات الاستدلال الحسابي
المحرك البرمجي المسؤول عن ضرب المصفوفات وتوليد الرموز:
- • llama.cpp (GGUF, Metal, CUDA)
- • vLLM (أنظمة GPU المتقدمة)
خدمات الإدارة والتنسيق
الطبقة المسؤولة عن دورة حياة النماذج وإدارة الموارد:
- • Direct / Embedded (مباشر)
- • Ollama Daemon
- • LM Studio / llmster
أسلوب وطريقة التشغيل
كيفية استدعاء العملية والتواصل معها داخل النظام:
- • direct_worker (عملية فرعية معزولة)
- • local_api_service (خادم محلي)
- • container (حاوية معزولة)
خوارزمية ميزانية الذاكرة الآمنة (Memory Budget Math)
لتجنب تجميد نظام التشغيل أو انهيار العمليات، يطبق LocalPilot معادلات ميزانية دقيقة تختلف بحسب معمارية العتاد:
1. أجهزة Apple Silicon (macOS):
في الذاكرة الموحدة (Unified Memory)، يتم حجز ميزانية آمنة لا تتجاوز:
هذا يضمن بقاء مساحة كافية لتطبيقات النظام وواجهة المستخدم الرسومية.
2. حواسيب Linux وبطاقات NVIDIA:
حساب دقيق لطبقات كارت الشاشة (GPU Offload Layers):
KV_Cache = 2 * layers * heads * dim * context * bytes
إذا لم تتسع VRAM بالكامل، يتم تفعيل التشغيل الهجين (Partial Offload) بين كرت الشاشة والرام.
دليل أوامر سطر الأوامر (CLI Reference)
جميع الأوامر تدعم الخيارات --plain للأتمتة النصية و --json للمخرجات المهيكلة:
| الأمر | الوصف الموجز | مثال على الاستخدام |
|---|---|---|
| localpilot doctor | فحص العتاد، سعة الذاكرة، كروت الشاشة، ومحركات التشغيل المتوفرة. | localpilot doctor --json |
| localpilot discover | استعراض النماذج المتوافقة بنسبة 100% مع جهازك وتقييم أدائها. | localpilot discover -q "qwen" |
| localpilot setup <ID> | تنزيل النموذج، فحص البصمة، وإجراء فحص استدلال حقيقي قبل الاعتماد. | localpilot setup cand_llama32_3b |
| localpilot run <ID> | بدء تشغيل النموذج المحمل وجعله جاهزاً للمحادثة واستقبال الطلبات. | localpilot run inst_llama32_3b |
| localpilot chat <ID> | بدء محادثة فورية وتدفق الكلمات مباشرة في الطرفية بشكل خاص. | localpilot chat inst_llama32_3b |
| localpilot stop <ID> | إيقاف النموذج وتفريغ الذاكرة فوراً وإعادتها لنظام التشغيل. | localpilot stop inst_llama32_3b |
| localpilot installed | عرض مكتبة النماذج المثبتة على حاسوبك وأحجامها وحالتها. | localpilot installed |
| localpilot running | عرض النماذج والعمليات النشطة قيد الاستخدام في الخلفية. | localpilot running --json |
| localpilot docs | استعراض المراجع الهندسية العميقة للمعمارية، تفريغ الذاكرة، والأمان في الطرفية. | localpilot docs --topic technical |
| localpilot remove <ID> | حذف ملفات النموذج المحملة واحتساب المراجع وتحرير مساحة القرص الصلب فوراً. | localpilot remove llama3.2:3b -y |
| localpilot logs | استعراض سجلات التشغيل مع حجب المفاتيح السرية والمسارات الشخصية تلقائياً. | localpilot logs --lines 50 |
| localpilot activity | سجل زمني لعمليات التثبيت، التشغيل، والإيقاف لتدقيق النشاط. | localpilot activity --json |
| localpilot storage | تفصيل استهلاك التخزين للملفات المؤقتة والأوزان وقاعدة البيانات. | localpilot storage |
| localpilot guide | استعراض التوثيق المدمج التفاعلي للمبتدئين والمطورين في الطرفية. | localpilot guide novice |
| localpilot support | توليد تقرير تشخيصي منقح بالكامل للمساعدة وحل المشكلات. | localpilot support -o ./debug.json |
| localpilot self update | فحص مستودع PyPI وترقية تطبيق LocalPilot لأحدث إصدار رسمي. | localpilot self update |
| localpilot self uninstall | إلغاء تثبيت التطبيق بنظافة، مع خيار حذف النماذج أو الاحتفاظ بها. | localpilot self uninstall --purge-models |