-->

⏱️ وقت القراءة المتوقع: 15 دقيقة

مقدمة عن MaxKB

MaxKB هو منصة قوية وسهلة الاستخدام مفتوحة المصدر مصممة لبناء عملاء الذكاء الاصطناعي على مستوى المؤسسات. تم تطوير هذا الحل الشامل من قبل فريق 1Panel، وقد حصل على اهتمام كبير بأكثر من 18,000 نجمة على GitHub، مما يجعله واحداً من أكثر منصات عملاء الذكاء الاصطناعي المؤسسية شعبية المتاحة اليوم.

ما يجعل MaxKB مميزاً

يتميز MaxKB في مجال عملاء الذكاء الاصطناعي المزدحم من خلال تقديم:

  • بنية جاهزة للمؤسسات: مبنية مع وضع القابلية للتوسع والأمان في الاعتبار
  • دعم متعدد النماذج: متوافق مع نماذج LLM المختلفة بما في ذلك Llama3 و DeepSeek-R1 و Qwen3
  • تكامل قاعدة المعرفة: قدرات RAG (الجيل المعزز بالاسترجاع) المتقدمة
  • منشئ سير العمل المرئي: واجهة سهلة الاستخدام لإنشاء سير عمل عملاء معقدة
  • مرونة المصدر المفتوح: مرخص بـ GPL-3.0 مع دعم مجتمعي نشط

نظرة عامة على البنية التقنية

مجموعة التقنيات الأساسية

يستفيد MaxKB من مجموعة تقنيات حديثة وقوية:

  • الواجهة الأمامية: Vue.js مع TypeScript لواجهات مستخدم متجاوبة
  • الخلفية: Python مع إطار عمل Django لخدمات API قوية
  • إطار عمل LLM: LangChain للتكامل السلس لنماذج الذكاء الاصطناعي
  • قاعدة البيانات: PostgreSQL مع امتداد pgvector لتخزين المتجهات
  • النشر: Docker و Docker Compose للنشر المحتوى

الميزات الرئيسية

  1. إدارة العملاء: إنشاء وتكوين وإدارة عملاء ذكاء اصطناعي متعددة
  2. قاعدة المعرفة: رفع وإدارة المستندات لتطبيقات RAG
  3. تكامل النماذج: دعم لمزودي ونماذج LLM المختلفة
  4. إدارة المحادثات: واجهة محادثة متقدمة مع وعي السياق
  5. وصول API: APIs RESTful للتكامل مع الأنظمة الموجودة
  6. بنية متعددة المستأجرين: دعم للمؤسسات والمستخدمين المتعددين

دليل التثبيت والإعداد

المتطلبات المسبقة

قبل تثبيت MaxKB، تأكد من أن نظامك يلبي المتطلبات التالية:

  • نظام التشغيل: Linux أو macOS أو Windows مع WSL2
  • Docker: الإصدار 20.10 أو أحدث
  • Docker Compose: الإصدار 2.0 أو أحدث
  • الذاكرة: 4GB RAM كحد أدنى (8GB موصى)
  • التخزين: 10GB مساحة خالية على الأقل

الطريقة 1: نشر Docker Compose (موصى)

الخطوة 1: استنساخ المستودع

# استنساخ مستودع MaxKB
git clone https://github.com/1Panel-dev/MaxKB.git
cd MaxKB

# التبديل إلى أحدث إصدار مستقر
git checkout v2

الخطوة 2: تكوين متغيرات البيئة

# إنشاء تكوين البيئة
cp .env.example .env

# تحرير ملف التكوين
nano .env

متغيرات البيئة الأساسية:

# تكوين قاعدة البيانات
POSTGRES_DB=maxkb
POSTGRES_USER=maxkb
POSTGRES_PASSWORD=your_secure_password

# تكوين Redis
REDIS_PASSWORD=your_redis_password

