Hugging Face ML インターン入門：最初の ML エージェントの構築

「論文は読んだのに、実際にハブ上にトレーニング済みのチェックポイントが揃うまでにはまだ遠い」という経験、一度や二度はないでしょうか。そのギャップを埋めるために Hugging Face が開発したのが ML Intern です。これは Hugging Face 製のオープンソース型コマンドラインインターフェース（CLI）エージェントで、機械学習のタスクを自然な英語で記述するだけで実行できます。

手作業で一つずつ組み立てる必要はありません。「モデルをファインチューンしてほしい」「論文の内容を探してほしい」「トレーニングを開始してほしい」と指示を出すだけで、ML Intern が対応します。実際には、ジュニアの機械学習エンジニアが普段行うような業務——ドキュメントの参照、GitHub での検索、スクリプト作成、ジョブの実行、結果の確認、そして反復的な改善——をすべて担います。

このシステムは Hugging Face のスタックをエンドツーエンドで活用して構築されています。Hub や arXiv 上の論文を検索したり、データセットを扱ったり、HF Jobs を使って GPU トレーニングジョブを実行したり、Trackio で実験結果をログ記録したりできます。また、作業が完了すれば学習済みモデルを Hub に公開することも可能です。

裏側では smolagents フレームワークを採用しており、API クレジットを消費したくない場合は Hugging Face Inference Providers またはローカルエンドポイントを経由してモデル呼び出しをルーティングできます。

これは単なる「コードのための ChatGPT」というよりは、シェルアクセス権限と Hugging Face アカウントを備えた、実際に動く研究インターンといった存在です。リポジトリは huggingface/ml-intern にあります。これを試したり、自分のニーズに合わせてカスタマイズしたり、継続的インテグレーション（CI）ワークフローの一部として組み込んだりすることも可能です。

# ML Intern が役立つ理由

**

実際の機械学習研究は直線的ではありません。何かを読み、関連する論文を追跡し、ほぼ条件に合うデータセットを見つけ、データローダーを二度書き換え、トレーニングを実行し、評価が間違っていたことに気づいて修正し、再度トレーニングを行う……といったプロセスの繰り返しです。

ML Intern はこうした反復作業の多くを自動化するために設計されており、設定コードの記述に時間を取られるのではなく、研究上の判断に集中できることを目指しています。

従来のチャットボットとは異なり、一度回答を生成して終わるわけではありません。代わりに、反復的なワークフローに従って進みます。

ML Intern のワークフローループ

Hugging Face が発表した結果によると、科学推論用のベンチマーク「GPQA」において、小規模な Qwen モデルがわずか 10 時間足らずで約 10% から約 32% へと性能を向上させたことが示されています。この特定のベンチマーク自体にこだわらなくても、このプロジェクトが一度スクリプトを実行して終わるようなおもちゃではないことがよく分かります。これは継続的に動作し続けるように設計されたものです。

これでプロジェクトの存在意義は理解いただけたはずです。次は実際に使ってみましょう。その前に、必要な環境設定が整っているか確認してください。

# 前提条件の確認

Hugging Face のアカウント、Python、uv、そしていくつかのトークンが必要です。

HF_TOKEN を指定しない場合、CLI は初回起動時にトークンの入力を求めます（ただし、完全にローカルでモデルを実行している場合は除きます）。トークンの作成方法がわからない場合は、以下の公式ガイドをご参照ください。

Hugging Face Access Tokens

GitHub Personal Access Tokens

ML Intern のインストール

以下のコマンドをコピーして実行してください。

git clone git@github.com:huggingface/ml-intern.git
cd ml-intern
uv sync
uv tool install -e .

これで ml-intern はどのディレクトリからでも利用可能になります。動作確認のために、以下を実行してみてください。

ml-intern --help

次に、.env ファイルに以下の設定を追加するか、シェルで同等の変数をエクスポートしてください。

HF_TOKEN=hf_your_token_here
GITHUB_TOKEN=ghp_your_token_here

インタラクティブモードとヘッドレスモードの比較

最初の実行を開始する前に、エージェントがサポートする 2 つのモードについて理解しておくと便利です。

