Hugging Face's logo

Chat UI documentation

تشغيل واجهة المحادثة مع ML Intern محلياً

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

تشغيل واجهة المحادثة مع ML Intern محلياً

هذا الدليل مخصص للمطورين الذين يرغبون في تشغيل ML Intern على أجهزتهم الخاصة، أو تجربة تعديلات عليه، أو نشره في نسخة Chat UI الخاصة بهم. إذا كنت ترغب فقط في استخدام ML Intern، راجع البدء باستخدام ML Intern.

ML Intern هو وضع مدمج في واجهة المحادثة. عند تفعيله، تصبح المحادثة:

  • يعمل على مجموعة ثابتة من النماذج القادرة على استخدام الأدوات
  • يتصل بخادم Hugging Face MCP مع مجموعة أدوات intern الخاصة بـ Hub
  • يحصل على أدوات مدمجة إضافية: التخطيط، البحث، ملفات سكربتات مُنَسَّخة، بيئات معزولة، لوحات تحكم Trackio، والانتظار على Jobs
  • يحمل ميزانية حسابات يفرضها الخادم على كل مهمة وعزل ينشئهما

المتطلبات

  • Node.js 20 أو أحدث، ونسخة من huggingface/chat-ui مع تنفيذ npm install.
  • حساب Hugging Face يحتوي على أرصدة. محادثات ML Intern التي تشغّلها محليًا تُطلق مهام (Jobs) وبيئات رملية (sandboxes) حقيقية على حسابك.
  • رمز وصول Hugging Face يحمل صلاحية استدعاء مزودي الاستدلال. يستخدم واجهة المحادثة هذا الرمز للتواصل مع النماذج.
  • تطبيق OAuth من Hugging Face (تم إعداده في الخطوة 1)، حتى تتمكن من تسجيل الدخول. يعمل ML Intern بأدوات Hub الخاصة به باستخدام رمز المستخدم المسجّل دخوله. بدون تسجيل الدخول، تعمل تلك الأدوات بشكل مجهول ولا تستطيع بدء مهام Jobs أو الكتابة إلى Hub.

MongoDB اختياري. إذا لم يتم تعيين MONGODB_URL، فإن Chat UI يبدأ قاعدة بيانات في الذاكرة ويحفظها في ./db.

الخطوة 1: إنشاء تطبيق OAuth لـ Hugging Face

  1. انتقل إلى huggingface.co/settings/applications/new.

  2. اضبط معرّف التحويل إلى http://localhost:5173/login/callback.

  3. اسمح بهذه النطاقات:

    • openid, profile
    • inference-api
    • read-mcp
    • read-billing
    • jobs
    • gated-repos
    • contribute-repos (اختياري)

    jobs إلزامي: بدونه، تُرجع كل عملية إرسال مهمة 403. يتيح contribute-repos لـ ML Intern النشر في Spaces، ولا يمكنه سوى تحديث المساحات التي أنشأها. يتيح gated-repos لـ ML Intern تنزيل النماذج والمجموعات البيانات المقيدة التي مُنح المستخدم حق الوصول إليها. يعرض read-billing المنظمات ومجموعات الموارد التي يمكن للمستخدم إصدار الفواتير إليها.

  4. لاحظ معرّف العميل (client ID) وسرّ التطبيق.

الخطوة 2: تكوين .env.local

أنشئ .env.local في جذر المستودع. القيم الافتراضية والتوثيق الكامل لكل متغير موجود في .env.

# Models, through the Hugging Face router
OPENAI_BASE_URL=https://huggingface.co/proxy/router.huggingface.co/v1
OPENAI_API_KEY=hf_***

# Sign in with Hugging Face (Step 1)
OPENID_CLIENT_ID=<client id>
OPENID_CLIENT_SECRET=<client secret>
OPENID_SCOPES="openid profile inference-api read-mcp read-billing contribute-repos gated-repos jobs"
# Send the signed-in user's token to the Hugging Face MCP server
MCP_FORWARD_HF_USER_TOKEN=true

# Compile ML Intern in
ML_ASSISTANT_MODE=true
# Models ML Intern may run on; the first entry is the default
ML_ASSISTANT_MODELS=[{"id":"zai-org/GLM-5.3-Flash","provider":"together"},{"id":"moonshotai/Kimi-K3","provider":"baseten"}]

