Menjalankan Chat UI dengan ML Intern secara lokal

Panduan ini ditujukan untuk pengembang yang ingin menjalankan ML Intern di mesin mereka sendiri, mencoba perubahan di dalamnya, atau mendeploynya di instance Chat UI mereka sendiri. Jika Anda hanya ingin menggunakan ML Intern, lihat Mulai dengan ML Intern.

ML Intern adalah mode yang dibangun ke dalam Chat UI. Saat diaktifkan, sebuah percakapan:

• berjalan pada set model yang tetap dengan kemampuan alat
• menghubungkan ke server MCP Hugging Face dengan set tool intern dari Hub
• mendapatkan alat bawaan tambahan: perencanaan, riset, file skrip berversi, sandbox, dasbor Trackio, dan menunggu pada Jobs
• memiliki anggaran komputasi yang diterapkan server pada setiap Job dan sandbox yang diluncurkannya

Prasyarat

• Node.js 20 atau lebih baru, dan klon dari huggingface/chat-ui dengan npm install yang sudah dijalankan.
• Akun Hugging Face dengan kredit. Percakapan ML Intern yang Anda jalankan secara lokal akan meluncurkan Jobs dan sandbox sungguhan di akun Anda.
• Token akses Hugging Face dengan izin untuk memanggil Inference Providers. Chat UI menggunakannya untuk berkomunikasi dengan model.
• Aplikasi OAuth Hugging Face (diatur di Langkah 1), agar Anda dapat masuk. ML Intern menjalankan alat Hub-nya dengan token pengguna yang sedang masuk. Tanpa masuk, alat-alat tersebut berjalan secara anonim dan tidak dapat memulai Jobs atau menulis ke Hub.

MongoDB bersifat opsional. Jika MONGODB_URL tidak disetel, Chat UI akan memulai database in-memory dan menyimpannya ke ./db.

Langkah 1: Buat aplikasi OAuth Hugging Face

1. Buka huggingface.co/settings/applications/new.

2. Atur URI redirect ke http://localhost:5173/login/callback.

3. Izinkan scope-scope berikut:

   • openid, profile
   • inference-api
   • read-mcp
   • read-billing
   • jobs
   • gated-repos
   • contribute-repos (opsional)

   jobs wajib: tanpanya, setiap pengajuan Job akan mengembalikan 403. contribute-repos memungkinkan ML Intern untuk melakukan deployment ke Spaces, dan hanya dapat memperbarui Spaces yang telah dibuatnya. gated-repos memungkinkan ML Intern untuk mengunduh model dan dataset bergerbang yang aksesnya telah diberikan kepada pengguna. read-billing menampilkan daftar organisasi dan grup sumber daya yang dapat ditagihkan kepada pengguna.

4. Catat ID klien dan rahasia aplikasi.

Langkah 2: Konfigurasi .env.local

Buat .env.local di root repository. Nilai default dan dokumentasi lengkap untuk setiap variabel ada di .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=

Catatan:

• ML_ASSISTANT_MODE adalah flag saat build. Vite mengompilasinya ke dalam bundle, sehingga build yang di-deploy akan menyertakan ML Intern atau tidak dapat mengaktifkannya. Setelah mengubahnya, restart dev server.
• ML_ASSISTANT_MODELS adalah array JSON5. Setiap entri memerlukan id yang ada di katalog model router dan provider; alias router tidak diterima. Objek parameters opsional digabungkan ke entri katalog.
  • Terhadap router Hugging Face, percakapan dikunci pada penyedia tersebut, terlepas dari preferensi penyedia milik pengguna.
  • Terhadap endpoint yang kompatibel dengan OpenAI lainnya, pin tidak diterapkan.
  • Jika daftar kosong, sakelar ML Intern disembunyikan dan mode menolak memulai percakapan.
• Penagihan. Tanpa PUBLIC_APP_ASSETS=huggingchat, tidak ada pilihan penagihan, dan tagihan Jobs ditagihkan ke pengguna yang masuk.

Langkah 3: Jalankan

npm run dev

Buka http://localhost:5173/?mode=ml-intern dan masuk. Parameter ?mode=ml-intern mengaktifkan mode tersebut (Anda juga dapat menggunakan saklar di bawah kotak pesan), dan parameter ini tetap ada di URL sehingga mode tetap aktif saat halaman dimuat ulang.

Setiap percakapan ML Intern dimulai dengan anggaran komputasi $0, sehingga tidak ada Jobs atau sandbox yang dapat diluncurkan sampai Anda menyetelnya. Setel anggaran tersebut dari bilah status di atas kotak pesan, dan pertahankan nilainya tetap kecil saat Anda bereksperimen.

Memilih model

ML Intern menjalankan loop pemanggilan alat yang panjang, sering kali dengan ratusan ribu token konteks. Tidak semua model atau penyedia menangani hal tersebut secara andal, itulah mengapa setiap entri di ML_ASSISTANT_MODELS mengunci satu penyedia. Untuk memeriksa model dan penyedia sebelum menambahkannya, jalankan skrip probe. Skrip ini memutar ulang riwayat bergaya ML Intern pada ukuran konteks besar dan menilai bagaimana aliran berakhir:

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

Header dari scripts/probe-model.ts mendokumentasikan suite, ukuran, dan verdict.

Saklar fitur

Beberapa bagian dari ML Intern memiliki saklar mati. Masing-masing aktif kecuali diatur ke false, dan masing-masing didokumentasikan di .env:

Di mana kode berada

Pengujian

Jalankan unit test untuk bagian yang Anda ubah, misalnya:

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

npm run test menjalankan semua, dan npm run test:e2e menjalankan suite Playwright. Suite e2e menggunakan mock LLM dan mock MCP servers, sehingga tidak memerlukan kunci dan tidak meluncurkan apa pun di Hugging Face. Butuh Node.js 22.6 atau lebih baru.

Pemecahan Masalah

• Tidak ada saklar ML Intern. Pastikan ML_ASSISTANT_MODE=true dan ML_ASSISTANT_MODELS telah diatur, lalu mulai ulang server dev. Saklar hanya muncul dalam percakapan kosong.
• Jobs gagal dengan 403. Aplikasi OAuth atau OPENID_SCOPES tidak memiliki jobs. Keluar dan masuk kembali setelah menambahkannya, agar token Anda membawa scope baru.
• Unduhan dari repo bergerbang gagal dengan 403 setelah gerbang diterima. Aplikasi OAuth atau OPENID_SCOPES tidak memiliki gated-repos. Hub tetap menyajikan metadata dan README repo tanpa itu, sehingga terlihat seperti gerbang belum diterima. Keluar dan masuk kembali setelah menambahkannya.
• ML Intern tidak dapat menggunakan alat Hub, atau bertindak secara anonim. Pastikan Anda telah masuk dan MCP_FORWARD_HF_USER_TOKEN=true telah disetel. Periksa juga alat mana yang diaktifkan di pengaturan Hugging Face MCP Anda.
• Setiap peluncuran ditolak. Anggaran komputasi percakapan masih $0. Atur dari bilah status.
• Pengalihan masuk gagal. URI pengalihan aplikasi OAuth harus cocok persis dengan http://localhost:5173/login/callback, termasuk portnya.