AI 模型微调（LoRA / QLoRA）¶

类比：
- 预训练 = 大学本科通识教育（学了很多但不精）
- 微调 = 研究生专业训练（在某个方向上变得很强）
- 推理 = 毕业后上班干活

原来的做法（全量微调）：
  W_new = W_old + ΔW       # 更新整个权重矩阵，ΔW 和 W 一样大

LoRA 的做法：
  W_new = W_old + B × A    # ΔW ≈ B × A，用两个小矩阵的乘积来近似 ΔW

其中：
  W_old: 原始权重矩阵，形状 [d × d]，比如 [4096 × 4096]
  B: 降维矩阵，形状 [d × r]，比如 [4096 × 16]
  A: 升维矩阵，形状 [r × d]，比如 [16 × 4096]
  r: 秩（rank），通常 4-64，远小于 d

训练时：
┌─────────────┐
│  输入 x      │
└──────┬──────┘
       │
       ├──────────── 冻结路径（不训练）──→ W_old × x
       │
       └──────────── LoRA路径（训练）──→ B × (A × x)
                                              │
                                    两路结果相加 ←┘
                                              │
                                         输出 y

类比：
- 全量微调 = 搬一整个图书馆进你家来改书（需要大别墅）
- LoRA = 图书馆不动，只带笔记本回家写笔记（需要正常房子）
- QLoRA = 把图书馆的书先压缩成缩微胶片再搬回家 + 写笔记（小公寓就够了）

# 创建 conda 环境
conda create -n finetune python=3.11 -y
conda activate finetune

# 安装核心包（PEFT 最新版 0.19.1，2026年4月）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install transformers==4.48.0    # HuggingFace 模型库
pip install peft==0.19.1            # 参数高效微调库
pip install datasets==3.3.0         # 数据集加载库
pip install bitsandbytes==0.49.2    # 量化支持（QLoRA必需）
pip install accelerate==1.5.0       # 分布式训练
pip install trl==0.17.0             # 训练器（SFTTrainer）

"""
LoRA微调文本分类模型 —— 完整示例
任务：微调 BERT 做情感分类（正面/负面）
"""

import torch
from datasets import load_dataset
from transformers import (
    AutoTokenizer,              # 自动加载分词器
    AutoModelForSequenceClassification,  # 文本分类模型
    TrainingArguments,          # 训练参数配置
    Trainer,                    # 训练器
    DataCollatorWithPadding,    # 数据填充器
)
from peft import (
    LoraConfig,                 # LoRA 配置
    get_peft_model,             # 给模型加上 LoRA
    TaskType,                   # 任务类型枚举
)
import numpy as np
from sklearn.metrics import accuracy_score  # 评估指标

# ============ 1. 加载数据集 ============
# imdb 数据集：25000条电影评论，二分类（正面/负面）
dataset = load_dataset("imdb")
# dataset["train"] 有 25000 条
# dataset["test"] 有 25000 条

# 只取子集加速演示（实际项目用全部数据）
train_data = dataset["train"].shuffle(seed=42).select(range(2000))  # 取2000条训练
eval_data = dataset["test"].shuffle(seed=42).select(range(500))     # 取500条验证

# ============ 2. 加载模型和分词器 ============
model_name = "bert-base-uncased"  # BERT基础模型，110M参数
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 加载分类模型（2分类：正面/负面）
model = AutoModelForSequenceClassification.from_pretrained(
    model_name,
    num_labels=2,                # 二分类
    torch_dtype=torch.float32,   # CPU用float32，GPU可用float16
)

# ============ 3. 配置 LoRA ============
lora_config = LoraConfig(
    r=8,                           # 秩=8，平衡效果和效率
    lora_alpha=16,                 # 缩放因子，通常 = 2×r
    target_modules=["query", "value"],  # BERT 的 attention 层
    lora_dropout=0.05,             # 5% dropout 防过拟合
    bias="none",                   # 不训练 bias
    task_type=TaskType.SEQ_CLS,    # 任务类型：序列分类
)

# 给模型套上 LoRA "外壳"
model = get_peft_model(model, lora_config)

# 打印可训练参数量
model.print_trainable_parameters()
# 输出类似：trainable params: 296,450 || all params: 109,783,810 || trainable%: 0.2701%
# → 只训练 0.27% 的参数！

# ============ 4. 数据预处理 ============
def tokenize_function(examples):
    """分词：把文本转成模型能理解的数字序列"""
    return tokenizer(
        examples["text"],
        truncation=True,       # 超长文本截断
        max_length=256,        # 最大256个token（节省显存）
        padding=False,         # 后面统一padding
    )

