# トラブルシューティングとFAQ バージョンや依存関係でまだ問題が発生している場合は、ぜひ私たちの [Docker イメージ](/docs/jp/meru/install/docker.md) を使用してください。必要なものがすべて事前インストールされています。 {% hint style="success" %} **問題を見つけたら、Unslothは常に更新するようにしてください。** `pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo` {% endhint %} ### Unslothでまだサポートされていない新しいモデルをファインチューニングしますか？ Unslothは、 `transformers`でサポートされている任意のモデルで動作します。モデルが私たちのアップロードに含まれていない、またはそのままでは動作しない場合でも、通常はまだサポートされています。最近のモデルの一部は、私たちの最適化の都合で少し手動調整が必要なだけかもしれません。 多くの場合、次を設定することで互換性を有効にできます。 `trust_remote_code=True` をファインチューニングスクリプトに追加してください。以下は [DeepSeek-OCR](/docs/jp/moderu/tutorials/deepseek-ocr-how-to-run-and-fine-tune.md): 
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で開く**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_\(14B\)-Reasoning-Conversational.ipynb) * Gemma-3 4B 会話用ノートブック [**Colabで開く**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3_\(4B\).ipynb) * Llama-3.2 3B 会話用ノートブック [**Colabで開く**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Llama3.2_\(1B_and_3B\)-Conversational.ipynb) * Phi-4 14B 会話用ノートブック [**Colabで開く**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Phi_4-Conversational.ipynb) * Mistral v0.3 7B 会話用ノートブック [**Colabで開く**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Mistral_v0.3_\(7B\)-Conversational.ipynb) * **さらに多くのノートブックは** [**ノートブックのドキュメントにあります**](/docs/jp/meru/unsloth-notebooks.md) ### GGUF / vLLM 16bit への保存がクラッシュする 次を変更して、保存時のGPU使用量の上限を下げてみてください。 `maximum_memory_usage`. デフォルトは `model.save_pretrained(..., maximum_memory_usage = 0.75)`です。50%のGPUピークメモリを使うには0.5などに下げてください。これにより保存時のOOMクラッシュを減らせます。 ### GGUFへ手動で保存するには？ まず次の方法でモデルを16bitとして保存します。 ```python model.save_pretrained_merged("merged_model", tokenizer, save_method = "merged_16bit",) ``` 以下のようにしてllama.cppをソースからコンパイルします。 ```bash 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として保存します。 ```bash python llama.cpp/convert_hf_to_gguf.py merged_model \ --outfile model-F16.gguf --outtype f16 \ --split-max-size 50G ``` ```bash # 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をデフォルトにして性能低下を減らすよう、変換プロセスを積極的に変更しています。 ### 評価のやり方 学習実行で評価を設定するには、まずデータセットを学習用とテスト用に分割する必要があります。必ず **データセットの選択をシャッフルする**必要があります。そうしないと評価が正しくありません！ ```python 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行程度に減らしてみてください。 ```python 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を使ってメモリを1/2に削減します。 まず学習データセットをtrainとtestに分割します。評価用のtrainer設定を次のようにします。 ```python 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のやり方は？ 評価損失が減少しないのでファインチューニング / 学習を停止したい場合は、学習プロセスを止めるEarly Stoppingを使えます。次を使用してください。 `EarlyStoppingCallback`. いつものようにtrainerと評価データセットを設定してください。以下は、 `eval_loss` （評価損失）が3ステップ程度経っても減少しない場合に学習を停止するために使います。 ```python 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", # Early Stopping用の保存済みチェックポイントの場所 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"], ) ``` 次に、カスタマイズ可能なコールバックを追加します。 ```python from transformers import EarlyStoppingCallback early_stopping_callback = EarlyStoppingCallback( early_stopping_patience = 3, # eval lossが減らない場合に待つステップ数 # たとえばlossが増えても、3ステップ後に減少するかもしれません early_stopping_threshold = 0.0, # もっと高く設定可能 - それまでにどれだけlossが減少すべきかを設定 # ここでEarly Stoppingとみなします。たとえば0.01なら、lossが # 0.02から0.01になったら、実行を早期停止するとみなします。 ) trainer.add_callback(early_stopping_callback) ``` その後、通常どおり次でモデルを学習します。 `trainer.train() .` ### ダウンロードが90〜95%で止まる モデルが90〜95%で長時間止まる場合は、いくつかの高速ダウンロード処理を無効にして、ダウンロードを同期的にし、より多くのエラーメッセージを出力するようにできます。 単に次を使ってください。 `UNSLOTH_STABLE_DOWNLOADS=1` を、どのUnslothのimportよりも前に設定します。 ```python import os os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1" from unsloth import FastLanguageModel ``` ### RuntimeError: CUDA error: device-side assert triggered 再起動してすべて実行し直してください。ただし、これをUnslothのimportより前の先頭に置いてください。また、できるだけ早くバグ報告もお願いします、ありがとうございます！ ```python 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ハイパーパラメータガイド**](/docs/jp/meru/fine-tuning-llms-guide/lora-hyperparameters-guide.md) 詳細について。 Llama 3.1、3.2、3.3系のモデルでは、以下を使用してください。 ```python 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系のモデルでは、以下を使用してください。 ```python from unsloth.chat_templates import train_on_responses_only trainer = train_on_responses_only( trainer, instruction_part = "user\n", response_part = "model\n", ) ``` ### Unslothは期待より遅いですか？ 最初は速度が遅く見える場合、たぶん原因は `torch.compile` がウォームアップしてコンパイルを完了するのに通常約5分（またはそれ以上）かかるためです。スループットは **後に** 完全に読み込まれてから測定してください。長めの実行では、Unslothはずっと速くなるはずです。 無効化するには次を使ってください。 ```python 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: A UTF-8 locale is required. Got ANSI を参照してください 新しいセルで、以下を実行してください。 ```python 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}} } ``` [^1]: このコード行を有効にして、動作するか確認してください。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://unsloth.ai/docs/jp/ji-ben/troubleshooting-and-faqs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.