# Optional: HuggingChat-only UI, including the billing picker in Settings
PUBLIC_APP_ASSETS=huggingchat
# Optional: a GitHub token with no scopes, to raise the rate limit of the
# tools that read example scripts from public repositories
GITHUB_TOKEN=

ملاحظات:

  • ML_ASSISTANT_MODE هو علم يُحدَّد وقت البناء. يقوم Vite بتجميعه ضمن الحزمة، لذا فإن أي بناء مُنشر إما يتضمن ML Intern أو لا يمكن تفعيله. بعد تغييره، أعد تشغيل خادم التطوير.
  • ML_ASSISTANT_MODELS مصفوفة JSON5. يحتاج كل عنصر إلى id موجود في كتالوج نماذج الموجّه، و provider; ؛ لا يُقبل الاسم المستعار للموجّه. كائن اختياري parameters يُدمج فوق كائن كتالوج النموذج. عند استخدام موجّه Hugging Face، تُثبَّت المحادثات على ذلك المزوّد بغضّ النظر عن تفضيل المستخدم الخاص. أما عند استخدام نقاط نهاية متوافقة مع OpenAI أخرى، فلا يُطبَّق هذا التثبيت. إذا كانت القائمة فارغة، يُخفى مفتاح ML Intern ويرفض الوضع بدء محادثة.
    • عند استخدام موجّه Hugging Face، تُثبَّت المحادثات على ذلك المزوّد، بغضّ النظر عن تفضيل المستخدم الخاص بالمزوّد.
    • فيما يتعلق بنقاط النهاية الأخرى المتوافقة مع OpenAI، لا يُطبَّق التثبيت.
    • إذا كانت القائمة فارغة، يتم إخفاء مفتاح ML Intern ويرفض الوضع بدء محادثة.
  • الفوترة. بدون PUBLIC_APP_ASSETS=huggingchat، لا يوجد منتقي للفوترة، وتُحتسب فواتير Jobs على المستخدم المسجّل.

الخطوة 3: تشغيله

npm run dev

افتح http://localhost:5173/?mode=ml-intern وسجّل الدخول. يُفعّل المعامل ?mode=ml-intern الوضع (يمكنك أيضاً استخدام المفتاح الموجود أسفل مربع الرسالة)، ويبقى في عنوان URL حتى يبقى وضعك نشطاً عند إعادة تحميل الصفحة.

تبدأ كل محادثة مع مساعد ML Intern بميزانية حوسبة قدرها $0، لذا لا يمكن إطلاق أي مهام أو بيئات اختبار حتى تقوم بتعيين ميزانية. قم بتعيينها من شريط الحالة الموجود فوق مربع الرسائل، وحافظ على قيمتها منخفضة أثناء تجاربك.

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

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

npm run probe-model -- --model zai-org/GLM-5.3-Flash --provider together
npm run probe-model -- --model moonshotai/Kimi-K3 --suite quick

يُوثّق ترويسة scripts/probe-model.ts الحزم والأحجام والحُكم.

مفاتيح الميزات

تحتوي عدة أجزاء من ML Intern على مفاتيح إيقاف. يكون كل مفتاح مفعّلًا ما لم يُضبط على false، وتُوثَّق كل مفاتيح في .env:

متغيرالتحكم
ML_ASSISTANT_VIRTUAL_FILESملفات سكربتات مُرقّمة (write_file، edit_file، read_file) تشير إليها مهام Jobs وsandboxes على أنها v-file://<name>
ML_ASSISTANT_STATE_BLOCKحالة الجلسة (المهام قيد التنفيذ، بيئات العزل، المستودعات، الملفات) المضافة إلى كل جولة
ML_ASSISTANT_SERVICE_POLLERالمُراقِب الخلفي الذي يتتبع حالة المهمة والبيئة المعزولة ويُسوّي الميزانية عند انتهائهما
ML_ASSISTANT_SERVICE_POLL_INTERVAL_MSHow often the poller looks for services that are due (default 5000)
ML_ASSISTANT_SERVICE_EVENTSإيقاظ دورٍ في قائمة الانتظار عند انتهاء مهمة أو بيئة معزولة (يتطلب وجود المُستطلِع)
ML_ASSISTANT_PUSH_CHECKSالتحقق من المستودعات التي قام بها Job المكتمل (يتطلب poller)
ML_ASSISTANT_JOB_LABELSتسمية وتوسيم وظائف التدريب العملي في مجال التعلم الآلي، واستعادة المشاركات التي ضاعت ردودها

