怎麼用 Unsloth 跑與微調 LLM

這篇教你用 Unsloth 在本機載入 LLM，完成 LoRA 微調前置設定，並跑通一次最小訓練驗證。

這篇給想把模型下載、推理、微調串成一條本機流程的開發者看。照做完，你會拿到一套可重複使用的 Unsloth 環境、可成功載入的模型，以及一個能直接延伸到正式訓練的工作流。

如果你常在不同模型家族之間切換，這份指南也會幫你先確認環境、再選對教程、最後用一次短訓練檢查把風險壓到最低。

開始之前

• Python 3.10 或 Python 3.11
• pip 24+
• Node 不需要；需要的是可用的 NVIDIA GPU 與對應 CUDA 驅動，或 Unsloth 支援的本機執行環境
• Hugging Face 帳號
• Hugging Face access token
• Git 已安裝
• 系統記憶體至少 16 GB
• GPU 記憶體足以容納你要載入的模型

Step 1: 建立 Unsloth 虛擬環境

目的：先隔離套件版本，避免 Python 依賴互相污染，讓後續載入模型時更穩定。

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install unsloth

驗收：你應該看到 Unsloth 安裝完成，且執行 python -c "import unsloth; print('ok')" 會輸出 ok。

Step 2: 登入 Hugging Face

目的：先完成授權，才能下載受限模型與 Unsloth 教程中引用的 checkpoint。

huggingface-cli login

驗收：你應該看到登入成功的提示，並且本機已保存 token，可用來後續拉取模型。

Step 3: 打開對應模型教程

目的：先選對模型家族，再決定推理或微調路線，避免把不同 checkpoint 的設定混在一起。

先從 Unsloth LLM Tutorials 入口開始，再打開你要用的模型家族頁面；原始碼與範例也可參考 Unsloth GitHub repo。每個教程都會標明模型名稱、載入方式與適合的微調步驟。

驗收：你應該看到的是具體模型頁面，而不是泛用首頁，且頁面名稱要和你準備使用的 checkpoint 家族一致。

Step 4: 載入本機推理模型

目的：先確認模型能在你的機器上成功下載與初始化，再進入訓練，避免把時間花在錯誤環境上。

from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/Qwen3-8B",
    max_seq_length = 2048,
    load_in_4bit = True,
)

驗收：你應該看到模型與 tokenizer 成功載入，且過程沒有 out-of-memory 錯誤。若載入失敗，先改小 checkpoint，再調低 max_seq_length。

Step 5: 轉成可訓練的 LoRA 模型

目的：把已載入的基礎模型包成可微調狀態，讓你能用較少參數完成適配。

model = FastLanguageModel.get_peft_model(
    model,
    r = 16,
    target_modules = ["q_proj", "k_proj", "v_proj", "o_proj"],
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    use_gradient_checkpointing = "unsloth",
    random_state = 3407,
)

驗收：你應該看到 LoRA adapters 已掛到模型上，而且可訓練參數數量會明顯小於原始模型。

Step 6: 跑一次短訓練檢查

目的：在正式訓練前先做最小可行驗證，確認資料管線、訓練迴圈與儲存流程都正常。

# 簡化的 smoke test
# trainer.train()
# trainer.save_model("./unsloth-checkpoint")

驗收：你應該看到至少一個訓練步驟完成，並且產生一個 checkpoint 資料夾。若失敗，先檢查 batch size、context length 與 GPU 記憶體。

常見錯誤

• 模型太大，GPU 記憶體不夠。修法：改用較小 checkpoint、開啟 4-bit 載入，或降低 max_seq_length。
• 還沒登入 Hugging Face 就開始下載。修法：先執行 huggingface-cli login，再確認 token 已保存。
• 把不同模型家族的教程混著用。修法：回到 Unsloth 教程索引，改跟同一個 checkpoint 家族的頁面走。

接下來可以看什麼

當本機載入與短訓練都成功後，下一步就去看對應模型的正式 fine-tuning 教程，再接著處理 chat template、資料格式與部署流程，讓這套 Unsloth 工作流可以直接進入應用環境。