StudioForge 2.0: الحسابات، مفاتيح API المحددة النطاق ومسار ترقية آمن

StudioForge هو خادم النماذج الذي يعمل باستخدام وحدات معالجة الرسومات فقط، وقد كتبته لأستبدل به برنامج LM Studio على جهازي (التفاصيل الكاملة موجودة في المقالة الأصلية). الإصدار 2.0 غير من يمكنه التواصل مع الخادم. في الإصدار 0.2.0، كان الخادم يستمع على جميع واجهات الشبكة ويثق بأي طرف يمكنه الوصول إليه، مع وجود خيار استخدام رمز PIN لأدوات التحكم. أما في الإصدار 2.0، فإن الخادم يستمع فقط على الجهاز الذي يعمل عليه، ولا يقبل أي طلبات من أجهزة أخرى إلا إذا تم تفعيل ذلك صراحةً؛ وعند تفعيله، يتطلب كل طرف متصل مفتاحًا للوصول.

المصدر على GitHub

قمت بترقية جهازي في تاريخ 19 أكتوبر 2026؛ فور ذلك، بدأت جميع البرامج التي كانت تتصل بالخادم دون استخدام مفتاح في تلقي رسائل خطأ من نوع 401 خلال دقائق: أداة البريد الخاصة بي، تطبيق الدردشة، أداة البحث في الذاكرة التابعة لبوابة الوكلاء، بالإضافة إلى عدة سكربتات أخرى. لم يكن هناك أي خلل في هذه البرامج؛ فقط لم تكن تمتلك مفاتيح الوصول اللازمة. هذه الصفحة هي ما كنت أتمنى أن أقرأه منذ البداية.

ما الذي يتغير بالنسبة لك؟

ثلاثة تغييرات، ببساطة.

• الخدمة خاصة بشكل افتراضي. البوابة (المنفذ 1234)، ولوحة التحكم (8080)، بالإضافة إلى أداة المراقبة والاستعادة (1235) ترتبط بعنوان 127.0.0.1. لا يمكن لأي جهاز آخر الوصول إليها على الإطلاق.
• فتح الخدمة يتطلب تسجيل دخول. إذا كان أحد هذه المكونات يستمع على عنوان شبكة، ولم يكن هناك حساب مالك أو مفتاح مسؤول، فإن الأمر studioforge serve يتوقف بكود خروج 4 ويوضح لك كيفية إصلاح المشكلة. لم يعد من الممكن تشغيل خادم مفتوح عن طريق الخطأ.
• كل برنامج يحصل على مفتاحه الخاص. المفتاح عبارة عن سلسلة نصية مثل sf-i-… يرسلها البرنامج كـ Authorization: Bearer <key>. لكل مفتاح اسم ونطاق، بالإضافة إلى تاريخ انتهاء اختياري والحد الأقصى للطلبات في الدقيقة؛ ويمكن إلغاء أي مفتاح دون التأثير على المفاتيح الأخرى.

فيما يلي رسالة الرفض، من اختبار قمت به باستخدام جميع المضيفين مع تعيينهم إلى 0.0.0.0 وبدون وجود أي حساب:

error: Refusing to start: the gateway, the control panel, the watchdog would listen on a
non-loopback address (0.0.0.0, 0.0.0.0, 0.0.0.0) but no owner account or admin API key exists,
so anyone on the network could drive this server. Fix: run `studioforge setup` (creates the
owner account) or `studioforge keys create --name admin --scope admin`, then start again.

هناك تفصيل واحد أربكني: إنشاء المفتاح الأول يفعّل المصادقة لجميع المستخدمين، بما في ذلك البرامج التي تعمل على نفس الجهاز. قمت بإنشاء مفتاح على خادم اختباري يعمل فقط على العنوان المحلي، وبعدها تغيرت استجابة أمر curl البسيط الموجه إلى /v1/models من الرقم 200 إلى 401. أما أدوات StudioForge مثل سطر الأوامر ولوحة التحكم فتستمر في العمل لأنها تُنشئ مفتاح مسؤول محلي خاص بها (local-cli)، ويُخزن هذا المفتاح للاستخدام من قبل المالك فقط في مجلد البيانات. أما باقي البرامج فتحتاج إلى مفتاح منذ تلك اللحظة.

