Unsloth 是一个开源训练库，配有桌面应用和 Web UI（Unsloth Studio）。它通过手写 Triton 内核对 Hugging Face Transformers、PEFT 和 TRL 打补丁，让相同的 LoRA 或 QLoRA 训练占用明显更少显存、完成更快。按官方说明，8B 模型 QLoRA 最低约需 6 GB 显存，14B 约 8.5 GB，70B 约 41 GB；16 位 LoRA 所需显存约为其 3 至 4 倍。
用途与入口
Unsloth 用于对 Llama、Qwen、Gemma 等开放大模型做 LoRA/QLoRA 微调。它有两个代码入口：其一为 Python API（Apache-2.0 核心库），FastLanguageModel.from_pretrained 加载模型（默认 4 位量化），FastLanguageModel.get_peft_model 挂载 LoRA 适配器，再用常规 TRL SFTTrainer 训练；其二为 unsloth CLI（AGPL-3.0，运行 Studio 训练后端），unsloth train 通过命令行参数或 YAML 文件启动训练，unsloth export 将检查点导出为合并权重、GGUF 或 LoRA 适配器。
安装与检查
官方建议在全新虚拟环境中安装，uv 会根据当前 CUDA 驱动选择 PyTorch 版本。仅安装 unsloth 只覆盖 Python API；unsloth train/export/list-checkpoints 命令依赖 Studio 后端（FastAPI、uvicorn、gguf 等），需安装 studio extra：uv venv unsloth_env --python 3.13；source unsloth_env/bin/activate；uv pip install "unsloth[studio]" --torch-backend=auto。若只需 Python API 加 vLLM 服务，可用 uv pip install unsloth vllm --torch-backend=auto。安装后用 unsloth --version 或 unsloth list-checkpoints 验证（全新安装显示 "No checkpoints found."，缺少依赖则提示需要 fastapi）。unsloth[studio] 已包含 Studio Web UI。桌面应用有独立安装程序，详见 https://unsloth.ai/docs。受限或私有模型需 Hugging Face token，可创建读取 token（推送模型需写入 token）并以 HF_TOKEN 环境变量提供。
数据准备与训练
unsloth train 可从 JSONL 文件或 Hub 数据集识别三种布局：chatml（messages 或 conversations 列，含 role/content 轮次）、sharegpt（同列，含 from/value 轮次）、alpaca（instruction、可选 input、output 列）。风格与领域适配通常只需数百到数千条干净样例，质量比数量更重要。CLI 训练示例中，--output-dir 是 Unsloth 自有输出文件夹内的运行名而非当前目录路径，如 outputs/support-llama32 实际落在 ~/.unsloth/studio/outputs/support-llama32（或 $UNSLOTH_STUDIO_HOME/outputs/...）。可先加 --dry-run 预览，再正式训练。dry run 显示的默认值包括：LoRA 训练、load_in_4bit: true、学习率 2e-4、批大小 2、梯度累积 4、max_seq_length 2048。长训练可写入 YAML 文件以保持可复现（命令行参数覆盖 YAML）。--enable-wandb 配合环境变量 WANDB_API_KEY 可将指标发送到 Weights & Biases，--enable-tensorboard 写入 TensorBoard 日志。
Python API 提供完全控制：加载模型与分词器，配置 LoRA 参数（如 r、lora_alpha、lora_dropout=0、target_modules、use_gradient_checkpointing="unsloth"），用 get_chat_template 设置对话模板（支持 llama-3.1、qwen3、gemma-3、mistral、phi-4、chatml 等），将数据集映射为 text 字段，再用 SFTTrainer 训练；train_on_responses_only 可让损失只计算助手回复部分。
测试、保存与导出
训练后可用 FastLanguageModel.for_inference 做推理测试。保存方式包括：save_pretrained 仅保存适配器（数十 MB）；save_pretrained_merged 保存合并的 16 位权重（供 vllm serve 使用；文档不建议 merged_4bit，除非显式传 merged_4bit_forced）；save_pretrained_gguf 导出 GGUF（quantization_method 可选 q4_k_m、q8_0、q5_k_m、f16、bf16 或列表），若模板已知会同时生成 Ollama Modelfile。首次 GGUF 导出会克隆并构建 llama.cpp，需要 git、cmake 和 C++ 编译器。CLI 的 unsloth export 可从已保存检查点导出 merged-16bit、merged-4bit、gguf、lora 格式，需传入 list-checkpoints 打印的绝对路径；相对输出目录会创建在 Unsloth 自有导出文件夹下，命令结束打印 Saved to:。可用 --push-to-hub --repo-id ... --private 推送到 Hub。
适用场景与限制
典型场景包括：用少量工单数据在小显存显卡上训练客服模型并导出到 Ollama，或将微调后的模型合并为 16 位权重用 vLLM 提供 OpenAI 兼容 API。官方指南建议：优先使用 unsloth/... 模型上传（含 -bnb-4bit 变体）；训练与推理使用相同对话模板（不匹配是导出 GGUF 或 Ollama 后输出乱码或无限生成的常见原因）；显存不足时先降低批大小并提高梯度累积，再缩短 max_seq_length，最后降低 LoRA rank；学习率默认 2e-4，若损失下降过快且输出开始重复训练数据可降至 1e-4 或 5e-5；通常训练 1 至 3 轮，更多易过拟合；导出前用留出提示评估。密钥应放在环境变量中而非 YAML 或 notebook；Studio 的 --password 会在进程列表中可见，应改用 UNSLOTH_STUDIO_PASSWORD；Studio 默认运行服务端工具（网页搜索、代码执行），应保持在 127.0.0.1，或用 --disable-tools 后再以 --secure 或 -H 0.0.0.0 暴露。许可方面，Python API（FastLanguageModel、save_* 函数）为 Apache-2.0，unsloth CLI 命令和 Unsloth Studio 为 AGPL-3.0，将 CLI 或 Studio 打包进产品前需确认；基础模型自身许可证（如 Llama、Gemma）仍适用于微调结果。不适用情形：LoRA/QLoRA/DoRA 以外的 PEFT 方法（IA3、prefix tuning）或自定义 Transformers 训练循环应使用普通 PEFT；Unsloth 面向单节点训练，大规模多节点预训练应选择相应框架；若修改提示词或检索（RAG）即可解决问题，应先尝试这些方法再微调。Unsloth 发布频繁且对 transformers 和 trl 版本范围限制较窄，应在 requirements.txt 中固定版本以保证可复现。