⚠️トラブルシューティングとFAQ

問題を解決するためのヒントと、よくある質問。

依然としてバージョンや依存関係で何らかの問題が発生している場合は、ぜひ私たちの Docker イメージ をご利用ください。必要なものがすべて事前にインストールされています。

何か問題を見つけたら、Unsloth は常に更新するようにしてください。

pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo

Unsloth がサポートしていない新しいモデルをファインチューニングしたいですか？

Unsloth は、次でサポートされている任意のモデルで動作します。 transformers。モデルが私たちのアップロード一覧にない場合や、箱から出してすぐに動作しない場合でも、通常はまだサポートされています。最近のモデルでは、最適化の関係で少し手動調整が必要なだけかもしれません。

ほとんどの場合、次を設定すれば互換性を有効にできます。 trust_remote_code=True をファインチューニングスクリプトに追加してください。以下は、 DeepSeek-OCR:

from huggingface_hub import snapshot_download
snapshot_download("unsloth/DeepSeek-OCR", local_dir = "deepseek_ocr")
model, tokenizer = FastVisionModel.from_pretrained(
    "./deepseek_ocr",
    load_in_4bit = False, # メモリ使用量を減らすには4bitを使用。16bit LoRA の場合は False。
    auto_model = AutoModel,
    trust_remote_code = True, # 新しいモデルをサポートするために有効化
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # 長いコンテキストには True または "unsloth"
)

Unsloth では正常に動作するのに、エクスポート後に他のプラットフォームで実行すると結果が悪い

モデルは Unsloth では正常に動作して良い結果を出すのに、Ollama や vLLM のような別のプラットフォームで使うと結果が悪かったり、意味不明な出力、無限生成になったりすることがあります。 または 繰り返し出力.

• になる、という問題に遭遇することがあります。このエラーの最も一般的な原因は、 誤ったチャットテンプレート. を使っていることです。Unsloth でモデルを学習したときと、後で llama.cpp や Ollama など別のフレームワークで実行するときに、同じチャットテンプレートを使うことが不可欠です。保存済みモデルから推論する際は、正しいテンプレートを適用することが重要です。

• また、推論エンジンが不要な「シーケンス開始」トークンを追加している（あるいは逆に必要なものが欠けている）可能性もあります。どちらの仮説も確認してください！

• チャットテンプレートを強制するには、私たちの会話用ノートブックを使ってください。これでほとんどの問題は解決します。

  • Qwen-3 14B 会話用ノートブック Colabで開く

  • Gemma-3 4B 会話用ノートブック Colabで開く

  • Llama-3.2 3B 会話用ノートブック Colabで開く

  • Phi-4 14B 会話用ノートブック Colabで開く

  • Mistral v0.3 7B 会話用ノートブック Colabで開く

  • さらに多くのノートブックは ノートブックのドキュメント

GGUF / vLLM 16bit への保存でクラッシュする

保存中の GPU 使用量の最大値を変更して、以下を減らしてみてください maximum_memory_usage.

デフォルトは model.save_pretrained(..., maximum_memory_usage = 0.75)です。これを 0.5 などに下げると、GPU ピークメモリの 50% を使用するようになります。これにより、保存中の OOM クラッシュを減らせる場合があります。

GGUF に手動で保存するにはどうすればよいですか？

まず、以下の方法でモデルを 16bit に保存します:

model.save_pretrained_merged("merged_model", tokenizer, save_method = "merged_16bit",)

以下のように llama.cpp をソースからコンパイルします:

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=ON -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-quantize llama-cli llama-gguf-split llama-mtmd-cli
cp llama.cpp/build/bin/llama-* llama.cpp

次に、モデルを F16 で保存します:

python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-F16.gguf --outtype f16 \
    --split-max-size 50G

# BF16 の場合:
python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-BF16.gguf --outtype bf16 \
    --split-max-size 50G
    
# Q8_0 の場合:
python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-Q8_0.gguf --outtype q8_0 \
    --split-max-size 50G

なぜ Q8_K_XL は Q8_0 GGUF より遅いのですか？