# 对训练集和验证集分词
train_tokenized = train_data.map(tokenize_function, batched=True)
eval_tokenized = eval_data.map(tokenize_function, batched=True)

# 移除不需要的列，只保留 input_ids, attention_mask, label
train_tokenized = train_tokenized.remove_columns(["text"])
eval_tokenized = eval_tokenized.remove_columns(["text"])

# ============ 5. 定义评估指标 ============
def compute_metrics(eval_pred):
    """计算准确率"""
    predictions, labels = eval_pred
    predictions = np.argmax(predictions, axis=-1)  # 取概率最大的类别
    return {"accuracy": accuracy_score(labels, predictions)}

# ============ 6. 训练配置 ============
training_args = TrainingArguments(
    output_dir="./lora_imdb_output",    # 模型输出目录
    num_train_epochs=3,                  # 训练3轮
    per_device_train_batch_size=16,      # 每张卡 batch=16
    per_device_eval_batch_size=32,       # 验证 batch=32
    learning_rate=2e-4,                  # LoRA通常用较大学习率
    weight_decay=0.01,                   # L2正则化
    eval_strategy="epoch",               # 每轮结束评估一次
    save_strategy="epoch",               # 每轮保存一次
    load_best_model_at_end=True,         # 训练结束加载最佳模型
    logging_steps=50,                    # 每50步打印日志
    fp16=torch.cuda.is_available(),      # 有GPU就用半精度
)

# ============ 7. 开始训练 ============
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_tokenized,
    eval_dataset=eval_tokenized,
    data_collator=DataCollatorWithPadding(tokenizer),
    compute_metrics=compute_metrics,
)

# 启动训练！
trainer.train()

# ============ 8. 保存 LoRA 权重 ============
# 只保存 LoRA 部分（很小，约1-2MB）
model.save_pretrained("./lora_imdb_adapter")
tokenizer.save_pretrained("./lora_imdb_adapter")
print("LoRA adapter 已保存！大小约 1-2MB")

# ============ 9. 加载和推理 ============
from peft import PeftModel

# 重新加载基础模型
base_model = AutoModelForSequenceClassification.from_pretrained(
    model_name, num_labels=2
)
# 加载 LoRA adapter
model_with_lora = PeftModel.from_pretrained(base_model, "./lora_imdb_adapter")
model_with_lora.eval()

# 推理示例
text = "This movie is absolutely fantastic! Great acting and storyline."
inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=256)
with torch.no_grad():
    outputs = model_with_lora(**inputs)
    prediction = torch.argmax(outputs.logits, dim=-1).item()
    print(f"预测结果: {'正面' if prediction == 1 else '负面'}")

"""
QLoRA 微调 7B 大模型 —— 8GB显存可运行
"""

import torch
from transformers import (
    AutoTokenizer,
    AutoModelForCausalLM,       # 因果语言模型（生成式）
    BitsAndBytesConfig,         # 量化配置
    TrainingArguments,
)
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
from trl import SFTTrainer      # 监督微调训练器
from datasets import load_dataset

# ============ 1. 4bit 量化配置 ============
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,                    # 加载为4bit（核心！）
    bnb_4bit_quant_type="nf4",            # NF4量化格式（QLoRA论文推荐）
    bnb_4bit_compute_dtype=torch.float16, # 计算时用FP16（速度和精度平衡）
    bnb_4bit_use_double_quant=True,       # 双重量化（再省~0.4GB/billion参数）
)

# ============ 2. 加载量化模型 ============
model_id = "meta-llama/Llama-2-7b-hf"  # 7B 参数模型
# 也可以用：Qwen/Qwen2.5-7B-Instruct、mistralai/Mistral-7B-v0.3

tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token  # 设置pad token

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=bnb_config,   # 应用4bit量化
    device_map="auto",                 # 自动分配到GPU
    trust_remote_code=True,
)

# 准备模型用于 k-bit 训练（冻结量化层，设置梯度）
model = prepare_model_for_kbit_training(model)