インタラクティブモードの利用

以下のコマンドを実行して、機械学習エージェントを起動します。

ml-intern

これによりチャットセッションが開かれます。やりたいことを説明すると、エージェントが手順を計画し、危険な操作を行う前に承認を求めるほか、作業中は随時状況を報告してくれます。会話中にモデルを切り替えることも可能です（コマンドは以下）。

/model

初心者におすすめのプロンプト例をいくつか紹介します：

Hugging Face ML Intern の始め方：初めての ML エージェント

• 「Hub 上の小規模な分類データセットを探し、datasets ライブラリを使って読み込む方法を示してください。」
• 「この論文の要約と、使用されているデータセットの一覧を提示してください：[arXiv リンク]。」
• Qwen2.5-0.5B を小さな公開データセットで低ランク適応（LoRA）微調整するための最小限のスクリプトを作成してください。トレーニングは実行せず、スクリプトの記述までで構いません。」

ヘッドレスモードの使用

ml-intern "fine-tune llama on my dataset"

このモードでは単一のプロンプトを使用し、アクションを自動承認します。エージェントは完了するか反復回数の上限に達するまで実行されます。これは夜間の実験用に GitHub Action に組み込む際に使用するモードです。

慣れてきたら以下のフラグが役立ちます：

ml-intern --max-iterations 100 "your prompt"   # cap the budget
ml-intern --no-stream "your prompt"            # cleaner output for CI logs
ml-intern --sandbox-tools "test this in a GPU sandbox"
ml-intern --model moonshotai/Kimi-K2.7-Code:novita "your prompt"

まずはインタラクティブモードで試してみましょう。操作に慣れてきたら、自動化のためにヘッドレスモードへ切り替えてください。

# 最初のランニングを開始する

両方のモードで同じプロンプトを使用し、その違いを確認してください。今回は学習を伴わない小規模なタスクから始めます。目標は Hugging Face Hub からデータセットを見つけ、ローダースクリプトを作成することです。

プロンプト:

Find the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to load_dataset.py. Do not run training.

作業を開始する前に、.env ファイルに HF_TOKEN と GITHUB_TOKEN の両方が設定されていることを確認してください。

// インタラクティブモードでの実行

チャットセッションを開き、プロンプトを入力してその動作を確認し、必要に応じて追跡質問を行います。

以下のコマンドを実行します：

ml-intern

プロンプトは > の後に入力します。

Find the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to /tmp/load_dataset_interactive.py. Do not run training.

出力結果:

Initializing agent runtime...
 User: kanwal8008
 Model: zai-org/GLM-5.2:novita
 Tool runtime: local filesystem
 Tools: 25 loaded
/help for commands · /model to switch · /quit to exit
Ready. Let's build something impressive.
> Find the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to /tmp/load_dataset_interactive.py. Do not run training.
The dataset is cornell-movie-review-data/rotten_tomatoes. It has a single default config with train/validation/test splits, columns are text and label. Writing the script now.
▸ write {"content": "\"\"\"Load the rotten_tomatoes dataset from the HF Hub and print th..."}
Done. The script is saved to /tmp/load_dataset_interactive.py.
What it does:
 - Loads cornell-movie-review-data/rotten_tomatoes via datasets.load_dataset
 - Prints the list of splits (train, validation, test)
 - Prints the first training example (a {"text": ..., "label": ...} dict)
Dataset details:
 - Columns: text (movie review sentence), label (0 = negative, 1 = positive)
 - ~10.6k examples total (5,331 positive / 5,331 negative)
You can run it locally with:
 python /tmp/load_dataset_interactive.py
> /quit
Bye.

作成されたファイル（/tmp/load_dataset_interactive.py）:

"""Load the rotten_tomatoes dataset from the HF Hub and print the first example."""
from datasets import load_dataset

# Load the full dataset (all splits) from the Hub
ds = load_dataset("cornell-movie-review-data/rotten_tomatoes")

print("Dataset splits:", list(ds.keys()))
first_train = ds["train"][0]
print("First training example:")
print(first_train)
print("\nLabel meaning: 0 = negative, 1 = positive")

