scGPT模型微调最佳操作指南

本指南涵盖从数据准备到最终评估的完整闭环，并融入了差分学习率、二阶段冻结、值域裁剪等经过验证的实战要诀，旨在帮助您避开常见陷阱，高效训练出高精度的下游任务模型。

1. 数据准备

此阶段的目的是收集和整理用于模型微调的数据。

• 输入数据格式：
  • 通常以 AnnData 对象 (.h5ad 文件) 形式存在，包含基因表达矩阵、细胞元数据和基因元数据。
  • 也可能是独立的计数矩阵 (cells × genes) 和对应的细胞注释文件。
• 核心数据：
  • 基因表达数据：每个细胞的基因表达水平（原始计数、TPM、FPKM 等）。
  • 细胞标签/目标变量：有监督微调任务（如细胞类型注释）所需标签。例如 adata.obs["celltype"]。其他任务可能需要扰动标签、批次信息或连续表型值。
• 基因词汇表 (Gene Vocabulary)：
  • scGPT 基于特定基因集预训练，请务必获取配套的 vocab.json 文件，微调时数据中的基因必须与此词汇表严格对齐。
• 数据集划分：
  • 将数据划分为训练集、验证集和测试集（常见比例 70/15/15 或 80/10/10）。
  • 划分时需进行分层抽样 (Stratified Sampling)，尤其针对类别不均衡或多批次数据，确保每个子集均能代表原始分布。

2. 数据处理

将原始数据转换为模型可直接输入的格式。此阶段的操作质量直接影响训练稳定性。

• 基因过滤 (Gene Filtering)：
  • 词汇表对齐：仅保留存在于预训练模型基因词汇表中的基因。
  • 低表达过滤：剔除在所有细胞中表达量极低或几乎不表达的基因。
• 细胞过滤 (Cell Filtering)：
  • 低质量细胞：移除表达基因数过少或文库总量过小的细胞。
  • 稀有类型处理：对于分类任务，若某类细胞数量极少，建议合并或剔除，防止模型学习偏颇。
• 数据标准化与归一化 (Normalization)：
  • 进行库大小标准化（如 sc.pp.normalize_total 归一化至每细胞 1e4 计数）。
  • 对标准化后的数据应用对数转换（如 sc.pp.log1p）。
  • ⭐ 关键实战要诀（值域裁剪）：完成 log1p 转换后，强烈建议将表达值裁剪至 [0, 20] 或 [0, 25] 区间（参考预训练数据集的 99.9% 分位数）。此举可防止极端离群值产生巨大梯度，有效避免训练时 Loss 震荡不收敛。
• 输入序列构建 (Tokenization & Formatting)：
  • 基因 ID 映射：利用 GeneVocab 将基因名称映射为整数 ID。
  • 特殊标记：
    • <cls>：通常置于序列开头，其最终的隐藏状态用作细胞表征。
    • <pad>：用于将序列填充至统一长度。
  • ⭐ 关键实战要诀（序列长度取舍）：请勿盲目设定极大的 max_seq_len。建议统计训练集中有效基因数量的 95% 分位数，并将其设为 max_seq_len。过长的填充不仅浪费显存，大量 [PAD] 标记还会稀释注意力机制对有效信息的关注。
  • 填充掩码 (Attention Mask)：生成布尔张量，指示填充位置，确保注意力计算时忽略这些无效位。
• 标签编码 (Label Encoding)：
  • 将文本格式的细胞标签转换为整数索引，用于分类任务。

3. 定义模型与参数

加载预训练模型，调整架构并设置微调策略。这里是决定模型性能上限的核心环节。

• 加载预训练模型：
  • 实例化模型架构（如 scgpt.model.TransformerModel）并加载预训练权重。
