التكامل مع الذكاء الاصطناعي

تكوين محادثة الذكاء الاصطناعي، واقتراحات إصلاح أخطاء LaTeX، ووصول المستخدمين، والحصص، وخدمات البحث الاختيارية.

هذه الميزة مقدَّمة من ayaka-notes/ayakaleaf-pro وهي متاحة بدءًا من الإصدار v6.3.0. نرحب بملاحظاتك إذا واجهت أي مشكلات.

​

مساعد الذكاء الاصطناعي ومساعد أخطاء LaTeX

يضيف Ayakaleaf Pro ميزات الذكاء الاصطناعي إلى المحرر بطريقتين.

• يمكن لمساعد الذكاء الاصطناعي (AI Assistant) استخدام مستندات مشروعك والتحديد الحالي كسياق للإجابة عن الأسئلة واقتراح تعديلات لتراجعها.
• يقترح مساعد الأخطاء (Error Assistant) إصلاحًا موجّهًا عند تحديد خطأ في ترجمة LaTeX.

​

تكوين Toolkit

أضف ما يلي إلى config/variables.env في نشر Toolkit الخاص بك، مع استبدال عنوان URL والمفتاح والنموذج الواردة في المثال بالقيم المقدمة من مزوّدك:

AI_ENABLED=true
AI_BASE_URL=https://ai-gateway.example.com/v1
AI_API_KEY=REPLACE_WITH_YOUR_GATEWAY_API_KEY
AI_MODEL=YOUR_TEXT_MODEL_ID

احتفظ بمفاتيح API الحقيقية في ملف بيئة النشر الخاص بك وبعيدًا عن نظام التحكم في الإصدارات. القيم أعلاه مجرد قيم نائبة، وليست بيانات اعتماد صالحة.

تعتمد جودة اقتراحات الذكاء الاصطناعي على النموذج الذي تختاره. إذا كان لديك اشتراك في Codex أو ChatGPT، فيمكنك ربطه عبر نقطة النهاية المتوافقة مع OpenAI في CLIProxyAPI.

AI_BASE_URL هو عنوان URL الأساسي لواجهة API المتوافقة مع OpenAI، بما في ذلك بادئة الإصدار الخاصة بالمزوّد عند الحاجة. لا تُلحق /chat/completions لأننا نضيفها داخليًا. يجب أن تدعم البوابة والنموذج إكمالات المحادثة المتدفقة (streaming) وأدوات الدوال (function tools). ترسل كلتا الميزتين سياق المستند إلى هذه البوابة؛ ويمكن للمحادثة أيضًا إرسال الصور المرفوعة عند استخدام نموذج يدعم الصور.

يمرّر Toolkit الملف config/variables.env إلى حاوية التطبيق. احتفظ بأسماء المتغيرات كما هي موضحة هنا؛ ولا تُضف البادئة OVERLEAF_. من مجلد Toolkit، أعد إنشاء حاوية التطبيق بعد تغيير هذه المتغيرات:

bin/up -d

​

إعدادات البوابة

المتغير	القيمة الافتراضية	الغرض
AI_ENABLED	false	اضبطه على true تمامًا لتفعيل المحادثة واقتراحات الأخطاء على مستوى النسخة. إذا لم يُضبط أو ضُبط على أي قيمة أخرى تبقى الميزتان معطّلتين. ويلزم أيضًا تكوين بوابة يعمل بشكل صحيح.
AI_BASE_URL	لا يوجد؛ مطلوب	عنوان URL الأساسي لواجهة API المتوافقة مع OpenAI.
AI_API_KEY	لا يوجد؛ مطلوب	مفتاح API لتلك البوابة، يستخدمه الخادم.
AI_MODEL	لا يوجد؛ مطلوب	النموذج النصي المستخدم في تكوين المحادثة الافتراضي وفي اقتراحات أخطاء LaTeX.
AI_IMAGE_MODEL	غير مضبوط	نموذج اختياري يدعم الصور على البوابة نفسها، ويستخدم مفتاح API نفسه.
AI_MAX_STEPS	20	الحد الأقصى لاستدعاءات الأدوات لكل رسالة مستخدم في محادثة الذكاء الاصطناعي، بما في ذلك المتابعات التلقائية. استخدم عددًا صحيحًا موجبًا.
AI_PROXY_URL	غير مضبوط	عنوان URL اختياري لوكيل HTTP للاستدعاءات الموجهة إلى بوابة الذكاء الاصطناعي. لا يؤثر في عملاء البحث على الويب أو البحث في الوثائق.
AI_TOKEN_QUOTA	0	حد الرموز (tokens) لكل مستخدم، مشترك بين المحادثة واقتراحات الأخطاء في كل فترة. عدم الضبط أو القيمة 0 تعني بلا حدود؛ استخدم عددًا صحيحًا موجبًا لتعيين حد.
AI_TOKEN_QUOTA_PERIOD	month	القيمة month تُعاد ضبطها في اليوم الأول من الشهر عند 00:00 UTC؛ والقيمة week تُعاد ضبطها يوم الاثنين عند 00:00 UTC. أي قيمة أخرى تُعامَل كـ month.

