Unsloth LoRA 训练
在本地GPU上使用Unsloth对聊天格式数据集进行LoRA训练，并将结果导出为GGUF。数据集由用户提供（生成数据集是具体问题相关的）；该技能从train.jsonl和val.jsonl开始。模型服务是一个单独的步骤：该技能生成的运行文件夹（GGUF文件加run.json）会被类似ollama-model的服务技能所使用。
通过启动器运行每个脚本，使用Bash工具：${CLAUDE_SKILL_DIR}/scripts/run <script.py> [args]。该技能只允许该确切命令，因此它在自动模式下运行；以其他方式调用脚本将被拒绝。如果用户发送新消息后启动器命令被拒绝，请重新调用此技能。启动器运行check_data.py（使用任何Python 3环境），以及preflight.py、train.py和export_gguf.py（使用Unsloth环境的Python），在其--out/--run文件夹的父目录中执行（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）会在每个训练的答案前放置一个空的
思考 响应块：告知用户应用程序会在答案中收到它，并且需要将其剥离。
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位模型（数GB，--keep-merged会保留它，此时GGUF会留在<run>/gguf_gguf/文件夹）以及Unsloth写在GGUF旁边的Modelfile：该文件使用了标准模板，而非训练时使用的布局，因此不要按照Unsloth的提示使用ollama create从它创建。每次导出都会出现关于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组合非常脆弱。
- 在删除运行文件夹或检查点之前，先征求用户许可。