التحديث الآمن في عشر دقائق

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

1. قم بإدراج عملائك. كل تطبيق دردشة، وكل وكيل، وكل سكريبت، وكل آلة أخرى تتصل بالخادم. إذا لم تكن متأكدًا، ابحث في إعداداتهم عن عنوان الخادم باستخدام أمر grep. هذه القائمة تمثل كامل المهمة.
2. قم بعمل نسخة احتياطية ومعاينة. انسخ دليل البيانات، ثم حدّث الكود (git pull)، وبعد ذلك أعد تثبيته في بيئة venv بالطريقة الموضحة في ملف README لمنصتك، ثم نفذ الأمر studioforge migrate --dry-run. الإصدار 2.0.1 ينقل قاعدة البيانات إلى المخطط رقم 10، ويقوم الأمر studioforge migrate بعمل نسخة احتياطية منها قبل تطبيق التغييرات.
3. أنشئ بيانات الاعتماد التي تسمح له بالبدء. إما باستخدام studioforge setup (الإعداد التوجيهي الأول؛ يقوم بإنشاء حساب المالك، وإذا اخترت “شبكتي المحلية”， فإنه يفعّل بروتوكول HTTPS ويُنشئ مفتاح مسؤول)، أو ببساطة باستخدام studioforge keys create --name admin --scope admin.
4. أنشئ مفتاحًا واحدًا لكل عميل، جميعهم دفعة واحدة، قبل أن تبدأ في إعداد الخادم الجديد:

   studioforge keys create --name chat-app  --scope inference --rate-limit-rpm 120
   studioforge keys create --name dashboard --scope read
   studioforge keys create --name laptop    --scope admin --expires-in-days 30

   يتم طباعة كل رمز مرة واحدة ولا يتم تخزينه أبدًا؛ لذا قم بلصقه مباشرةً في إعدادات ذلك العميل.
5. قم ببدء تشغيل الخادم واختبر كل عميل باستخدام طلب حقيقي واحد. ظهور رسالة 401 invalid_api_key يعني أن العميل لا يزال لا يملك مفتاحًا؛ أما رسالة 403 permission_denied فتعني أن نطاق الصلاحيات المرتبط بمفتاح العميل ضعيف جدًا بالنسبة لما حاول القيام به.
6. قم بإلغاء الاعتماد على بيانات الاعتماد القديمة في النهاية. بمجرد أن يعمل كل عميل باستخدام مفتاحه الخاص: استخدم الأمر studioforge keys revoke legacy، ثم امسح قيمة server.api_key وأوقف تشغيل رمز PIN الخاص بـ MCP. راجع مشكلة رمز PIN أدناه؛ فمجرد مسح رمز PIN وحده لا يكفي.
7. قم بتشغيل studioforge doctor واقرأ ما يظهر بعد ذلك.

إذا كنت قد استخدمت بالفعل server.api_key، فإن عملية الترقية نفسها لا تؤدي إلى أي مشاكل: فالمفتاح القديم يتم نسخه في جدول المفاتيح كمفتاح مسؤول باسم legacy ويستمر في العمل. أما جهازي فلم يحتوِ على أي مفتاح مشترك، بل كان لديّ فقط رمز PIN، لذلك توقفت جميع العملاء عن العمل دفعة واحدة. لو قمت بالخطوة 4 قبل الخطوة 5، لكنت تجنبت معظم هذه المشاكل.

لوحة التحكم: تسجيل الدخول، الإعداد، وإنشاء المفاتيح

هذه لقطات الشاشة مأخوذة من نسخة مؤقتة من الإصدار 2.0.1 قمت بتشغيلها باستخدام Podman على جهاز لا يحتوي على أي بطاقة رسوميات من NVIDIA (مزيد من التفاصيل أدناه)، لذا فإن البطاقتين الرسوميتين مجرد محاكاة والمفاتيح غير صالحة للاستخدام.

أصبحت لوحة التحكم تحتوي الآن على صفحة تسجيل دخول. يمكنك استخدام اسم المستخدم وكلمة المرور الخاصين بالمالك، أو ترك حقل اسم المستخدم فارغًا ولصق مفتاح إداري بدلاً من ذلك. لكن لا يمكن استخدام مفتاح read أو inference لفتح اللوحة.