# تكوين MaxKB
SECRET_KEY=your_secret_key_here
DEBUG=false
ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.com

# تكوين التخزين
MEDIA_ROOT=/opt/maxkb/media
STATIC_ROOT=/opt/maxkb/static

الخطوة 3: تشغيل MaxKB

# بدء جميع الخدمات
docker-compose up -d

# فحص حالة الخدمة
docker-compose ps

# عرض السجلات
docker-compose logs -f

الخطوة 4: الإعداد الأولي

# الوصول إلى الحاوية للإعداد الأولي
docker-compose exec maxkb python manage.py migrate

# إنشاء حساب المستخدم الرئيسي
docker-compose exec maxkb python manage.py createsuperuser

# جمع الملفات الثابتة
docker-compose exec maxkb python manage.py collectstatic --noinput

الطريقة 2: التثبيت اليدوي

الخطوة 1: تثبيت التبعيات

# تثبيت تبعيات Python
pip install -r requirements.txt

# تثبيت تبعيات Node.js للواجهة الأمامية
cd ui
npm install
npm run build
cd ..

الخطوة 2: إعداد قاعدة البيانات

# تثبيت PostgreSQL و pgvector
# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# تمكين امتداد pgvector
sudo -u postgres psql
CREATE DATABASE maxkb;
CREATE USER maxkb WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE maxkb TO maxkb;
CREATE EXTENSION vector;
\q

الخطوة 3: التكوين

# تكوين إعدادات Django
export DATABASE_URL=postgresql://maxkb:your_password@localhost/maxkb
export SECRET_KEY=your_secret_key
export DEBUG=False

# تشغيل الترحيلات
python manage.py migrate

# إنشاء مستخدم رئيسي
python manage.py createsuperuser

# بدء خادم التطوير
python manage.py runserver 0.0.0.0:8000

التكوين والإعداد

1. تسجيل الدخول والإعداد الأولي

  1. الوصول لواجهة الويب: انتقل إلى http://localhost:8000 في متصفحك
  2. تسجيل الدخول: استخدم بيانات اعتماد المستخدم الرئيسي التي أنشأتها أثناء الإعداد
  3. تكوين النظام: أكمل معالج إعداد النظام الأولي

2. تكوين النماذج

إضافة نماذج OpenAI

{
  "provider": "openai",
  "api_key": "your_openai_api_key",
  "base_url": "https://api.openai.com/v1",
  "models": [
    {
      "name": "gpt-4",
      "max_tokens": 8192,
      "temperature": 0.7
    },
    {
      "name": "gpt-3.5-turbo",
      "max_tokens": 4096,
      "temperature": 0.7
    }
  ]
}

إضافة النماذج المحلية (Ollama)

# تثبيت Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# سحب النماذج
ollama pull llama3
ollama pull qwen2

# التكوين في MaxKB
{
  "provider": "ollama",
  "base_url": "http://localhost:11434",
  "models": ["llama3", "qwen2"]
}

3. إعداد قاعدة المعرفة

رفع ومعالجة المستندات

  1. إنشاء قاعدة معرفة: انتقل إلى قاعدة المعرفة ← إنشاء جديد
  2. رفع المستندات: دعم لصيغ PDF، DOCX، TXT، MD
  3. تكوين التقسيم: تعيين حجم القطع ومعاملات التداخل
  4. نموذج التضمين: اختيار نموذج التضمين المناسب لغتك

تكوين قاعدة بيانات المتجهات

# إعدادات قاعدة بيانات المتجهات
vector_db:
  type: "pgvector"
  connection:
    host: "localhost"
    port: 5432
    database: "maxkb"
    user: "maxkb"
    password: "your_password"
  embedding:
    model: "text-embedding-ada-002"
    dimensions: 1536

إنشاء أول عميل ذكاء اصطناعي

