简介：这套基于Python的蛋白质二级结构预测项目源码，面向生物信息学与机器学习方向的初学者，以及需要完成期末大作业的高校学生。项目同时实现了ResNet编码器（CNN）与Transformer两种建模方案，涵盖数据加载、模型定义、训练与运行脚本，并附有训练好的参数文件与两种模型的预测输出文本，配合说明文档可以直接复现完整预测流程，方便对比不同架构的效果。压缩包共12个文件，以5个Python脚本为核心，辅以3个txt结果或说明文档、2个模型参数文件（.pdparams）及2个缓存文件，整体约43.76MB，目录结构按模型、参数、结果分层，关键脚本与对应产物一一对应，便于按模块对照学习。目前已有227人浏览学习，项目源码经过本地编译并达到95分以上评审水准，难度适中，适合作为课程设计、毕业设计或深度学习入门的实战参考。

1. 蛋白质二级结构预测项目为什么值得跑：先认清任务再选模型

如果你打开这个标题只是为了找一份能交差、能答辩的 Python 项目源码，我建议你先停下来把任务本身看清：蛋白质二级结构预测不是“输入一条序列，输出一个类别”，而是给序列里的每一个氨基酸残基预测一个结构标签（H 螺旋 / E 折叠 / C 卷曲，或者更细的八态）。它本质上是序列标注，和 BERT 做命名实体识别属于同一个范式，只是输入换成了 20 种氨基酸。看清楚这一点，你就明白为什么这个项目里 CNN 和 transformer 都能用，但用法跟图像分类完全不同。适合做它的人有两类：一类是生物信息方向需要一份拿得出手的深度学习项目，另一类是熟悉 NLP 但想试试结构化序列数据的人。后者上手更快，但该踩的数据坑一个都不会少。

2. 先从数据下手：把PDB结构变成Q8标签和可训练张量

2.1 二级结构标签从哪来：DSSP输出与三态/八态映射

蛋白质二级结构标签不是序列自带的，而是从 PDB 三维结构文件里用工具算出来的。最常用的工具是 DSSP，它读入一个 PDB 文件后，按残基输出每个氨基酸的二级结构类别。DSSP 的原始输出是八态：H（α螺旋）、B（孤立β桥）、E（β折叠股）、G（310螺旋）、I（π螺旋）、T（转角）、S（弯曲）、C（卷曲）。课程项目里最常见的做法是把它映射成三态（Q3）直接当分类目标，或者保留八态（Q8）做更细的预测。

映射规则在论文里几乎是固定的：G 和 I 并入 H，B 并入 E，T、S、C 全部归到 C。不要自己发明映射，否则模型报告没法跟公开结果对比。下面这段代码就是这个映射，建议直接复制到你的数据预处理脚本里：

""" 把DSSP的8态标签映射成3态标签。 H: alpha helix G: 310 helix, I: pi helix -> H E: beta strand, B: isolated beta bridge -> E T: turn, S: bend, C: coil -> C """ EIGHT_TO_THREE = { "H": "H", "G": "H", "I": "H", "E": "E", "B": "E", "T": "C", "S": "C", "C": "C", } def map_ss8_to_ss3(ss8: str) -> str: """把一条8态标签字符串逐字符映射成3态。""" return "".join(EIGHT_TO_THREE.get(ch, "C") for ch in ss8)

这段代码逻辑上没有任何技巧，唯一要注意的是get(ch, "C")的兜底。DSSP 在遇到无法确定的残基时会输出!或空字符，如果不做兜底，整条标签字符串的长度会和序列长度不一致，后续训练时错位问题会非常隐蔽。参数上你只需要确认传入的是字符串而不是列表，DSSP 解析出来的是什么结构，就先转成什么结构再喂进这个函数。

真正容易翻车的地方在 DSSP 文件解析。DSSP 输出是固定列宽的文本，不同版本的 DSSP 列偏移会有差异。常见做法是逐行读取，找到每个残基对应的 PDB 编号和氨基酸字母，再把标签按位置对齐。千万不要用line[16]这种硬编码列号去取标签，DSSP 版本一换就全错。最稳妥的方式是用残基编号作为字典的 key，从 PDB 序列里逐个残基去查，查不到就跳过，而不是按顺序强行拼接。