يشرح دليل الإعداد المتاح على الرابط /setup ثماني خطوات: إنشاء حساب المالك، تهيئة الأجهزة، اختيار محرك المعالجة، مكتبات النماذج، نموذج تجريبي للبدء، إجراء محادثة اختبارية، الحصول على أكواد برمجية للعملاء، وتحديد من يمكنه الوصول إلى الخادم. يمكن تخطي أي خطوة من هذه الخطوات. وفي الخطوة الأخيرة يتم اختيار ما بين “فقط هذا الكمبيوتر” و“شبكتي المحلية عبر بروتوكول HTTPS”.

توجد المفاتيح تحت قسم المستخدمون والمفاتيح. يجب إعطاء كل مفتاح اسماً يوضح البرنامج الذي سيستخدمه، كما يمكن تحديد نطاق استخدامه وتاريخ انتهائه وحدود معدل الاستخدام.

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

تعرض الجدول كل المفاتيح مع تفاصيل مثل نطاق الاستخدام، أول بضعة أحرف من الرمز، آخر استخدام له، تاريخ انتهاء الصلاحية، حدود معدل الاستخدام وحالة المفتاح. أسفل ذلك يوجد سجل التدقيق: كل مفتاح تم إنشاؤه أو إلغاؤه، كل عملية تسجيل دخول وكل تغيير إداري، مع ذكر الشخص المسؤول ومصدر الطلب. أما البيانات السرية فلا يتم تسجيلها أبداً في هذا السجل.

النطاقات: قراءة، استنتاج، إدارة

النطاق	ما يمكن فعله	لمن يمكن منحه
read	الاطلاع على الحالة وقوائم النماذج و/metrics، بالإضافة إلى أدوات MCP للقراءة فقط. لا يمكن إرسال أي بيانات عبر POST.	لوحات التحكم وأدوات المراقبة
inference	القراءة، بالإضافة إلى إمكانية الدردشة (/v1/chat/completions، /v1/messages، /v1/responses)، تحميل النماذج وإلغاء تحميلها واختبارها، بالإضافة إلى استخدام أو إطلاق موارد GPU الخاصة بها.	تطبيقات الدردشة والبرامج النصية وغيرها من برامج GPU
admin	تعديل الإعدادات وإعادة التشغيل وتثبيت المحركات وتحديثها وتنزيلها وحذفها، بالإضافة إلى إدارة الحسابات وسجلات المراجعة وأدوات MCP التي قد تؤدي إلى تغييرات جوهرية.	أنت فقط

القاعدة هنا هي الكود وليست الاتفاقيات التقليدية (api/auth.py:required_scope). يتم تحديد النطاق بناءً على بادئة المسار، وأي مسار يغير الحالة ولا يحمل تصنيفًا محددًا يتطلب استخدام نطاق admin؛ وبالتالي فإن المسارات الجديدة تُغطى تلقائيًا. يتم فرض النطاق في كل مرة يتم فيها إرسال مفتاح وصول، حتى على الخوادم التي لا تتطلب نطاقات خاصة؛ فمثلاً، مفتاح الوصول من نوع read لا يمكنه إرسال بيانات عبر POST حتى على الخوادم المخصصة للاستخدام المحلي فقط. لقد اختبرت الحالات الحدودية على نسخة تجريبية؛ حيث حصل مفتاح الوصول من نوع inference على رمز استجابة 200 عند طلب /v1/models، بينما حصل على رمز 403 عند طلب /api/keys.

تحصل البرامج الذكية أيضًا على مفاتيح وصول، لكن لا تحصل أبدًا على كلمة مرور المالك. تُعرض في صفحة “التكاملات” باللوحة الإدارية كتل نصية جاهزة للنسخ والاستخدام مع OpenClaw و SDKs لـ OpenAI وAnthropic بلغة Python، بالإضافة إلى DisPatch وأداة curl وملف --mcp-config الخاص ببرنامج Claude. يجب أولاً اختيار نطاق مفتاح الوصول من القائمة المنسدلة؛ فعند تحديد الخيار الافتراضي، يتم حذف رأس Authorization من كتلة الأوامر الخاصة بـ curl، وبالتالي يؤدي لصقها كما هي إلى الحصول على رمز استجابة 401.