# ============ 3. LoRA 配置 ============
lora_config = LoraConfig(
    r=16,                               # QLoRA 推荐用稍大的 r
    lora_alpha=32,                      # alpha = 2×r
    target_modules=[                    # Llama 的目标层
        "q_proj", "k_proj", "v_proj", "o_proj",  # attention 层
        "gate_proj", "up_proj", "down_proj",      # FFN 层（可选，效果更好）
    ],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",              # 因果语言模型
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# → trainable params: ~40M || all params: ~7B || trainable%: 0.57%

# ============ 4. 训练 ============
training_args = TrainingArguments(
    output_dir="./qlora_output",
    num_train_epochs=1,
    per_device_train_batch_size=4,       # 4bit下4可以跑
    gradient_accumulation_steps=4,       # 等效 batch_size = 4×4 = 16
    learning_rate=2e-4,
    optim="paged_adamw_8bit",            # 分页优化器（QLoRA特色）
    fp16=True,
    logging_steps=10,
    save_strategy="steps",
    save_steps=100,
    warmup_ratio=0.03,                   # 3% warmup
    max_grad_norm=0.3,                   # 梯度裁剪
)

# 使用 SFTTrainer（更简洁的微调训练器）
trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=dataset["train"],
    peft_config=lora_config,
    max_seq_length=512,                  # 最大序列长度
    tokenizer=tokenizer,
)

trainer.train()
model.save_pretrained("./qlora_adapter")

[
  {
    "instruction": "解释什么是宏基因组",
    "input": "",
    "output": "宏基因组（Metagenomics）是直接从环境样本中提取所有微生物的DNA进行测序和分析的方法，不需要单独培养每种微生物。"
  },
  {
    "instruction": "根据以下基因功能描述，预测它属于哪个KEGG通路",
    "input": "该基因编码一种短链脂肪酸转运蛋白，主要在肠道上皮细胞中表达",
    "output": "该基因最可能属于 ko00650（丁酸代谢通路）或 ko04978（矿物质吸收通路）。短链脂肪酸转运蛋白参与肠道中丁酸、丙酸等SCFAs的吸收。"
  }
]

[
  {
    "conversations": [
      {"role": "system", "content": "你是一个专业的生物信息学助手。"},
      {"role": "user", "content": "MetaPhlAn4 和 Kraken2 有什么区别？"},
      {"role": "assistant", "content": "MetaPhlAn4 基于标记基因（marker gene）进行物种定量，准确率高但只能识别数据库中的已知物种。Kraken2 基于 k-mer 匹配全基因组，速度极快但可能有更多假阳性。通常两者结合使用效果最佳。"}
    ]
  }
]

# Alpaca 格式的 prompt 模板
ALPACA_TEMPLATE = """Below is an instruction that describes a task. \
Write a response that appropriately completes the request.

### Instruction:
{instruction}

### Input:
{input}

### Response:
{output}"""

# 数据格式化函数
def format_alpaca(example):
    """把 Alpaca JSON 转成模型训练用的纯文本"""
    if example.get("input", ""):
        text = ALPACA_TEMPLATE.format(
            instruction=example["instruction"],
            input=example["input"],
            output=example["output"],
        )
    else:
        text = ALPACA_TEMPLATE.format(
            instruction=example["instruction"],
            input="（无）",
            output=example["output"],
        )
    return {"text": text}

# 应用格式化
from datasets import load_dataset
dataset = load_dataset("json", data_files="my_data.json", split="train")
dataset = dataset.map(format_alpaca)

□ 数据量：指令微调建议 1000-50000 条
□ 去重：确保没有重复样本（用 hash 去重）
□ 长度分布：统计 token 长度，去掉异常短/长的样本
□ 标签平衡：分类任务各类别数量不要差太多（>1:10需过采样）
□ 格式一致：所有样本遵循同一个模板
□ 人工抽检：随机抽 50 条检查质量

# 方法1：一键安装（推荐，macOS/Linux/WSL）
curl -fsSL https://unsloth.ai/install.sh | sh

# 方法2：pip 安装
pip install unsloth

# 方法3：指定 CUDA 版本安装
pip install "unsloth[cu124]"  # CUDA 12.4

"""
用 Unsloth 加速 QLoRA 微调 —— 比原生 HuggingFace 快 2x
"""

from unsloth import FastLanguageModel  # Unsloth 核心
from trl import SFTTrainer
from transformers import TrainingArguments
from datasets import load_dataset

# ============ 1. 加载模型（Unsloth 自动 4bit 量化） ============
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Qwen2.5-7B-Instruct-bnb-4bit",  # 预量化模型（下载更快）
    max_seq_length=2048,       # 最大序列长度
    load_in_4bit=True,         # 4bit 量化
    dtype=None,                # 自动检测（float16/bfloat16）
)

# ============ 2. 添加 LoRA adapter ============
model = FastLanguageModel.get_peft_model(
    model,
    r=16,                      # LoRA 秩
    lora_alpha=16,             # 缩放因子
    lora_dropout=0,            # Unsloth 优化版不需要 dropout
    target_modules=[           # 自动检测目标模块
        "q_proj", "k_proj", "v_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj",
    ],
    use_gradient_checkpointing="unsloth",  # Unsloth 特有优化，省30%显存
)