الخطوة 1: إنشاء العميل

  1. انتقل للعملاء: انقر على “العملاء” في التنقل الرئيسي
  2. إنشاء عميل جديد: انقر على زر “إنشاء عميل”
  3. المعلومات الأساسية:
    • اسم العميل: “روبوت دعم العملاء”
    • الوصف: “مساعد ذكي لاستفسارات العملاء”
    • الصورة الرمزية: رفع صورة رمزية مخصصة

الخطوة 2: اختيار النموذج

{
  "model_provider": "openai",
  "model_name": "gpt-4",
  "temperature": 0.7,
  "max_tokens": 1000,
  "top_p": 1.0,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0
}

الخطوة 3: تكامل قاعدة المعرفة

  1. اختيار قواعد المعرفة: اختر قواعد المعرفة ذات الصلة
  2. تكوين إعدادات RAG:
    • عتبة التشابه: 0.7
    • أقصى مستندات مسترجعة: 5
    • استراتيجية الاسترجاع: “similarity”

الخطوة 4: هندسة المطالبة

مطالبة النظام:
أنت مساعد دعم عملاء مفيد لـ [اسم الشركة]. 
لديك وصول إلى قاعدة معرفتنا ويجب أن تقدم استجابات دقيقة 
ومفيدة بناءً على المعلومات المتاحة.

الإرشادات:
- كن مهذباً ومهنياً دائماً
- إذا لم تعرف شيئاً، اعترف بذلك واعرض التصعيد
- قدم حلولاً محددة عندما يكون ذلك ممكناً
- اطرح أسئلة توضيحية عند الحاجة

المعرفة المتاحة:
{context}

الخطوة 5: اختبار عميلك

  1. واجهة الاختبار: استخدم واجهة المحادثة المدمجة لاختبار الاستجابات
  2. استرجاع المعرفة: تحقق من أن المستندات ذات الصلة يتم استرجاعها
  3. جودة الاستجابة: قيم دقة وفائدة الاستجابات

الميزات المتقدمة والتخصيص

1. أتمتة سير العمل

يدعم MaxKB أتمتة سير العمل المعقدة من خلال منشئه المرئي:

إنشاء سير عمل متعدد الخطوات

{
  "workflow": {
    "name": "معالج استفسارات العملاء",
    "steps": [
      {
        "id": "intent_detection",
        "type": "classification",
        "model": "gpt-4",
        "prompt": "صنف نية العميل: دعم، مبيعات، فوترة، تقني"
      },
      {
        "id": "route_to_specialist",
        "type": "conditional",
        "conditions": {
          "دعم": "عميل_دعم_عام",
          "تقني": "متخصص_تقني",
          "فوترة": "عميل_فوترة"
        }
      },
      {
        "id": "knowledge_search",
        "type": "rag",
        "knowledge_base": "customer_support_kb",
        "max_results": 3
      },
      {
        "id": "response_generation",
        "type": "generation",
        "model": "gpt-4",
        "template": "بناءً على السياق التالي: {context}\n\nقدم استجابة مفيدة لـ: {query}"
      }
    ]
  }
}

2. تكامل API

يوفر MaxKB APIs REST شاملة لتكامل النظام:

المصادقة

import requests

# تسجيل الدخول والحصول على الرمز المميز
login_response = requests.post('http://localhost:8000/api/auth/login/', {
    'username': 'your_username',
    'password': 'your_password'
})
token = login_response.json()['token']

# استخدام الرمز المميز للطلبات المصادق عليها
headers = {'Authorization': f'Bearer {token}'}

API تفاعل العميل

# إرسال رسالة للعميل
def chat_with_agent(agent_id, message, conversation_id=None):
    url = f'http://localhost:8000/api/agents/{agent_id}/chat/'
    payload = {
        'message': message,
        'conversation_id': conversation_id
    }
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

# مثال على الاستخدام
result = chat_with_agent(
    agent_id='123',
    message='كيف يمكنني إعادة تعيين كلمة المرور؟',
    conversation_id='conv_456'
)