حساب المالك، ومفتاح الوصول القديم، ورمز PIN

يحتوي الإصدار 2.0 على ثلاثة أنواع من بيانات الاعتماد؛ اثنان منها في طور التقاعد.

• حساب المالك: يُستخدم للدخول إلى لوحة التحكم. يجب أن تكون كلمة المرور مكونة من 10 أحرف على الأقل، ويتم تشفيرها باستخدام خوارزمية argon2id. يتم حفظ النتيجة إما في سجل المفاتيح الخاص بالنظام (إذا تم تثبيت الإضافة الاختيارية keyring) أو في ملف خاص بمالك الحساب فقط. هذه البيانات غير موجودة في قاعدة البيانات، لذا فإن نسخة قاعدة البيانات لا تحتوي على أي بيانات تسجيل دخول.
• server.api_key (تم إهماله): لا يزال يعمل كبيانات اعتماد للمسؤول في كل مكان؛ يظهر تحت اسم المفتاح legacy، وتؤدي أداة keys revoke legacy إلى تعطيله فعليًا.
• mcp.pin (تم إهماله): هو رمز PIN مكون من ثمانية أرقام، ويُستخدم كبيانات اعتماد للمسؤول فقط في نقاط اتصال MCP. حتى في الخوادم التي لا تحتوي على أي مفاتيح، يظل هذا الرمز صالحًا للاستخدام، لذا تستمر الإعدادات القديمة في العمل؛ لكن بمجرد وجود أي مفتاح آخر، يتوقف ذلك عن الحدوث.

نقطة خفية بخصوص رمز PIN. يذكر سجل التغييرات أنه يجب "مسح server.api_key وmcp.pin"؛ لكن إذا قمت بتعيين mcp.pin: null فقط، فإن النظام سيولد رمز PIN عشوائيًا جديدًا عند بدء التشغيل ويحفظه، لأن قيمة mcp.pin_required لا تزال true. لقد شاهدت ذلك بنفسي. للتخلص من هذا الرمز نهائيًا، يجب تعيين كلا القيمتين:

mcp:
  pin: null
  pin_required: false

وبنفس المنطق، فإن أي تثبيت جديد للإصدار 2.0.1 سيولد رمز PIN عند أول تشغيل، ثم تقوم أداة studioforge doctor بالإشارة إلى أن هذا الرمز قد تم إهماله. الأمر غير ضار، لكن لا تتفاجأ به.

الربط، HTTPS والمتصفحات

• قاعدة الربط. قيم server.host وgui.host وwatchdog.host تكون بشكل افتراضي 127.0.0.1. أما الإعدادات التي تم كتابتها بواسطة إصدار قديم فتحدد قيمة 0.0.0.0 صراحةً، لذا فإن القيمة الافتراضية الجديدة لا تغير ذلك؛ هذه الإعدادات تمنع الوصول حتى يتم إضافة بيانات الاعتماد المناسبة.
• HTTPS. خاصية server.tls.mode هي المفتاح الذي يتحكم في جميع المستمعين الثلاثة: قيمها تكون off أو self_signed (يتم إنشاء شهادة تلقائيًا في دليل البيانات، ويظهر بصمة SHA-256 الخاصة بها في اللوحة لكي تستخدمها العملاء للتحقق من صحة الشهادة) أو cert (لاستخدام ملفاتك الخاصة). عند تفعيل الربط الشبكي وإيقاف TLS، يصدر برنامج doctor تحذيرًا من أن المفاتيح تُنقل عبر الشبكة بشكل غير مشفر؛ ويمكن أيضًا استخدام بروكسي عكسي أو أداة tailscale serve للقيام بذلك.
• المتصفحات. أصبحت قيمة server.cors_origins افتراضيًا فارغة (كانت سابقًا ["*"]). العملاء غير المتصفحات لا يهتمون بهذا الأمر. أما نقاط النهاية الخاصة ببروتوكول MCP فتضيف تحققًا إضافيًا على خاصية Origin: يجب أن تأتي الطلبات التي تحتوي على رأس Origin من صفحة محلية أو من أصل مصرح به، ولا يتم اعتبار القيمة * كأصل مسموح به. هذا الإجراء يمنع أي صفحة ويب عشوائية من التحكم في أدوات إدارة الجهاز عبر المتصفح.
• الهجوم القسري. يتم منح كل عنوان IP ثلاث محاولات مجانية لإدخال بيانات الاعتماد الصحيحة، وبعد ذلك يزيد وقت الانتظار بشكل مضاعف حتى خمس دقائق؛ ويتم تطبيق ذلك بشكل منفصل على واجهة API واللوحة الإدارية ونظام المراقبة.

