Docker経由でUnslothをインストールする

Unsloth Docker コンテナを使ってモデルの実行と学習を行う方法を学びましょう。セットアップは不要です。依存関係はすべてあらかじめインストールされています。イメージを pull するだけで、ローカルの NVIDIA または AMD GPU でモデルの実行と学習を始められます。

クイックスタート

このガイドのセクションは NVIDIA GPU を搭載したシステム向けです。お使いの環境が AMD の場合はこちら.

Linux / WSL

Windows（PowerShell）

NVIDIA GPU で Unsloth の Docker を使うには、ターミナルで次を実行します:

コピー

docker run -d --name unsloth --gpus all --ipc=host \
  --ulimit memlock=-1 --ulimit stack=67108864 \
  -p 8000:8000 -p 8888:8888 \
  -e JUPYTER_PASSWORD="mypassword" \
  -v "$PWD":/workspace/host \
  -v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
  -v unsloth-studio:/opt/unsloth-studio \
  unsloth/unsloth

• プロジェクトフォルダーから実行してください。そのフォルダー（$PWD）が /workspace/host.

• 各フラグの役割: 8000（Unsloth Studio）と 8888（JupyterLab）のポートを公開し、3 つの -v フラグにより、ファイル、モデル、Unsloth Studio のデータが保持されます。

• 要件: NVIDIA ドライバー 570.26 以降。

PowerShell で次を実行します:

• プロジェクトフォルダーから実行してください。そのフォルダー（${PWD}）が /workspace/host.

• 各フラグの役割: 8000（Unsloth Studio）と 8888（JupyterLab）のポートを公開し、3 つの -v フラグにより、ファイル、モデル、Unsloth Studio のデータが保持されます。

• 要件: NVIDIA ドライバー 570.26 以降。

前提条件

NVIDIA Container Toolkit 用の Docker がインストールされていない場合は、以下に従ってください:

Linux / WSL

Windows

インストール Docker Engine または Docker Desktop、まだの場合は:

NVIDIA GPU をお使いの場合は、 NVIDIA Container Toolkit まだの場合は:

Docker Desktop と NVIDIA ドライバーをインストールしてください。

インストール Windows 用 Docker Desktop および最新の NVIDIA Windows ドライバー。 その後、PowerShell で WSL を更新します:

Docker Desktop の設定で、 一般 を選択し、 Use the WSL 2 based engine が有効になっていることを確認してください。続行する前にエンジンが起動するまで待ちます。

別途 NVIDIA Container Toolkit をインストールする必要はありません。 Windows の GPU トラブルシューティング.

AMD クイックスタート

このガイドのセクションは AMD GPU を搭載したシステム向けです。お使いの環境が NVIDIA の場合はこちら.

Docker がインストールされていない場合は、次のコマンドを実行してください:

AMD ではコンテナツールキットは不要で、必要なのは amdgpu ホスト上のドライバーだけです。Windows では、Docker Desktop と WSL2 対応の AMD ドライバーをインストールしてください。

📖 使い方ガイド

Unsloth Studio のセットアップ

Unsloth Studio はあらかじめインストールされているため、同じ Docker コンテナからモデルとのチャット、ファインチューニング、画像生成を行えます。

モデルとチャットする

1

ページ上部でモデルを選択してダウンロードします。

開く モデルを選択 参照するか、 おすすめ、またはモデル名を入力して Hub を検索 をクリックして Hugging Face を検索します。モデルは モデルハブ.

でも閲覧できます。GGUF モデルでは、利用可能な RAM と VRAM に合う量子化を選んでください。 OOM.

と表示されたバリアントは避けてください。最初のメッセージを送る前に、モデルのダウンロードと読み込みが完了するのを待ってください。ダウンロード済みのモデルは デバイス上.

ダウンロードしたモデルは /workspace/.cache/huggingfaceに保存されます。クイックスタートのボリュームマウントを使うと、このキャッシュはノートブックと共有され、コンテナを削除してもお使いのコンピューターに残ります。

2

メッセージを送信

モデルの準備ができたら、メッセージを入力して Enterを押します。次を試してみてください:

Docker コンテナと仮想マシンの違いを説明してください。

完全な対応ランタイムフラグ一覧については、 Unsloth Studio Chat ウェブ検索とその他のチャット設定についてのガイド。

モデルを学習する

テキスト、 ビジョン そして 音声のモデルを学習できます。 埋め込み や画像拡散にも対応しています。すべて同じ Docker イメージから行えます。

モデルとデータセットを選択

選択 学習 を開き、 設定します。モデルと学習方法を選び、Hugging Face のデータセットを選択するか、自分のデータをアップロードしてください。

学習を開始

確認 パラメータ を シンプル または 高度な モードで確認してから、 学習を開始をクリックします。進捗、損失、GPU 使用率は 現在の実行.

学習済みモデルを試す

学習が終わったら、 チャットで比較をクリックします。元のモデルとファインチューニング後のモデルを同じプロンプトでテストし、応答の違いを確認できます。

完全な対応ランタイムフラグ一覧については、 詳細は Studio の学習ガイド をご覧ください。または Data Recipes を使ってデータセットを準備してください。