لرفع الصور، اضبط AI_IMAGE_MODEL على نموذج يقبل إدخال الصور ويدعم الأدوات التي تستخدمها المحادثة. أي طلب محادثة يحتوي سجله على صورة مرفقة يستخدم هذا النموذج، بما في ذلك الرسائل اللاحقة في تلك المحادثة. بدون هذا الإعداد، تستخدم طلبات الصور نموذج المحادثة العادي، الذي يجب أن يدعم الصور بنفسه. أما اقتراحات أخطاء LaTeX فتستمر في استخدام AI_MODEL.

على سبيل المثال، لتفعيل نموذج للصور وحصة أسبوعية للذكاء الاصطناعي:

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

وصول المستخدمين والموافقة

إتاحة الميزة على مستوى النسخة وصلاحيات المستخدم أمران منفصلان. يتحكم AI_ENABLED وتكوين البوابة في الإتاحة على مستوى النسخة. ويجب على المستخدم المسجّل دخوله أيضًا اجتياز عمليات التحقق الحالية للحساب:

• يجب ألا تكون قيمة aiFeatures.enabled هي false. يتحكم حقل قاعدة البيانات هذا في كل من المحادثة واقتراحات أخطاء LaTeX.
• يجب أن تطابق قيمة features.aiUsageQuota الفعلية للمستخدم المستوى غير المحدود المكوَّن (unlimited افتراضيًا)، أو يجب أن تكون الصلاحية القديمة features.aiErrorAssistant مفعّلة. تشمل الميزات الفعلية أي تجاوزات لميزات الحساب سارية عليه.

تفعيل مربع الاختيار وحده لا يغيّر خطة المستخدم. الحقل aiUsageQuota هو مستوى صلاحيات، وليس حصة رقمية من الرموز. أما AI_TOKEN_QUOTA فهو حد منفصل يُطبَّق بالتساوي على كل مستخدم مسموح له؛ ولا توفر الوحدة الحالية حدًا رقميًا فرديًا لكل حساب.

في قائمة المستخدمين في لوحة الإدارة، حدد مستخدمًا وافتح Update account info → AI features. يقوم الخيار Enable AI features بتحديث aiFeatures.enabled عند حفظ تغييرات الحساب. يتحقق الخادم من الصلاحيات الحالية عند كل طلب ذكاء اصطناعي جديد، بما في ذلك الطلبات الصادرة من محرر مفتوح بالفعل. حدّث صفحة المحرر لتحديث عناصر التحكم المرئية بعد تغيير الصلاحيات.

​

الاستخدام وإعادة الضبط

تعرض علامة تبويب AI features في لوحة الإدارة Usage وLimit وزر Reset للفترة الحالية في صف واحد. تُقرأ قيمة الاستخدام عند فتح علامة التبويب؛ ولا تُحدَّث باستمرار. أعد فتح علامة التبويب بعد انتهاء محادثة أو اقتراح خطأ لرؤية أحدث عدد. تسري إعادة الضبط فورًا وتمسح عدّاد الفترة الحالية لذلك المستخدم فقط، ثم تعيد تحميل الاستخدام المعروض. ولا تتطلب حفظ بقية نموذج الحساب.