مشاركة البطاقات الرسومية: عقود الإيجار والمستأجرون

إذا كان هناك برامج أخرى على الجهاز تستخدم وحدات معالجة الرسومات (مثل مولد الصور، أو خادم المعالجة الصوتية، أو أداة القياس)، فيمكن لهذه البرامج أولاً الحصول على حق استخدام مؤقت لإحدى وحدات معالجة الرسومات؛ ولن يقوم StudioForge بتحميل أي نموذج على تلك الوحدة إلا بعد انتهاء مدة الاستخدام المؤقت أو عندما تصبح الوحدة خاملة لفترة طويلة. الإصدار 2.0 يضيف سجل المستأجرين، مما يسمح لهذه البرامج بالإعلان عن وجودها وعرض حالتها الحالية على صفحة التوزيع؛ كما يدعم خيار devices: "auto" الذي يتيح للمستأجر طلب أي وحدة معالجة رسومات تتوفر بها ذاكرة كافية بدلاً من تحديد وحدة معينة. يقوم StudioForge بعرض قائمة المستأجرين، ويمكنه طلب من أحدهم تحضير وحدة معالجة الرسومات أو إخلاءها، لكنه لا يبدأ تشغيل هذه البرامج أو يوقفها أبدًا.

إصلاح الإصدار 2.0.1 مهم إذا كنتم تستخدمون أيًا من هذه الميزات: في الإصدار 2.0.0، كانت مسارات المستأجرين تتطلب وجود مفتاح admin؛ لذلك فإن أي خادم للصوت أو الصور يحتوي على مفتاح inference مناسب كان يحصل على رمز الخطأ 403 عند محاولته الحصول على ترخيص. أما في الإصدار 2.0.1، فقد أصبحت هذه المسارات تُعرف باسم مسارات inference، وكل ترخيص يرتبط بالمفتاح الذي حصل عليه؛ لذا لا يمكن لأي مفتاح inference آخر إلغاء هذا الترخيص (لقد جربت ذلك، وحصلت على رسالة الخطأ 403 permission_denied مع نص “لم يتم إنشاء هذا الترخيص بواسطة هذا المفتاح”)، بينما لا يزال بإمكان مفتاح admin القيام بذلك.

شيء واحد يجب معرفته عند تسمية المستأجر: يتم ربط العقود بالمستأجرين بناءً على الاسم العائلي، وهو الاسم الموجود قبل أول علامة -. المستأجر المسجل باسم speech-demo لم يجد عقده الخاص باسم speech-demo (لأن الاسم العائلي للعقد هو speech)؛ أما إذا سُجّل باسم speech، فقد وجد عقده. لذا يجب استخدام اسم مستأجر لا يحتوي على شرطة. يتم توثيق البروتوكول نفسه في ملف docs/TENANTS.md داخل المستودع.

sfctl 2.0.1، أداة التحكم عن بُعد

sfctl هو عميل صغير يُستخدم للتحكم في خادم StudioForge من جهاز آخر، كما يعمل كجسر MCP للوكلاء. يتطلب الآن مفتاحًا للتشغيل؛ وهو غير متوفر على PyPI (فأمر uv tool install studioforge-companion المذكور في ملف README لا يعمل)، لذا يجب تثبيته عبر استنساخ المستودع:

git clone https://github.com/LaserLloyd/StudioForge.git
uv tool install ./StudioForge/packages/studioforge-companion
sfctl servers add rig http://192.0.2.10:1234 --api-key sf-i-your-key --use
sfctl status

يتم حفظ ملف الإعدادات في المسار ~/.config/studioforge/companion.toml، ويكون قابلاً للقراءة فقط من قبل المالك نظرًا لاحتوائه على المفتاح السري. كما يمكن استخدام المتغير البيئي SF_API_KEY بدلاً من ذلك. وإذا لم يكن بوابة الاتصال تعمل على المنفذ 1234، فيجب إضافة المعلمة --watchdog-url؛ حيث يتم استنتاج عنوان خدمة المراقبة من عنوان البوابة نفسها. وفي حالتي، مع استخدام مفتاح من نوع inference:

$ sfctl status
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┓
┃ GPU ┃ Name                           ┃ Total    ┃ Used ┃ Free     ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━┩
│ 0   │ Demo GPU 0 (simulated) (sm_86) │ 24.0 GiB │ 0 B  │ 24.0 GiB │
│ 1   │ Demo GPU 1 (simulated) (sm_86) │ 24.0 GiB │ 0 B  │ 24.0 GiB │
└─────┴────────────────────────────────┴──────────┴──────┴──────────┘
no models loaded

$ sfctl leases add --devices 1 --holder image-render --reason "a render job outside StudioForge"
lease 933d9554c0c6 holds GPU 1 for image-render
release it with: sfctl leases release 933d9554c0c6

(لقد قمت بحذف أعمدة Util وTemp وجدول الخوادم لضمان تناسب المحتوى مع العرض.)

أداة Doctor وحزمة الدعم

studioforge doctor تتحقق من المنافذ، ووحدات معالجة الرسومات، والمحرك، والقرص الصلب، وأذونات الملفات، والشهادة الأمنية، بالإضافة إلى عمليات الترحيل وإعدادات المصادقة؛ ثم تعرض حلاً لكل مشكلة. الخيار --strict يجعل الأداة تنهي عملها بقيمة غير صفرية في حال وجود تحذيرات، وهو ما يناسب عمليات المراقبة. هذا هو حاوية العرض التوضيحي؛ حيث تستمع على الشبكة باستخدام حساب مالك وتعطيل تشفير TLS:

[ok  ] GPU: 2 GPU(s) via fake: Demo GPU 0 (simulated) (24 GiB), Demo GPU 1 (simulated) (24 GiB).
[WARN] Engine: No llama.cpp engine is installed.
        fix: Run `studioforge setup` or `studioforge engine --update` to install and smoke-test one.
[ok  ] Permissions: The data directory is writable and credential files are owner-only.
[ok  ] Migrations: The database is at schema 10 (current).
[info] Authentication: The server listens on the network and requires an API key or an account.
[WARN] Authentication: The network listeners use plain HTTP, so keys and passwords cross the network in the clear.
        fix: Set server.tls.mode to self_signed (or cert), or front the server with a TLS reverse proxy / `tailscale serve`.
[info] Authentication: mcp.pin is set. It is deprecated and grants admin on the MCP endpoints.

9 ok, 3 info, 2 warnings, 0 failures.

على خادم الاختبار المحلي الذي كان لا يزال يحتوي على إعداد server.api_key، أصدرت الأداة تحذيراً يقول: "تم تعيين server.api_key؛ فهو لا يزال يعمل (كمفتاح إداري من نوع 'legacy') لكنه أصبح غير مستخدم حالياً"، مع اقتراح الحل التالي: إنشاء مفاتيح ذات نطاق محدد، ونقل العملاء إلى استخدامها، وإلغاء صلاحية المفتاح legacy.

studioforge support-bundle تقوم بإنشاء ملف مضغوط صغير لتقارير الأخطاء؛ يحتوي على إعدادات معدلة، ونتائج تشغيل أداة Doctor، وأرقام الإصدارات، وقائمة وحدات معالجة الرسومات، بالإضافة إلى آخر سطور من السجلات. كان حجم ملفي 6 كيلوبايت، وتم إخفاء قيمة PIN فيه على شكل [REDACTED]. كما تم إخفاء قيمة engine.pinned_tag، وهي رقم بناء llama.cpp؛ وهو معلومة مفيدة في تقارير الأخطاء ولا تُعتبر سرية، لذا يجب إدخالها يدوياً. الأداة نفسها تنصح بـ "التفكير قبل المشاركة"، وهي نصيحة صائبة للغاية.

التشغيل داخل حاوية

