AI Models

المسار في لوحة الإدارة: System › Admin › License & updates (/license) لتفعيل الوحدة. ثم Services › AI Models: Providers (/ai/providers) وModels (/ai/models) وProfit (/ai/profit) وAudit (/ai/audit). يستخدم العملاء AI › API في بوابة العملاء.

الوظيفة

يُعد AI Models بوابة وطبقة فوترة على لوحتك الخاصة. يحصل عملاؤك على مفاتيح API ويستدعون نقطة نهاية واحدة على نطاقك، بتنسيق متوافق مع OpenAI أو متوافق مع Anthropic. تختار أنت النماذج التي تريد تقديمها وتكلفة كل منها لكل 1 مليون رمز (tokens). يتحقق NexCMP من المفتاح والحدود والمحفظة، ويرسل الطلب إلى مزود أضفته، ويقيس الرموز ويخصم من محفظة العميل مسبقة الدفع.

أنت من يوفر مصادر النماذج. لا يأتي NexCMP مع أي مزود أو نموذج أو عنوان افتراضي أو سعر، ولا يوفر نماذج أو مفاتيح API أو رموزاً (tokens) أو حسابات لدى المزودين.

تحقق من شروط المصادر أولاً

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

يُعد AI Models منتجاً منفصلاً عن AI Chat and AI Agent (الوحدة AI، راجع مزودي الذكاء الاصطناعي). ولا تعتمد أي من الوحدتين على الأخرى.

المتطلبات

العنصر	المتطلب
الوحدة	تفعيل AI Models ضمن License & updates،‏ Modules. وتكون معطلة افتراضياً.
المزودون	مصدر نماذج واحد أو أكثر مصرّح لك بإعادة بيعه، يوفّر كل منها واجهة API متوافقة مع OpenAI (/chat/completions) أو واجهة API متوافقة مع Anthropic (/messages)، أو كليهما. يتطلب كل منها عنوان URL أساسي ومفتاح API.
الشبكة	يجب أن تتمكن اللوحة من الوصول إلى كل مزود عبر HTTPS على المنفذ 443 باستخدام اسم نطاق عام. وأي مزود على مضيف داخلي أو منفذ آخر أو بروتوكول HTTP عادي يجب إدراجه ضمن Allowed internal hosts (الإعداد ai_endpoint_allow).
العملاء	حساب عميل ببريد إلكتروني موثق ورصيد في المحفظة.
العتاد	لا يوجد. يقتصر دور NexCMP على إعادة توجيه الطلبات فقط: دون الحاجة إلى GPU أو ملفات نماذج.

تجهيز البنية التحتية

