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

تكوين محادثة الذكاء الاصطناعي، واقتراحات إصلاح أخطاء 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). ترسل كلتا الميزتين سياق المستند إلى هذه البوابة؛ ويمكن للمحادثة أيضًا إرسال الصور وملفات PDF المرفوعة عند استخدام نموذج يقبلها.

يمرّر 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_PDF_MODEL	غير مضبوط	نموذج اختياري على البوابة نفسها للمحادثات التي تتضمن ملفات PDF، ويستخدم مفتاح API نفسه. بدءًا من الإصدار v6.4.0.
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.

أُضيفت مرفقات PDF بدءًا من الإصدار v6.4.0 وما بعده. يمكن للمستخدمين إرفاق ملفات PDF يصل حجمها إلى 2 ميغابايت، تمامًا مثل الصور. ترسل المحادثة كل ملف PDF كما هو، كجزء file في Chat Completions، لذا يجب أن تقبل البوابة والنموذج إدخال PDF: نماذج الرؤية من OpenAI تقبله، بينما تقبل كثير من البوابات المستضافة ذاتيًا، مثل vLLM، الصور لكنها ترفض ملفات PDF. اضبط AI_PDF_MODEL على نموذج يقرأ ملفات PDF؛ إذ تستخدمه أي محادثة يحتوي سجلها على ملف PDF، بما في ذلك الرسائل اللاحقة وأي صور في تلك المحادثة، لذا ينبغي أن يقبل الصور أيضًا. بدون هذا الإعداد، تستخدم محادثات PDF النموذج AI_MODEL. وعندما يرفض النموذج ملف PDF، تُبلغ المحادثة المستخدم بأن يطلب من المسؤول ضبط AI_PDF_MODEL.

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

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

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

إتاحة الميزة على مستوى النسخة وصلاحيات المستخدم أمران منفصلان. يتحكم AI_ENABLED وتكوين البوابة في الإتاحة على مستوى النسخة. ويجب على المستخدم المسجّل دخوله أيضًا اجتياز التحقق الحالي للحساب: يجب ألا تكون قيمة aiFeatures.enabled هي false. يتحكم حقل قاعدة البيانات هذا في كل من المحادثة واقتراحات أخطاء LaTeX. وعندما لا يكون مضبوطًا، تكون ميزات الذكاء الاصطناعي مفعّلة للمستخدم.

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 للبحث في الوثائق. للسماح لعملاء الذكاء الاصطناعي من خارج Ayakaleaf بالعمل على مشروع، راجع MCP Server.

أُضيفت قراءة صفحات الويب بدءًا من الإصدار v6.4.0 وما بعده. يمكن للمحادثة قراءة صفحة من خلال عنوان URL الخاص بها، مثل رابط يقدّمه المستخدم أو نتيجة بحث. تجلب الصفحة عبر وكيل عناوين URL المرتبطة، وهو الخدمة نفسها التي تجلب الملفات من عناوين URL الخارجية، لذا تنطبق عليها أيضًا قيود الشبكة الموضحة في External URL. لا حاجة إلى أي إعداد إضافي.

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

​

أسئلة وأجوبة

لا يظهر مساعد الذكاء الاصطناعي في المحرر

الإجابة: يظهر مساعد الذكاء الاصطناعي في الشريط الجانبي الأيسر للمحرر فقط عندما يكون AI_ENABLED=true وتكون AI_BASE_URL وAI_API_KEY وAI_MODEL مضبوطة جميعها. إذا كان أحدها مفقودًا، يُخفى مساعد الذكاء الاصطناعي عن جميع المستخدمين.

بعد تغيير config/variables.env، أعد إنشاء الحاوية باستخدام bin/up -d. تحديث المتصفح وحده لا يطبّق المتغيرات الجديدة. لا يُظهر مفتاح Enable AI features في لوحة الإدارة مساعد الذكاء الاصطناعي ولا يخفيه؛ بل يحدد فقط ما إذا كان المستخدم يستطيع إرسال الرسائل.

أرسل رسالة، لكن مساعد الذكاء الاصطناعي لا يرد

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

ثم ابحث عن الأخطاء في سجل خدمة web:

bin/logs web

رسالة السجل	المعنى
workbench AI chat requested but no AI gateway is configured	أحد المتغيرات AI_ENABLED أو AI_BASE_URL أو AI_API_KEY أو AI_MODEL مفقود في الحاوية قيد التشغيل. أعد إنشاءها باستخدام bin/up -d.
workbench chat stream error	أعادت البوابة خطأً. يرى المستخدم الرسالة “The AI service returned an error”. يُظهر الخطأ المسجَّل رمز الحالة ورسالة البوابة.
workbench chat failed	فشل الطلب قبل البث أو أثناءه، على سبيل المثال لأنه يتعذر الوصول إلى البوابة.

إذا لم تُظهر لوحة تحكم المزوّد أي استخدام، فهذا يعني أن الطلب لم يصل إلى المزوّد. الأسباب الشائعة هي:

• قيمة AI_BASE_URL خاطئة، على سبيل المثال /v1 مفقودة أو زائدة، أو إلحاق /chat/completions بها.
• لا يستطيع الخادم الوصول إلى البوابة. إذا كان يجب أن تمر حركة المرور الصادرة عبر وكيل، فاضبط AI_PROXY_URL.
• AI_MODEL ليس معرّف نموذج تعرفه البوابة.

إذا أظهر المزوّد الطلبات لكن المحادثة لا تزال تفشل، فتحقق من أن النموذج يدعم إكمالات المحادثة المتدفقة وأدوات الدوال.

هل يُحفظ سجل المحادثة؟

الإجابة: لا. تُحفظ المحادثة فقط في تبويب المتصفح المفتوح. يؤدي تحديث الصفحة أو إغلاقها إلى مسحها، ويستبدل Start new chat المحادثة الحالية. لا توجد قائمة بالمحادثات السابقة، ويعرض كل مشروع محادثة واحدة في كل مرة.