> ## 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، ووصول المستخدمين، والحصص، وخدمات البحث الاختيارية.

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

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

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

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

<Frame>
  <img src="https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/image-48.png?fit=max&auto=format&n=x9kfDjtWlyyhG_mR&q=85&s=107b27f8843a326269b5e3711ccf2616" alt="" width="2844" height="1710" data-path="images/on-premises/image-48.png" />
</Frame>

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

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

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

يمرّر 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_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`.

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

```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.
* يجب أن تطابق قيمة `features.aiUsageQuota` الفعلية للمستخدم المستوى غير المحدود المكوَّن (`unlimited` افتراضيًا)، أو يجب أن تكون الصلاحية القديمة `features.aiErrorAssistant` مفعّلة. تشمل الميزات الفعلية أي تجاوزات لميزات الحساب سارية عليه.

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

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

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

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

<Frame>
  <img src="https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max&auto=format&n=x9kfDjtWlyyhG_mR&q=85&s=3c52c12aa1551cda22f218ec2dfda63b" alt="" width="563" data-path="images/on-premises/img-2f5a5399.png" />
</Frame>

يتشارك استخدام المحادثة واقتراحات الأخطاء عدّادًا واحدًا في 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 للبحث في الوثائق؛ ولا تكشف هذه الوحدات ملفات المشروع كخادم MCP ولا توفر سجلًا عامًا لخوادم MCP.

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


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