> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/jp/ji-ben/troubleshooting-and-faqs.md).

# トラブルシューティング＆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):

<pre class="language-python" data-expandable="true"><code class="lang-python">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,
    <a data-footnote-ref href="#user-content-fn-1">trust_remote_code = True</a>, # 新しいモデルをサポートするために有効化
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # 長いコンテキストには True または "unsloth"
)
</code></pre>

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

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

* になる、という問題に遭遇することがあります。このエラーの最も一般的な原因は、 <mark style="background-color:blue;">**誤ったチャットテンプレート**</mark>**.** を使っていることです。Unsloth でモデルを学習したときと、後で llama.cpp や Ollama など別のフレームワークで実行するときに、同じチャットテンプレートを使うことが不可欠です。保存済みモデルから推論する際は、正しいテンプレートを適用することが重要です。
* また、推論エンジンが不要な「シーケンス開始」トークンを追加している（あるいは逆に必要なものが欠けている）可能性もあります。どちらの仮説も確認してください！
* <mark style="background-color:green;">**チャットテンプレートを強制するには、私たちの会話用ノートブックを使ってください。これでほとんどの問題は解決します。**</mark>
  * 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)`です。これを 0.5 などに下げると、GPU ピークメモリの 50% を使用するようになります。これにより、保存中の 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 にして性能低下を抑えるよう、変換プロセスを積極的に変更しています。

### 評価の方法

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

```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 を使うことで、メモリを半分に削減します。

まず、学習用データセットを 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 を使用できます。次を使用してください。 `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", # 早期終了用に保存されるチェックポイントの保存先
        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 が下がらない場合に待つステップ数
                                     # たとえば損失が増加しても、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 する前に。

```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 = "<start_of_turn>user\n",
    response_part = "<start_of_turn>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: UTF-8 ロケールが必要です。ANSI が指定されました

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

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

```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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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=<question>
```

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.