• add_new_tokens 是 Unsloth 提供的工具函数，主要用于 扩展 tokenizer 和模型的词表。
  • 必须在 LoRA / QLoRA / PEFT 之前调用

model, tokenizer = FastLanguageModel.from_pretrained(...)
from unsloth import add_new_tokens
add_new_tokens(model, tokenizer, new_tokens=["<X>", "<Y>", "<Z>"])
model = FastLanguageModel.get_peft_model(...)

1 主要参数

add_new_tokens(
    model,
    tokenizer,
    new_tokens=["<NEW_TOKEN_1>", "<NEW_TOKEN_2>"],
    special_tokens=True,   # 是否作为特殊 token
    verbose=True           # 是否打印日志
)

在 transformers / Unsloth 的 tokenizer 机制里：

• special tokens（如 <bos>, <eos>, <pad>, <unk>）

  • 默认不在普通文本生成范围里。

  • 在 generate() 的时候，如果 skip_special_tokens=True，解码时会被直接过滤掉。

  • 通常只在 控制任务边界 或 解码时截断 用，不会自然出现在输出里。

• 普通 tokens（非 special）

  • 会作为正常词表的一部分参与预测。

  • 模型有可能生成它们（前提是训练数据里学过这些 token 的用法）。

2 内部流程

• tokenizer.add_tokens(new_tokens, special_tokens=...)

  • 将 token 加入词表

  • 返回实际新增 token 数量

• 模型扩展 embedding 矩阵

  • 复制旧 embedding 权重

  • 为新 token 初始化 embedding（随机 or 其他策略）

  • 同步扩展输入 embedding 和输出 embedding (lm_head)

• 确保新 token 的 embedding 参与训练 (requires_grad=True)。

  • 注：unsloth中，默认旧的embedding是不train的