يأتي الإصدار 2.0 مع ملف Dockerfile يحتوي على نسخ مخصصة لـ CUDA وROCm وVulkan، بالإضافة إلى مستخدم غير جذر، ونظام ملفات للقراءة فقط، وحجم تخزيني مسمى؛ كما يتضمن ملفات compose لكل من Docker وPodman. تقوم الحاوية بإنشاء حساب المالك عند أول تشغيل لها على وحدة تخزين جديدة، وذلك باستخدام كلمة المرور المحددة في المتغير SF_OWNER_PASSWORD أو كلمة مرور تم إنشاؤها وحفظها على الوحدة التخزينية؛ وذلك لأن نشر أي منفذ يُعتبر "خارج نطاق الـ loopback" من داخل الحاوية. يتم نشر المنافذ إلى 127.0.0.1 ما لم تقم بتحديد القيمة في المتغير SF_BIND.

الصور الخاصة بالحاويات غير متوفرة بعد في أي سجل صور (ففي الوقت الحالي يتم رفض محاولات السحب من الرابط ghcr.io/laserlloyd/studioforge)، لذا يجب عليك بناء الصورة بنفسك؛ ويحتوي ملف README على الأوامر الدقيقة لكل منصة. لقد قمت ببناء صورة Vulkan باستخدام Podman من أجل هذه اللقطات: حجمها 568 ميجابايت، وتم تشغيلها في وضع القراءة فقط مع تعطيل جميع القدرات المتاحة. الصورة الخاصة بـ NVIDIA هي الوحيدة التي استُخدمت لتشغيل نموذج حقيقي؛ أما صورات AMD وVulkan فهي تبدأ التشغيل وتستجيب لطلب /health، لكنها لم تُجرّب بعد على أجهزة AMD أو Intel. يمكن الاطلاع على أحجام الصور، وإعدادات وحدات معالجة الرسومات، ونتائج اختبارات الترقية، بالإضافة إلى خطط النسخ الاحتياطي للنظام بأكمله في صفحة كل الوحدات في Docker، لذا لن أكرر ذلك هنا.

جديد أيضًا في الإصدار 2.0

• المزيد من العملاء يمكنهم الاستخدام دون تغييرات: واجهة REST الأصلية الخاصة بـ LM Studio تحت المسار /api/v1، بالإضافة إلى مسار متوافق مع أنظمة Anthropic وهو /v1/messages (حيث يعمل كل من x-api-key ومفتاح الحامل كذلك)، وكذلك مسار OpenAI الخالي من الحالة وهو /v1/responses.
• رسائل خطأ توضح كيفية إصلاحها: يوجد 76 رمز خطأ، ولكل منها حقلان هما fix و docs داخل نص الخطأ. فعلى سبيل المثال، عندما يحصل العميل على رمز الخطأ 401 دون وجود مفتاح، يتم ذكر الأمر اللازم لإنشاء مفتاح جديد.
• دعم أكثر من أنظمة NVIDIA، نظريًا على الأقل: يوجد دعم لأنظمة ROCm وVulkan وMetal لفحص بطاقات الرسوميات، بالإضافة إلى أداة تثبيت المحركات التي تتحقق من ملفات التحميل. تم الاختبار باستخدام نتائج فحص مسجلة مسبقًا، وليس على أجهزة AMD أو Apple الحقيقية؛ كما يتم رفض أي جهاز Vulkan برمجي مثل llvmpipe، لأن استخدام النماذج على وحدة المعالجة المركزية هو بالضبط ما صُمم StudioForge لتجنبه.
• لوحة تحكم أكبر: تضم 11 قسمًا (نظرة عامة، النماذج، خدمة التشغيل، المحركات، التكاملات، المستخدمون والمفاتيح، التحديثات، السجلات والمقاييس، أدوات التشخيص، والميزات المتقدمة) بالإضافة إلى ثلاثة سمات جديدة.
• نظام ترقيم إصدارات دلالي: الإصدار 2.0.0 يتبع نظام الترقيم القديم “1.26-09-23”، كما أن أداة التحديث تقوم بترتيب كلا النظامين بشكل صحيح.

كيف قمت بالاختبار، وما الذي لم أختبره

