> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

> [!NOTE]
>
> هذه الميزة مقدَّمة من [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) وهي متاحة بدءًا من الإصدار v6.3.0. نرحب بملاحظاتك إذا واجهت أي مشكلات.

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

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

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

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-49.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=609d6a28104dfb16264790c00123eeb4)

### تكوين Toolkit

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

```dotenv theme={null}
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 الحقيقية في ملف بيئة النشر الخاص بك وبعيدًا عن نظام التحكم في الإصدارات. القيم أعلاه مجرد قيم نائبة، وليست بيانات اعتماد صالحة.

> [!NOTE]
>
> تعتمد جودة اقتراحات الذكاء الاصطناعي على النموذج الذي تختاره. إذا كان لديك اشتراك في Codex أو ChatGPT، فيمكنك ربطه عبر نقطة النهاية المتوافقة مع OpenAI في [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI).

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

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

```sh theme={null}
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`.

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

```dotenv theme={null}
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** للفترة الحالية في صف واحد. تُقرأ قيمة الاستخدام عند فتح علامة التبويب؛ ولا تُحدَّث باستمرار. أعد فتح علامة التبويب بعد انتهاء محادثة أو اقتراح خطأ لرؤية أحدث عدد. تسري إعادة الضبط فورًا وتمسح عدّاد الفترة الحالية لذلك المستخدم فقط، ثم تعيد تحميل الاستخدام المعروض. ولا تتطلب حفظ بقية نموذج الحساب.

![](https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max\&auto=format\&n=x9kfDjtWlyyhG_mR\&q=85\&s=3c52c12aa1551cda22f218ec2dfda63b)

يتشارك استخدام المحادثة واقتراحات الأخطاء عدّادًا واحدًا في 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` | نقطة نهاية البحث في الوثائق. اضبطها على سلسلة فارغة لتعطيل البحث في الوثائق. |

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

```dotenv theme={null}
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](https://ayakaleaf-pro.mintlify.site/ar/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md).

أُضيفت قراءة صفحات الويب بدءًا من الإصدار v6.4.0 وما بعده. يمكن للمحادثة قراءة صفحة من خلال عنوان URL الخاص بها، مثل رابط يقدّمه المستخدم أو نتيجة بحث. تجلب الصفحة عبر وكيل عناوين URL المرتبطة، وهو الخدمة نفسها التي تجلب الملفات من عناوين URL الخارجية، لذا تنطبق عليها أيضًا قيود الشبكة الموضحة في [External URL](https://ayakaleaf-pro.mintlify.site/ar/on-premises/configuration/overleaf-toolkit/external-url.md). لا حاجة إلى أي إعداد إضافي.

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

### أسئلة وأجوبة

> [accordion] لا يظهر مساعد الذكاء الاصطناعي في المحرر
>
> **الإجابة:** يظهر مساعد الذكاء الاصطناعي في الشريط الجانبي الأيسر للمحرر فقط عندما يكون `AI_ENABLED=true` وتكون `AI_BASE_URL` و`AI_API_KEY` و`AI_MODEL` مضبوطة جميعها. إذا كان أحدها مفقودًا، يُخفى مساعد الذكاء الاصطناعي عن جميع المستخدمين.
>
> بعد تغيير `config/variables.env`، أعد إنشاء الحاوية باستخدام `bin/up -d`. تحديث المتصفح وحده لا يطبّق المتغيرات الجديدة. لا يُظهر مفتاح **Enable AI features** في لوحة الإدارة مساعد الذكاء الاصطناعي ولا يخفيه؛ بل يحدد فقط ما إذا كان المستخدم يستطيع إرسال الرسائل.

> [accordion] أرسل رسالة، لكن مساعد الذكاء الاصطناعي لا يرد
>
> **الإجابة:** أولًا، تحقق من أن المستخدم قد وافق على بطاقة الموافقة على الذكاء الاصطناعي المعروضة في مساعد الذكاء الاصطناعي. لا يمكن إرسال الرسائل قبل ذلك.
>
> ثم ابحث عن الأخطاء في سجل خدمة web:
>
> ```sh theme={null}
> 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` ليس معرّف نموذج تعرفه البوابة.
>
> إذا أظهر المزوّد الطلبات لكن المحادثة لا تزال تفشل، فتحقق من أن النموذج يدعم إكمالات المحادثة المتدفقة وأدوات الدوال.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.