70 lines
5.6 KiB
Markdown
70 lines
5.6 KiB
Markdown
# SovereignAI Starter
|
|
|
|
مشروع تعليمي لبناء مساعد ذكاء اصطناعي محلي قابل للتوسع. النموذج المحمّل حاليًا: `qwen2.5:1.5b-instruct-q4_K_M` (نحو 986 ميغابايت).
|
|
|
|
## مكونات النسخة الأولى
|
|
- FastAPI كواجهة HTTP محلية.
|
|
- وكيل تجريبي بأداة حساب آمنة ومحدودة.
|
|
- واجهة `/docs` لاستكشاف الـ API من المتصفح.
|
|
- يمكن توصيلها بخادم نموذج محلي يوفّر واجهة OpenAI مثل Ollama.
|
|
- دون إعداد عنوان خادم نموذج، تعمل الواجهة في وضع العرض التجريبي.
|
|
|
|
## التشغيل على Windows
|
|
1. ثبّت Python 3.11 أو أحدث.
|
|
2. افتح PowerShell داخل المجلد. إذا كانت `.venv` موجودة، تخطَّ خطوة إنشائها وثبّت الاعتماديات فقط عند الحاجة.
|
|
3. أنشئ بيئة افتراضية وثبت الاعتماديات:
|
|
|
|
```powershell
|
|
py -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
python -m pip install -r requirements.txt
|
|
```
|
|
|
|
4. (اختياري على جهاز جديد فقط) شغّل Ollama واسحب النموذج:
|
|
|
|
```powershell
|
|
ollama pull qwen2.5:1.5b-instruct-q4_K_M
|
|
```
|
|
|
|
الخادم الحالي مضبوط افتراضيًا على Ollama المحلي واسم النموذج أعلاه. لتغييرهما عرّف المتغيرات في نافذة PowerShell نفسها:
|
|
|
|
```powershell
|
|
$env:LOCAL_LLM_BASE_URL = "http://127.0.0.1:11434/v1"
|
|
$env:LOCAL_MODEL = "qwen2.5:1.5b-instruct-q4_K_M"
|
|
```
|
|
|
|
راجع رخصة النموذج المختار وشروطه الحالية قبل الاستخدام التجاري. تنزيل النموذج يحتاج اتصال إنترنت ومساحة تخزين.
|
|
|
|
5. شغل الـ API على جهازك فقط (أو شغل `start-api.ps1`):
|
|
|
|
```powershell
|
|
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
|
|
```
|
|
|
|
6. افتح `http://127.0.0.1:8000/docs`.
|
|
|
|
## نقاط التجربة
|
|
- `GET /health` للتأكد من أن الخدمة تعمل.
|
|
- `POST /v1/chat/completions` لإرسال رسالة.
|
|
- `POST /v1/agent/run` لتجربة الوكيل والأداة الحسابية.
|
|
- `POST /v1/chat/completions` يمرر الطلب إلى الخادم المحلي عند ضبط المتغيرين أعلاه.
|
|
|
|
الخدمة مربوطة بـ `127.0.0.1` عمدًا، فلا تعرضها على الشبكة أو الإنترنت الآن. الوكيل الحالي يمرر السؤال النصي للنموذج، وينفذ الحسابات البسيطة بأداة حساب محلية محدودة. لا يقرأ ملفات ولا ينفذ أوامر النظام.
|
|
|
|
## واجهة Flutter
|
|
|
|
يوجد تطبيق Flutter متعدد المنصات في `flutter_app`، ويبدأ كواجهة محادثة ويب عربية متصلة بهذا الـ API. راجع `flutter_app/README.md` للتشغيل. عنوان الاتصال الافتراضي `http://127.0.0.1:8000`؛ التطبيق يسمح بتغييره من الإعدادات.
|
|
|
|
### المحادثات والصوت
|
|
|
|
- تحفظ FastAPI المحادثات والرسائل في SQLite محليًا. على Windows يوجد الملف في `%LOCALAPPDATA%\SovereignAI\data\sovereign_ai.sqlite3`، وخارج مجلد المشروع لتجنب مزامنة قاعدة البيانات مع OneDrive.
|
|
- لكل سجل محادثة `user_id`، وتُفلتر عمليات القراءة والتعديل والحذف على أساسه. في النسخة المحلية يوفّر FastAPI ملف مستخدم تطوير ثابتًا، وترسل الواجهة معرّفه في ترويسة `X-User-ID`؛ هذا ليس تسجيل دخول أو عزلًا أمنيًا صالحًا للاستضافة العامة.
|
|
- جدول `user_identities` مهيأ لربط المستخدم مستقبلًا بمعرّف مزود مثل Google أو البريد/الهاتف، لكن تدفق تسجيل الدخول لم يُنفذ بعد. عند إضافة مستخدمين حقيقيين يجب استبدال الترويسة بهوية موثقة من جلسة/JWT.
|
|
- رسائل الدردشة ترسل إلى Ollama المحلي. التسجيل الصوتي يحوّل إلى نص عبر Groq Whisper؛ لذلك يُرسل الصوت إلى Groq عند الضغط على إيقاف التسجيل.
|
|
- مفتاح Groq يجب أن يبقى في متغير البيئة `GROQ_API_KEY` الخاص بخادم FastAPI، ولا يوضع في Flutter أو في ملفات المشروع.
|
|
- على جهاز التطوير الحالي حُفظ المتغير في بيئة Windows الخاصة بالمستخدم، وليس في ملف `.env`. يقرأه `start-api.ps1` عند تشغيل الخادم، ويظهر `/health` حالة الإعداد فقط دون إظهار المفتاح. عند استضافة الخادم لاحقًا، أضف المفتاح إلى إعدادات البيئة السرية في خدمة الاستضافة.
|
|
|
|
### عنوان الشبكة
|
|
|
|
عنوان Wi-Fi الحالي لهذا الجهاز `192.168.100.20` والبوابة `192.168.100.1`، والعنوان موزع عبر DHCP. لتثبيته، احجز العنوان الحالي من صفحة الراوتر ضمن DHCP Reservation / Address Reservation للجهاز `DESKTOP-13T75A5`، مستخدمًا MAC واجهة Wi-Fi الظاهر في `ipconfig /all`. لا تغيّر إعداد IPv4 يدويًا في Windows بالتزامن مع حجز DHCP. هذا يثبت العنوان داخل الشبكة المنزلية فقط؛ لا يفتح وصولًا من الإنترنت. الخوادم ما زالت مربوطة بـ `127.0.0.1`.
|