الجهاز الذي أكتب عليه لا يحتوي على بطاقة رسوميات من NVIDIA، لذا لم أستطع تحميل أي نموذج. يضم StudioForge واجهة برمجية لمحاكاة بطاقات الرسوميات في مجموعة الاختبارات الخاصة به (SF_GPU_PROBE=fake مع قائمة بأسماء البطاقات في SF_FAKE_GPUS)، وتعمل عليه جميع المكونات مثل لوحة التحكم والمفاتيح والحسابات والتراخيص والمستأجرين ووحدة الدعم. كل ما ورد أعلاه تحت عنوان “لقد جربت” أو ما يظهر كمخرجات تم تنفيذه باستخدام الإصدار 2.0.1؛ مرة من خلال نسخة من المستودع في دليل مؤقت، ومرة أخرى داخل حاوية Podman، وكلاهما على منافذ loopback، باستخدام ملفات نماذج تجريبية تحتوي على رؤوس البيانات فقط دون أوزان. أحجام النماذج ومستويات التكميم المذكورة في لوحة التحكم هي قيم حقيقية؛ لكن النماذج نفسها ليست كذلك.

<pوما لم أختبره هنا: تحميل أو تقديم النماذج للاستخدام، واستخدام بروتوكول TLS في وضع self_signed، بالإضافة إلى عملية الترقية المباشرة من دليل بيانات الإصدار 1.26 (يغطي مقال Docker عملية الترقية على نفس وحدة التخزين). أما الدرس المتعلق بالترقية المذكور في البداية فهو مستمد من جهازي الحقيقي، وليس من النسخة التجريبية.

نقاط الضعف والعيوب

• لا يوجد إصدار بعد. الإصدار 2.0.1 موجود في فرع main دون أي علامات تعريف، ولا يوجد إصدار رسمي على GitHub، ولا حزمة على PyPI، ولا صورة جاهزة للاستخدام. لذا فإن أداة التحديث الذاتي لا تملك شيئًا يمكن تحديثه حتى يصدر إصدار جديد.
• تحذير مضلل. في خادم متصل بالشبكة يحتوي على حساب مالك لكن بدون وجود server.api_key، فإن قائمة الإعدادات في صفحة “النظرة العامة” تذكر أن الخادم يمكن الوصول إليه “بدون مفتاح API؛ أي أي شخص على الشبكة المحلية يمكنه تحميل النماذج أو حذفها”. لكن هذا غير صحيح؛ فصفحة “المستخدمون والمفاتيح” والطلبات الفعلية تُظهر أن عملية تسجيل الدخول إلزامية. القائمة المذكورة تأخذ في الاعتبار فقط المفتاح المشترك القديم.
• الوثائق غير متفقة بشأن محرك الحاوية. طريقة التشغيل عبر Docker الموضحة في ملف README تستخدم صورة بحجم 14 جيجابايت وهي -cuda-devel، حيث يتم تجميع برنامج llama.cpp عند أول تشغيل؛ بينما يذكر دليل استخدام الحاويات أن الصورة الأصغر حجمًا وهي -cuda تقوم بتحميل محرك جاهز للاستخدام. لم أتمكن من التأكد من ذلك بدون بطاقة NVIDIA؛ لذا يُفضل اتباع تعليمات ملف README حتى يتم الاتفاق بين الوثائق.
• لم يقم أحد بمراجعته أمنيًا. تم توثيق نموذج الأمان في ملف docs/SECURITY.md ضمن المستودع، ويشمل ذلك ما لا يحميه النظام (مثل وجود مسؤول على نفس الجهاز، أو استخدام بروتوكول HTTP العادي في شبكة غير خاضعة لسيطرتك). يُنصح بقراءته قبل تشغيل StudioForge على أي شبكة مشتركة.

احصل عليه

git clone https://github.com/LaserLloyd/StudioForge.git

بعد ذلك، اتبع التعليمات الموجودة في ملف README الخاص بمنصتك. الإصدار القديم المتاح على المقالة الأصلية هو الإصدار 0.2.0 ولا يحتوي على أي من هذه الميزات. الرخصة المستخدمة: MIT.

ذات صلة: StudioForge: خادم LLM يعمل باستخدام وحدات معالجة الرسومات فقط (يشمل أدوات التخطيط والقياسات وأدوات MCP)، تشغيل كل الوحدات في Docker (طريقة تشغيل الحزمة بأكملها داخل حاويات)، وDisPatch (تطبيق دردشة يتصل بهذا الخادم باستخدام مفتاح خاص).