インタラクティブモードでは、実行中にデータセットの詳細やスクリプトの動作、実行方法など、より多くのコンテキスト情報を得ることができます。また、/quit コマンドを入力する前に追加質問を投げかけることも可能です。

// ヘッドレスモードでの実行

ヘッドレスモードでは、1 つのコマンドでエージェントが開始から終了までを一貫して実行し、その後即座に終了します。

以下のコマンドを実行してください：

ml-intern --max-iterations 15 --no-stream \
"Find the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to /tmp/load_dataset.py. Do not run training."

出力結果は以下の通りです：

HF token loaded
Model: zai-org/GLM-5.2:novita
Tool runtime: local filesystem
Max iterations: 15
Prompt: Find the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to /tmp/load_dataset.py. Do not run training.
---
▸ hf_inspect_dataset {"dataset": "cornell-movie-review-data/rotten_tomatoes", "sample_rows": 1}
▸ write {"content": "from datasets import load_dataset\n\ndataset = load_dataset(\"rotte..."}
▸ bash {"command": "cd /tmp && python load_dataset.py", "description": "Run the dataset..."}
Done. The script is saved at /tmp/load_dataset.py and verified working. It loads the rotten_tomatoes dataset (dataset ID: cornell-movie-review-data/rotten_tomatoes) via datasets.load_dataset and prints the first training example:
 {'text': 'the rock is destined to be the 21st century\'s new " conan " ...',
 'label': 1}
The dataset has two columns -- text (the review) and label (0 = negative, 1 = positive) -- across train (8,530 rows), validation (1,066), and test (1,066) splits.
--- Agent turn_complete (history_size=9) ---

作成されたファイル（/tmp/load_dataset.py）の内容は次の通りです：

from datasets import load_dataset
dataset = load_dataset("rotten_tomatoes", split="train")
print(dataset[0])

ヘッドレスモードではすべての承認が自動的に行われます。これは、実行したい内容が明確で、実行途中の操作を制御する必要がない場合に特に有効です。

# ローカルモデルを使用した ML Intern の実行

Hugging Face 推論プロバイダーの利用や API 利用料の支払いを避けたい場合、ML Intern はローカルでホストされたモデルとも連携できます。モデルの重み自体をダウンロードして読み込むのではなく、すでにマシン上で稼働している OpenAI 互換サーバーに接続する仕組みです。

つまり、以下のような人気のローカル推論フレームワークを利用可能です：

• Ollama
• vLLM
• LM Studio
• llama.cpp

例えば、Ollama を使用している場合は以下のように実行できます：

ml-intern --model ollama/llama3.1:8b "Summarize the README in this repository."

あるいは、vLLM でモデルを実行している場合は：

ml-intern --model vllm/meta-llama/Llama-3.1-8B-Instruct "Your prompt"

ローカルモデルサーバーがカスタムエンドポイントで稼働している場合、環境変数を使用して設定可能です：

LOCAL_LLM_BASE_URL=http://localhost:8000
LOCAL_LLM_API_KEY=optional-if-your-server-requires-it

一部のプロバイダーでは独自環境変数のサポートも提供されています。例えば Ollama を利用する場合は、OLLAMA_BASE_URL を設定することで、汎用的な LOCAL_LLM_BASE_URL より優先されます。ただし注意すべきは、小規模なローカルモデルだと多段階のトレーニングパイプラインを処理するのは困難だということです。探索やスクリプト作成には十分ですが、本格的なエージェントループでは推論能力に余裕のあるモデルを選ぶ必要があります。

ML Intern の仕組みを理解する

アーキテクチャを丸暗記する必要はありませんが、なぜエージェントが途中で停止して承認を求めるのかを知っておくと役立ちます。デフォルトでは、このエージェントは最大 300 ターンまでの反復ループを実行します。以下のフローチャートは、各呼び出しで何が起こっているかのおおよそのイメージを示しています。

ML Intern の各呼び出し処理の流れ

