Unsloth LoRA 訓練
在本地 GPU 上使用 Unsloth 對聊天格式資料集訓練 LoRA，並將結果匯出為 GGUF。資料集來自使用者（產生資料集取決於具體問題）；此技能從 train.jsonl 和 val.jsonl 開始。服務模型是另一個步驟：此技能留下的執行資料夾（GGUF 加上 run.json）是像 ollama-model 這樣的服務技能所需的輸入。
每個腳本都透過啟動器執行，使用 Bash 工具：${CLAUDE_SKILL_DIR}/scripts/run <script.py> [args]。此技能僅允許該確切指令，因此它會以自動模式執行；以其他方式呼叫腳本將會被拒絕。如果使用者在發送新訊息後啟動器指令被拒絕，請再次呼叫此技能。啟動器使用任何 Python 3 執行 check_data.py，並使用 Unsloth 環境的 Python 在其 --out/--run 資料夾的上層資料夾中執行 preflight.py、train.py 和 export_gguf.py（Unsloth 會在當前目錄寫入一個 unsloth_compiled_cache/ 資料夾）。所有路徑都請使用絕對路徑：指令不共享工作目錄。
開始之前，請先確認
- 資料集資料夾，以及稍後用於比較模型的評估集：評估集不得包含在訓練資料中。如果沒有評估集，建議在訓練前保留一些範例作為評估集。
- 基礎模型，以 Unsloth 4-bit 名稱表示（例如
unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit）。多個基礎模型意味著每個模型一個執行資料夾，並依序執行相同的步驟（參閱references/base-models.md）。 - 機器：訓練需要 CUDA GPU 和 Unsloth 環境的 Python。如果未設定
UNSLOTH_PYTHON且~/.config/llm-finetune/unsloth-python不存在，請向使用者詢問該 Python 的路徑，並在使用者同意的情況下將該路徑寫入該檔案的第一行：啟動器會從那裡讀取。 - 執行資料夾，用於存放執行資料夾，應位於任何 git 倉庫之外。下面的
<runs>是其絕對路徑。
步驟
1. 檢查資料
${CLAUDE_SKILL_DIR}/scripts/run check_data.py <data> --eval <eval.jsonl>
必須輸出 ok。它會檢查損毀的行、不以助理回答結尾的對話，以及與訓練集中相同或不同答案的驗證或評估提示：模型已經看過這些資料，因此它們衡量的是召回率。修復方法是將它們從驗證或評估集中移除（或修正資料分割方式），絕對不要為了通過檢查而更改訓練資料。它還會報告系統訊息的使用情況：無、共用一個或混合使用（參閱 references/chat-formats.md）。
2. 機器預檢
${CLAUDE_SKILL_DIR}/scripts/run preflight.py --params-b <十億參數> --out <runs>/<run>
可用的 GPU 記憶體比總記憶體更重要：遊戲、啟用 GPU 加速的瀏覽器，或本地伺服器仍在載入的模型（ollama ps，使用 ollama stop <model> 卸載）都可能導致可用記憶體過少。如果預檢列出其他 GPU 使用者，請告知使用者並讓他們決定，不要殺死程序。使用 --params-b 可以估算需求（一個 3B 模型，4-bit，序列長度 1024，批次大小 4，峰值記憶體為 6.6 GiB；7B 模型則為 8.1 GiB），當可用記憶體不足時，它會建議使用的 --batch-size/--grad-accum 組合。這只是一個基於兩次執行的估算：對於其他大小或序列長度，請傳遞 --need-gib 並觀察煙霧測試報告的峰值記憶體。
如果匯入失敗，表示環境已損壞，請在重新安裝任何東西之前參閱 references/troubleshooting.md。
3. 煙霧測試
${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>-smoke --max-steps 2
請閱讀輸出，而不僅僅是檢查退出碼：
- 第一個範例的呈現方式：頂部的系統提示行是模型將學習期望的內容，
- 接收損失的 token：僅限答案，而非問題，
- token 長度：截斷警告意味著需要增加
--max-seq-length或刪除範例， - 伺服器必須發送的系統回合，以及關於它的警告。思考模板（Qwen3、Qwen3.5）會在每個訓練過的答案前面放置一個空的
thinking response區塊：告知使用者應用程式會在答案中收到它，並且必須將其移除。
4. 完整訓練
${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>
會執行一段時間（對於 3B 模型，數千個範例需要幾分鐘；7B 模型則更久）。使用 Bash 工具的後台選項啟動它，而不是保持會話開啟（工具會將輸出保存在檔案中，這就是日誌：請勿在指令中添加 >、; 或 &&，預先核准的範圍僅涵蓋完全如圖所示的啟動器指令），並使用 ${CLAUDE_SKILL_DIR}/scripts/run train_status.py <runs>/<run> 檢查其狀態：步驟、損失、最低驗證損失的步驟以及預計剩餘時間（截至上次檢查點）。崩潰後可使用 --resume 恢復。報告訓練和驗證損失以及 GPU 記憶體峰值。驗證損失遠高於訓練損失表示過擬合：減少訓練輪數或增加資料量。
5. 匯出
${CLAUDE_SKILL_DIR}/scripts/run export_gguf.py --run <runs>/<run>
需要幾分鐘（3B 模型）到十幾分鐘（7B 模型）（合併、轉換、量化），這比 Bash 工具允許前景指令執行的時間更長：請像訓練一樣在後台啟動它並等待其完成。它會將 GGUF 寫入 <run>/gguf/，並將其大小和校驗碼記錄在 run.json 中。它會移除合併後的 16-bit 模型（數 GB，使用 --keep-merged 可保留它，此時 GGUF 會留在 <run>/gguf_gguf/ 中）以及 Unsloth 寫在 GGUF 旁邊的 Modelfile：該 Modelfile 使用的是標準模板，而非訓練時使用的佈局，因此請不要依照 Unsloth 的提示使用 ollama create 從該 Modelfile 建立模型。每次匯出都會預期看到關於 llama.cpp 轉換器的 [CRITICAL] 警告；請告知使用者其含義（參閱 references/troubleshooting.md），它不會阻止匯出。執行資料夾現在已準備好進行服務：繼續使用 ollama-model 技能，或將 run.json 的 chat 部分交給任何服務模型的程式（參閱 references/run-json.md）。
6. 清理（先詢問）
模型匯出並評估完成後，建議刪除僅用於恢復或檢查設定的檔案：<run>/checkpoints/（用於 --resume，7B 模型約數 GB）和 <run>-smoke 資料夾。說明每個檔案佔用的空間大小，並僅刪除使用者同意的部分。保留 adapter/ 和 run.json：它們很小，且是新的匯出和發行說明所需的。
規則
- 絕對不要為了讓評估結果更好看而更改資料集，也絕對不要在訓練資料上進行評估。
- 未經詢問，請勿在 Unsloth 環境中安裝或升級套件：其 torch/CUDA 組合很脆弱。
- 刪除執行資料夾或檢查點之前務必先詢問使用者。