# ============ 3. 准备数据 ============
dataset = load_dataset("json", data_files="bio_qa_data.json", split="train")

# 定义 prompt 模板
prompt_template = """<|im_start|>system
你是一个专业的生物信息学助手。<|im_end|>
<|im_start|>user
{instruction}<|im_end|>
<|im_start|>assistant
{output}<|im_end|>"""

def format_data(example):
    return {"text": prompt_template.format(
        instruction=example["instruction"],
        output=example["output"],
    )}

dataset = dataset.map(format_data)

# ============ 4. 训练 ============
trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    max_seq_length=2048,
    args=TrainingArguments(
        output_dir="./unsloth_output",
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        num_train_epochs=3,
        learning_rate=2e-4,
        fp16=not torch.cuda.is_bf16_supported(),  # 优先用 bf16
        bf16=torch.cuda.is_bf16_supported(),
        logging_steps=10,
        optim="adamw_8bit",           # 8bit 优化器
        warmup_steps=5,
        save_strategy="epoch",
    ),
)

# 开始训练（比原生快 2x！）
trainer.train()

# ============ 5. 保存和导出 ============
# 保存 LoRA adapter
model.save_pretrained("./bio_qa_lora")

# 导出为 GGUF 格式（可用 Ollama/llama.cpp 运行）
model.save_pretrained_gguf(
    "bio_qa_gguf",
    tokenizer,
    quantization_method="q4_k_m",  # 4bit量化
)
print("模型已导出为 GGUF 格式，可直接用 Ollama 加载！")

"""
案例：微调一个生物信息学QA模型
数据：自制的生信问答数据集
"""

# 示例数据（实际需要 500-5000 条）
bio_qa_data = [
    {
        "instruction": "什么是Shannon多样性指数？",
        "output": "Shannon多样性指数（H'）衡量群落的物种多样性。公式：H' = -Σ(pi × ln(pi))，其中pi是第i个物种的相对丰度。H'越大表示群落多样性越高。通常肠道菌群的H'在2-5之间。"
    },
    {
        "instruction": "解释 LEfSe 分析的原理和用途",
        "output": "LEfSe（Linear discriminant analysis Effect Size）用于发现组间差异生物标志物。步骤：1) Kruskal-Wallis检验找组间差异特征；2) Wilcoxon检验做组内一致性验证；3) LDA评分量化效应大小。LDA>2通常被认为有生物学意义。常用于肠道菌群的差异物种筛选。"
    },
    {
        "instruction": "宏基因组数据中如何判断一个MAG的质量？",
        "output": "MAG质量评估用CheckM2，主要看三个指标：1) Completeness（完整度）>50%为中质量，>90%为高质量；2) Contamination（污染度）<10%为中质量，<5%为高质量；3) N50>10kb表示组装连续性好。MIMAG标准：高质量需要completeness>90%且contamination<5%且有23S+16S+5S+tRNA≥18。"
    },
]

# 保存为JSON文件供训练使用
import json
with open("bio_qa_data.json", "w", encoding="utf-8") as f:
    json.dump(bio_qa_data, f, ensure_ascii=False, indent=2)

"""
案例：微调模型预测蛋白质的GO功能注释
输入：蛋白质序列描述 + 同源信息
输出：预测的GO term 和置信度
"""

protein_data = [
    {
        "instruction": "根据以下蛋白质信息预测其GO功能注释",
        "input": "序列长度：342aa，含有ABC转运蛋白结构域（PF00005），与E.coli MalK蛋白序列相似度68%，在革兰氏阴性菌中高表达",
        "output": "预测GO注释：\n- GO:0005524 ATP binding (MF, 置信度0.95)\n- GO:0042626 ATPase-coupled transmembrane transporter (MF, 置信度0.91)\n- GO:0005886 plasma membrane (CC, 置信度0.87)\n- GO:0055085 transmembrane transport (BP, 置信度0.89)\n推理依据：ABC转运蛋白结构域(PF00005)是典型的ATP结合盒，MalK是麦芽糖ABC转运蛋白的ATP酶亚基。"
    },
    {
        "instruction": "根据以下蛋白质信息预测其GO功能注释",
        "input": "序列长度：189aa，含有CRISPR相关蛋白Cas2结构域（PF09827），在嗜热古菌中发现，与Pyrococcus furiosus Cas2相似度72%",
        "output": "预测GO注释：\n- GO:0004519 endonuclease activity (MF, 置信度0.93)\n- GO:0043571 maintenance of CRISPR repeat elements (BP, 置信度0.96)\n- GO:0003677 DNA binding (MF, 置信度0.85)\n推理依据：Cas2是CRISPR-Cas免疫系统的核心组分，作为核酸内切酶参与spacer获取阶段。"
    },
]