画像を生成する

1

Images を開き、モデルを選択

選択 画像 をサイドバーで。 作成 ワークフローがデフォルトで開きます。

開く 画像モデルを選択 そして次から選択します おすすめ、たとえば Z-Image-Turbo などです。GGUF モデルでは、お使いのデバイスに合う量子化を選んでください。 厳しい 低速で実行される場合があります; OOM と表示されたモデルは、収まらない可能性が高いです。

2

プロンプトを入力して生成

作成したい画像を説明してください。たとえば:

日本庭園の鯉の池を真上から撮影した写真。数十匹のオレンジ、白、黒の鯉が密集して泳いでいる。水は石の底が見えるほど澄んでおり、水面には赤いモミジの葉が浮かんでいる。明るい真昼の光、鮮やかな色彩、くっきりした反射。リアルな写真、50mm。

画像設定は既定のままにして、 生成.

ギャラリーで画像を開き、 ダウンロード 保存するには、または レシピ そのプロンプトと設定を再利用するには、

Transform, インペイント そして 編集 は読み込まれたモデルによって異なります。対応ワークフローと設定については、 画像拡散ガイド を参照してください。

JupyterLab にアクセス

Unsloth Docker イメージには、JupyterLab とすぐに使えるノートブックが含まれています。

開く http://localhost:8888 してサインインします。コンテナの起動時に選んだ JUPYTER_PASSWORD を使ってください。設定していない場合は、コンテナログに表示される生成済みパスワードを使ってください。

JupyterLab のパスワードはコンテナ作成時に設定されます。変更するには、コンテナを削除して新しいパスワードで再作成してください。

サインインすると、 Unsloth Notebooksが表示され、フォルダーはモデルとタスクごとにグループ化されています。

これらのフォルダーには、 /workspace/unsloth-notebooks内のノートブックファイルへのショートカットが入っています。コンテナが起動するたびに、編集内容を上書きせずに GitHub からノートブックが更新されます。

ダブルクリックして 01 Main Notebooks を開いて例を参照するか、vision、speech、reinforcement learning などのカテゴリを選択してください。

ノートブックでモデルをファインチューニングする

学習を始める前に、Unsloth Studio で読み込まれているモデルをすべてアンロードして、ノートブックに必要な GPU メモリを確保してください。

でノートブックを開き 01 Main Notebooks 、指示に従ってください。 Shift+Enter を押して各セルを順番に実行します。最初の実行で、モデルが Hugging Face キャッシュにダウンロードされます。

たとえば、 Gemma3_(4B)-Vision.ipynb では、数式画像を LaTeX に変換するための Gemma 3 4B のファインチューニング手順が案内されます。

学習後は、ノートブックの 推論 セクションを使ってモデルをテストします。学習済みモデルを数式画像でテストします。以下に、可読性のため高解像度で再作成した数式を示します。

モデルは元のデータセット画像から LaTeX を生成します。セルの下に LaTeX の結果を出力します。

モデルを保存してエクスポートする

ノートブックの Saving セクションに従って、学習済み LoRA アダプターを保存するか、マージ済みモデルをエクスポートしてください。

次のような相対パスは "gemma_3_lora" ノートブックの隣、次の場所に保存されます /workspace/Unsloth Notebooks/...。そのフォルダーはコンテナ内にあるため、コンテナを削除すると削除されます。結果を自分のコンピューターに残すには、次の場所に保存してください: /workspace/host.

• LoRA アダプターをローカルに保存: このセルは既定で実行されます。パスを次に変更してください /workspace/host.

• マージ済み 16 ビットモデルをエクスポート: エクスポート用セルでは、 if False: を if True: を使いたい विकल्पに応じて切り替えてください。選べるのは 1 つだけです。

• Hugging Face にアップロード: アップロードには書き込み権限のあるトークンが必要です。 YOUR_USERNAME そして YOUR_HF_TOKEN のプレースホルダーを自分の情報に置き換えてください。

さらに詳しい手順は、 ファインチューニングガイド, RL ガイドと ノートブック集.

コンテナを停止、再起動、更新する

コマンドはイメージ名ではなく、コンテナ名または ID を指定します unsloth/unsloth.

コンテナを停止するが保持する:

同じ状態で再起動する:

実行中かどうかにかかわらず、コンテナを再度見つける:

コンテナを停止して削除する:

コンテナを削除しても、モデル、ホスト上のファイル（/workspace/host）、または Unsloth Studio のデータ（アカウント、チャット、エクスポート）は削除されません。同じ -v フラグで新しいコンテナを起動すると、前回の続きから再開され、Unsloth のパスワードもそのままです。コンテナ内に書き込まれたその他のものは失われます。

Unsloth Studio のデータを完全に削除するには、そのボリュームを削除します:

最新の Unsloth バージョンに更新するには、新しいイメージを pull します:

その後、古いコンテナを削除して、同じフラグでクイックスタートのコマンドを再度実行してください。モデル、ファイル、Unsloth Studio のデータは引き継がれます。

SSH で接続する