Mac デバイスでは、BF16 は F16 より遅いようです。Q8_K_XL は一部の層を BF16 にアップキャストするため、そのぶん遅くなります。私たちは現在、Q8_K_XL のデフォルトを F16 にして性能低下を抑えるよう、変換プロセスを積極的に変更しています。

評価の方法

トレーニング実行で評価を設定するには、まずデータセットを学習用とテスト用に分割する必要があります。 データセットの選択は必ずシャッフルしてください。そうしないと評価が正しくありません！

new_dataset = dataset.train_test_split(
    test_size = 0.01, # テストサイズは1%にする。行数の整数でも可
    shuffle = True, # 必ず True に設定すること！
    seed = 3407,
)

train_dataset = new_dataset["train"] # 学習用データセット
eval_dataset = new_dataset["test"] # 評価用データセット

次に、評価を有効にするよう学習パラメータを設定できます。注意: 評価は非常に非常に遅くなることがあります。特に次を設定している場合はそうです。 eval_steps = 1 これは、毎ステップ評価していることを意味します。そうしている場合は、eval_dataset のサイズを 100 行程度に減らしてみてください。

from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,         # メモリ使用量を減らすために設定
        per_device_eval_batch_size = 2,# これを増やすとより多くのメモリを使用します
        eval_accumulation_steps = 4,   # これをバッチサイズ代わりに増やせます
        eval_strategy = "steps",       # 数ステップまたはエポックごとに評価を実行します。
        eval_steps = 1,                # 学習ステップごとに何回評価するか
    ),
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
    ...
)
trainer.train()

評価ループ - メモリ不足またはクラッシュ。

OOM になるよくある原因は、バッチサイズを高く設定しすぎていることです。VRAM をより少なく使うには 2 未満に下げてください。また、次も使用してください。 fp16_full_eval=True 評価に float16 を使うことで、メモリを半分に削減します。

まず、学習用データセットを train と test に分割してください。評価用の trainer 設定を次のようにします:

new_dataset = dataset.train_test_split(test_size = 0.01)

from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,
        per_device_eval_batch_size = 2,
        eval_accumulation_steps = 4,
        eval_strategy = "steps",
        eval_steps = 1,
    ),
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
    ...
)

これで OOM は発生せず、ある程度速くなります。次も使用できます。 bf16_full_eval=True bf16 マシン向けです。デフォルトでは、2025年6月時点で Unsloth はこれらのフラグをデフォルトで設定しているはずです。

早期終了を行うにはどうすればよいですか？

評価損失が下がらないためにファインチューニング / 学習実行を停止したい場合は、学習を停止する early stopping を使用できます。次を使用してください。 EarlyStoppingCallback.

いつものように、trainer と評価データセットを設定します。以下は、学習実行を停止するために使用されます。 eval_loss （評価損失）が 3 ステップほど経っても減少しない場合。

from trl import SFTConfig, SFTTrainer
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,
        per_device_eval_batch_size = 2,
        eval_accumulation_steps = 4,
        output_dir = "training_checkpoints", # 早期終了用に保存されるチェックポイントの保存先
        save_strategy = "steps",             # モデルを N ステップごとに保存
        save_steps = 10,                     # モデルを保存するまでのステップ数
        save_total_limit = 3,                # ディスク容量節約のため、保存済みチェックポイントを 3 つだけ保持
        eval_strategy = "steps",             # N ステップごとに評価
        eval_steps = 10,                     # 評価を行うまでのステップ数
        load_best_model_at_end = True,       # early stopping では必須
        metric_for_best_model = "eval_loss", # early stop の基準にしたい指標
        greater_is_better = False,           # eval loss は低いほど良い
    ),
    model = model,
    tokenizer = tokenizer,
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
)

次に、カスタマイズも可能なコールバックを追加します：

from transformers import EarlyStoppingCallback
early_stopping_callback = EarlyStoppingCallback(
    early_stopping_patience = 3,     # eval loss が下がらない場合に待つステップ数
                                     # たとえば損失が増加しても、3 ステップ後に減少することがあります
    early_stopping_threshold = 0.0,  # より高く設定することも可能 - どれだけ損失が減少すれば
                                     # early stopping と見なすかを設定します。例えば 0.01 なら、損失が
                                     # 0.02 から 0.01 になった場合に、早期終了すると見なします。
)
trainer.add_callback(early_stopping_callback)

