Chạy Chat UI với ML Intern cục bộ

Hướng dẫn này dành cho các nhà phát triển muốn chạy ML Intern trên máy của riêng mình, thử nghiệm các thay đổi đối với nó, hoặc triển khai nó trong một phiên bản Chat UI của riêng họ. Nếu bạn chỉ muốn sử dụng ML Intern, hãy xem Bắt đầu với ML Intern.

ML Intern là một chế độ được tích hợp sẵn trong Chat UI. Khi được bật, một cuộc trò chuyện:

chạy trên một tập hợp các mô hình có khả năng sử dụng công cụ cố định
kết nối với máy chủ MCP của Hugging Face bằng bộ công cụ intern của Hub
nhận thêm các công cụ tích hợp sẵn: lập kế hoạch, nghiên cứu, các tệp script có phiên bản, các môi trường sandbox, các bảng điều khiển Trackio, các không gian gr.Workflow, và chờ đợi các Job
chứa một ngân sách tính toán mà máy chủ thực thi trên mọi Job và sandbox mà nó khởi chạy

Yêu cầu tiên quyết

Node.js 20 trở lên, và một bản sao của huggingface/chat-ui đã chạy npm install.
Tài khoản Hugging Face có sẵn tín dụng. Các cuộc trò chuyện ML Intern mà bạn chạy cục bộ sẽ khởi tạo các Job và sandbox thực trên tài khoản của bạn.
Một token truy cập Hugging Face có quyền gọi Inference Providers. Chat UI sử dụng nó để giao tiếp với các model.
Một ứng dụng OAuth của Hugging Face (được thiết lập trong Bước 1) để bạn có thể đăng nhập. ML Intern chạy các công cụ Hub của nó bằng token của người dùng đã đăng nhập. Nếu không đăng nhập, các công cụ đó sẽ chạy ẩn danh và không thể khởi tạo Jobs hoặc ghi vào Hub.

MongoDB là tùy chọn. Nếu MONGODB_URL không được đặt, Chat UI sẽ khởi động một cơ sở dữ liệu trong bộ nhớ và lưu trữ nó vào ./db.

Bước 1: Tạo ứng dụng OAuth của Hugging Face

Truy cập huggingface.co/settings/applications/new.
Đặt URI chuyển hướng thành http://localhost:5173/login/callback.
Cho phép các phạm vi sau:
- openid, profile
- inference-api
- read-mcp
- read-billing
- jobs
- gated-repos
- contribute-repos (tùy chọn)
jobs là bắt buộc: nếu không có nó, mọi thao tác gửi Job đều trả về mã 403. contribute-repos cho phép ML Intern triển khai đến Spaces, và chỉ có thể cập nhật các Spaces mà nó đã tạo. gated-repos cho phép ML Intern tải xuống các model và dataset có điều kiện truy cập mà người dùng đã được cấp quyền. read-billing liệt kê các tổ chức và nhóm tài nguyên mà người dùng có thể tính phí.
Lưu ý client ID và secret của ứng dụng.

Bước 2: Cấu hình .env.local

Tạo .env.local ở thư mục gốc của kho. Các giá trị mặc định và tài liệu đầy đủ cho từng biến nằm trong .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=

Ghi chú:

ML_ASSISTANT_MODE là một cờ thời điểm build. Vite biên dịch nó vào bundle, nên một bản build đã triển khai sẽ hoặc là có sẵn ML Intern hoặc không thể bật nó lên. Sau khi thay đổi, hãy khởi động lại dev server.
ML_ASSISTANT_MODELS là một mảng JSON5. Mỗi mục cần có một id tồn tại trong danh mục model của router và một provider; alias của router không được chấp nhận. Một đối tượng parameters tùy chọn sẽ được gộp đè lên các thuộc tính của mục trong danh mục. Đối với router của Hugging Face, các cuộc trò chuyện sẽ được cố định với provider đó, bất kể sở thích provider của người dùng. Đối với các endpoint tương thích OpenAI khác, việc cố định này không được áp dụng. Nếu danh sách trống, công tắc ML Intern sẽ bị ẩn và chế độ sẽ từ chối bắt đầu cuộc trò chuyện.
- Đối với router của Hugging Face, các cuộc trò chuyện sẽ được gắn với nhà cung cấp đó, bất kể sở thích về nhà cung cấp của người dùng là gì.
- Đối với các endpoint tương thích OpenAI khác, pin không được áp dụng.
- Nếu danh sách trống, công tắc ML Intern sẽ bị ẩn và chế độ sẽ từ chối bắt đầu cuộc trò chuyện.
Hóa đơn. Nếu không có PUBLIC_APP_ASSETS=huggingchat, sẽ không có bộ chọn hóa đơn, và Jobs sẽ tính phí cho người dùng đã đăng nhập.

Bước 3: Chạy

npm run dev

Mở http://localhost:5173/?mode=ml-intern và đăng nhập. Tham số ?mode=ml-intern bật chế độ này (bạn cũng có thể dùng công tắc bên dưới hộp thông báo), và nó được giữ trong URL nên việc tải lại trang vẫn duy trì chế độ này.

Mọi cuộc trò chuyện với ML Intern đều bắt đầu với ngân sách tính toán là $0, do đó không thể khởi chạy Jobs hay sandbox nào cho đến khi bạn thiết lập ngân sách. Hãy thiết lập từ thanh trạng thái phía trên hộp nhắn tin và giữ mức ngân sách ở mức thấp trong khi bạn thử nghiệm.

Chọn mô hình

