> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# استخدام Ace Data Cloud في Jan

> Platform API guide - Ace Data Cloud

[Jan](https://jan.ai/) هو عميل سطح مكتب مفتوح المصدر للذكاء الاصطناعي يركز على العمل دون اتصال، ويمكنه تشغيل النماذج محليًا أو الاتصال بنقاط نهاية متوافقة مع OpenAI عبر **Remote Engine**. يوضح هذا المقال كيفية الاتصال بـ Ace Data Cloud.

## عملية التقديم

للاتصال بـ Ace Data Cloud في Jan، انتقل أولًا إلى [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications)، واحصل على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا.

![الحصول على Ace Data Cloud API Key](https://cdn.acedata.cloud/dvc3cg.jpg)

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

عند التقديم لأول مرة، يتم منحك رصيد مجاني، ويمكنك تجربة خدمة نماذج Ace Data Cloud مجانًا.

## تنزيل Jan

انتقل إلى [الموقع الرسمي لـ Jan](https://jan.ai/) وقم بالتنزيل حسب المنصة (Windows وmacOS وLinux). بالنسبة لأجهزة Apple Silicon، يرجى تنزيل حزمة arm64 للحصول على أفضل أداء.

## إعداد Ace Data Cloud

يقسم Jan النماذج إلى نوعين: **Local Engine** (تشغيل محلي) و**Remote Engine** (واجهات API تابعة لجهات خارجية). يستخدم Ace Data Cloud بروتوكولًا متوافقًا مع OpenAI، ويتم الاتصال به عبر Remote Engine.

افتح Jan، وانتقل إلى **Settings → Model Providers**، وابحث عن بطاقة **OpenAI** وقم بتحريرها:

| الحقل | القيمة | الوصف |
| - | - | - |
| API Key | Ace Data Cloud Token الخاص بك | Token المنسوخ من وحدة التحكم |
| Base URL | `https://api.acedata.cloud/v1` | **يجب أن ينتهي بـ `/v1`، ولا تضع شرطة مائلة في النهاية** |

> يجب أن ينتهي Base URL بـ `/v1`، وهذا اتفاق واضح في وثائق Jan الرسمية. إذا كنت لا تريد استبدال إعدادات OpenAI الأصلية، يمكنك إنشاء Provider جديد من نوع `openai-compatible` عبر «+ Add Provider»، وملء المحتوى نفسه.

![واجهة إعداد Jan لإضافة AceDataCloud Provider](https://cdn.acedata.cloud/26017d28afa1.png)

بعد حفظ Provider المخصص، سيحاول Jan أولًا استدعاء `{Base URL}/models` للحصول على قائمة النماذج. إذا لم يُرجع الإصدار أو نقطة النهاية الحالية قائمة متاحة، فانقر على **+ Add Model** أسفل صفحة التحرير نفسها لملء معرّف النموذج يدويًا. بعد الإضافة، سيظهر النموذج في القائمة المنسدلة في أعلى اليسار، وسيحمل أيقونة «Cloud» للتمييز بين البعيد / المحلي.

![واجهة إدارة نماذج Jan Provider](https://cdn.acedata.cloud/ae485550946c.png)

> `MODEL_ID` هو عنصر نائب؛ يرجى الانتقال إلى [دليل النماذج](https://platform.acedata.cloud/models) لعرضه واستبداله باسم النموذج المستهدف؛ وعند التحقق الدقيق، تكون القيمة `id` في استجابة `/v1/models` هي المرجع. هذه القيمة هي اسم النموذج المستخدم في معامل API `model`، وليست UUID للخدمة أو API.

## اختيار النموذج

يتم تحديث [دليل النماذج](https://platform.acedata.cloud/models) باستمرار. استخدم قائمة النماذج التي يحمّلها العميل تلقائيًا أولًا؛ وعند الحاجة إلى الملء اليدوي، اطلب أولًا `GET https://api.acedata.cloud/v1/models`، وانسخ قيمة `id` للنموذج المستهدف من مصفوفة `data` في الاستجابة، ثم اختر وفقًا لقدرات السياق والصور واستدعاء الأدوات التي يدعمها العميل.

## التحقق من الاتصال

إذا لم تكن متأكدًا مما إذا كانت المشكلة في Jan أو في الشبكة، فيمكنك أولًا استخدام curl للتحقق من نقطة النهاية مباشرةً (استبدل `{token}` بـ Token الخاص بك):

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

إن إرجاع كائن `chat.completion` متوافق مع OpenAI يعني أن Token ونقطة النهاية كلاهما جاهزان؛ وإذا تم إرجاع `HTTP 403 used_up` فهذا يعني أن Token صالح لكن الرصيد غير كافٍ، ويمكنك إعادة الشحن من [وحدة التحكم](https://platform.acedata.cloud/console/applications).

## متقدم: مزيج محلي + سحابي

يتضمن Jan خادم API محليًا متوافقًا مع OpenAI يمكن تشغيله (Settings → Local API Server)، وبعد تشغيله يستمع إلى `http://localhost:1337/v1/chat/completions` ويشغّل النماذج المحلية التي قمت بتنزيلها. بهذه الطريقة، يمكنك توجيه Base URL إلى المحلي لإجراء تصحيح مجاني في أطر مثل LangChain / LlamaIndex، ثم التحويل إلى نماذج Ace Data Cloud البعيدة للمهام المعقدة. لن يُفقد سياق المحادثة عند تبديل النماذج.

## الأسئلة الشائعة

### ظهور Connection error أو 404

عادةً ما يكون Base URL يفتقد إلى `/v1`. غيّره إلى `https://api.acedata.cloud/v1` (يجب أن ينتهي بـ `/v1`، ولا تكتبه بالشكل `.../openai/v1`).

### ظهور 401 Unauthorized

يرجى التأكد من أن ما تم لصقه في API Key هو Token الخاص بـ Ace Data Cloud (من دون بادئة `Bearer` ومن دون مسافات إضافية)، وأن رصيد التطبيق التابع له كافٍ.

### لا تظهر النماذج البعيدة في القائمة المنسدلة

انقر أولًا على زر تحديث النماذج لتشغيل `/v1/models`؛ وإذا فشل الاكتشاف التلقائي، فأضف النموذج يدويًا عبر **+ Add Model**، وأضف قيمة `id` للنموذج في الدليل كما هي.

### هل يمكن رفع الصور ليحللها النموذج

نعم، ولكن يجب اختيار نموذج يدعم إدخال الصور بوضوح من دليل النماذج الحالي.

## معرفة المزيد

* [الموقع الرسمي لـ Jan](https://jan.ai/) ｜ [Jan GitHub](https://github.com/menloresearch/jan) ｜ [وثائق Jan](https://jan.ai/docs)
* [الوثائق الرسمية لـ Jan للاتصال بنقطة نهاية مخصصة متوافقة مع OpenAI](https://jan.ai/docs/desktop/remote-models/custom-endpoint)
* [الوثائق الرسمية لـ Jan Local API Server](https://jan.ai/docs/desktop/api-server)
* [وثائق Ace Data Cloud OpenAI Chat Completions API](https://platform.acedata.cloud/documents/openai-chat-completions)
* [قائمة خدمات Ace Data Cloud](https://platform.acedata.cloud/documents)
* [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console)


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