次に、通常どおり以下でモデルを学習します trainer.train() 。

ダウンロードが 90～95% で止まる

モデルのダウンロードが 90、95% 付近で長時間止まる場合は、いくつかの高速ダウンロード処理を無効にして、ダウンロードを同期的に強制し、より多くのエラーメッセージを表示できます。

単に次を使用してください。 UNSLOTH_STABLE_DOWNLOADS=1 Unsloth を import する前に。

import os
os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1"

from unsloth import FastLanguageModel

RuntimeError: CUDA error: device-side assert triggered

再起動してすべて実行し直してください。ただし、これは Unsloth を import する前の最初に置いてください。また、できるだけ早くバグ報告をお願いします、ありがとうございます！

import os
os.environ["UNSLOTH_COMPILE_DISABLE"] = "1"
os.environ["UNSLOTH_DISABLE_FAST_GENERATION"] = "1"

データセット内のラベルがすべて -100 です。学習損失はすべて 0 になります。

これは、次の使い方が train_on_responses_only そのモデルに対して正しくないことを意味します。train_on_responses_only を使うと、ユーザーの質問をマスクし、アシスタントの応答をより高い重みで出力するようにモデルを学習できます。これにより精度が 1%以上向上することが知られています。私たちの LoRA ハイパーパラメータガイド 詳細について。

Llama 3.1、3.2、3.3 系のモデルには、以下を使用してください。

from unsloth.chat_templates import train_on_responses_only
trainer = train_on_responses_only(
    trainer,
    instruction_part = "<|start_header_id|>user<|end_header_id|>\n\n",
    response_part = "<|start_header_id|>assistant<|end_header_id|>\n\n",
)

Gemma 2、3、3n 系のモデルには、以下を使用してください。

from unsloth.chat_templates import train_on_responses_only
trainer = train_on_responses_only(
    trainer,
    instruction_part = "<start_of_turn>user\n",
    response_part = "<start_of_turn>model\n",
)

Unsloth は予想より遅いですか？

最初に速度が遅く見えるなら、それはおそらく torch.compile ウォームアップとコンパイル完了に通常約 5 分（またはそれ以上）かかるためです。スループットを測定する際は、 後で 完全に読み込まれてから行ってください。長時間の実行では、Unsloth ははるかに高速になるはずです。

無効にするには次を使用してください:

import os
os.environ["UNSLOTH_COMPILE_DISABLE"] = "1"

Gemma3nForConditionalGeneration の一部の重みはモデルチェックポイントから初期化されませんでした

これは重大なエラーです。いくつかの重みが正しく解析されず、誤った出力につながることを意味するためです。通常は Unsloth を更新することで修正できます。

pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo

次に transformers と timm をアップグレードします:

pip install --upgrade --force-reinstall --no-cache-dir --no-deps transformers timm

それでも問題が解決しない場合は、できるだけ早くバグ報告をしてください！

NotImplementedError: UTF-8 ロケールが必要です。ANSI が指定されました

https://github.com/googlecolab/colabtools/issues/3409 を参照してください

新しいセルで、以下を実行してください:

import locale
locale.getpreferredencoding = lambda: "UTF-8"

Unsloth の引用

モデルアップロードの利用を引用する場合は、以下の BibTeX を使用してください。これは Qwen3-30B-A3B-GGUF Q8_K_XL 用です。

@misc{unsloth_2025_qwen3_30b_a3b,
  author       = {Unsloth AI and Han-Chen, Daniel and Han-Chen, Michael},
  title        = {Qwen3-30B-A3B-GGUF:Q8\_K\_XL},
  year         = {2025},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/unsloth/Qwen3-30B-A3B-GGUF}}
}

Github パッケージの利用、または私たちの作業全般を引用する場合:

@misc{unsloth,
  author       = {Unsloth AI and Han-Chen, Daniel and Han-Chen, Michael},
  title        = {Unsloth},
  year         = {2025},
  publisher    = {Github},
  howpublished = {\url{https://github.com/unslothai/unsloth}}
}