1. احصل على مفتاح API من كل مصدر نماذج ستستخدمه، وسجّل عنوان URL الأساسي له (على سبيل المثال https://api.example.com/v1).
2. تحقق من شروط المصدر بشأن إعادة البيع.
3. إذا كان المصدر يعمل داخل شبكتك، فحدد عنوانه، على سبيل المثال http://10.0.0.5:8000/v1. وستقوم بإدراج 10.0.0.5:8000 ضمن Allowed internal hosts.

الربط في NexCMP

1. تفعيل الوحدة

افتح System › Admin › License & updates، وابحث عن بطاقة Module، ثم قم بتفعيل AI Models. ستتم إعادة تحميل القائمة ويظهر Services › AI Models. وطالما أن الوحدة معطلة، فإن صفحات العملاء وصفحات المسؤول والبوابة تستجيب جميعها بـ 404 module_disabled، ولن يتم الاتصال بأي مزود.

2. إضافة مزود

1. افتح AI Models › Providers واختر Add provider.
2. أدخل slug قصيرًا، واسمًا (تراه أنت فقط)، والنوع (OpenAI-compatible أو Anthropic-compatible أو Both)، وbase URL وAPI key، بالإضافة إلى الأولوية (تتم تجربة الرقم الأقل أولاً).
3. احفظ. يتم تخزين المفتاح مشفرًا ولا تظهر سوى آخر أربعة أحرف منه بعد ذلك. لا يمكن إدخال المفتاح إلا من جلسة مسؤول مسجل دخوله.

استخدم Both فقط للبوابة التي تدعم كلا التنسيقين بالفعل. إن NexCMP لا يحول بين التنسيقين: يتم الوصول إلى النموذج الذي يقدمه مزود OpenAI-compatible عبر /ai/v1/chat/completions، والنموذج الذي يقدمه مزود Anthropic-compatible عبر /ai/v1/messages.

3. اختبار الاتصال

اختر Test connection لدى المزود. يقرأ NexCMP GET <base URL>/models بالمفتاح ويفيد بـ ok، أو يوضح سبب الفشل: auth (مفتاح خاطئ)، أو blocked، أو billing، أو unreachable. يقتصر الاختبار على 6 اختبارات في الدقيقة.

4. مزامنة النماذج

اختر Sync models. يقرأ NexCMP قائمة نماذج المزود ويضيف كل نموذج جديد معطلاً ودون سعر. يتم تمييز أي نموذج لم يعد المزود يدرجه في القائمة. وطالما أن الوحدة قيد التشغيل، تتم أيضًا مزامنة القائمة تلقائيًا كل 6 ساعات (الإعداد ai_models_sync_hours).

5. تحديد الأسعار وتفعيل النماذج

1. افتح AI Models › Models.
2. لكل نموذج ترغب في بيعه، حدد سعر البيع بالدولار الأمريكي لكل 1 مليون token: input وcached input وoutput.
3. يمكنك اختياريًا إدخال التكلفة الخاصة بك للنموذج. عندئذٍ يعرض Profit الإيرادات مقابل التكلفة حسب اليوم وحسب النموذج، ويتم رفض أي سعر بيع يقل عن تكلفتك مضافًا إليها الحد الأدنى لهامش الربح (الإعداد ai_min_margin_pct، القيمة الافتراضية 10) ما لم تؤكد خسارة متعمدة. يستخدم Set price from cost هامش ربح تختاره أنت؛ لا يوجد هامش ربح افتراضي.
4. قم بتفعيل النموذج. لا يمكن تفعيل أي نموذج ليس له سعر بيع. وإذا تُرِك سعر cached input عند الصفر، فسيتم احتسابه بسعر input.

6. المسارات والتبديل عند الفشل

في صفحة النموذج، يسرد Routes المزودين الذين يقدمونه بالترتيب. أضف مزودًا ثانيًا كبديل احتياطي، وحدد الترتيب، واختياريًا حدد اسم نموذج مختلف لكل مزود (يمكن أن يختلف الاسم المرسل إلى المزود عن الاسم الذي تنشره). عندما يُرجع المزود خطأ في الخادم أو خطأ في التفويض أو الفوترة أو نموذجًا مفقودًا أو حدًا لمعدل الطلبات، يجرب NexCMP المسار التالي. إذا انتهت مهلة القراءة بعد إرسال الطلب، فإنه لا يُرسل إلى مزود آخر، وبذلك لن تدفع مرتين.

يتم تنظيم معدل كل مزود عند ai_provider_rpm طلب في الدقيقة (50 افتراضيًا). إذا استمر المزود في إرجاع أخطاء التفويض أو الفوترة، فسيقوم NexCMP بتنبيه المسؤول عبر Telegram عند إعداد Telegram.

7. تفعيل مفتاح البيع

في الجزء العلوي من صفحات AI Models، يكون مفتاح البيع (الإعداد feature_ai_models) معطلاً افتراضيًا. وطالما أنه معطل، يرى العملاء أن الخدمة لم تفتح بعد، وتفيد قائمة الأسعار العامة بأنها غير متاحة. تأكد من تفعيل نموذج واحد على الأقل ووجود سعر بيع ومسار مزود بمفتاح، ثم قم بتفعيله.

ما يمكن للعملاء فعله

في بوابة العملاء، AI › API:

• يعرض Models النماذج والأسعار الخاصة بك، وbase URL وأوامر أمثلة جاهزة للاستخدام.
• API Keys: إنشاء المفاتيح وإعادة تسميتها وتدويرها وتعطيلها وحذفها. يُعرض المفتاح السري مرة واحدة فقط؛ ويُخزّن رمز التجزئة فقط. لكل مفتاح: النماذج المسموح بها، وتاريخ انتهاء الصلاحية، وميزانية مرنة (تحذير) وميزانية صارمة (حظر مع 402)، وعدد الطلبات في الدقيقة وعدد tokens في الدقيقة.
• Usage حسب النموذج والمفتاح واليوم، مع إمكانية التصدير.
• Logs: سجلات طلبات قابلة للتصفية (الوقت، المفتاح، النموذج، tokens، التكلفة، الحالة، زمن الاستجابة). لا تُسجَّل نصوص المطالبات والردود. يُحتفظ بالسجلات لمدة 90 يومًا افتراضيًا (ai_log_retention_days).
• Settings: ميزانية الحساب وعنوان البريد الإلكتروني لتنبيهات الميزانية.
• Playground: المحادثة مع نموذج، ومقارنة النماذج جنبًا إلى جنب، ونسخ الكود المتطابق.

نقاط نهاية البوابة، على نطاقك:

POST /ai/v1/chat/completions      OpenAI-compatible
POST /ai/v1/messages              Anthropic-compatible (also /ai/v1/messages/count_tokens)
GET  /ai/v1/models                model list
GET  /ai/v1/models/pricing        public price list, no key needed

المحفظة والفوترة

يتم خصم استخدام الذكاء الاصطناعي من محفظة الدفع المسبق نفسها كأي خدمة أخرى. قبل إرسال الطلب إلى المزود، يحجز NexCMP مبلغًا يعادل أقصى تكلفة محتملة للطلب؛ وإذا كان الرصيد أقل من الحد الأدنى (ai_min_balance_cents، 20 سنتًا افتراضيًا) أو غير كافٍ، يُرفض الطلب مع 402 insufficient_balance ولا يتم استدعاء أي مزود. يتم جمع الاستخدام لكل حساب وتسويته في قيود دفتر أستاذ المحفظة بعد كل ساعة، مع فحص دوري كل 5 دقائق؛ ويُخصم الاستخدام الذي لم تتم تسويته بعد تلقائيًا من الرصيد الذي تراه البوابة.

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

التحقق

1. بعد الخطوة 3، يُظهر Test connection الحالة ok وعدد النماذج.

2. بعد الخطوة 4، تُدرج النماذج الجديدة كمعطلة، ودون تحديد سعر.

3. بصفتك عميلًا لديه محفظة مشحونة، أنشئ مفتاحًا واستدعِ البوابة:

   curl https://your-domain/ai/v1/chat/completions \
     -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \
     -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}'

   يتضمن الرد 200 إجابة النموذج. يُظهر Usage الطلب، ويُظهره Profit إذا كنت قد أدخلت تكلفة.