يتشارك استخدام المحادثة واقتراحات الأخطاء عدّادًا واحدًا في Redis، يُحدَّث بناءً على إجمالي الرموز الذي يبلّغ عنه مزوّد النموذج بعد اكتمال الطلب. ويشمل ذلك رموز الإدخال والإخراج عبر خطوات النموذج. قد يتضمن الإدخال سجل المحادثة وسياق المستند ونتائج الأدوات، لذا قد تستهلك رسالة المتابعة رموزًا أكثر من الرسالة الجديدة وحدها. يُسجَّل الاستخدام حتى عندما يكون الحد Unlimited. الطلبات التي لا يُبلَّغ فيها عن إجمالي الرموز لا تُضاف إلى العدّاد؛ ولا يمكن للوحدة إعادة بناء الاستخدام التاريخي غير المسجّل.

يتم التحقق من الحصة قبل بدء البث. قد يتجاوز طلب واحد، أو عدة طلبات متزامنة، الحصة المتبقية قبل حظر الطلبات اللاحقة. لذا فهذه حصة استخدام وليست سقفًا صارمًا للإنفاق لدى المزوّد. إذا فشل الاستعلام عن الحصة، يُسمح بالطلب ويُسجَّل الفشل.

تستخدم كلتا الميزتين AI_TOKEN_QUOTA؛ ولا يوجد لاقتراحات الأخطاء حد منفصل لعدد الطلبات. إعادة ضبط العدّاد لا تغيّر الصلاحيات أو الموافقة أو الحد المكوَّن أو سجلات الفوترة الخاصة بالمزوّد. تستخدم العدّادات مفاتيح فترات بتوقيت UTC وتنتهي صلاحيتها بعد 40 يومًا؛ والاحتفاظ ببيانات Redis يحافظ على الاستخدام الحالي عبر عمليات إعادة تشغيل التطبيق.

​

خدمات البحث الاختيارية

يستخدم البحث على الويب واجهة API متوافقة مع Tavily. ويكون متاحًا عند تكوين مفتاح API للبحث. هذه الإعدادات مستقلة عن بوابة الذكاء الاصطناعي:

المتغير	القيمة الافتراضية	الغرض
TAVILY_API_KEY	غير مضبوط	مفتاح API للبحث. له الأولوية على WEB_SEARCH_API_KEY.
WEB_SEARCH_API_KEY	غير مضبوط	اسم بديل لمفتاح API للبحث.
WEB_SEARCH_URL	https://api.tavily.com/search	نقطة نهاية البحث؛ يجب أن تقبل نقاط النهاية المخصصة تنسيق الطلب والاستجابة الخاص بـ Tavily.
WEB_SEARCH_MAX_RESULTS	5	عدد النتائج المطلوبة لكل بحث؛ استخدم عددًا صحيحًا موجبًا تدعمه الخدمة.
WEB_SEARCH_DEPTH	basic	عمق البحث، وعادةً ما يكون basic أو advanced.
WEB_SEARCH_PROVIDER	tavily	يدعم التنفيذ الحالي البروتوكول المتوافق مع Tavily فقط؛ وتغيير هذه القيمة لا يختار محوّلًا آخر.
DOCS_MCP_URL	https://docs.overleaf.com/~gitbook/mcp	نقطة نهاية البحث في الوثائق. اضبطها على سلسلة فارغة لتعطيل البحث في الوثائق.

على سبيل المثال:

TAVILY_API_KEY=REPLACE_WITH_YOUR_SEARCH_API_KEY
WEB_SEARCH_MAX_RESULTS=5
WEB_SEARCH_DEPTH=basic
DOCS_MCP_URL=https://docs.overleaf.com/~gitbook/mcp

يستدعي البحث في الوثائق الأداة searchDocumentation الخاصة بنقطة نهاية GitBook MCP المكوَّنة، ويقبل استجابات JSON أو SSE. هذا عميل MCP للبحث في الوثائق؛ ولا تكشف هذه الوحدات ملفات المشروع كخادم MCP ولا توفر سجلًا عامًا لخوادم MCP.

تُرسَل استعلامات البحث إلى خدمة البحث المكوَّنة. ويمكن بعد ذلك تضمين نتائج البحث في الطلبات المرسلة إلى بوابة الذكاء الاصطناعي. تتيح قائمة Tools في المحادثة للمستخدمين تفعيل Web وDocumentation أو تعطيلهما لطلباتهم؛ ويجب أيضًا تكوين الأداة على الخادم حتى تكون متاحة للنموذج.