2.2 序列编码：独热、PSSM与未知氨基酸的处理

模型吃的是张量，不是字符串。第一步是把氨基酸字母映射成数字索引。标准做法是维护一个 20 种标准氨基酸的字母表，遇到 B（天冬酰胺或天冬氨酸）、Z（谷氨酰胺或谷氨酸）、J（亮氨酸或异亮氨酸）、U（硒代半胱氨酸）这类不常见字符时，统一映射到一个 21 号位“X”。很多项目源码在这一步直接报错，因为测试集里总能冒出几个非标准字符。

AAS = "ACDEFGHIKLMNPQRSTVWY" AA_TO_IDX = {aa: i for i, aa in enumerate(AAS)} AA_TO_IDX["X"] = len(AAS) # 第21号位留给未知氨基酸 def encode_sequence(seq: str) -> list[int]: """氨基酸序列转索引列表，非标准字符统一落到X。""" seq = seq.upper().strip() idx_list = [] for ch in seq: if ch in AA_TO_IDX: idx_list.append(AA_TO_IDX[ch]) else: idx_list.append(AA_TO_IDX["X"]) return idx_list

这里有个参数需要留意：AA_TO_IDX["X"] = 21，所以你的独热向量维度是 21，不是 20。很多复现项目把这个维度算错，后面模型输入维度对不上，报错之后又回头改字母表，浪费时间。另一个经验是：B、Z、J 这类字符如果能拿到原始 PDB 文件，最好去查它到底对应哪个标准氨基酸再替换，纯粹映射到 X 虽然不报错，但对预测是有损的。

比独热编码更能拉开分数差距的是 PSSM（位置特异性打分矩阵），它来自 PSI-BLAST 的多序列比对结果，维度是 L×20，每个数值表示这个位置出现某种氨基酸的偏好强度。公开论文里几乎都会用 PSSM 作为输入特征，因为它能把同源进化信息带进模型。但 PSSM 的生成是整条管线里环境配置最容易翻车的一步：PSI-BLAST 需要安装、需要构建数据库、跑一次还要几分钟到几十分钟。如果你只是先跑通流程，建议先用纯独热编码，等模型和评估都稳定了再补 PSSM。

import torch def build_features(seq_indices: list[int], pssm: torch.Tensor | None = None) -> torch.Tensor: """ 把序列索引转成模型输入特征。 seq_indices: encode_sequence 的输出 pssm: (L, 20) 的浮点张量，可为None 返回: (L, F)，F=21(独热) 或 41(独热+PSSM) """ seq_len = len(seq_indices) one_hot = torch.zeros(seq_len, len(AAS) + 1) one_hot[torch.arange(seq_len), torch.as_tensor(seq_indices)] = 1.0 if pssm is None: return one_hot return torch.cat([one_hot, pssm], dim=-1)

代码里one_hot[torch.arange(seq_len), torch.as_tensor(seq_indices)] = 1.0是 PyTorch 里用索引张量做批量赋值的写法，比 for 循环快一个量级。PSSM 矩阵的数值范围通常在 -5 到 +15，直接拼进特征后数值尺度跟独热的 0/1 差太多，训练容易震荡。我一般会先对 PSSM 做一个简单的缩放，除以 10 或者做一次标准化，这个细节能让 CNN 收敛快不少。

2.3 把整条序列打包成样本：padding与mask的约定

序列长度不一样，不能直接堆成 batch。两种常见做法：固定max_len截断或 padding，或者每个 batch 内取最长序列 padding。固定长度实现简单但会截断长序列，丢失尾部信息；取 batch 内最大值没有截断问题，但序列长度差异大时 padding 浪费严重。我在做二级结构预测项目时的习惯是设一个上限（比如 700），超过的序列截断或丢弃，以内的用 batch 内最大长度 padding。

padding 位置必须同时处理好两件事：特征张量补 0，标签置为 -100，mask 标记哪些是真残基。下面这个 collate 函数能直接用在 PyTorch DataLoader 里：