4. عندما يكون رصيد المحفظة صفرًا، يُرجع الاستدعاء نفسه 402 insufficient_balance.

القيود والملاحظات

• لا تتضمن الوحدة أي مزود أو نموذج أو سعر مدمج مسبقًا، ولا يتم قراءة أي قائمة أسعار من أي مزود مطلقًا.
• تُرفض الأدوات التي تعمل لدى المزود وتُحسب تكلفتها لكل استدعاء، مثل البحث على الويب، لتعذر قياس استهلاكها. ويتم تمرير قائمة قصيرة فقط من معلمات الطلب.
• يتم احتساب استهلاك tokens من رد المزود؛ وإذا خلا الرد منها، يقدّر NexCMP الاستهلاك ويصنّف السجل على أنه تقديري.
• تتم تنقية الأخطاء الواردة من المزود قبل أن تصل إلى العميل (تُزال الأسماء والمضيفون والعناوين واسم النموذج لدى المزود). ولا يرى العملاء مطلقًا المزود الذي تولى معالجة الطلب.
• يصل العملاء إلى البوابة عبر نطاق لوحتك، لذا يجب أن يكون بروتوكول TLS الخاص بذلك النطاق يعمل بشكل صحيح.
• لا يقدّم NexCMP اتفاقية مستوى الخدمة أو الضبط الدقيق أو استضافة GPU لهذه الوحدة.

استكشاف الأخطاء وإصلاحها

العَرَض	السبب والحل
تُرجع كل صفحة من صفحات AI Models والبوابة الرد 404 module_disabled	الوحدة معطلة. فعّل AI Models ضمن License & updates, Modules.
فشل إضافة المزود مع endpoint_host_not_allowed أو endpoint_must_be_https أو invalid_endpoint_port	يجب أن يكون عنوان URL الأساسي بصيغة HTTPS على المنفذ 443 لنطاق عام. بالنسبة للمضيف الداخلي أو منفذ آخر أو بروتوكول HTTP عادي، أدرج host:port ضمن Allowed internal hosts.
blocked_endpoint	العنوان هو عنوان IP، أو يتم حل الاسم إلى عنوان خاص. أدرجه ضمن Allowed internal hosts إذا كان هذا ما تريده.
Test connection يُظهر auth	المفتاح غير صحيح أو لا يملك صلاحية الوصول. أدخل المفتاح مرة أخرى.
يتعذر تفعيل النموذج (no_price)	عيّن سعر البيع أولًا.
يتلقى العملاء 503 ai_unavailable	مفتاح البيع معطّل، أو مفتاح AI الخاص بالموزع معطّل.
يتلقى العملاء 503 upstream_unavailable	لا يوجد مسار مفعّل بمفتاح يخدم هذا النموذج بالتنسيق المطلوب. تحقق من مسارات النموذج ونوع المزود.
يتلقى العملاء 402 insufficient_balance	رصيد المحفظة أقل من الحد الأدنى أو غير كافٍ للطلب. اطلب من العميل شحن الرصيد.