مكان وجود الكود

المساحةالموقع
علم البناءsrc/lib/utils/mlAssistantFlag.ts, vite.config.ts
الوضع، مجموعة النماذج، والإعداد المسبق لمركز MCPsrc/lib/server/mlAssistant.ts, src/lib/server/mlAssistantModels.ts
موجّه النظامsrc/lib/server/mlAssistantPrompt.ts
الأدوات المدمجة (plan، research، sandbox، wait، files، Trackio، questions)src/lib/server/textGeneration/builtinTools/
حلقة الأدوات وMCPsrc/lib/server/textGeneration/mcp/
المهام والبيئات المعزولة والمستودعات التي أنشأها المحادثةsrc/lib/server/mlRegistry/
ملفات السكربتات المُرقّمةsrc/lib/server/mlFiles/
حالة العميلsrc/lib/stores/mlAssistant.svelte.ts, src/lib/stores/mlRegistry.svelte.ts
واجهة المستخدم: مفتاح تبديل، شريط الحالة، التهيئة، اللوحة الجانبيةsrc/lib/components/chat/MlInternPill.svelte, MlAssistantStrip.svelte, MlInternOnboardingModal.svelte, MlRegistryPane.svelte
نسخ، أمثلة على الأوامر الثابتة المسبقةsrc/lib/constants/mlAssistant.ts

الاختبار

شغّل اختبارات الوحدة للأجزاء التي قمت بتعديلها، على سبيل المثال:

npx vitest run src/lib/server/mlRegistry
npx vitest run src/lib/server/textGeneration/builtinTools

npm run test يشغّل كل شيء، بينما npm run test:e2e يشغّل مجموعة Playwright. تستخدم مجموعة e2e نموذج LLM وهميًا وخوادم MCP وهمية، لذا لا تحتاج إلى مفاتيح ولا تطلق أي شيء على Hugging Face. تتطلب Node.js 22.6 أو أحدث.

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

  • لا يوجد مفتاح ML Intern. تأكد من ضبط ML_ASSISTANT_MODE=true وML_ASSISTANT_MODELS، ثم أعد تشغيل خادم التطوير. يظهر المفتاح فقط في محادثة فارغة.
  • تفشل المهام مع رمز 403. لا يحتوي تطبيق OAuth أو OPENID_SCOPES على jobs. سجّل الخروج ثم سجّل الدخول مرة أخرى بعد إضافته، حتى يحمل رمزك النطاق الجديد.
  • تفشل عمليات التنزيل من مستودع محكوم (gated) برمز 403 بعد قبول شروط الوصول. تطبيق OAuth أو OPENID_SCOPES يفتقر إلى gated-repos. لا يزال Hub يقدّم بيانات المستودع الوصفية وملف README دونها، مما يجعل الأمر يبدو وكأن شروط الوصول لم تُقبل. سجّل الخروج ثم سجّل الدخول مرة أخرى بعد إضافتها.
  • لا يمكن لـ ML Intern استخدام أدوات Hub، أو يعمل بشكل مجهول. تأكد من تسجيل الدخول وأن MCP_FORWARD_HF_USER_TOKEN=true مضبوط. كما تحقق من الأدوات المفعّلة في إعدادات Hugging Face MCP.
  • يُرفض كل إطلاق. ميزانية الحوسبة للمحادثة لا تزال 0 دولار. اضبطها من شريط الحالة.
  • تفشل عمليات إعادة التوجيه عند تسجيل الدخول. يجب أن يطابق معرّف إعادة التوجيه لتطبيق OAuth بدقة http://localhost:5173/login/callback، بما في ذلك المنفذ.
Update on GitHub

←البدء روبوت Slack→