print(result['response'])

إدارة قاعدة المعرفة

# رفع مستند إلى قاعدة المعرفة
def upload_document(kb_id, file_path):
    url = f'http://localhost:8000/api/knowledge-bases/{kb_id}/documents/'
    
    with open(file_path, 'rb') as file:
        files = {'file': file}
        response = requests.post(url, files=files, headers=headers)
    
    return response.json()

# البحث في قاعدة المعرفة
def search_knowledge(kb_id, query, limit=5):
    url = f'http://localhost:8000/api/knowledge-bases/{kb_id}/search/'
    payload = {
        'query': query,
        'limit': limit,
        'threshold': 0.7
    }
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

3. تكامل النماذج المخصصة

إضافة مزودي LLM مخصصين

# مثال: تكامل مزود نموذج مخصص
class CustomModelProvider:
    def __init__(self, api_key, base_url):
        self.api_key = api_key
        self.base_url = base_url
    
    def generate_response(self, prompt, model_config):
        headers = {
            'Authorization': f'Bearer {self.api_key}',
            'Content-Type': 'application/json'
        }
        
        payload = {
            'model': model_config['model'],
            'prompt': prompt,
            'max_tokens': model_config.get('max_tokens', 1000),
            'temperature': model_config.get('temperature', 0.7)
        }
        
        response = requests.post(
            f'{self.base_url}/completions',
            headers=headers,
            json=payload
        )
        
        return response.json()['choices'][0]['text']

# تسجيل المزود المخصص
custom_provider = CustomModelProvider(
    api_key='your_custom_api_key',
    base_url='https://your-custom-llm-api.com/v1'
)

النشر الإنتاجي

1. إعداد البيئة

متطلبات النظام للإنتاج

  • المعالج: 4+ نوى موصى
  • الذاكرة: 16GB+ RAM للأداء الأمثل
  • التخزين: SSD مع 100GB+ مساحة متاحة
  • الشبكة: اتصال إنترنت مستقر لـ APIs النماذج

تكوين الأمان

# docker-compose.prod.yml
version: '3.8'
services:
  maxkb:
    image: maxkb:latest
    environment:
      - DEBUG=false
      - ALLOWED_HOSTS=your-domain.com
      - SECURE_SSL_REDIRECT=true
      - SECURE_HSTS_SECONDS=31536000
      - SECURE_CONTENT_TYPE_NOSNIFF=true
      - SECURE_BROWSER_XSS_FILTER=true
    volumes:
      - ./ssl:/etc/ssl/certs
    ports:
      - "443:8000"

2. توزيع الأحمال والتوسع

تكوين Nginx

