بنّي واستعمل قاعدة معارف محلية ديال الملفات بـ FastAPI وSQLite وMCP

نظرة عامة

المرحلة 1 من قاعدة المعرفة هي قاعدة معرفة للملفات بالحد الأدنى القابل للتطبيق، مبنية باستعمال FastAPI وSQLite والتخزين المحلي فالنظام ديال الملفات. كتدعم تسيير الوثائق بالمصادقة، والمجلدات المتداخلة، والمعاينات المحلية فالمتصفح، والبيانات الوصفية والوسوم، وأدوات المسؤول، ومعلومات التدقيق، والولوج للقراءة فقط بالنسبة لوكلاء الذكاء الاصطناعي عبر Model Context Protocol، أو MCP.

هاد المرحلة خفيفة عن قصد. ما كتحتاجش Docker ولا PostgreSQL ولا MinIO ولا LibreOffice ولا ONLYOFFICE ولا شي خدمة أخرى ديال قاعدة بيانات خدامة. PostgreSQL والتخزين ديال الكائنات مخليين لعملية ترحيل لاحقة.

شنو كيوفر المشروع

• المستخدمين اللي كينشئهم المسؤول، وتسجيل الدخول، والمصادقة باستعمال JWT.
• قواعد معرفة عامة بمجلدات متداخلة وتنقل عبر مسار التصفح.
• عرض الوثائق حسب المجلد، ورفع ملف واحد، والرفع بالجملة.
• دعم ملفات PDF والنصوص وMarkdown وHTML والصور وPowerPoint وWord وExcel.
• البيانات الوصفية ديال الوثائق، والوسوم، ومعلومات المالك واللي رفع الملف.
• معاينة وتحميل الملف الأصلي.
• القراءة داخل التطبيق لملفات النصوص وMarkdown وPDF وDOCX وXLSX وPPTX والصور.
• استخراج النص بشكل تقريبي من ملفات DOC وXLS وPPT القديمة.
• تعديل الوثائق من طرف المالك فقط، والحذف غير النهائي، والاسترجاع، وإعادة تسمية المجلدات، وحذف المجلدات الفارغة.
• سلة محذوفات للوثائق المحذوفة.
• نسخ الوثائق والمجلدات بين النطاقات، بما فيها النسخ التكراري للمجلدات ونسخ التخزين الفعلي.
• تسيير المستخدمين، وسجلات التدقيق، وسجلات استدعاءات MCP من طرف المسؤول فقط.
• واجهة REST API للقراءة فقط، وتوثيق OpenAPI مولد آليا، وتكامل MCP.

كيفاش كيخدم التخزين

التطبيق كينشئ ملفات التشغيل داخل backend/data/. قاعدة بيانات SQLite مخزنة فـ backend/data/knowledge_base.db، بينما الملفات المرفوعة وملفات Markdown المولدة كيتحطّو داخل backend/data/storage/.

التخزين المحلي فيه حماية من اجتياز المسارات. إعداد Docker Compose الموجود مخصص للترحيل اللاحق لـ PostgreSQL وتخزين الكائنات، وماشي ضروري فهاد المرحلة.

تثبيت الواجهة الخلفية

1. إنشاء ملف البيئة

حل PowerShell، دخل لمجلد backend ديال المستودع، ونسخ قالب البيئة الموجود فالجذر إلى backend/.env.

cd backend
Copy-Item ..\.env.example .env

الإعدادات التشغيلية محددة عبر .env.example وbackend/app/core/config.py وملفات التحكم ديال PowerShell الموجودة داخل scripts/.

2. إنشاء بيئة افتراضية ديال Python

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

شغّل هاد الأوامر من مجلد backend. تفعيل البيئة الافتراضية كيخلي حزم المشروع مفصولة على تثبيت Python العام ديالك.

3. تهيئة SQLite

python -m app.db.init_db

هاد الأمر كيهيّأ أو كيعيد إنشاء جداول SQLite المطلوبة. حيث إعادة إنشاء الجداول تقدر تأثر على البيانات الموجودة، خاصك تتعامل معاه بحذر من بعد ما تبدا تخزن الوثائق.

4. تشغيل FastAPI

uvicorn app.main:app --reload

من بعد كيولي خادم التطوير متاح فـ http://127.0.0.1:8000. الخيار --reload كيعيد تحميل التطبيق أوتوماتيكيا ملي كتتبدل ملفات المصدر.

5. فتح توثيق API

مشي لـ http://127.0.0.1:8000/docs باش تشوف وتجرب نقاط النهاية ديال OpenAPI المولدة.

التحقق من التثبيت

الاختبارات كتحتاج مجلد الواجهة الخلفية يكون فـ PYTHONPATH. فـ Windows Command Prompt، شغّل:

set PYTHONPATH=.
python -m pytest

وفـ PowerShell، استعمل:

$env:PYTHONPATH = "."
python -m pytest

المستودع كيوفر حتى ملفات تحكم منفصلة ديال PowerShell داخل scripts/ لتشغيل الخدمة وإعادة تشغيلها وإيقافها وعرض الحالة ديالها.

المصادقة مع REST API

المستخدمين كينشئهم المسؤول. منين يكون عندك حساب، صيفط اسم المستخدم وكلمة السر ديالو لنقطة نهاية تسجيل الدخول. الاستجابة فيها الرمز اللي خاص للطلبات المصادق عليها.

$body = @{
  username = "demo"
  password = "password-123"
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/auth/login `
  -ContentType "application/json" `
  -Body $body

$response

نسخ رمز الولوج اللي رجع واستعملو كبيانات اعتماد Bearer. صلاحيات الرمز كتتبع هوية ودور المستخدم المصادق عليه.

رفع وثيقة

نقطة نهاية الرفع كتقبل بيانات النموذج متعددة الأجزاء. عطِ معرّف قاعدة المعرفة، والوسوم الاختيارية، والملف، ورمز Bearer:

$token = "<access_token>"
$knowledgeBaseId = 1

curl.exe `
  -X POST `
  "http://127.0.0.1:8000/api/v1/documents/upload" `
  -H "Authorization: Bearer $token" `
  -F "knowledge_base_id=$knowledgeBaseId" `
  -F "tags=制度,测试" `
  -F "file=@D:\path\to\guide.txt"

المشروع كيدعم الرفع الفردي والرفع بالجملة. النسخ الأصلية المرفوعة كاتبقى فالتخزين المحلي، والمحتوى المدعوم يقدر يتحل فالقارئ داخل التطبيق.

إنشاء المجلدات واستعمالها

أنشئ مجلدا بإرسال معرّف قاعدة المعرفة والاسم ديالو لنقطة نهاية المجلدات:

$body = @{
  knowledge_base_id = 1
  name = "实验方案"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/folders `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body $body

باش ترفع داخل مجلد محدد، زِد folder_id لنموذج الرفع متعدد الأجزاء. الواجهة الويب كتضيفو أوتوماتيكيا ملي كتختار مجلدا.

محدِّد قاعدة المعارف كيبدا افتراضياً بـ 全部، بمعنى «الكل». هاد العرض كيبان فيه الوثائق والمجلدات الجذرية من جميع قواعد المعارف العمومية. ملي كتَنشئ مجلد، اختار قاعدة المعارف اللي غادي يتحط فيها من النافذة الحوارية. والرفع اللي كيتدار من عرض جميع قواعد المعارف كيستعمل أول قاعدة معارف متاحة، إلا إلا كان مجلد مختار.

فهم المعاينات المحلية فالمتصفح

الواجهة الأمامية كتجيب الملفات عبر الواجهة البرمجية الموثَّقة، وكتخليهم فذاكرة المتصفح، وكتعرضهم محلياً. كتستعمل vue3-office-preview لملفات DOCX وPPTX وXLS وXLSX، و@vue3-office/vue-pdf لملفات PDF، و@deot/docs-markdown لملفات Markdown. عرض PPTX كيستعمل pptx-renderer المضمَّن.

هاد المسار ما كيحتاجش LibreOffice ولا ONLYOFFICE ولا Docker ولا حزمة Python لمعاينة الوثائق. الملف الأصلي كيبقى فالتخزين المحلي. استخراج Markdown والمعالجة الاحتياطية للملفات القديمة .doc و.xls و.ppt كيبقاو من مسؤوليات الواجهة الخلفية.

ربط وكيل ذكاء اصطناعي عبر MCP

المستودع فيه خدمة MCP منفصلة للقراءة فقط. كتشارك قاعدة بيانات SQLite ديال تطبيق FastAPI، والتخزين المحلي، وسر JWT، وقارئ الوثائق. أدوات المرحلة 1 المتاحة هي:

• list_knowledge_bases
• list_documents
• search_knowledge
• get_document
• get_document_metadata

عملية MCP ما كتقدرش ترفع الملفات ولا تنقلها ولا تحذفها ولا تسيّر المجلدات. والولوج للوثائق ديالها محدود غير فالنطاق اللي مسموح للمستخدم المرتابط به يقراه.

تثبيت تبعيات MCP

أنشئ بيئة افتراضية خاصة بـ MCP من مجلد backend:

cd backend
python -m venv .mcp-venv
.\.mcp-venv\Scripts\python.exe -m pip install -r requirements-mcp.txt

تشغيل MCP عبر الإدخال والإخراج المعياريين

ضبط عملية MCP بنفس إعدادات قاعدة البيانات والتخزين المستعملة من طرف الواجهة البرمجية. حط رمز ولوج ديال تسجيل الدخول فـ KB_MCP_TOKEN، ومن بعد شغّل الخادم:

$env:PYTHONPATH = "."
$env:KB_MCP_TOKEN = "<access_token>"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

بالنسبة لعملاء stdio المحليين، يمكن ما تحطّش KB_MCP_TOKEN. فهاد الحالة، خاص الوكيل يعيّط لأداة authenticate مرة وحدة باستعمال اسم المستخدم وكلمة السر ديال المستخدم. الجلسة الناتجة قصيرة المدة وكتبقى غير فذاكرة عملية MCP.

ما تزيدش استدعاءات عادية ديال print() لخدمة MCP ديال stdio. الإخراج المعياري كينقل رسائل البروتوكول، لذلك خاص التشخيصات تمشي للإخراج المعياري للأخطاء.

تشغيل اختبار MCP السريع

$env:PYTHONPATH = "."
.\.mcp-venv\Scripts\python.exe scripts\mcp_stdio_smoke.py

إتاحة MCP عبر Streamable HTTP

ضبط النقل، وعنوان الاستماع، والمنفذ، والمسار، ووضعية انعدام الحالة قبل ما تشغّل نفس وحدة MCP:

$env:PYTHONPATH = "."
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8020"
$env:MCP_PATH = "/mcp"
$env:MCP_STATELESS_HTTP = "true"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

من بعد ما تضبط وكيلاً عكسياً بـ HTTPS، يقدر يكون العنوان العمومي هو https://your-domain/mcp. خاص العملاء البعيدين يرسلو Authorization: Bearer <access_token>، ومن الأفضل يستعملو نفس بيانات اعتماد Bearer المحمية ديال اتصال الواجهة البرمجية.

صفحة المتصفح /mcp-token.html تقدر تطلب رمز MCP للحساب اللي داخل، بلا ما تقرا كلمة السر ديالو ولا تخزنها. ويقدرو المسؤولين يستعملو /admin.html باش يسيّرو حالة المستخدمين، والأدوار، وكلمات السر، وسياسات انتهاء رموز MCP الخاصة بكل مستخدم، بما فيها الرموز الدائمة طويلة المدة.

نصائح تشغيلية متقدمة

• خلّي إعدادات الواجهة البرمجية وMCP متطابقة. بجوج الخدمات خاصهم يشيرو لنفس قاعدة بيانات SQLite ولنفس مسارات التخزين ويستعملو نفس سر JWT.
• استعمل هويات بأقل صلاحيات. وكيل MCP كيرث نطاق الوثائق القابلة للقراءة ديال المستخدم المرتابط بالرمز ديالو.
• حمي رموز Bearer. ما تحطّش بيانات اعتماد الواجهة البرمجية ولا MCP فمستودع الشيفرة ولا فالسجلات ولا فالإخراج العادي ديال وحدة التحكم.
• حافظ على بروتوكول stdio. صيفط تشخيصات MCP للإخراج المعياري للأخطاء عوض الإخراج المعياري.
• استعمل HTTPS عن بُعد. حط نقطة نهاية Streamable HTTP وراء وكيل عكسي بـ HTTPS قبل ما تتيحها خارج الجهاز المحلي.
• تذكّر حدود المرحلة 1. Docker Compose وPostgreSQL وتخزين الكائنات أهداف للترحيل، وماشي متطلبات التشغيل الحالية.
• راجع قيود الملكية. تعديل الوثائق، والحذف اللين، والاسترجاع، وإعادة تسمية المجلدات، وحذف المجلدات الفارغة عمليات مخصصة للمالكين فقط.
• استعمل توثيق الواجهة البرمجية المُولَّد. صفحة /docs هي الطريقة الأكثر مباشرة لفحص حقول الطلبات والاستجابات المتاحة خارج الأمثلة المعروضة هنا.

الخلاصة

كتوفّر المرحلة 1 من قاعدة المعارف أساساً محلياً عملياً لتنظيم الملفات الموثَّق، ومعاينتها، واسترجاعها، وإتاحة الوصول إليها من طرف الوكلاء. غير باستعمال Python وSQLite والتخزين المحلي، تقدر تهيّأ الخدمة، وترفع مجموعات وثائق منظَّمة، وتسيّر المجلدات والبيانات الوصفية، وتتيح بأمان أدوات معرفة للقراءة فقط عبر stdio المحلي أو نقل MCP عن بُعد باستعمال Streamable HTTP.