SSH は SSH_KEY または PUBLIC_KEYを設定しない限り無効です。コンテナ内の 22 番ポートで、鍵のみの認証を使って root ユーザーとして接続します。

SSH キーを生成:

SSH キーはコンテナ作成時に適用されるため、追加するにはコンテナを再作成する必要があります。次の完全なコマンドを使って、SSH ポートをホストの 2222 に割り当て、パスワードを設定し、ボリュームをマウントしてください。

UNSLOTH_STUDIO_PASSWORD は、 unsloth-studio ボリュームが最初に使用されるときにのみ適用されます。 詳細設定 以下で、すべての環境変数、ボリューム、ポートを確認してください。

コンテナに接続:

📂 コンテナ構成

• /workspace/host/ — マウントされた作業ディレクトリ

• /workspace/.cache/huggingface — モデルとデータセットのダウンロード

• /workspace/.cache/triton — コンパイル済み Triton カーネル

• /workspace/unsloth-notebooks/ — 編集内容を含む、ファインチューニング用のサンプルノートブック

• /workspace/Unsloth Notebooks — 起動のたびに再構築される、トピック別のサンプルファインチューニングノートブック

• /opt/unsloth-studio — Unsloth Studio のアカウント、チャット、出力、エクスポート、実行履歴

トラブルシューティング

Unsloth が私の GPU を検出しない / 使用しない

Docker 用に特に GPU が使われていない場合は、次を試してください:

最新のイメージを手動で pull する:

• GPUアクセスでコンテナを起動します:

  • docker run: --gpus all

  • Docker Compose: capabilities: [gpu]

  • AMD: --device /dev/kfd --device /dev/dri に加えて --group-add ids（Quickstart の $GPU_FLAGS ブロック）

• Linux（NVIDIA）では、NVIDIA Container Toolkit がインストールされていることを確認し、インストール後に docker を再起動してください。

• Windows（NVIDIA）では:

  • 実行 docker exec unsloth nvidia-smi。GPU が表示されれば、コンテナから見えています。

  • に従ってください Docker のガイド

• AMD では、次を実行してください docker exec unsloth rocm-smi。GPU が表示されれば、コンテナから見えています。での権限エラーは /dev/kfd は、 --group-add ids が不足していたことを意味します。

ポートはすでに割り当てられています

ホスト側のポートを変更してください。例: -p 8001:8000、その後 http://localhost:8001.

Unsloth Studio が1時間後に応答しなくなる

自動生成されたパスワードを変更しないと、Unsloth Studio は自動的に停止します。次を実行してください docker restart unsloth して再度起動し、パスワードを変更してください。

プロジェクトフォルダ内のファイルの所有者が root になっている

コンテナは root として実行されるため、次を使用してください sudo chown、または core を --user.

⚙️ 詳細設定

環境変数

以下のいずれかを次に渡してください docker run を -e NAME=value または --env-file。これらは両方に適用されます unsloth/unsloth そして unsloth/unsloth-rocm.

ボリューム

ボリュームに含まれていないものは、コンテナを削除すると失われます。これらは次でマウントしてください -v <host path or volume name>:<container path>.

• /workspace は作業ディレクトリであり、JupyterLab が開くフォルダです。

• 次には名前付きボリュームを使用してください /opt/unsloth-studio、ホストフォルダではありません。Unsloth Studio にはそこでシンボリックリンクが必要で、Windows や macOS のホストフォルダではそれを許可しない場合があり、その場合はコンテナの起動が停止します。

• Unsloth Studio または JupyterLab にさらに多くのファイルを使わせるには、次の下にさらにフォルダをマウントしてください /workspace。例: -v /data/datasets:/workspace/datasets、そしてそのコンテナ内パスで参照してください。

ポート

コンテナのポートを空いている任意のホストポートに次で割り当てます -p <host>:<container>。たとえば、ホストポートで SSH を有効にするには 2222:

🔒 セキュリティに関する注意

• コンテナは root として実行されます。次を使用してください unsloth/unsloth:core を --user <uid>:<gid> マウントされたファイルをホストユーザーの所有にする必要がある場合。

• SSH は次の場合を除きオフです SSH_KEY または PUBLIC_KEY が設定されている場合。ポート 22 で、root としてキー認証のみです。

• 公開されたポートはすべてのインターフェースで待ち受けます。クラウドホストでは、次にバインドしてください 127.0.0.1 、または次を使用してください -e UNSLOTH_STUDIO_SECURE=1.

• JupyterLab は完全なシェルです。JupyterLab にログインできる人は、コンテナ内で任意のコマンドを実行できます。Unsloth Studio と JupyterLab はプレーン HTTP で提供されるため、インターネットに直接公開しないでください。

• Unsloth Studio のツールはコードを実行できます。Studio のサーバー側ツールは既定で有効になっており、コンテナ内でコマンドを実行できます。コンテナにアクセスを許してもよいホストフォルダだけをマウントしてください。

• 環境変数は Docker ユーザーに見えます。次で渡した値は -e または --env-file、トークンやパスワードを含め、次に表示されます docker inspect。Docker デーモンにアクセスできる人は誰でもそれらを読み取れます。