def collate_batch(batch): """ batch: 列表，每一项是 (features, labels) features: (L, F) 张量 labels: (L,) 张量，类别索引 返回: (feats_padded, labels_padded, mask) mask 中 1=真实残基, 0=padding padding 位置的标签填 -100，配合 CrossEntropyLoss 的 ignore_index 使用 """ max_len = max(x.shape[0] for x, _ in batch) feats, labels, mask = [], [], [] for feat, lab in batch: seq_len = feat.shape[0] pad_len = max_len - seq_len feats.append(torch.cat([feat, torch.zeros(pad_len, feat.shape[1])], dim=0)) labels.append(torch.cat([lab, torch.full((pad_len,), -100)], dim=0)) mask.append(torch.cat([torch.ones(seq_len), torch.zeros(pad_len)], dim=0)) return torch.stack(feats), torch.stack(labels), torch.stack(mask)

这段代码里最关键的是-100和 mask 的配合。-100是 PyTorchCrossEntropyLoss默认的ignore_index值，loss 计算会自动跳过这些位置；mask 则留给评估和 transformer 的src_key_padding_mask。很多项目跑起来 loss 很怪，先查这一处：padding 位置的标签如果填的是 0，模型会把大量梯度花在“学会预测 padding 位置”，真实残基反而学不好。mask 的另一个约定是方向：你自己的 mask 里 1 表示真实残基，但 PyTorchTransformerEncoder接收的src_key_padding_mask里 True 表示“该位置是 padding，不要参与注意力”，两者正好相反，转换时最容易看反。

3. 用CNN做残基级预测：一维卷积堆叠与感受野设计

3.1 为什么优先试CNN：短程模式直觉与一维卷积基本结构

二级结构中 α螺旋和 β折叠股的形成，很大程度上取决于序列局部几个残基的性质：疏水残基周期性出现、带电残基的间隔模式。这些是典型的局部模式，而一维 CNN 天生就是局部算子，卷积核滑动几次就能捕捉到“第 i 个残基附近 15 个残基”的模式。所以在项目里我通常先跑 CNN 而不是直接上 transformer：CNN 参数少、收敛快、在小数据集上不容易过拟合，能最快验证你的数据管线和评估逻辑是不是对的。

一维 CNN 的基本结构就是把图像里的二维卷积替成一维：Conv1d + BatchNorm1d + ReLU堆叠，必要时加dropout。和图像分类不同，二级结构预测每个残基都要一个输出，所以整个网络不能做下采样池化，必须保持序列长度 L 不变。如果你之前只写过二维 CNN，这里最容易搞错的是张量形状：PyTorch 的Conv1d期望输入是(B, F, L)，而你的特征张量是(B, L, F)，必须转置一次，别漏掉。CNN 基本结构的三板斧就是这个：转置、卷积堆叠、转置回来。

3.2 一个能跑的CNN网络：空洞卷积扩大感受野

如果只用kernel_size=3的普通卷积堆四层，每一层的感受野只增加 2，四层也才看到 9 个残基。β折叠片里的氢键配对可以跨几十个残基，局部窗口抓不到这种远程关系。解决方案是用空洞卷积，dilation 逐层翻倍，感受野指数增长。