• 任务特定头部 (Task-Specific Head)：
  • 技术澄清：模型前向传播后，取出序列首位（即 [CLS] 对应的输出向量），其形状为 (batch_size, hidden_size)。
  • 分类任务：将该向量输入新增的线性层 (nn.Linear)，映射至类别数量。
  • 回归/其他任务：设计相应层数的 MLP 以适配输出维度。
• ⭐ 核心策略：二阶段冻结与解冻 (Two-stage Freezing)：
  • 阶段一（预热期，约前 5~10 个 Epoch）：完全冻结 Transformer 主干网络，仅训练新添加的任务头部。这能让头部参数快速适应数据分布，而不破坏预训练权重。
  • 阶段二（联合微调期）：解冻主干的最后 3~6 层（若数据充足可解冻全部层），使用极小的学习率进行全参数微调。该策略比“一上来就全解冻”收敛更稳定、效果更优。
• ⭐ 关键要诀：差分学习率 (Differential Learning Rates)：
  • 任务头 (Head)：学习率设为 1e-3 ~ 1e-4。
  • 主干网络 (Backbone)：学习率设为 1e-5 ~ 1e-6（通常比头部小 10~100 倍）。对主干使用统一的大学习率极易破坏预训练权重的内在表征，导致灾难性遗忘。
• 超参数设置 (Hyperparameters)：
  • 优化器：AdamW（适配 Transformer 的经典选择）。
  • 权重衰减：L2 正则化系数，防止过拟合。
  • 批次大小 (Batch Size)：根据显存容量调整。
  • 学习率调度器：建议采用 Warmup 后线性衰减策略。

4. 微调训练

实际的模型参数迭代过程，需依据阶段一的策略执行。

• 损失函数 (Loss Function)：
  • 分类：交叉熵损失 (nn.CrossEntropyLoss)。
  • 回归：均方误差损失 (nn.MSELoss)。
• 优化器 (Optimizer)：
  • 实例化优化器时，若采用了差分学习率将头部参数与主干参数分为两组，并分别赋予上述设置的差分学习率。
• 训练循环 (Training Loop)：
  1. 设置 model.train()。
  2. 遍历 Epoch 与 DataLoader。
  3. 每个 Batch 迭代：
     • 数据移至 GPU/CPU。
     • 前向传播：输入 gene_ids, values, src_key_padding_mask 获取输出（如 Logits）。
     • 计算损失：与真实标签比较。
     • 反向传播：loss.backward() 计算梯度。
     • 参数更新：optimizer.step() 按差分学习率更新。
     • 梯度清零：optimizer.zero_grad()。
• 验证 (Validation)：
  • 每个 Epoch 结束后（或固定间隔）于验证集评估。
  • 切换至 model.eval() 模式（不计算梯度）。
  • 计算验证损失及指标（如准确率）。
  • 根据验证集性能（最低损失或最高准确率）保存最优模型权重，防止过拟合并确保最佳泛化性。

5. 结果评估

利用独立的测试集对最终模型进行客观评价。

• 评估指标 (Metrics)：
  • 分类任务：准确率 (Accuracy)；精确率/召回率/F1（推荐使用宏平均 Macro-F1 或加权平均 Weighted-F1 处理类别不平衡）；混淆矩阵 (Confusion Matrix)；ROC-AUC 值。
  • 回归任务：均方误差 (MSE)、均方根误差 (RMSE)、平均绝对误差 (MAE)、决定系数 (R²)。
  • 其他任务：如聚类的调整兰德指数 (ARI)、归一化互信息 (NMI) 等。
• 测试集评估：
  • 加载验证阶段保存的最佳模型。
  • 设置 model.eval()，在测试集上进行推理并计算指标。测试集的表现是衡量模型泛化能力的最终金标准。
• 结果解释与可视化：
  • 深入分析指标，剖析模型优劣。
  • 利用 UMAP/t-SNE 等方法对细胞嵌入 (Cell Embeddings) 进行降维可视化，直观验证微调后的模型是否在生物学上有效区分不同细胞类型或状态。