unsloth FastLanguageModel类主要函数详解,具体作用和参数
FastLanguageModel 是 Unsloth 框架里的一个核心类，用于快速加载、微调和推理大语言模型（LLMs）。
| 功能 | 方法 | 作用说明 |
|---|---|---|
| 加载模型 + tokenizer | from_pretrained(...) | 支持量化模型，快速加载 HF 模型和 tokenizer。 |
| LoRA 微调 | get_peft_model(...) | 在指定层插入 LoRA adapter，实现高效微调。 |
| 推理加速 | for_inference(model) | 合并 LoRA 权重、禁用 dropout，推理速度提升约 2×。 |
| 扩展词表 | add_new_tokens(...) | 向 tokenizer 和 embedding 层添加自定义 token（表情、特殊符号等）。 |
1. FastLanguageModel.from_pretrained(...)
作用：加载预训练的语言模型（支持 4-bit/8-bit 量化），并同时返回 tokenizer。
model, tokenizer = FastLanguageModel.from_pretrained(model_name="unsloth/Meta-Llama-3.1-8B-bnb-4bit", # 模型名称或路径max_seq_length=2048, # 最大序列长度，影响训练/推理dtype=None, # torch 数据类型，如 torch.float16 / bfloat16load_in_4bit=True, # 是否使用 4-bit 量化 (节省显存)trust_remote_code=True # 允许加载带自定义代码的模型
)1.参数:
model_name：HF Hub 模型名称，或本地路径。max_seq_length：输入的最大 token 数，显存与速度都受影响。dtype：控制推理时的精度（float16/bfloat16）。load_in_4bit：是否用 QLoRA 常见的 4bit 量化。trust_remote_code：加载带自定义层的模型时要设为 True。trust_remote_code这个参数其实是 Hugging Face Transformers 里的，不是 Unsloth 独有的。
默认情况下，
from_pretrained只会加载 标准的模型结构（BERT、LLaMA、GPT-2 等官方支持的）。但很多社区模型有自定义模块（比如新的注意力机制、新的层、新的 forward 逻辑）。
如果不开启
trust_remote_code=True，Transformers 会拒绝执行这些自定义代码，以防止执行恶意代码。
开启后，Transformers 才会下载并运行模型作者在 Hugging Face Hub 上附带的 modeling_xxx.py、configuration_xxx.py 等 Python 脚本。
2.from_pretrained 的内部流程
1.下载 / 读取权重
- 如果是
"unsloth/Meta-Llama-3.1-8B-bnb-4bit"这种名字：→ 会从 Hugging Face Hub 拉取权重。
如果是本地路径：
→ 直接从本地pytorch_model.bin/safetensors里加载。
构建模型骨架
调用 HF 的
AutoModelForCausalLM.from_pretrained(...)；如果设置了量化参数，就会替换掉默认的
Linear层为 bitsandbytes 的量化层；加载权重到 GPU（或 CPU）。
应用 Unsloth 优化
替换掉一些计算热点层（attention, norm 等），用更高效的 CUDA kernel；
修改 forward 函数，兼容 LoRA/QLoRA；
预先做一些显存分配优化。
加载 tokenizer
调用
AutoTokenizer.from_pretrained(model_name)；设置
padding_side="right"、truncation=True；把
max_seq_length写入 config。
代码效果：返回一个 HuggingFace transformers.PreTrainedModel 和一个 tokenizer，可以立即进行训练或推理。
2. FastLanguageModel.get_peft_model(...)
作用：调用 get_peft_model → 给模型插入 LoRA 层；
1.参数：
model = FastLanguageModel.get_peft_model(model,r=16, # LoRA rank，控制可训练参数规模lora_alpha=16, # LoRA 缩放因子target_modules=["q_proj","v_proj"], # 需要应用 LoRA 的模块（通常是注意力层的 q/v 投影）lora_dropout=0.05, # dropout 比例bias="none", # LoRA 是否训练 bias (一般设 "none")use_gradient_checkpointing=True, # 是否启用梯度检查点，节省显存random_state=42 # 随机种子，保证可复现
)
r：LoRA 的秩，决定低秩矩阵的大小。越大，可学习的自由度越多。lora_alpha：缩放系数，用来调节 LoRA 贡献的权重：ΔW=α/r A⋅B
例子：
lora_alpha=16（常见默认值），保证更新量适中。
lora_alpha=128，更加强调 LoRA 对原模型的影响，但可能忘记原来的技能。
target_modules：指定在哪些模块插入 LoRA
LLaMA / Mistral:
注意力机制：q_proj, k_proj, v_proj, o_proj
GPT-2: c_attn (这是 q, k, v 合并的一个大矩阵), c_proj (输出投影)
多层感知机 (MLP) 层：有时为了更强的微调能力，也会把 FFN 层的投影矩阵加入。例如，在 QLoRA 中常见：
前馈网络： gate_proj, up_proj, down_proj
target_modules=['q_proj', 'k_proj', 'v_proj', 'o_proj', 'gate_proj', 'up_proj', 'down_proj']这会同时微调注意力层和FFN层，参数量更大，效果可能更好，但也会更耗显存。
lora_dropout：在 LoRA 层引入 dropout，防止过拟合。
在 LoRA 的 A⋅B 输出中随机丢弃部分单元，增加正则化。
bias：在 LoRA 微调过程中如何处理线性层中的偏置项
bias 的可选值"none"：不训练任何 bias（默认，最省显存和参数）。"lora_only"：只训练 LoRA 层里的 bias。"all"：训练所有 bias（模型原本层里的 bias 也会更新）。bias 参数如何选择，取决你是否需要精准度非常高的任务，具体可以看以下例子
1.分类任务 (bias="all" 常见)
例子：情感分类（正面 / 负面）、新闻类别分类（体育 / 财经 / 娱乐）。
原因：
分类任务往往对输出 logits 的“微小偏移”很敏感。
bias 直接控制某一类的“基准倾向”，训练 bias 可以帮助模型更好区分类别。
用 "all" 往往能显著提升分类精度。
2. 风格化任务 (bias="none" 常见)
例子：把普通文本改写成“莎士比亚风格”、生成“古文风格”、改写成“幽默风格”。
原因：
风格迁移本质上依赖上下文模式（attention）而不是单个 bias。
风格特征通常分布在高维 embedding / attention 权重中，
LoRA adapter 就能学到。
bias 并不是关键，所以大多数情况下 "none" 足够。
3. 结构化任务 (bias=可选 lora_only)
例子：
信息抽取（NER：从文本里抽出人名/地名/机构）。
对话槽位填充（slot filling：识别时间、地点、数字）。
原因：
这类任务需要局部 bias 来调整 token 级别的倾向。
不一定需要改动全局 bias，但在 LoRA adapter 层的 bias 可以帮忙。
适合 "lora_only"。
4. 生成任务 (bias="none")
例子：故事生成、代码生成、问答对话。
原因：
生成任务依赖上下文建模，而不是 logits 的整体偏移。
bias 基本没用，还可能增加过拟合风险。
推荐 "none"。
use_gradient_checkpointing：开启梯度检查点，节省显存。
原理：在反向传播时不保存中间激活，而是重新计算，从而减少显存占用。
如何理解get_peft_model
你有一本很厚的字典（大模型权重），但你只需要学习其中几个专业领域的表达方式。
与其把整本字典改写（全量微调），你只是在字典边缘贴了几个便利贴（LoRA 适配器）。
训练时，你只改这些便利贴（更新少量参数），节省时间和精力；
用的时候，你查字典+便利贴，一样能得到新的表达能力。
代码效果：在模型的注意力层插入 LoRA adapter，准备进行 PEFT 微调。
3. FastLanguageModel.for_inference(model)
🔹 作用：把训练好的模型切换到 推理模式，并自动开启 2× 加速。
用法：
FastLanguageModel.for_inference(model)
函数会：
禁用 dropout
合并 LoRA 权重
启用 Unsloth 的推理优化
代码效果：模型进入高效推理状态，内存占用减少，推理速度提升 2 倍左右。
4. add_new_tokens(model, tokenizer, new_tokens=[...])
🔹 作用：给 tokenizer 和模型添加新的 token（比如 <custom>、领域专用符号）。
1.用法：
from unsloth import add_new_tokensmodel, tokenizer = add_new_tokens(model,tokenizer,new_tokens=["<NEW_TOKEN_1>", "<NEW_TOKEN_2>"],special_tokens=True # 是否作为特殊 token 添加
)
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
model | transformers.PreTrainedModel | 需要扩展 token 的模型 | 必填 |
tokenizer | transformers.PreTrainedTokenizer | 模型对应的 tokenizer | 必填 |
new_tokens | List[str] | 要添加的字符串列表，每个元素是一个新 token | 必填 |
special_tokens | bool | 是否将这些 token 作为特殊 token（如 <BOS>、<EOS>），特殊 token 在 tokenizer 内部处理方式略有不同 | True |
verbose | bool | 是否打印添加 token 的数量和新 vocab 大小 | True |
2.add_new_tokens 是 Unsloth 提供的一个工具函数，用于向现有 tokenizer 和模型添加新的 token
目的：当你希望模型理解领域特定的词、符号或特殊标记（例如
<USER>、<SPECIAL_TOKEN>、自定义 emoji 等）时，需要扩展 tokenizer 的词表，并同步扩展模型的 embedding 层。应用场景：
新增特殊符号（对话开始/结束标记、任务标记）
自定义领域词汇（医学、法律、金融术语）
新语言或方言的 token
让模型识别(⁄ ⁄•⁄ω⁄•⁄ ⁄)为害羞的表情
3.底层流程：
Tokenizer 增加 token
tokenizer.add_tokens(new_tokens, special_tokens=special_tokens)new_tokens被加入 tokenizer 的词表返回增加的 token 数量
模型 embedding 层扩张
old_embedding = model.get_input_embeddings() new_embedding = nn.Embedding(old_vocab_size + len(new_tokens), hidden_size) new_embedding.weight.data[:old_vocab_size] = old_embedding.weight.data model.set_input_embeddings(new_embedding)原 embedding 数据保留
新 token 对应 embedding 随机初始化
如果有输出层 tied embedding（输入输出共享），也同步扩张
可训练性
新 embedding 默认参与梯度更新
与 LoRA 或其他 adapter 兼容
⚠️ 注意：要在 调用 LoRA 前 添加，否则新 token 的 embedding 不会被训练到。