1. 数据收集
   ├── 从文献/数据库提取 Q&A 对
   ├── 用 GPT-4 生成种子数据 + 人工审核
   └── 从 UniProt/KEGG/PubMed 结构化导出

2. 数据格式化
   └── 转为 Alpaca/ShareGPT 格式 JSON

3. 选择基座模型
   ├── 通用问答：Qwen2.5-7B-Instruct
   ├── 生物序列：DNABERT-2、ESM-2
   └── 中文生信：Qwen2.5 / Yi 系列

4. 微调训练
   └── Unsloth + QLoRA，单卡 3-6小时

5. 评估与部署
   ├── 人工评估 + 自动评测（BLEU/Rouge/准确率）
   └── 导出 GGUF → Ollama 本地部署

RuntimeError: CUDA out of memory. Tried to allocate 256.00 MiB

# 方法1：减小 batch_size
per_device_train_batch_size=1  # 改为1
gradient_accumulation_steps=16  # 增加梯度累积补偿

# 方法2：减小序列长度
max_seq_length=256  # 从2048降到256

# 方法3：启用梯度检查点（用时间换显存）
model.gradient_checkpointing_enable()

# 方法4：用QLoRA（4bit）代替LoRA（16bit）

ValueError: Target modules ['q_proj', 'v_proj'] not found in the model

# 先打印模型结构看看实际层名
print(model)
# 或者
for name, module in model.named_modules():
    if "Linear" in str(type(module)):
        print(name)

# BERT 用 "query", "value"
# Llama/Qwen 用 "q_proj", "v_proj", "k_proj", "o_proj"
# GPT-2 用 "c_attn", "c_proj"

RuntimeError: CUDA Setup failed despite GPU being available

# 检查 CUDA 版本
nvidia-smi  # 看右上角 CUDA Version
python -c "import torch; print(torch.version.cuda)"

# 重新安装匹配版本
pip install bitsandbytes --force-reinstall
# 如果还不行，指定版本
pip install bitsandbytes==0.49.2

ValueError: Asking to pad but the tokenizer does not have a padding token

# 方法1：用 eos_token 当 pad_token（最常用）
tokenizer.pad_token = tokenizer.eos_token
model.config.pad_token_id = tokenizer.eos_token_id

# 方法2：添加新的 pad_token
tokenizer.add_special_tokens({"pad_token": "[PAD]"})
model.resize_token_embeddings(len(tokenizer))

输出：the the the the the the...
或：<unk><unk><unk>...

# 降低学习率
learning_rate=1e-5  # 从 2e-4 降到 1e-5

# 减少训练轮次
num_train_epochs=1  # 先只训1轮看效果

# 检查数据格式是否正确（特别是 EOS token）
# 确保每条数据结尾有 EOS
text = text + tokenizer.eos_token

ERROR: Could not find a version that satisfies the requirement unsloth

# Unsloth 要求 Python 3.10+ 和 Linux/WSL
python --version  # 确认 >= 3.10

# 使用官方安装脚本
curl -fsSL https://unsloth.ai/install.sh | sh

# 或者用 conda
conda create -n unsloth python=3.11 pytorch-cuda=12.4 pytorch -c pytorch -c nvidia -y
conda activate unsloth
pip install unsloth

# 安装全家桶
pip install peft transformers trl datasets bitsandbytes accelerate

# 检查GPU显存
nvidia-smi
python -c "import torch; print(torch.cuda.get_device_properties(0).total_mem/1e9, 'GB')"

# 合并LoRA到基础模型（部署用）
python -c "
from peft import PeftModel
from transformers import AutoModelForCausalLM
base = AutoModelForCausalLM.from_pretrained('base_model_path')
model = PeftModel.from_pretrained(base, 'lora_adapter_path')
merged = model.merge_and_unload()  # 合并！
merged.save_pretrained('merged_model_path')
"

全量微调显存 ≈ 模型参数量 × 18 字节（FP16: 参数2B + 梯度2B + 优化器状态12B + 中间值2B）
LoRA (FP16) ≈ 模型参数量 × 2 字节 + LoRA参数 × 18 字节
QLoRA (4bit) ≈ 模型参数量 × 0.5 字节 + LoRA参数 × 18 字节

例子（7B模型）：
- 全量微调：7B × 18 ≈ 126GB（需要多卡）
- LoRA FP16：7B × 2 + 40M × 18 ≈ 14.7GB
- QLoRA 4bit：7B × 0.5 + 40M × 18 ≈ 4.2GB ← 单卡8GB可以！