Запуск Chat UI с ML Intern локально

Это руководство предназначено для разработчиков, которые хотят запустить ML Intern на собственном компьютере, внести в него изменения или развернуть его в собственном экземпляре Chat UI. Если вы просто хотите использовать ML Intern, см. Начало работы с ML Intern.

ML Intern — это режим, встроенный в Chat UI. Когда он включен, диалог:

• работает с фиксированным набором моделей, поддерживающих инструменты
• подключается к MCP-серверу Hugging Face с набором инструментов intern Hub
• получает дополнительные встроенные инструменты: планирование, исследования, версионируемые файлы скриптов, песочницы, дашборды Trackio и ожидание Jobs
• предусматривает вычислительный бюджет, который сервер применяет к каждому запускаемому им Job и песочнице

Предварительные требования

• Node.js 20 или более поздняя версия, а также клонированный репозиторий huggingface/chat-ui с выполненной командой npm install.
• Аккаунт Hugging Face с кредитами. Диалоги с ML Intern, которые вы запускаете локально, создают реальные Jobs и песочницы на вашем аккаунте.
• Доступный токен Hugging Face с разрешением на вызов Inference Providers. Chat UI использует его для взаимодействия с моделями.
• Приложение 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. Установите URI перенаправления в http://localhost:5173/login/callback.

3. Разрешите эти области:

   • openid, profile
   • inference-api
   • read-mcp
   • read-billing
   • jobs
   • gated-repos
   • contribute-repos (необязательно)

   jobs обязателен: без него каждая отправка Job возвращает 403. contribute-repos позволяет ML Intern развертывать проекты в Spaces, при этом обновлять можно только те Spaces, которые были созданы им. gated-repos позволяет ML Intern скачивать модели и наборы данных с ограниченным доступом, к которым у пользователя есть права. read-billing выводит список организаций и групп ресурсов, на которые пользователь может выставить счет.

4. Запишите идентификатор клиента и секрет приложения.

Шаг 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 либо включён, либо его невозможно активировать. После изменения этого флага перезапустите dev-сервер.
• 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:

Где находится код

Тестирование

Запустите модульные тесты для изменённых частей, например:

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

npm run test запускает все тесты, а npm run test:e2e — набор Playwright. Набор e2e использует mock-LLM и mock-серверы MCP, поэтому не требует ключей и ничего не запускает на Hugging Face. Требуется Node.js 22.6 или новее.

Устранение неполадок

• Переключатель ML Intern отсутствует. Убедитесь, что установлены ML_ASSISTANT_MODE=true и ML_ASSISTANT_MODELS, и перезапустите dev-сервер. Переключатель отображается только в пустом диалоге.
• Задачи завершаются с ошибкой 403. В OAuth-приложении или в OPENID_SCOPES отсутствует jobs. После добавления выполните выход и повторный вход, чтобы в вашем токене появился новый scope.
• Загрузка из репозитория с ограниченным доступом завершается ошибкой 403 после принятия условий доступа. В OAuth-приложении или переменной OPENID_SCOPES отсутствует gated-repos. Hub по-прежнему предоставляет метаданные и README репозитория без этого параметра, из-за чего кажется, что условия доступа не были приняты. После добавления параметра выполните выход и повторный вход в систему.
• ML Intern не может использовать инструменты Hub или действует анонимно. Убедитесь, что вы вошли в систему и установлено MCP_FORWARD_HF_USER_TOKEN=true. Также проверьте, какие инструменты включены в ваших настройках Hugging Face MCP.
• Каждый запуск отклоняется. Вычислительный бюджет разговора всё ещё равен $0. Установите его из строки состояния.
• Перенаправление при входе в систему не работает. URI перенаправления OAuth-приложения должен точно соответствовать http://localhost:5173/login/callback, включая порт.