ML Intern chạy các vòng lặp gọi công cụ dài, thường với hàng trăm nghìn token ngữ cảnh. Không phải mô hình hay nhà cung cấp nào cũng xử lý điều đó một cách đáng tin cậy, đó là lý do mỗi mục trong ML_ASSISTANT_MODELS đều cố định một nhà cung cấp. Để kiểm tra một mô hình và nhà cung cấp trước khi thêm chúng, hãy chạy script dò. Script này phát lại một lịch sử theo phong cách ML Intern ở các kích thước ngữ cảnh lớn và chấm điểm cách luồng kết thúc:

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

Phần tiêu đề của scripts/probe-model.ts mô tả các bộ kiểm thử, kích thước và kết luận.

Công tắc tính năng

Một số phần của ML Intern có công tắc tắt. Mỗi công tắc đều được bật trừ khi được đặt thành false, và mỗi công tắc đều được tài liệu hóa trong .env:

Biến	Điều khiển
`ML_ASSISTANT_VIRTUAL_FILES`	Các tệp script có phiên bản (`write_file`, `edit_file`, `read_file`) mà Jobs và sandbox tham chiếu dưới dạng `v-file://<name>`
`ML_ASSISTANT_STATE_BLOCK`	Trạng thái phiên (các Job đang chạy, sandbox, repos, files) được thêm vào mỗi lượt
`ML_ASSISTANT_SERVICE_POLLER`	Bộ poller nền theo dõi trạng thái của Job và sandbox, đồng thời quyết toán ngân sách khi chúng kết thúc
`ML_ASSISTANT_SERVICE_POLL_INTERVAL_MS`	Tần suất bộ poller kiểm tra các dịch vụ đến hạn (mặc định là 5000)
`ML_ASSISTANT_SERVICE_EVENTS`	Thức tỉnh lượt đang chờ khi một Job hoặc sandbox kết thúc (cần poller)
`ML_ASSISTANT_PUSH_CHECKS`	Kiểm tra các kho mà một Job đã hoàn thành đẩy lên (cần poller)
`ML_ASSISTANT_JOB_LABELS`	Đặt tên và dán nhãn các công việc thực tập ML, và khôi phục các bài nộp mà phản hồi đã bị mất
`ML_ASSISTANT_WORKFLOWS`	Công cụ `create_workflow`, triển khai các Spaces gr.Workflow công khai dưới tài khoản của người dùng

Nơi đặt mã nguồn

Diện tích	Vị trí
Cờ build	`src/lib/utils/mlAssistantFlag.ts`, `vite.config.ts`
Chế độ, bộ mô hình và cài đặt trước Hub MCP	`src/lib/server/mlAssistant.ts`, `src/lib/server/mlAssistantModels.ts`
Lời nhắc hệ thống	`src/lib/server/mlAssistantPrompt.ts`
Công cụ tích hợp sẵn (plan, research, sandbox, wait, files, Trackio, workflows, questions)	`src/lib/server/textGeneration/builtinTools/`
Vòng lặp công cụ và MCP	`src/lib/server/textGeneration/mcp/`
Các tác vụ, hộp cát và kho mà cuộc trò chuyện đã tạo	`src/lib/server/mlRegistry/`
Tệp script có phiên bản	`src/lib/server/mlFiles/`
Trạng thái client	`src/lib/stores/mlAssistant.svelte.ts`, `src/lib/stores/mlRegistry.svelte.ts`
UI: công tắc, thanh trạng thái, hướng dẫn sử dụng, bảng bên	`src/lib/components/chat/MlInternPill.svelte`, `MlAssistantStrip.svelte`, `MlInternOnboardingModal.svelte`, `MlRegistryPane.svelte`
Sao chép, các prompt ví dụ và các hằng số cài đặt sẵn	`src/lib/constants/mlAssistant.ts`

Kiểm thử

Chạy các bài kiểm tra đơn vị cho các phần bạn đã thay đổi, ví dụ:

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

npm run test chạy tất cả, và npm run test:e2e chạy bộ Playwright. Bộ e2e sử dụng LLM giả lập và các máy chủ MCP giả lập, nên không cần key và không khởi chạy gì trên Hugging Face. Cần Node.js 22.6 trở lên.

Xử lý sự cố

Không có công tắc ML Intern. Kiểm tra xem ML_ASSISTANT_MODE=true và ML_ASSISTANT_MODELS đã được đặt hay chưa, sau đó khởi động lại dev server. Công tắc chỉ hiển thị trong một cuộc trò chuyện trống.
Các tác vụ thất bại với mã 403. Ứng dụng OAuth hoặc OPENID_SCOPES đang thiếu jobs. Hãy đăng xuất rồi đăng nhập lại sau khi thêm phạm vi này để token của bạn mang theo phạm vi mới.
Tải xuống từ kho có cổng bị lỗi 403 sau khi chấp nhận cổng. Ứng dụng OAuth hoặc OPENID_SCOPES thiếu gated-repos. Hub vẫn cung cấp metadata và README của kho mà không cần nó, nên trông như thể cổng chưa được chấp nhận. Đăng xuất rồi đăng nhập lại sau khi thêm nó.
ML Intern không thể sử dụng công cụ Hub, hoặc hoạt động ẩn danh. Hãy đảm bảo bạn đã đăng nhập và MCP_FORWARD_HF_USER_TOKEN=true được đặt. Ngoài ra, hãy kiểm tra các công cụ nào đang được bật trong cài đặt Hugging Face MCP của bạn.
Mọi lần khởi động đều bị từ chối. Ngân sách tính toán của cuộc hội thoại vẫn là $0. Hãy thiết lập nó từ thanh trạng thái.
Chuyển hướng đăng nhập thất bại. URI chuyển hướng của ứng dụng OAuth phải khớp chính xác với http://localhost:5173/login/callback, bao gồm cả cổng.

Update on GitHub