يغطي هذا الدليل إنشاء وإدارة واستخدام بيانات اعتماد الذكاء الاصطناعي (الأسرار المشتركة) عبر نماذج اللغات الكبيرة (LLMs)، ونماذج التضمين (embedding models)، وأدوات الذكاء الاصطناعي المخصصة في إضافة Discourse AI.
مستوى المستخدم المطلوب: المشرف
الملخص
توفر بيانات اعتماد الذكاء الاصطناعي طريقة مركزية وآمنة لإدارة أسرار المصادقة — مثل مفاتيح API — عبر إعدادات Discourse AI الخاصة بك. بدلاً من لصق مفاتيح API الخام في كل نموذج لغة كبيرة، أو تعريف تضمين، أو أداة مخصصة على حدة، يمكنك إنشاء بيانات اعتماد مرة واحدة والاستشهاد بها في أي مكان يُطلب فيها.
عند تدوير مفتاح (مثل مفتاح OpenAI API الخاص بك)، تقوم بتحديثه في مكان واحد، وتلتقط كل نموذج لغة كبيرة، أو تضمين، أو أداة تستخدم بيانات الاعتماد هذا التغيير تلقائيًا.
يتناول هذا التوثيق:
- إنشاء وإدارة بيانات الاعتماد
- ربط بيانات الاعتماد بنماذج اللغة الكبيرة ونماذج التضمين
- استخدام بيانات الاعتماد في أدوات الذكاء الاصطناعي المخصصة
- حماية الحذف ودورة حياة بيانات الاعتماد
- واجهة برمجة التطبيقات (API) لإدارة بيانات الاعتماد برمجياً
ما هي بيانات الاعتماد؟
بيانات الاعتماد هي سر مسمى وقابل لإعادة الاستخدام يتم تخزينه بشكل مركزي في Discourse AI. يحتوي على حقلين رئيسيين:
| الحقل | الوصف |
|---|---|
| الاسم | تسمية فريدة يمكن قراءتها بواسطة البشر (مثل “مفتاح OpenAI API”). الحد الأقصى 100 حرف. |
| القيمة | السر الفعلي (مفتاح API، رمز مميز، إلخ). الحد الأقصى 10,000 حرف. |
يمكن الاستشهاد ببيانات الاعتماد من قبل ثلاثة أنواع من الكيانات:
- نماذج اللغة الكبيرة (LLM) — كمفتاح API الأساسي
- تعريفات التضمين — كمفتاح API الأساسي
- أدوات الذكاء الاصطناعي المخصصة — كروابط أسرار مسموعة يتم الوصول إليها من JavaScript
بالإضافة إلى ذلك، تشير بعض معاملات مزود اللغة الكبيرة من نوع “السر” (مثل access_key_id لـ AWS Bedrock) أيضًا إلى بيانات الاعتماد.
إنشاء وإدارة بيانات الاعتماد
الوصول إلى صفحة بيانات الاعتماد
انتقل إلى المشرف → الإضافات → Discourse AI → بيانات الاعتماد، أو قم بزيارة /admin/plugins/discourse-ai/ai-secrets مباشرةً.
[موقع لقطات شاشة: صفحة قائمة بيانات الاعتماد تظهر أعمدة الاسم، المستخدمة بواسطة، وزر التعديل]
إنشاء بيانات اعتماد جديدة
- في صفحة بيانات الاعتماد، انقر فوق “بيانات اعتماد جديدة”.
- أدخل اسمًا لبيانات الاعتماد (مثل “مفتاح OpenAI API”).
- أدخل القيمة — مفتاح API الفعلي أو الرمز المميز. يتم عرض هذا الحقل كمدخل لكلمة مرور.
- انقر فوق “حفظ”.
[موقع لقطات شاشة: نموذج محرر بيانات الاعتماد مع حقول الاسم والقيمة]
يمكنك أيضًا إنشاء بيانات اعتماد مباشرة أثناء إعداد نموذج لغة كبيرة، أو تضمين، أو أداة. يسمح لك حوار منبثق بإضافة بيانات اعتماد جديدة دون مغادرة الصفحة الحالية، وتظهر بيانات الاعتماد فورًا في قائمة الاختيار المنسدلة.
تعديل بيانات اعتماد
- في صفحة قائمة بيانات الاعتماد، انقر فوق “تعديل” بجوار بيانات الاعتماد.
- قم بتحديث الاسم أو القيمة حسب الحاجة.
- انقر فوق “حفظ”.
عند عرض بيانات اعتماد موجودة، تكون قيمة السر مخفية (********) في عرض القائمة. لا تُعرض القيمة الفعلية إلا في صفحة تعديل بيانات الاعتماد الفردية.
حذف بيانات اعتماد
لا يمكن حذف بيانات الاعتماد إذا كانت تشير إليها حاليًا أي نموذج لغة كبيرة، أو تضمين، أو أداة. إذا حاولت حذف بيانات اعتماد قيد الاستخدام، يعرض الواجهة رسالة تسرد الكيانات التي تشير إليها، مع روابط لصفحات تعديلها.
لحذف بيانات اعتماد:
- أولاً، أزل أو أعيد تعيين جميع الإشارات إلى بيانات الاعتماد من أي نماذج لغة كبيرة، أو تضمينات، أو أدوات.
- عد إلى صفحة تعديل بيانات الاعتماد.
- انقر فوق “حذف” و Confirm الإجراء.
ربط بيانات الاعتماد بنماذج اللغة الكبيرة والتضمينات
نماذج اللغة الكبيرة (LLM)
عند إعداد نموذج لغة كبيرة في صفحة إعدادات اللغة الكبيرة، يمكنك اختيار بيانات اعتماد موجودة من قائمة منسدلة بدلاً من لصق مفتاح API مباشرة. أثناء وقت التشغيل، يحل النموذج السر من بيانات الاعتماد المرتبطة.
بالنسبة لأسرار محددة للمزود — مثل access_key_id الخاص بـ AWS Bedrock — يتم تخزين معرف بيانات الاعتماد داخل معاملات المزود ويتم حله بشكل شفاف عندما يقوم النموذج بطلبات API.
تعريفات التضمين
تعمل نماذج التضمين بنفس الطريقة. عند إعداد تعريف تضمين، اختر بيانات اعتماد من القائمة المنسدلة. يتحقق نموذج التضمين من وجود إما بيانات اعتماد أو مفتاح API مضمن، ويستخدم قيمة بيانات الاعتماد أثناء وقت التشغيل.
استخدام بيانات الاعتماد في أدوات الذكاء الاصطناعي المخصصة
تستخدم أدوات الذكاء الاصطناعي المخصصة نمط العقد والربط للأسرار، مما يبقي تعريف الأداة قابلاً للنقل (قابل للتصدير/الاستيراد) بينما تظل الأسرار محلية للموقع.
الخطوة 1: إعلان عقود الأسرار
عند إنشاء أداة أو تحريرها، تعلن عن الأسرار التي تتطلبها الأداة بإضافة إدخالات إلى عقود بيانات الاعتماد الخاصة بها. يحتوي كل إدخال على اسم مستعار — معرف بسيط يستخدم الحروف والأرقام والشرطات السفلية.
في صفحة محرر الأداة، انقر فوق “إضافة بيانات اعتماد” لإضافة إدخال عقد جديد ومنحه اسمًا مستعارًا، على سبيل المثال external_api_key.
[موقع لقطات شاشة: محرر الأداة يظهر حقول الاسم المستعار لبيانات الاعتماد ومحددات بيانات الاعتماد]
يجب أن تطابق الأسماء المستعارة النمط [a-zA-Z0-9_] وأن تكون فريدة داخل الأداة.
الخطوة 2: ربط بيانات الاعتماد بالأسماء المستعارة
بجانب كل اسم مستعار مُعلن في صفحة إعدادات الأداة، اختر بيانات اعتماد موجودة من القائمة المنسدلة. هذا ينشئ ارتباطًا بين الاسم المستعار وبيانات الاعتماد.
يتم التحقق من صحة الربط لضمان:
- وجود بيانات الاعتماد المحددة
- إعلان الاسم المستعار في عقود الأداة
الخطوة 3: الوصول إلى الأسرار أثناء وقت التشغيل في JavaScript
داخل JavaScript الخاص بالأداة، قم بالوصول إلى الأسرار باستخدام واجهة برمجة التطبيقات secrets.get():
function invoke(params) {
const apiKey = secrets.get("external_api_key");
const result = http.get("https://api.example.com/data", {
headers: { "Authorization": "Bearer " + apiKey }
});
return JSON.parse(result.body);
}
استبدل external_api_key بالاسم المستعار الذي أعلنته في عقود بيانات اعتماد الأداة.
يجب أن يكون لجميع الأسماء المستعارة المُعلنة روابط بيانات اعتماد قبل أن تتمكن الأداة من التشغيل. إذا كانت هناك أي روابط مفقودة، يتم حظر التنفيذ برسالة خطأ تسرد الأسماء المستعارة غير المرتبطة.
مثال: أداة متعددة بيانات الاعتماد
افترض أنك تبني أداة تستدعي واجهتين برمجتين مختلفتين. أعلن عن عقدتين لبيانات الاعتماد:
| الاسم المستعار | الوصف |
|---|---|
weather_api_key |
مفتاح لواجهة بيانات الطقس |
geocode_api_key |
مفتاح لواجهة الترميز الجغرافي |
ثم اربط كل اسم مستعار ببيانات الاعتماد المناسبة في صفحة إعدادات الأداة.
في السكربت:
function invoke(params) {
const weatherKey = secrets.get("weather_api_key");
const geocodeKey = secrets.get("geocode_api_key");
const location = http.get(
"https://geocode.example.com/search?q=" + encodeURIComponent(params.city),
{ headers: { "X-Api-Key": geocodeKey } }
);
const coords = JSON.parse(location.body);
const forecast = http.get(
"https://weather.example.com/forecast?lat=" + coords.lat + "&lon=" + coords.lon,
{ headers: { "Authorization": "Bearer " + weatherKey } }
);
return JSON.parse(forecast.body);
}
تتبع استخدام بيانات الاعتماد
تتبع كل بيانات اعتماد المكان الذي تشير إليه. في صفحة قائمة بيانات الاعتماد، يعرض عمود “المستخدمة بواسطة” روابط لكل نموذج لغة كبيرة، أو تضمين، أو أداة تستخدم حاليًا تلك بيانات الاعتماد.
تساعدك هذه الرؤية على:
- فهم التأثير قبل تدوير أو تحديث سر
- تحديد بيانات الاعتماد غير المستخدمة التي يمكن إزالتها بأمان
- التنقل بسرعة إلى الكيانات التي تعتمد على بيانات الاعتماد
مرجع واجهة برمجة التطبيقات (API)
تتطلب جميع نقاط النهاية مصادقة المشرف وتقع تحت المسار /admin/plugins/discourse-ai/ai-secrets.
| الطريقة | المسار | الوصف |
|---|---|---|
GET |
/ai-secrets |
سرد جميع بيانات الاعتماد (القيم مخفية) |
GET |
/ai-secrets/:id |
عرض بيانات اعتماد واحدة (القيمة غير مخفية) |
POST |
/ai-secrets |
إنشاء بيانات اعتماد جديدة |
PUT |
/ai-secrets/:id |
تحديث بيانات اعتماد |
DELETE |
/ai-secrets/:id |
حذف بيانات اعتماد (يرجع 409 إذا كانت قيد الاستخدام) |
جسم الطلب للإنشاء والتحديث:
{
"ai_secret": {
"name": "مفتاح OpenAI API",
"secret": "sk-..."
}
}
يتم تسجيل جميع عمليات الإنشاء والتحديث والحذف في سجل إجراءات الطاقم. تُعامل قيم الأسرار على أنها حساسة ولا تُكتب أبدًا في السجلات.
الترحيل التلقائي من مفاتيح API المضمنة
يتم ترحيل التثبيتات الحالية التي استخدمت سابقًا مفاتيح API مضمنة تلقائيًا. عملية الترحيل:
- تقرأ جميع نماذج اللغة الكبيرة وتعريفات التضمين غير المضمنة التي تحتوي على مفتاح API مضمن.
- تزيل التكرار حسب مفتاح API والمزود — إذا كان نموذجان يشاركان نفس المفتاح والمزود، فسيتم تعيين بيانات اعتماد واحدة لهما.
- ينشئ سجلات بيانات اعتماد بأسماء مولدة تلقائيًا مثل “مفتاح OpenAI API”، “مفتاح AWS Bedrock API”، إلخ.
- يقوم بتحديث سجلات نموذج اللغة الكبيرة وتعريف التضمين للإشارة إلى بيانات الاعتماد الجديدة.
- يتعامل مع قيم
access_key_idالخاصة بـ AWS Bedrock في معاملات المزود — استخراج المفتاح الخام، وإنشاء بيانات اعتماد، واستبدال القيمة المضمنة بمعرف بيانات الاعتماد.
يتم تشغيل هذا الترحيل تلقائيًا عند الترقية ولا يمكن عكسه. لا يلزم أي إجراء يدوي.
المشاكل الشائعة والحلول
“هذه بيانات الاعتماد مستخدمة حاليًا ولا يمكن حذفها”
هذا يعني أن أحد نماذج اللغة الكبيرة، أو التضمينات، أو الأدوات تشير إلى بيانات الاعتماد. تحقق من عمود “المستخدمة بواسطة” في صفحة قائمة بيانات الاعتماد لتحديد وإعادة تعيين أو إزالة تلك الإشارات قبل الحذف.
“روابط بيانات اعتماد مطلوبة مفقودة” عند تشغيل أداة
يجب أن يكون لجميع الأسماء المستعارة لبيانات الاعتماد المُعلنة في عقود الأداة روابط. افتح صفحة تحرير الأداة، وتحقق من أن كل اسم مستعار لديه بيانات اعتماد محددة في القائمة المنسدلة، ثم احفظ.
تظهر قيمة بيانات الاعتماد كـ ********
هذا سلوك متوقع. يتم إخفاء قيم الأسرار في عروض القائمة لأسباب أمنية. لعرض أو تحرير القيمة الفعلية، انقر فوق “تعديل” على بيانات الاعتماد المحددة.
تم تدوير مفتاح ولكن ميزات الذكاء الاصطناعي تفشل
بعد تحديث قيمة بيانات الاعتماد، تحقق من أن اختبار نموذج اللغة الكبيرة (في صفحة إعدادات اللغة الكبيرة) يمر. إذا كان المفتاح الجديد لديه أذونات مختلفة أو ينتمي إلى حساب مختلف، تحقق من متطلبات إعداد المزود.
الأسئلة الشائعة
هل يمكنني ما زال استخدام مفاتيح API المضمنة بدلاً من بيانات الاعتماد؟
تعمل مفاتيح API المضمنة القديمة بشكل صحيح للإعدادات الحالية. ومع ذلك، فإن بيانات الاعتماد هي النهج الموصى به لأنها تبسط تدوير المفاتيح وتقلل التكرار.
هل يتم تشفير قيم بيانات الاعتماد أثناء الراحة؟
يتم تخزين قيم بيانات الاعتماد في قاعدة البيانات. تتبع نفس نموذج الأمان مثل بيانات Discourse الحساسة الأخرى. تأكد من تأمين قاعدة بياناتك بشكل صحيح وأن النسخ الاحتياطية يتم التعامل معها بشكل مناسب.
ماذا يحدث عندما أستورد أداة تستخدم بيانات اعتماد؟
تشمل استيراد الأدوات أسماء المستعارة لعقود بيانات الاعتماد ولكن ليس القيم السرية الفعلية. بعد استيراد أداة، ستحتاج إلى إنشاء أو اختيار بيانات اعتماد لكل اسم مستعار مُعلن في صفحة إعدادات الأداة.
هل يمكنني مشاركة بيانات اعتماد واحدة عبر نماذج لغة كبيرة متعددة؟
نعم. يمكن لنماذج لغة كبيرة وتضمينات متعددة الإشارة إلى نفس بيانات الاعتماد. هذا مفيد بشكل خاص عندما تستخدم نفس مفتاح مزود API عبر عدة إعدادات نموذج.