upstream maxkb_backend {
    server maxkb_1:8000;
    server maxkb_2:8000;
    server maxkb_3:8000;
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /etc/ssl/certs/your-domain.crt;
    ssl_certificate_key /etc/ssl/private/your-domain.key;
    
    location / {
        proxy_pass http://maxkb_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location /static/ {
        alias /opt/maxkb/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

3. المراقبة والصيانة

سكريپت فحص الصحة

#!/bin/bash
# health_check.sh

MAXKB_URL="https://your-domain.com"
HEALTH_ENDPOINT="/api/health/"

# فحص توفر الخدمة
response=$(curl -s -o /dev/null -w "%{http_code}" "${MAXKB_URL}${HEALTH_ENDPOINT}")

if [ $response -eq 200 ]; then
    echo "✅ MaxKB بحالة جيدة"
    exit 0
else
    echo "❌ فشل فحص صحة MaxKB (HTTP $response)"
    # إرسال تنبيه لنظام المراقبة
    # curl -X POST "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK" \
    #      -H 'Content-type: application/json' \
    #      --data '{"text":"فشل فحص صحة MaxKB"}'
    exit 1
fi

إدارة السجلات

# تكوين دوران السجلات
echo "/opt/maxkb/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 maxkb maxkb
    postrotate
        docker-compose restart maxkb
    endscript
}" > /etc/logrotate.d/maxkb

استكشاف الأخطاء وإصلاحها

1. مشاكل التثبيت

مشاكل أذونات Docker

# إضافة المستخدم لمجموعة docker
sudo usermod -aG docker $USER
newgrp docker

# التحقق من وصول docker
docker run hello-world

مشاكل الذاكرة

# فحص ذاكرة النظام
free -h

# زيادة الذاكرة التبديلية عند الحاجة
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

2. مشاكل تكوين النماذج

التحقق من مفتاح API

# اختبار اتصال OpenAI API
import openai

try:
    client = openai.OpenAI(api_key="your_api_key")
    response = client.models.list()
    print("✅ نجح اتصال API")
    print(f"النماذج المتاحة: {[model.id for model in response.data]}")
except Exception as e:
    print(f"❌ فشل اتصال API: {e}")

مشاكل النماذج المحلية

# فحص خدمة Ollama
systemctl status ollama

# إعادة تشغيل Ollama عند الحاجة
systemctl restart ollama

# اختبار توفر النموذج
ollama list
ollama run llama3 "مرحباً، كيف حالك؟"

3. تحسين الأداء

تحسين قاعدة البيانات

-- ضبط أداء PostgreSQL
-- تشغيل كمستخدم postgres

-- إنشاء فهارس للبحث المتجه
CREATE INDEX CONCURRENTLY idx_documents_embedding 
ON documents USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

-- تحليل إحصائيات الجداول
ANALYZE documents;

-- فحص استخدام الفهارس
SELECT schemaname, tablename, indexname, idx_scan, idx_tup_read, idx_tup_fetch
FROM pg_stat_user_indexes
WHERE schemaname = 'public';

تكوين التخزين المؤقت

# تخزين Redis المؤقت لتحسين الأداء
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://localhost:6379/1',
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
        },
        'KEY_PREFIX': 'maxkb',
        'TIMEOUT': 3600,  # مهلة افتراضية لمدة ساعة
    }
}

# تخزين البيانات التي يتم الوصول إليها بكثرة مؤقتاً
@cache_page(300)  # تخزين مؤقت لمدة 5 دقائق
def get_agent_config(agent_id):
    return Agent.objects.get(id=agent_id).config

أفضل الممارسات والنصائح

1. إرشادات تصميم العملاء

هندسة المطالبة الفعالة

  • كن محدداً: حدد بوضوح دور العميل وقدراته
  • قدم السياق: تضمين معلومات خلفية ذات صلة
  • وضع الحدود: اذكر صراحة ما لا يجب على العميل فعله
  • استخدم الأمثلة: تضمين أمثلة few-shot للمهام المعقدة

تنظيم قاعدة المعرفة

# هيكل المجلدات الموصى لقواعد المعرفة

دعم العملاء/
├── الأسئلة الشائعة/
│   ├── مشاكل_الحساب.md
│   ├── أسئلة_الفوترة.md
│   └── المشاكل_التقنية.md
├── السياسات/
│   ├── سياسة_الاسترداد.md
│   ├── سياسة_الخصوصية.md
│   └── شروط_الخدمة.md
└── الإجراءات/
    ├── إعادة_تعيين_كلمة_المرور.md
    ├── إعداد_الحساب.md
    └── دليل_استكشاف_الأخطاء.md

2. أفضل ممارسات الأمان

أمان API

# تنفيذ تحديد المعدل
from django_ratelimit.decorators import ratelimit

@ratelimit(key='ip', rate='100/h', method='POST')
def chat_endpoint(request):
    # تنفيذ نقطة نهاية API
    pass

# التحقق من صحة الإدخال
def validate_message(message):
    if len(message) > 4000:
        raise ValidationError("الرسالة طويلة جداً")
    
    # إزالة المحتوى الضار المحتمل
    cleaned_message = bleach.clean(message, strip=True)
    return cleaned_message

