ML Intern をローカルで実行して Chat UI を起動する

このガイドは、ML Internを自分のマシンで実行し、変更を試したり、独自のChat UIインスタンスにデプロイしたりしたい開発者向けです。ML Internを単に使用したい場合は、ML Internの入門を参照してください。

ML Internは、Chat UIに組み込まれたモードです。これを有効にすると、会話の

固定のツール対応モデルセットで実行されます
HubのinternツールセットでHugging Face MCPサーバーに接続します
追加の組み込みツールが利用可能になります: プランニング、リサーチ、バージョン管理されたスクリプトファイル、サンドボックス、Trackio ダッシュボード、および Jobs の待機
サーバーが起動するすべてのJobとサンドボックスに適用される計算予算を保持します

前提条件

Node.js 20以降、およびnpm installを実行したhuggingface/chat-uiのクローンが必要です。
クレジットのある Hugging Face アカウント。ローカルで実行する ML Intern の会話では、あなたのアカウント上で実際の Jobs とサンドボックスが起動されます。
Inference Providersを呼び出す権限を持つHugging Faceアクセストークン。Chat UIはこれを使用してモデルと通信します。
Hugging Face の OAuth アプリ（ステップ 1で設定したもの）で、サインインできるようにします。ML Intern は、サインインしたユーザーのトークンを使用して Hub ツールを実行します。サインインなしで実行すると、これらのツールは匿名で動作し、Jobs の開始や Hub への書き込みができなくなります。

MongoDB は任意です。MONGODB_URL が設定されていない場合、Chat UI はインメモリデータベースを起動し、./db に永続化します。

ステップ 1: Hugging Face OAuth アプリの作成

huggingface.co/settings/applications/new に移動します。
リダイレクト URI をhttp://localhost:5173/login/callbackに設定します。
これらのスコープを許可します:
- 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 は、ユーザーが請求可能な組織とリソースグループをリスト表示します。
アプリのクライアント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のスイッチは非表示になり、モードは会話の開始を拒否します。
請求。PUBLIC_APP_ASSETS=huggingchatが設定されていない場合、請求先選択機能は表示されず、Jobsの請求はサインインしたユーザーに適用されます。

ステップ3: 実行

npm run dev

http://localhost:5173/?mode=ml-intern を開き、サインインしてください。?mode=ml-intern パラメータはモードを有効にします（メッセージボックス下のスイッチも使用できます）。また、URL に残るため、リロードしてもモードが維持されます。

ML Internのすべての会話では、計算予算が$0から始まるため、設定を行うまでJobsやサンドボックスを起動できません。メッセージボックス上部のステータスバーから設定し、実験中は小さく保ってください。

モデルの選択

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`	Jobsとサンドボックスが`v-file://<name>`として参照する、バージョン管理されたスクリプトファイル（`write_file`、`edit_file`、`read_file`）
`ML_ASSISTANT_STATE_BLOCK`	各ターンに付加されるセッション状態（実行中のJobs、サンドボックス、リポジトリ、ファイル）
`ML_ASSISTANT_SERVICE_POLLER`	Jobとサンドボックスのステータスを追跡し、終了時に予算を確定するバックグラウンドポーラー
`ML_ASSISTANT_SERVICE_POLL_INTERVAL_MS`	ポーラーが期限切れのサービスを確認する頻度（デフォルトは5000）
`ML_ASSISTANT_SERVICE_EVENTS`	Jobまたはサンドボックスが終了した際に待機中のターンを起動する（ポーラーが必要）
`ML_ASSISTANT_PUSH_CHECKS`	完了したJobがプッシュしたリポジトリを確認する（pollerが必要です）
`ML_ASSISTANT_JOB_LABELS`	MLインターンシップの求人名称とラベル付け、および返信が失われた応募の復旧

コードの場所

領域	場所
ビルドフラグ	`src/lib/utils/mlAssistantFlag.ts`, `vite.config.ts`
モード、モデルセット、および Hub MCP プリセット	`src/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/`
ツールループとMCP	`src/lib/server/textGeneration/mcp/`
会話によって作成されたジョブ、サンドボックス、リポジトリ	`src/lib/server/mlRegistry/`
バージョン管理されたスクリプトファイル	`src/lib/server/mlFiles/`
クライアント状態	`src/lib/stores/mlAssistant.svelte.ts`, `src/lib/stores/mlRegistry.svelte.ts`
UI: スイッチ、ステータスバー、オンボーディング、サイドパネル	`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が欠落しています。追加した後にサインアウトして再サインインし、トークンに新しいスコープが反映されるようにしてください。
ゲート付きリポジトリへのアクセスを承認した後、ダウンロードが 403 エラーで失敗する OAuth アプリまたは OPENID_SCOPES に gated-repos が含まれていません。このスコープが欠落していても、Hub はリポジトリのメタデータと README を引き続き提供するため、ゲートが承認されていないように見えます。スコープを追加した後に、サインアウトしてから再度サインインしてください。
ML InternがHubツールを使用できない、または匿名として動作します。 サインインしていること、およびMCP_FORWARD_HF_USER_TOKEN=trueが設定されていることを確認してください。また、Hugging Face MCP設定でどのツールが有効化されているかも確認してください。
すべての起動が拒否されます。 会話の計算予算は引き続き $0 です。ステータスバーから設定してください。
サインインのリダイレクトが失敗します。OAuth アプリのリダイレクト URI は、ポート番号を含む http://localhost:5173/login/callback と完全に一致する必要があります。

Update on GitHub