import torch import torch.nn as nn class CNNSecondaryStructure(nn.Module): def __init__(self, in_features: int, num_classes: int, hidden: int = 128): """ in_features: 21(独热) 或 41(独热+PSSM) num_classes: 3 或 8 hidden: 隐层通道数，128在二级结构项目里够用，256不是必须 """ super().__init__() self.in_proj = nn.Sequential( nn.Conv1d(in_features, hidden, 1), # 逐点变换，不改序列长度 nn.BatchNorm1d(hidden), nn.ReLU(inplace=True), ) layers = [] dilation = 1 for _ in range(4): layers.append(nn.Conv1d(hidden, hidden, kernel_size=3, padding=dilation, dilation=dilation)) layers.append(nn.BatchNorm1d(hidden)) layers.append(nn.ReLU(inplace=True)) dilation *= 2 self.dilated_stack = nn.Sequential(*layers) self.out_proj = nn.Conv1d(hidden, num_classes, 1) def forward(self, x: torch.Tensor) -> torch.Tensor: # x: (B, L, F) x = x.transpose(1, 2) # (B, F, L) x = self.in_proj(x) x = self.dilated_stack(x) x = self.out_proj(x) return x.transpose(1, 2) # (B, L, num_classes)

四层空洞卷积的 dilation 分别取 1、2、4、8，每层卷积核是 3，感受野从 3 增加到 7、15、31。这个规模对二级结构预测够用，再加深对精度的帮助就很有限了。padding=dilation是保持序列长度不变的关键，别用默认的 0，否则你每过一层序列就缩 2，到最后一层长度对不上标签了。in_features参数要跟第 2 章的特征构建对上：纯独热是 21，加了 PSSM 是 41。很多人训练时报维度不匹配，就是因为前面build_features改成了带 PSSM，模型定义里还写着 21。

3.3 CNN训练参数与收敛观察

CNN 在序列标注任务上学习率可以用得比 transformer 激进，我通常直接上AdamW，lr=1e-3。损失函数用带ignore_index=-100的CrossEntropyLoss，和 collate 里 padding 标签的约定刚好配套。

criterion = nn.CrossEntropyLoss(ignore_index=-100) # padding标签自动忽略 optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3, weight_decay=1e-5) for epoch in range(100): model.train() total_loss = 0.0 for feats, labels, mask in train_loader: feats = feats.to(device) labels = labels.to(device) logits = model(feats) # (B, L, num_classes) logits = logits.view(-1, num_classes) labels = labels.view(-1) loss = criterion(logits, labels) optimizer.zero_grad() loss.backward() optimizer.step() total_loss += loss.item() * feats.size(0) print(f"epoch {epoch} loss {total_loss / len(train_dataset):.4f}")

CNN 的收敛曲线通常在前 10 个 epoch 就有明显下降，loss 如果连续 20 个 epoch 不动，先别调网络结构。按照踩坑经验，90% 的可能出在三个地方：padding 标签没有置 -100、DSSP 标签和序列错位、PSSM 没有归一化导致梯度震荡。这三个问题在第 5 章会展开讲。这里的mask在训练循环里没有直接用，因为ignore_index=-100已经处理了 loss，mask 主要留给评估和 transformer。但如果之后你想用 Focal Loss 处理类别不均衡，mask 就要手动参与计算了。

4. 换用Transformer：双向注意力、位置编码与逐残基分类

4.1 为什么Transformer值得换：长程依赖与注意力视野

CNN 靠堆层扩大感受野，但每堆一层只能多看到几个残基，想建立序列两端的长程联系成本很高。Transformer 不一样，自注意力一层就能让任意两个位置的表示直接交互，这个特性对二级结构预测很重要——β折叠的两个股可能相隔几十甚至上百个残基，它们的配对关系本质上就是远程依赖。另一个现实原因是：课程项目答辩时，CNN 方案很难讲出新意，而 transformer 方案只要讲清楚位置编码和掩码，技术上就比纯堆卷积高一档。

但这个任务和 transformer 做图像分类、时序预测有一个关键差异：图像分类对整张图输出一个标签，时序预测通常对最后一个位置输出预测，而二级结构预测要对序列的每一个位置输出标签，属于 token-level 的分类任务。所以分类头不是取[CLS]的表示，而是把每个位置隐藏层的输出都接一个线性层。如果你把 BERT 做序列标注的分类头搬过来，结构上基本就对了。想彻底搞懂多头注意力的内部顺序，建议对着 The Illustrated Transformer 的拆解图把 Q、K、V 投影、缩放点积、softmax、加权求和这个过程在纸上过一遍，再写代码，比直接照抄MultiheadAttention靠谱得多。

4.2 位置信息怎么算：可学习位置编码与正弦编码的取舍

Transformer 本身没有序列顺序概念，必须加位置编码。二级结构项目里两种方案都很常见：正弦位置编码和可学习位置编码。正弦编码的好处是理论上能外推到训练时没见过的更长序列，数值也稳定；可学习编码在序列长度比较固定的场景下更灵活，会让模型稍微好收敛一点。

class PositionalEncoding(nn.Module): """正弦位置编码, 可外推到更长序列。""" def __init__(self, d_model: int, max_len: int = 1024): super().__init__() pe = torch.zeros(max_len, d_model) pos = torch.arange(max_len).unsqueeze(1).float() denom = 10000 ** (torch.arange(0, d_model, 2).float() / d_model) pe[:, 0::2] = torch.sin(pos / denom) pe[:, 1::2] = torch.cos(pos / denom) self.register_buffer("pe", pe.unsqueeze(0)) def forward(self, x: torch.Tensor) -> torch.Tensor: return x + self.pe[:, : x.size(1)] class LearnablePositionalEncoding(nn.Module): """可学习位置编码, 序列长度固定时用起来更方便。""" def __init__(self, d_model: int, max_len: int = 1024): super().__init__() self.pe = nn.Parameter(torch.randn(1, max_len, d_model) * 0.02) def forward(self, x: torch.Tensor) -> torch.Tensor: return x + self.pe[:, : x.size(1)]

两种实现的差异全在register_buffer和nn.Parameter：前者不参与梯度更新，后者会。这意味着可学习位置编码会随训练不断调整，也更依赖数据量。我的选择标准是：如果训练集只有几千条序列，用可学习编码；如果希望模型能处理比训练集更长的蛋白，用正弦编码。0.02的初始化方差是从 BERT 借鉴的经验值，位置编码初始化太大，前几步训练 loss 会非常高。

4.3 一个能跑的Transformer网络：Embedding、多头注意力与分类头

下面是一个能直接跑通的 transformer 版本。输入特征先经过一个线性层投影到d_model，加上位置编码，再进TransformerEncoder，最后对每个位置接分类头。

class TransformerSecondaryStructure(nn.Module): def __init__(self, in_features: int, num_classes: int, d_model: int = 192, nhead: int = 4, num_layers: int = 4): super().__init__() self.input_proj = nn.Linear(in_features, d_model) self.pos = LearnablePositionalEncoding(d_model) layer = nn.TransformerEncoderLayer( d_model=d_model, nhead=nhead, dim_feedforward=512, dropout=0.1, batch_first=True, norm_first=True ) self.encoder = nn.TransformerEncoder(layer, num_layers=num_layers) self.classifier = nn.Linear(d_model, num_classes) def forward(self, x: torch.Tensor, src_key_padding_mask: torch.Tensor | None = None): """ x: (B, L, F) src_key_padding_mask: (B, L) BoolTensor, True=忽略该位置, 来自collate里mask的反转 """ h = self.input_proj(x) h = self.pos(h) key_padding_mask = None if src_key_padding_mask is not None: key_padding_mask = src_key_padding_mask == 0 # 1=真实残基, 转成 True=padding h = self.encoder(h, src_key_padding_mask=key_padding_mask) return self.classifier(h) # (B, L, num_classes)

这里有两个参数值得画重点。第一个是batch_first=True，PyTorch 1.9 之后支持这个参数，它决定输入张量是(B, L, d_model)还是(L, B, d_model)，写错的话 forward 里的h输出比预期少一维，报错信息还很绕。第二个是norm_first=True，这是 PyTorch 新版针对TransformerEncoderLayer的一个可选参数，表示先做层归一化再做注意力，实践里这种写法收敛更稳定。d_model选 192 而不是 512，是因为二级结构预测的数据量通常只有几千到几万条序列，大模型过拟合非常快。如果显卡显存紧张，可以进一步把num_layers降到 3 或把d_model降到 128。

这个任务里不需要因果掩码。蛋白质二级结构预测是一个编码任务，每个残基能看到整条序列的任意位置，包括它右侧的残基，这和文本生成必须遮挡未来 token 的逻辑完全不同。如果你把 GPT 的因果掩码搬过来，预测右侧残基时看不到右侧上下文，Q3 会掉得很明显，这是新手最容易犯的错误。

4.4 Transformer在小数据集上的调参要点

Transformer 在小数据集上过拟合几乎是必然的，loss 曲线先降后升是家常便饭。我的调参顺序是：第一改 dropout，从 0.1 加到 0.2 或 0.3；第二减模型尺寸，d_model从 192 降到 128，层数从 4 降到 3；第三加 label smoothing。学习率方面，AdamW配lr=3e-4是稳妥起点，CNN 的 1e-3 对 transformer 来说太大了。

criterion = nn.CrossEntropyLoss(ignore_index=-100, label_smoothing=0.1) optimizer = torch.optim.AdamW(model.parameters(), lr=3e-4, weight_decay=1e-4)

label_smoothing=0.1会让模型不再追求“预测得过于自信”，这对容易过拟合的小数据项目有明显帮助。注意一个坑：PyTorch 的CrossEntropyLoss里weight和label_smoothing不要同时用，指定了weight后 label smoothing 会被忽略。想同时处理类别不均衡和标签平滑，需要自己写一个结合两者的 loss，这个放到第 5 章避坑部分细说。

长序列的显存问题也不能忽视。一个max_len=700、d_model=192、4 层的 transformer，batch size 8 在 8GB 显存上已经有点勉强。常见做法是限制最大长度，或者按长度分 bucket，让同 batch 内的序列差距不要太大。直接上长序列全连接注意力，显存会教你做人。

5. 评估与避坑：Q3/Q8、数据泄漏和五条血泪经验

5.1 评估别只盯准确率：Q3、Q8与SOV到底是什么关系

很多人报告结果时只写一句“Q3 达到 85%”，然后就没了。Q3 和 Q8 的计算确实简单：预测正确的残基数除以总残基数。但如果只看这个单一指标，你很容易被类别不均衡欺骗。SOV 指标考虑了片段的完整性，预测的螺旋段如果断成几截，即使每个残基都猜对了，SOV 也会给惩罚。课程项目报告里同时给出 Q3/Q8 和 SOV，比只报准确率高一个档次。

def q3_q8_accuracy(y_true: list[str], y_pred: list[str]) -> tuple[float, float]: """计算Q8准确率和映射到三态后的Q3准确率。""" assert len(y_true) == len(y_pred) n = len(y_true) q8 = sum(a == b for a, b in zip(y_true, y_pred)) / n true3 = [EIGHT_TO_THREE[ch] for ch in y_true] pred3 = [EIGHT_TO_THREE[ch] for ch in y_pred] q3 = sum(a == b for a, b in zip(true3, pred3)) / n return q8, q3 def sov_simple(y_true: list[str], y_pred: list[str]) -> float: """简化版SOV，不考虑正式定义里的容差项，用于项目报告够用。""" def segments(y): segs, start, prev = [], 0, y[0] for i, ch in enumerate(y[1:], start=1): if ch != prev: segs.append((prev, start, i - 1)) start, prev = i, ch segs.append((prev, start, len(y) - 1)) return segs true_segs = segments(y_true) pred_segs = segments(y_pred) sov_sum, total_len = 0.0, 0 for tseg in true_segs: s1_len = tseg[2] - tseg[1] + 1 total_len += s1_len best = 0.0 for pseg in pred_segs: if pseg[0] != tseg[0]: continue ov = min(tseg[2], pseg[2]) - max(tseg[1], pseg[1]) + 1 if ov <= 0: continue minov = ov maxov = max(tseg[2], pseg[2]) - min(tseg[1], pseg[1]) + 1 best = max(best, minov / maxov * s1_len) sov_sum += best return sov_sum / total_len if total_len else 0.0

上面segments函数把标签序列切成连续的片段，比如"HHHCCCEE"会切成[('H', 0, 2), ('C', 3, 5), ('E', 6, 7)]。SOV 计算时只考虑相同类别的片段对，重叠越多、覆盖跨度越接近，得分越高。这个版本省略了正式定义里复杂的不确定残基容差项，项目报告里注明是简化版就行。注意计算 SOV 之前一定要把 padding 位置去掉，否则 padding 会被当成一个超长的同类片段，严重扭曲数值。

5.2 同源性泄漏：测试集与训练集序列太像导致的高分幻觉

现象：随机划分后验证集 Q3 轻松到 88%，但换一批外部数据立刻掉到 70%，而且多跑几个 seed 分数波动巨大。

原因：从 PDB 里随机抽取链划分训练集和测试集时，同一条蛋白的多个突变体、同一结构域的多条链会被拆到两边。模型在训练时见过这些近乎重复的序列，验证时等于开卷考试。

解决：在划分前先按序列相似度去重。常用工具是 CD-HIT，按 30% 序列同一性聚类，同一簇的序列只能全部进训练集或全部进测试集。命令行参数如下：

cd-hit -i all_seqs.fa -o all_seqs_cdhit30.fa -c 0.3 -n 2 -M 0 -T 4

-c 0.3是 30% 相似度阈值，-n 2是 word length，-M 0表示内存不设上限，-T 4使用 4 个线程。跑完后输出文件里每个簇的代表序列可以拿来做数据集划分。这个操作会把训练集规模缩小不少，但得到的分数才有说服力。如果你没有 CD-HIT 环境，至少做到按 PDB 链 ID 划分，而不是按残基随机划分，否则泄漏问题无法避免。

5.3 “全预测卷曲也能上60%”的类别不均衡陷阱

现象：训练 loss 降得很快，Q3 也有 60% 以上，但打开混淆矩阵发现模型绝大多数预测都落在 C 类，H 和 E 几乎没预测出来。

原因：三态标签里 C 类（卷曲）占比明显高于 H 和 E。模型如果全部输出 C，准确率已经能到 50% 上下，这在 loss 上不是一个很差的结果，所以模型没有动力去区分 H 和 E。

解决：给CrossEntropyLoss传入按类别频率计算的权重。基于前提是三态索引固定为 0=H、1=E、2=C，否则权重顺序错乱会让模型更不收敛。

from collections import Counter counts = Counter(all_train_ss3) # 三态标签列表 total = sum(counts.values()) class_weights = torch.tensor([ total / (3 * counts["H"]), total / (3 * counts["E"]), total / (3 * counts["C"]), ]).to(device) criterion = nn.CrossEntropyLoss(weight=class_weights, ignore_index=-100)

这里的权重公式是频率倒数的变体，样本多的类别权重小，样本少的类别权重大。另一个办法是使用 Focal Loss，它对难分类样本更敏感，实现稍复杂。评估时也别只看 accuracy，同时报 per-class F1 或 macro-F1，能看出模型是否真的学会了预测 H 和 E。之前提过weight和label_smoothing不能同时用，如果你两个都想要，需要自己写一个带标签平滑的加权交叉熵，这在开源实现里很容易找到参考。

5.4 DSSP标签与序列错位：一个残基偏移造成的连锁错误

现象：训练 loss 正常下降，可视化预测结果时发现预测的 H/E/C 片段整体比真实标签往左或往右偏移一位。

原因：DSSP 解析脚本没有按残基编号对齐，靠顺序硬拼。DSSP 在处理某些柔性的 N 端残基时会跳过不输出，或者输出顺序和原始序列顺序在个别地方不一致，但解析脚本还在按行号逐个填，结果就是整段错位。

解决：解析时用 PDB 残基编号作为 key 做对齐，做完后一定要加一个断言：

assert len(ss8) == len(seq), f"length mismatch {len(ss8)} vs {len(seq)} at {seq_name}"

这个断言放在训练脚本启动前，任何长度对不上的序列直接跳过，不要尝试修补。因为错位问题不只是一行标签偏移，手动修补的代码引入新 bug 的概率比解决旧 bug 的概率还高。项目里宁可丢掉几条异常链，也不要带着错位标签跑完整轮训练。我早期在这里栽过一次，浪费了两天时间反复调模型结构，结果是数据问题。序列和数据对齐是二级结构预测项目里最大的玄学黑匣子，先把它撬开再谈模型。

5.5 padding位置参与loss：mask缺失时的诡异梯度

现象：训练 loss 和验证指标都很高，但模型预测几乎没有区分度；换模型、调学习率都没用。

原因：collate 函数里 padding 位置的标签没有置 -100，模型把大量梯度花在“认真预测 padding 位置”上。padding 位置的特征是全 0，模型很容易把它们预测成一个固定类别，整体准确率被虚高的 padding 预测拉起来。

解决：在 collate 阶段把 padding 标签置 -100，loss 用ignore_index=-100，评估时用 mask 过滤掉 padding 位置：

def evaluate(model, loader): model.eval() total_correct, total_valid = 0, 0 with torch.no_grad(): for feats, labels, mask in loader: logits = model(feats) pred = logits.argmax(dim=-1) keep = mask.bool() # 只统计真实残基 total_correct += (pred[keep] == labels[keep]).sum().item() total_valid += keep.sum().item() return total_correct / total_valid

mask.bool()这一步把 0/1 的 mask 张量转成布尔型，可以当作索引掩码直接用在张量上。这个问题的隐蔽性在于 loss 可能看起来很正常，因为 padding 预测对 loss 的贡献是真实且平滑的，模型也顺着这个梯度继续优化。自查办法很简单：用单条短序列过一遍模型，打印出预测标签和真实标签，人工数一下正确的残基数，能对上再跑全量数据。

6. 让项目变成“95分可交付”：外部验证、可视化与交付技巧

6.1 用CB513做外部基准，别只报随机划分分数

课程项目的高分并不只看模型精度，更要看评估是否经得起追问。随机划分的验证集分数很好看，答辩时被问到“这个分数能跟论文对比吗”就会很被动。经典的做法是用 CB513 作为外部测试集，它是 513 条去冗余蛋白质链组成的标准基准，公开论文里大量二级结构预测工作都报这一组数字。你可以从文献补充材料里找到现成的 CB513 序列与 DSSP 标签，把训练集换成自己的去重子集，只把 CB513 当测试集用。这样报告里可以同时给出“随机划分验证结果”和“CB513 外部基准结果”两列数字，前者说明你管线没问题，后者说明模型有泛化能力。如果连 CB513 也不好找，退一步用 CD-HIT 去重后重新划分，并在报告里写清楚划分方式，至少做到可复现。

6.2 把预测结果可视化：逐残基比对图与序列对齐输出

答辩时一张对齐图，胜过十段文字。我习惯在项目里加一个脚本，把每一条测试序列输出成三行对齐文本：第一行原始氨基酸序列，第二行真实标签，第三行预测标签，并用^标记预测错误的位置。

def format_alignment(seq: str, true_ss: str, pred_ss: str) -> str: lines = [] for i in range(0, len(seq), 80): lines.append(seq[i:i + 80]) lines.append(true_ss[i:i + 80]) lines.append(pred_ss[i:i + 80]) diff = "".join(" " if a == b else "^" for a, b in zip(true_ss[i:i + 80], pred_ss[i:i + 80])) lines.append(diff) lines.append("") return "\n".join(lines)

这个输出直接写进日志文件，每 100 步打印一条，训练过程能看到预测质量在肉眼变好，比只看 loss 数字更踏实。如果项目要求面更漂亮的图，用 matplotlib 按残基位置画彩色条带也行，每类一个固定颜色，序列一长看起来就像一条条形码。但文本对齐格式在答辩时更实用，可以直接贴到 PPT 里，也能让老师一眼看出错位问题是否还存在。

6.3 我的交付习惯和一句话建议

这个项目我做过不止一次，一个习惯保留到现在：所有实验记录里同时保留训练日志和预测对齐样例，一个都不能少。训练日志证明模型在收敛，对齐样例证明收敛方向是对的。很多项目源码能跑但拿不到高分，问题往往不在精度，而在“讲不清楚”。答辩时被问“你为什么这么设计”，如果你能掏出 DSSP 标签映射图、感受野计算、CB513 对比表，这个项目基本就立住了。先对齐数据，再调模型；先跑通单条序列，再跑全量；先报外部基准，再谈网络结构创新。这几个顺序走对，剩下就是时间问题。希望帮到你。

本文还有配套的精品资源，点击获取