خصوصية البيانات

# تنفيذ سياسات الاحتفاظ بالبيانات
from celery import task
from datetime import datetime, timedelta

@task
def cleanup_old_conversations():
    cutoff_date = datetime.now() - timedelta(days=90)
    Conversation.objects.filter(
        created_at__lt=cutoff_date,
        is_archived=True
    ).delete()

3. تحسين الأداء

تحسين البحث المتجه

# تحسين البحث بالتشابه المتجه
class OptimizedVectorSearch:
    def __init__(self, embedding_model, vector_db):
        self.embedding_model = embedding_model
        self.vector_db = vector_db
        self.cache = {}
    
    def search(self, query, limit=5, threshold=0.7):
        # فحص التخزين المؤقت أولاً
        cache_key = f"{hash(query)}_{limit}_{threshold}"
        if cache_key in self.cache:
            return self.cache[cache_key]
        
        # توليد تضمين الاستعلام
        query_embedding = self.embedding_model.encode(query)
        
        # إجراء البحث المتجه مع المرشحات
        results = self.vector_db.similarity_search(
            query_embedding,
            limit=limit,
            threshold=threshold,
            filter={'status': 'active'}
        )
        
        # تخزين النتائج مؤقتاً
        self.cache[cache_key] = results
        return results

الخلاصة

يمثل MaxKB تقدماً مهماً في تطوير عملاء الذكاء الاصطناعي للمؤسسات، حيث يقدم منصة شاملة توازن بين القوة وسهولة الاستخدام. طبيعته مفتوحة المصدر، مقترنة بميزات مستوى المؤسسات، تجعله خياراً ممتازاً للمؤسسات التي تتطلع لتنفيذ عملاء ذكاء اصطناعي على نطاق واسع.

النقاط الرئيسية

  1. منصة متعددة الاستخدامات: يدعم MaxKB مجموعة واسعة من حالات الاستخدام من دعم العملاء إلى أتمتة سير العمل المعقدة
  2. بنية قابلة للتوسع: مبنية للتعامل مع متطلبات مستوى المؤسسات مع النشر والتحسين المناسبين
  3. مجتمع نشط: دعم مجتمعي قوي وتحديثات منتظمة تضمن التحسين المستمر
  4. فعالة من حيث التكلفة: ترخيص مفتوح المصدر يقلل التكلفة الإجمالية للملكية مقارنة بالحلول المملوكة

الخطوات التالية

لمواصلة رحلتك مع MaxKB:

  1. التجريب: ابدأ بعملاء بسطاء وزد التعقيد تدريجياً
  2. المشاركة المجتمعية: انضم لمجتمع MaxKB على GitHub للدعم والمساهمات
  3. الوثائق: استكشف الوثائق الرسمية للميزات المتقدمة
  4. التطوير المخصص: فكر في المساهمة في المشروع أو تطوير امتدادات مخصصة

موارد إضافية

  • الموقع الرسمي: maxkb.cn
  • مستودع GitHub: github.com/1Panel-dev/MaxKB
  • منتدى المجتمع: متاح من خلال GitHub Discussions
  • الوثائق: أدلة شاملة متاحة في المستودع

يمكّن MaxKB المؤسسات من الاستفادة من الإمكانات الكاملة لعملاء الذكاء الاصطناعي مع الحفاظ على التحكم والأمان والمرونة. سواء كنت تبني روبوتات دعم العملاء أو مساعدي معرفة داخليين أو سير عمل أتمتة معقدة، يوفر MaxKB الأدوات والإطار المطلوبين للنجاح.

هذا البرنامج التعليمي جزء من سلسلة الذكاء الاصطناعي والأتمتة الشاملة. لمزيد من البرامج التعليمية المتقدمة وحلول الذكاء الاصطناعي للمؤسسات، قم بزيارة Thaki Cloud.

참고