> 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-chu/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):
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 など別のフレームワークで実行する際にも必ず使うことが重要です。保存済みモデルから推論する場合は、正しいテンプレートを適用することが非常に大切です。
* 推論エンジンが不要な「start of sequence」トークンを追加している（または逆に必要なものが欠けている）可能性もあるので、両方の可能性を確認してください！
* **チャットテンプレートを強制するには、私たちの対話用ノートブックを使ってください。これでほとんどの問題は解決します。**
* 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 を既定の選択肢にして性能低下を抑えるよう、変換プロセスを積極的に変更しています。
### 評価の方法
学習実行で評価を設定するには、まずデータセットを学習用とテスト用に分割する必要があります。次のことを行ってください。 **データセットの選択は常にシャッフルしてください**。そうしないと評価が正しくなくなります！
```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 に分割してください。評価用にトレーナー設定を次のようにします:
```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が減少しない場合に待機するステップ数
# たとえば、損失はいったん増加しても、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 より前に設定してください。
```python
import os
os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1"
from unsloth import FastLanguageModel
```
### RuntimeError: CUDA エラー: device-side assert が発生しました
再起動してすべて実行してください。ただし、どの 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: UTF-8 ロケールが必要です。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
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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://unsloth.ai/docs/jp/ji-chu/troubleshooting-and-faqs.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.