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

問題解決のヒントとよくある質問。

バージョンや依存関係でまだ問題が発生する場合は、どうぞ私たちの を使って Unsloth をインストールすることもできます。 をご利用ください。すべてが事前にインストールされています。

問題を見つけたら、常に 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)です。ピークGPUメモリの50%を使うように0.5などに下げるか、それ以下にしてください。これにより保存中のOOMクラッシュを減らせます。

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

まず次でモデルを16ビットで保存します：

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/ggerganov/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 にするよう、変換プロセスを積極的に変更しています。

評価（Evaluation）の方法

トレーニング実行で評価を設定するには、まずデータセットをトレーニング用とテスト用に分割する必要があります。あなたは データセットの選択は常にシャッフルするべきです、そうしないと評価が間違ってしまいます！

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,   # batch_size の代わりにこれを増やせます
        eval_strategy = "steps",       # 数ステップまたはエポックごとに評価を実行します。
        eval_steps = 1,                # トレーニングステップ数あたり何回評価を行うか
    ),
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
    ...
)
trainer.train()

評価ループ - メモリ不足（OOM）やクラッシュ

OOM が発生する一般的な原因はバッチサイズを高く設定しすぎていることです。VRAM を節約するには 2 未満に設定してください。また fp16_full_eval=True を使用して評価に float16 を使うとメモリが半分になります。

まずトレーニングデータセットをトレインとテストに分割してください。評価のためにトレーナー設定を以下のようにします:

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 マシン用です。デフォルトでは Unsloth は 2025 年 6 月以降これらのフラグをデフォルトで設定しているはずです。

早期終了（Early Stopping）はどう行いますか？

評価損失が減少しないためにファインチューニング／トレーニングを停止したい場合、トレーニングプロセスを停止する早期停止（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,       # 早期終了には必ず使用すること
        metric_for_best_model = "eval_loss", # 早期終了に用いる指標
        greater_is_better = False,           # 評価損失が低いほど良い
    ),
    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,     # 評価損失が減少しない場合に待つステップ数
                                     # 例えば損失が増加することもあるが、3ステップ後に減少するかもしれない
    early_stopping_threshold = 0.0,  # より高く設定可能 - どれだけ損失が減少すれば
                                     # 早期終了とみなすかを設定します。例えば0.01は損失が
                                     # 0.02から0.01になった場合に実行を早期終了することを意味します。
)
trainer.add_callback(early_stopping_callback)

その後、通常どおり次でモデルを訓練します trainer.train() 。

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

モデルのダウンロードが 90〜95% で長時間止まる場合、一部の高速ダウンロードプロセスを無効にして同期ダウンロードに強制し、より多くのエラーメッセージを出力させることができます。

単純に次を使用してください UNSLOTH_STABLE_DOWNLOADS=1 を Unsloth のインポートより前に設定してください。

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

from unsloth import FastLanguageModel

RuntimeError: CUDA error: device-side assert triggered

再起動してすべて実行し直してください。ただし Unsloth のインポートより前にこれを置いてください。また、できるだけ早くバグレポートを提出してください、ありがとうございます！

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 の引用（Citing 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}}
}