ML Intern の最大の強みの一つは、標準で利用可能なツールの多さです。組み込みツールには HF エコシステム（ドキュメント、データセット、リポジトリ、論文、ジョブ）や GitHub 検索、ローカルファイル操作、プランニング支援が含まれており、さらに Model Context Protocol (MCP) を通じて任意のツールを接続することも可能です。また、同じ引数でツール呼び出しが繰り返される「無限ループ」を検出する機能も備わっており、コードエージェントを利用した経験がある方ならおなじみの問題への対策です。

すべてのセッションは、自動的に Hugging Face のアカウントにあるプライベートデータセット（{username}/ml-intern-sessions）へアップロードされます。この形式は Agent Trace Viewer で認識可能です。これらのトレースはデバッグに特に役立ちます。なぜなら、エージェントが実行したすべての推論ステップを詳細に確認できるからです。何か問題が発生した場合でも、Agent Trace Viewer でセッションを開けば、どこで判断ミスがあったのかを正確に特定できます。

また、セッション中にトレースをどのように共有するかを制御することも可能です。

/share-traces private
/share-traces public

あるいは、セッション履歴を保存したくない場合は、設定ファイルを通じてトレースのアップロード自体を無効化することもできます。

# 一般的なミスを避ける

プロンプトは具体的にする。「llama をファインチューンする」では曖昧です。代わりに「meta-llama/Llama-3.2-1BをimdbでLoRAを使ってファインチューンし、最大 1 エポックまでとし、Hub へのプッシュは行わない」と指示するのが良いでしょう。

承認プロセスに注意してください。トレーニングジョブもサンドボックスもコストがかかります。エージェントが確認を求めてくるので、最初の試行では安易にすべて承認しないようにしてください。

実験中は--max-iterationsを設定しましょう。デフォルトの 300 回という制限は複雑なタスクには最適ですが、テスト中には計算リソースを無駄にする可能性があります。

トレースを確認しましょう。何か不審なことが起きた場合、Hub のプライベートセッションデータセットがブラックボックスレコーダーとして機能します。

次のステップへ進む

ML Intern はあなたの判断を代替するものではありません。トレーニングログの読み込み、評価結果の妥当性チェック、そして「GPQA で 32% というスコアが本当に望んでいたものか」という最終的な決定は、あなた自身が行う必要があります。しかし、train.py を前に立ちすくみ、どこから手をつけていいかわからない経験をしたことがあるなら、Hugging Face Hub の使い方に精通したインターンがいることは、非常に強力な第一歩となるでしょう。

まずは ml-intern を実行し、小さなタスクを与えてその挙動を確認してみましょう。これが最初のゲームのルールです。次に試すべき実践的なステップをいくつか紹介します：

• GitHub リポジトリを確認する。ソースコードを閲覧し、サンプルコードをチェックして、新機能や改善点の最新情報をキャッチアップしよう。
• 独自のツールを作成する。ML Intern は拡張性を重視して設計されているため、agent/core/tools.py ファイルを編集して独自ツールを追加し、パッケージを再インストールできます：

uv tool install -e . --force

• MCP サーバーに接続する。 MCP を使用している場合は、configs/cli_agent_config.json ファイルを更新することで、外部ツールやサービスを追加できます。

環境変数 ${YOUR_TOKEN} は、自動的に .env ファイルから読み込まれます。

• Slack 通知を有効にする。 完了時にアラートを受け取りたい場合は、SLACK_BOT_TOKEN と SLACK_CHANNEL_ID を設定してください。

Kanwal Mehreen 氏は、データサイエンスと AI と医療の交差点に深い情熱を注ぐ機械学習エンジニアであり技術ライターです。共著書として『ChatGPT で生産性を最大化する』という電子書籍があります。APAC 地域の Google Generation Scholar（2022 年）に選出され、多様性と学術的卓越性の推進に尽力しています。また、Teradata のダイバーシティ・イン・テック・スカラー、Mitacs Globalink リサーチ・スカラー、Harvard WeCode スカラーとしても認定されています。Kanwal は変革の熱心な提唱者であり、STEM 分野における女性を支援する団体「FEMCodes」を設立しました。