LLMのファインチューニング（追加学習）に挑戦しようとして、最初に「どのフレームワークを使えばいいのか分からない」と詰まる人は多いです。結論から言うと、Axolotl は LoRA・QLoRA・DeepSpeed・Flash Attention を1枚の YAML で切り替えられる LLM ファインチューニング専用フレームワークで、設定ファイル1枚と1コマンドで学習が回せます。この記事では Ubuntu 24.04 LTS 上に Axolotl 0.17.0 を導入する手順を、実際に Docker コンテナと PyPI を叩いて取得した一次データとともに解説します。数字はすべて 2026-06-15 に実測した実値です。
この記事のポイント
- Axolotl の PyPI 最新版は
0.17.0（2026-06-03 公開）。要件は Python ≥ 3.10 で、Ubuntu 24.04 の Python 3.12.3 で満たせます（実測） - 本体 wheel はわずか 1.05MB ですが、依存パッケージは
requires_dist上で83個。torch≥2.9.1・transformers==5.9.0を引き込むので venv 分離が事実上必須です（実測） - 前提環境は
apt install python3 python3-venv git build-essentialの1コマンドで完成（Ubuntu 24.04 で実測） - 学習コマンドは
python -m axolotl.cli.train config.yamlのみ。設定はすべてconfig.yamlに集約します - 同名の
python-axolotlはまったくの別物（Signal暗号プロトコルの移植）。間違ってインストールしないよう注意
目次
- Axolotl とは
- PyPI の実データで見る Axolotl 0.17.0
- 動作確認済み環境
- Ubuntu 24.04 への Python 環境構築
- Axolotl のインストール
- config.yaml の書き方
- ファインチューニングの実行
- GPU サーバー（VPS）への接続設定
- よくあるエラーと解決策
- まとめ
Axolotl とは
Axolotl（アホロートル）は、LLM（大規模言語モデル）のファインチューニングを効率化するための Python フレームワークです。開発元は axolotl-ai-cloud で、リポジトリは github.com/axolotl-ai-cloud/axolotl、公式ドキュメントは docs.axolotl.ai にあります。個人開発者や研究者が config.yaml ひとつでさまざまな学習手法を切り替えられるように設計されているのが特徴です。
主な特徴は次の3点です。
- 多様な学習手法に対応：LoRA・QLoRA・Full Fine-tuning・選好学習（DPO等）を YAML の数行で切り替え可能
- Flash Attention & DeepSpeed 統合：VRAM 効率を上げるアテンション高速化や複数GPUでの分散学習をオプション一つで有効化
- Hugging Face エコシステムと直結：transformers・peft・trl・accelerate と連携し、Hub 上のモデルをそのまま使える（これらは依存として自動で入ります）
上のフローのとおり、環境構築からモデル完成まで大きく6ステップで進みます。本記事では①〜②の環境構築・インストールを実測ベースで掘り下げつつ、③〜⑤の設定と実行コマンドまで一通り解説します。
注意：同名の別パッケージに気をつける
PyPI には python-axolotl という紛らわしい名前のパッケージがありますが、これは Signal の暗号プロトコル（libaxolotl）を Python に移植した まったく無関係なライブラリです（最新は0.2.3／2019年公開）。LLM用は pip install axolotl（ハイフンなし）の方なので、取り違えないようにしてください。
PyPI の実データで見る Axolotl 0.17.0
まずインストール前に、PyPI の公式 JSON API（pypi.org/pypi/axolotl/json）を実際に叩いて、最新バージョンと依存関係を確認しました。これを知っておくと「なぜ venv が必須なのか」「ディスクと回線がどれだけ必要か」が腑に落ちます。
実取得した値を整理すると、次のことが分かりました。
- 最新版は 0.17.0（2026-06-03 公開、全26リリース）。要求 Python は
>=3.10 - 本体 wheel（
axolotl-0.17.0-py3-none-any.whl）は 1,075,101 バイト（約1.05MB）とごく小さい - 一方で
requires_distには 83個もの依存が宣言されており、torch>=2.9.1・transformers==5.9.0（完全固定）・accelerate==1.13.0・peft・trl・datasets・bitsandbytesなどが含まれる
「本体は1MBなのに依存が83個」というのが Axolotl の正体です。transformers==5.9.0 のようにバージョンが固定で要求されるので、既存の Python 環境にそのまま入れると確実に衝突します。だから venv で隔離するのが大前提なんです。
動作確認済み環境
| 項目 | 値 |
|---|---|
| OS | Ubuntu 24.04 LTS（Noble Numbat）／公式 Docker イメージ |
| Python | 3.12.3（apt から取得・実測） |
| pip | 24.0（apt 版）／venv 更新後 26.1.2（実測） |
| git | 2.43.0（apt から取得・実測） |
| gcc | 13.3.0（build-essential・実測） |
| OpenSSH | 9.6p1（実測） |
| Axolotl | 0.17.0（PyPI 最新・2026-06-15 確認） |
| GPU（学習実行時） | NVIDIA GPU + CUDA 12.x（ファインチューニングに必要） |
注意
Axolotl での学習実行には NVIDIA GPU と CUDA 環境が必要です。CPU だけでもインストール自体は可能ですが、実際の学習には GPU を載せたサーバー（VPS・クラウドGPU）が要ります。本記事の Python/pip/git のインストールと axolotl パッケージの導入手順は、CPU 環境（Docker の ubuntu:24.04 公式イメージ）で実測しています。
Ubuntu 24.04 への Python 環境構築
手順1：パッケージリストを更新して依存パッケージをインストールする
まず apt でシステムを最新化し、Python 3・pip・venv・git・ビルドツールを一括で入れます。Ubuntu 24.04 LTS には Python 3.12.3 が標準で含まれており、Axolotl の要件（Python ≥ 3.10）を十分に満たします。
Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Reading package lists… Done
$ sudo apt install -y python3 python3-pip python3-venv python3-dev git curl build-essential
Setting up build-essential (12.10ubuntu1) …
Processing triggers for ca-certificates (20240203) …
$ python3 –version && pip3 –version && git –version
Python 3.12.3
pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.12)
git version 2.43.0
$ cc –version | head -n1
cc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
上図は docker run --rm ubuntu:24.04 で実際に流したインストールログです。Python 3.12.3・pip 24.0・git 2.43.0・gcc 13.3.0 が入り、コマンドは正常終了（returncode=0）しました。build-essential（gcc 等）を入れておくのは、後段で Flash Attention などをソースビルドする可能性があるためです。
手順2：Ubuntu 22.04 との違いを把握する
Axolotl の要件は Python ≥ 3.10 なので、実は Ubuntu 22.04 でも動かせます。ただし得られるバージョンが違います。同じコマンドを ubuntu:22.04 と ubuntu:24.04 の両コンテナで実行して比較しました。
実測の要点は次のとおりです。22.04 は Python 3.10.12、24.04 は Python 3.12.3。どちらも要件は満たしますが、git や OpenSSH も含めて 24.04 の方が新しく、サポート期限も2029年4月までと長いので、新規構築なら 24.04 を選ぶのが無難です。
手順3：仮想環境（venv）を作成する
前述のとおり Axolotl は transformers==5.9.0 など固定バージョンを大量に要求します。システムの Python を汚さないよう、venv で分離するのは必須だと考えてください。
$ source /opt/axolotl-env/bin/activate
(axolotl-env) $
(axolotl-env) $ pip install –upgrade pip
Successfully installed pip-26.1.2
Axolotl のインストール
手順1：PyTorch（CUDA 対応版）をインストールする
Axolotl の前に、まず PyTorch の CUDA 対応版を入れます。Axolotl 0.17.0 は torch>=2.9.1 を要求するので、GPU サーバーの CUDA バージョンに合った wheel を選んでください（CUDA 12.4 の例）。
(axolotl-env) $ pip install torch –index-url https://download.pytorch.org/whl/cu124
Collecting torch
Successfully installed torch-2.x.x+cu124
(axolotl-env) $ python -c “import torch; print(torch.cuda.is_available())”
True
注意
PyTorch の CUDA 版は PyTorch 公式サイト（pytorch.org）でインストールコマンドを生成してください。GPU の CUDA バージョンと PyTorch が合っていないと torch.cuda.is_available() が False を返します。上記の +cu124 部分はお使いの環境に合わせて変わります。
手順2：Axolotl 本体をインストールする
PyTorch の動作を確認できたら Axolotl を入れます。実際に ubuntu:24.04 の venv で pip install axolotl==0.17.0 を実行した結果が次のスクリーンショットです。
本体 wheel は約1.1MBなので一瞬でダウンロードが終わります（実測14.3MB/s）。pip show axolotl の Requires: 行を見ると、accelerate・bitsandbytes・datasets・peft・torch・transformers・trl など 54個のパッケージが連なっており、本体を入れるだけで学習スタック一式を引き込む設計だと分かります。GPU 環境では [flash-attn,deepspeed] オプションを付けて最適化を有効にします。
(axolotl-env) $ pip install “axolotl[flash-attn,deepspeed]”
Installing collected packages: axolotl, peft, trl, accelerate, …
Successfully installed axolotl-0.17.0
手順3：インストールを確認する
Name: axolotl
Version: 0.17.0
Summary: LLM Trainer
Home-page: https://axolotl.ai/
(axolotl-env) $ python -m axolotl.cli.train –help
usage: axolotl train [-h] … config
config Path to the config.yaml file
config.yaml の書き方
Axolotl の設定はすべて config.yaml に書きます。LoRA の最小構成例を示します。
base_model: meta-llama/Llama-3.2-1B-Instruct
# データセット設定
datasets:
– path: my_dataset.jsonl
type: alpaca
# 学習設定（LoRA）
adapter: lora
lora_r: 16
lora_alpha: 32
lora_dropout: 0.05
# トレーニングパラメーター
sequence_len: 2048
micro_batch_size: 2
num_epochs: 3
learning_rate: 0.0002
# 出力先
output_dir: ./outputs/lora-finetune
主要なパラメーターを表にまとめます。
| パラメーター | 説明 | 推奨値（7B モデル） |
|---|---|---|
adapter |
学習手法。lora / qlora / full |
qlora（VRAM 節約） |
lora_r |
LoRA のランク。高いほど表現力UP・VRAM消費増 | 16〜64 |
lora_alpha |
スケーリング係数。lora_r × 2 が目安 |
32〜128 |
micro_batch_size |
1 GPU あたりのバッチサイズ。VRAM と相談 | 1〜4 |
sequence_len |
最大トークン長。長いほど VRAM 消費増 | 2048〜4096 |
load_in_4bit |
true で QLoRA（4bit 量子化）を有効化 |
true（VRAM 16GB未満） |
正直、lora_r と micro_batch_size はここだけ詰まりやすいです。最初は lora_r: 16・micro_batch_size: 1 から始めて、VRAM に余裕があれば少しずつ上げるのが安全です。
データセットのフォーマット（Alpaca 形式）
最もシンプルな Alpaca 形式の例です。instruction / input / output の3キーを持つ JSONL を用意します。
{“instruction”: “SSHの公開鍵を生成するには？”, “input”: “”, “output”: “ssh-keygen -t ed25519 -C ‘your_email’ を使います。”}
ファインチューニングの実行
手順1：学習を開始する
設定とデータセットが揃ったら、学習コマンドは1行だけです。
[INFO] Loading model: meta-llama/Llama-3.2-1B-Instruct
[INFO] Applying LoRA adapter (r=16, alpha=32)
trainable params: 3,407,872 || all params: 1,238,343,680 (0.28%)
{‘loss’: 2.1732, ‘epoch’: 0.5}
Training completed. Model saved to ./outputs/lora-finetune
注意（この学習ログはイメージです）
上の学習ログは典型的な出力イメージで、実機GPUでの実測値ではありません（本記事の実測対象は環境構築・パッケージ導入・ディスク/SSH の各コマンドです）。実際の loss やステップ数はモデル・データセット・GPUによって変わります。
手順2：tmux でセッションを維持する（長時間学習の場合）
ファインチューニングは数時間かかることがあります。SSH が切れても学習が続くよう、tmux でセッションを維持するのが定番です。
# tmux セッション内で venv を有効化して学習を起動
$ source /opt/axolotl-env/bin/activate
$ python -m axolotl.cli.train config.yaml
# Ctrl+B → D でデタッチ（学習は継続）。再接続は ↓
$ tmux attach-session -t axolotl
手順3：マルチ GPU での学習（DeepSpeed）
GPU が複数ある場合は accelerate launch と DeepSpeed で分散学習できます。設定はやはり YAML 側で完結します。
[INFO] Detected 2 GPU(s)
[INFO] Using DeepSpeed ZeRO Stage 2
GPU サーバー（VPS）への接続設定
自宅にGPUがない場合は Vultr などのクラウドGPUを使います。ここで効いてくるのが ストレージ速度です。前述のとおり Axolotl はモデルや依存を大量に読み込むので、ディスクI/Oが遅いとロード待ちが長くなります。ubuntu:24.04 環境で dd を使い、512MBファイルの逐次I/Oを3回ずつ実測しました。
結果は 書き込み平均 1.57 GB/s（1.2〜2.1）、読み込み平均 3.27 GB/s（2.5〜3.8）でした。仮に7Bモデル（約14GB）をこの読み込み速度でロードするなら、単純計算で約4.3秒です。GPUインスタンスを借りる際は NVMe SSD 搭載プランを選ぶと、モデルのロード待ちを短縮できます。
SSH 鍵の生成と登録
GPUサーバーへの接続にはパスワードよりSSH鍵認証が安全です。ubuntu:24.04（OpenSSH 9.6p1）で ed25519 鍵を実際に生成しました。
Generating public/private ed25519 key pair.
Your identification has been saved in ~/.ssh/axolotl_key
256 SHA256:9breLG8qn/DyFWFmWPB4mgLWSF5Ffp2HrQPOvF9sQ9k axolotl-gpu-server (ED25519)
$ cat ~/.ssh/axolotl_key.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAII…tU82U axolotl-gpu-server
# この公開鍵をVPSのコントロールパネルか ~/.ssh/authorized_keys に登録する
SSH 設定ファイルを書いておくと接続コマンドが短くなります。
HostName your-gpu-server-ip
User ubuntu
IdentityFile ~/.ssh/axolotl_key
Port 22
$ ssh gpu-server
Welcome to Ubuntu 24.04 LTS
よくあるエラーと解決策
①「CUDA out of memory」が出る
VRAM 不足の典型的なエラーです。次の設定を順に試してください。
解決策
micro_batch_sizeを 1 に下げるload_in_4bit: trueで QLoRA（4bit量子化）に切り替えるsequence_lenを 1024 に下げるgradient_checkpointing: trueを追加する
②「No module named ‘flash_attn’」
Flash Attention のビルドに失敗するケースがあります。PyTorch と CUDA のバージョンを合わせたうえで、単体インストールを試します。
$ pip install flash-attn –no-build-isolation
Successfully installed flash-attn-2.x.x
③「No module named ‘axolotl’」
venv が有効化されていないのが原因です。あるいは、冒頭で触れた python-axolotl（別物）を入れていないかも確認してください。
$ source /opt/axolotl-env/bin/activate
(axolotl-env) $ python -m axolotl.cli.train config.yaml
④「Dataset not found」
config.yaml のデータセットパスが間違っているか、ファイルが存在しない場合に出ます。相対パスではなく絶対パスを指定するか、config.yaml と同じディレクトリにデータセットを置いてください。
まとめ
Axolotl は設定ファイル1枚で LLM ファインチューニングの全工程を管理できる強力なフレームワークです。今回の実測で確認できたポイントを整理します。
- PyPI 最新版は 0.17.0（2026-06-03 公開）。要件は Python ≥ 3.10 で、Ubuntu 24.04 の Python 3.12.3 で満たせる
- 本体 wheel は約1.05MBだが依存は83個。torch≥2.9.1・transformers==5.9.0 を固定で要求するため venv 分離が必須
- 前提環境は apt 1コマンドで完成（Python 3.12.3・pip 24.0・git 2.43.0・gcc 13.3.0 を実測）
- 同名の python-axolotl はSignalプロトコルの別物。pip install axolotl（ハイフンなし）を入れること
- 学習は tmux でセッション維持、SSH は ed25519 鍵（OpenSSH 9.6p1 で生成確認）が安全。ストレージは読み込み3.27GB/s実測でNVMe推奨
GPUサーバーを選ぶ際は、東京リージョン + NVMe SSD + 時間課金の組み合わせが使いやすいです。VPSの選び方や各社の比較はも参考にしてください。
コメント