零样本学习论文代码复现：兼容函数、生成式与GZSL评测

简介：面向零样本学习入门与论文复现实践，这份资料围绕零样本识别任务提供基础复现与基于PyTorch的原文复现，适合已具备一定机器学习基础、希望打通从论文公式到代码实现环节的读者。压缩包共11个文件，包含6个Python源码、2份PDF论文或说明、1个Excel属性表、1个TXT说明及1个Jupyter Notebook，整体约38.98MB，覆盖模型代码、数据处理、语义空间矩阵与实验记录等模块。已有2851人学习下载。读者可据此对照论文梳理算法流程，理解属性语义空间、样本划分与基础KNN基线，并参考数据说明自行准备体积较大的数据集，完成复现与二次实验。

1. 训练集里没有猫，模型却要认出猫

这个场景我碰到过不止一次：标注团队只覆盖了几十个常见类别，业务方转头就要模型识别一批从没进过训练集的新类别。零样本学习（zero-shot learning）就是冲着这个缺口来的，它靠类别之间的语义属性建立桥梁，让模型在“没见过某个类”的情况下依然能给出判断。这份“论文+代码”的资源价值在于链路完整，论文里推导的兼容函数、损失项和评测协议，代码里都有对应实现，而不是只给一堆公式让人自行脑补。

它适合两类读者。一类是手上标注不全、又必须覆盖新类的工程开发者，想搞清楚这份代码能不能直接接进自己的数据管线；另一类是想把零样本学习从论文公式落到可跑脚本的人，尤其是被 GZSL 指标折磨过的同学，可见类准确率挺高、未见类却接近零，谐波均值卡在中间不上不下。把仓库跑通、拿到 ZSL 与 GZSL 两套指标、再把自己的类别体系换进去，这条路径是走得通的。

2. 架构选型：语义属性、视觉特征和嵌入空间怎么搭

2.1 三条技术路线，先选一条再谈代码

零样本学习发展到现在，工程上能直接落地的路线基本三条。第一条是嵌入式，学一个把视觉特征映射到语义空间的函数，或者反过来，再用兼容函数打分。ALE、DeViSE、ESZSL 都属于这一支，优点是训练快、显存友好、代码量小，一份几百行的脚本就能跑起来；缺点是对语义属性的质量极其敏感，属性表设计得糙，指标直接塌。第二条是生成式，用条件 GAN 或 VAE 给未见类合成视觉特征，把零样本问题转成普通的监督分类，f-CLSWGAN、f-VAEGAN 是代表，优点是 GZSL 场景下效果好，缺点是训练不稳定，调参调得人怀疑人生。第三条是借视觉-语言预训练模型直接做开放词汇分类，不需要额外训练，但这类方案对算力和数据分布的要求跟前面两条不是一个量级。

这份资源的主体是前两条路线。论文部分铺的是嵌入式的推导，代码仓里同时留了生成式的分支。我一般建议按“先跑嵌入式拿到基线，再上生成式看提升”的顺序来，原因是嵌入式的链路短，出了问题容易定位，等数据管线和评测协议都验证过了，再换生成式，变量才是可控的。

选型时还要先想清楚一件事：你要的是 ZSL 还是 GZSL。前者测试时只有未见类，后者测试集里可见类和未见类混在一起，更接近真实业务。两者对模型的要求完全不同，生成式方法在 GZSL 上的优势明显，而很多嵌入式方法在 GZSL 下会把绝大多数样本判成可见类。资源里的配置按两种协议分开，别混着用。

2.2 论文公式到工程模块的映射

读到论文里那个兼容函数的时候，别急着抄公式，先在脑子里过一遍维度。以双线性兼容为例，视觉特征是 2048 维，属性向量常见在几十到几百维，兼容矩阵 W 的尺寸就是视觉维度乘以属性维度，参数量在一百万量级，单卡完全放得下。代码里通常不显式构造 W，而是用一个不带 bias 的线性层把视觉特征投到属性维度，再做余弦相似度，这样既省显存又顺手做了归一化。

论文里的损失函数也要对照着看。ALE 用的是加权排序损失，目标是让正确类别的得分比错误类别高出一个 margin；ESZSL 把损失写成闭式解，训练时不需要迭代；DeViSE 用的是点积加 hinge。资源里的代码把这几类损失拆成独立模块，配置里切换一个字段就能换，这是我觉得设计得比较舒服的地方，因为对比实验的时候你不想每次都改训练脚本。

还有一块容易被忽略：属性矩阵到底表示什么。论文里默认每个类有一组人工定义的属性值，比如“有尾巴”“会飞”“体型大小”，取值在 0 到 1 之间。工程上换到自己的业务类别时，这套属性表得自己造，后面二次开发那章会展开。先把“视觉分支负责提取判别特征、语义分支负责携带类间关系、兼容函数负责把两者对齐”这个三段式记住，看代码时就不会迷路。

2.3 目录结构：一份能跑的实验仓长什么样

仓库的骨架大致是这样，我按自己会怎么整理来写，实际资源的命名可能略有出入，但分层逻辑是通的：

zsl-project/ ├── configs/ # 每个数据集 + 方法一个 yaml │ ├── attr_ale.yaml │ └── attr_wgan_gzsl.yaml ├── data/ │ ├── features/ # 预抽取的视觉特征 .npy │ ├── attributes/ # 类别属性矩阵 │ └── splits/ # 可见/未见类划分 json ├── datasets/ │ └── zsl_dataset.py ├── models/ │ ├── embedding.py # 兼容函数 │ ├── generator.py # 条件生成器 │ └── critic.py ├── losses/ │ ├── ranking_loss.py │ └── wgan_loss.py ├── engine/ │ ├── train_zsl.py │ └── evaluate.py └── scripts/ ├── extract_features.py └── run_all.sh

这个结构的关键在于data/和datasets/分开。原始特征、属性、划分文件都躺在data/里，只读不改；datasets/只负责把它们组装成张量。我第一次看这类仓库时吃过亏，把归一化和标签重映射写进了 Dataset，后来换一份划分文件，旧脚本静默地给出了错误结果，查了大半天。把“数据是什么”和“数据怎么喂”切开，是这类项目最基本的一条纪律。

configs/也值得单独说。零样本学习的超参里，margin、正则系数、校准偏置的扫描范围都跟数据集强相关，硬编码在脚本里迟早出事。资源里每个实验一个 yaml，跑对比实验时用文件名区分，比在命令行敲一长串参数可靠得多。

3. 数据管线拆解：从预抽取特征到 ZSLDataset

3.1 视觉特征、属性矩阵与类别索引的对齐

零样本学习很少端到端训练 CNN，常见做法是先用骨干网络把图片过一遍，把 2048 维或 512 维的特征存成.npy，训练时只读特征。好处是快，一个 epoch 几十秒；坏处是对齐一旦出错，整个实验就是黑匣子。三个文件必须严格对齐：特征文件的行索引是样本，属性文件的行索引是类别，划分文件里存的是每个样本对应的类别 id。

对齐的核心是建立一条单向映射：类别名 → 类别 id → 属性行号。我一般会写一个断言检查，在 Dataset 初始化时把所有类别的名字排一次序，跟属性文件的顺序比对，不一致就直接抛异常，而不是让它悄悄跑完给出一个看似正常的结果。

import json, numpy as np def build_label_map(attr_classes, split_info): """attr_classes: 属性文件里的类别名列表，顺序即属性行号 split_info: 划分 json，含 seen/unseen 的类别名 """ name_to_attr = {name: i for i, name in enumerate(attr_classes)} seen = [name_to_attr[n] for n in split_info['seen']] unseen = [name_to_attr[n] for n in split_info['unseen']] # 类别索引统一用属性行号，避免二次映射 assert len(set(seen) & set(unseen)) == 0, "可见类与未见类存在重叠" return seen, unseen

这段代码只做一件事：把类别名统一翻译成属性矩阵的行号，并且让可见类、未见类共用同一套索引。参数上，attr_classes必须是属性文件的原始顺序，不能是排序后的结果；split_info里的类别名要和它完全一致，大小写、下划线都得对上。断言那行是保命的，可见类和未见类一旦有交集，ZSL 指标会虚高得离谱，你还以为是方法有效。

3.2 ZSLDataset 与 DataLoader 的落地写法

Dataset 要做的事情其实很少：按索引取一行特征、做 L2 归一化、取出对应类别的属性向量、返回标签。归一化放在这里还是放在特征提取阶段，是个容易翻车的点，后面踩坑章会专门讲。

import torch from torch.utils.data import Dataset import numpy as np import torch.nn.functional as F class ZSLDataset(Dataset): def __init__(self, feat_path, attr_path, split_path, split='train', normalize=True): # mmap 方式读，避免一次性把几个 G 的特征全塞进内存 self.feat = np.load(feat_path, mmap_mode='r') self.attr = np.load(attr_path).astype(np.float32) info = json.load(open(split_path)) self.labels = np.asarray(info[split]['labels'], dtype=np.int64) self.normalize = normalize def __len__(self): return len(self.labels) def __getitem__(self, idx): x = np.asarray(self.feat[idx], dtype=np.float32) y = int(self.labels[idx]) if self.normalize: x = F.normalize(torch.from_numpy(x), dim=0).numpy() return (torch.from_numpy(x), torch.from_numpy(self.attr[y]), torch.tensor(y))

mmap_mode='r'是这份代码里我最认可的一处细节，特征文件动辄几个 G，用内存映射读只加载需要的页，训练时内存占用能降一大截。labels存的是全局类别 id，训练集里只出现可见类的 id，测试集里出现未见类或全部类，这一点在构造划分文件时就要定死。normalize开关建议保留，方便做消融，但生产配置里只在一个地方打开。

DataLoader 那边，num_workers开到 4 到 8 就够了，特征读取是纯 IO，worker 太多反而抢内存。shuffle=True只给训练集，评测集必须关掉，否则你没法按索引回查是哪些样本判错了。

3.3 可见/未见划分与 GZSL 测试集的构造

划分文件是整个实验的考卷，考卷换了，分数就没有可比性。标准做法是按类别划分：从全部类别里抽一部分作为未见类，其余作为可见类，比例常见是二八或三七。抽取时要固定随机种子，并且把结果落盘成 json，之后所有实验都读同一份，不要每次运行时重新抽。

ZSL 和 GZSL 的测试集构造不同。ZSL 只测未见类，标签空间是未见类 id 的集合；GZSL 要测全部类别，可见类和未见类的样本混在一起，模型必须自己判断该往哪边靠。资源里通常提供两个入口，或者用配置项protocol: zsl | gzsl切换。这里有个细节：GZSL 测试时，标签必须映射回全局类别 id，而不是在可见类、未见类内部重新编号，否则评测函数算出来的混淆矩阵是错的。

还有一个常被忽视的点，验证集怎么来。零样本学习不能拿未见类做验证，因为那等于提前泄露了测试信息。常见做法是从可见类里再切一小部分做验证，或者干脆用可见类的留出集调超参，最后只在未见类上跑一次。资源里的配置按前一种来，我在复现时也建议保持一致，不然调出来的超参没法跟论文比。

4. 核心代码拆解：兼容函数、生成器与评测链路

4.1 嵌入式方法：一个兼容函数撑起半边天

嵌入式的核心就是那个打分函数。视觉特征进来，投影到属性空间，跟所有类别的属性向量算相似度，得到每个类的得分，再拿得分去算损失。代码短，但每一行都有讲究。

import torch import torch.nn as nn import torch.nn.functional as F class BilinearCompat(nn.Module): def __init__(self, visual_dim=2048, attr_dim=85): super().__init__() # 不显式构造 W，用线性层等价实现 x^T W a self.proj = nn.Linear(visual_dim, attr_dim, bias=False) def forward(self, visual, attr): # visual: [B, D_v] attr: [C, D_a] v = F.normalize(self.proj(visual), dim=1) # 投影后再归一化 a = F.normalize(attr, dim=1) return v @ a.t() # [B, C] 兼容得分

proj这一层就是兼容矩阵，参数量是 2048 乘以属性维度，动物属性数据集常见 85 维，算下来十几万参数，轻得很。投影之后做 L2 归一化，等价于把双线性形式约束到余弦相似度，好处是得分范围稳定在 -1 到 1，margin 好设；坏处是丢掉了模长信息，有些论文靠模长做校准，这个后面可以自己加回来做对比。attr是全部类别的属性矩阵，训练时只取可见类那几行，测试时换成未见类或全部类，函数本身不用改。

损失这边，ALE 风格的排序损失最直观：正确类的得分要高出错误类一个 margin。实现上要注意 mask 的写法，别把正确类自己算进负样本里。

class RankingLoss(nn.Module): def __init__(self, margin=0.1): super().__init__() self.margin = margin def forward(self, scores, labels): # scores: [B, C] labels: [B] 全局类别 id pos = scores.gather(1, labels.view(-1, 1)).squeeze(1) mask = torch.ones_like(scores, dtype=torch.bool) mask.scatter_(1, labels.view(-1, 1), False) neg = scores.masked_fill(~mask, -1e9).max(dim=1).values return F.relu(self.margin + neg - pos).mean()

margin建议从 0.1 起扫，0.05 到 0.5 之间都试一遍，不同属性维度下最优点不一样。mask的作用是排除正确类，用-1e9填充后取 max，等价于只在错误类里挑最难的那个，这是 hinge 损失的标准写法。如果数据里一个样本可能对应多个标签，这里要改成对每个正类都算一次，资源里的实现是单标签版本，二次开发时注意。

4.2 生成式方法：条件生成器和它的训练循环

生成式的思路是给每个类别合成视觉特征，把零样本变成有监督。生成器接收“类别属性 + 随机噪声”，输出一个视觉特征向量。属性决定了生成哪个类，噪声决定了类内多样性。

class CondGenerator(nn.Module): def __init__(self, attr_dim=85, noise_dim=100, visual_dim=2048, hidden=4096): super().__init__() self.net = nn.Sequential( nn.Linear(attr_dim + noise_dim, hidden), nn.LeakyReLU(0.2, inplace=True), nn.Linear(hidden, visual_dim), nn.ReLU(inplace=True), # 特征非负，贴近真实分布 ) def forward(self, attr, noise): return self.net(torch.cat([attr, noise], dim=1))

hidden给到 4096 是这类工作的常见配置，小了生成不出有判别力的特征，大了显存吃紧。最后一层用 ReLU 而不是 tanh，因为骨干网络输出的特征经过 ReLU，本身就是非负的，这个细节对生成质量影响不小。noise_dim一般 100 够用，再大收益不明显。

训练循环里，判别器（论文里常叫 critic）和生成器交替更新，生成器每个 epoch 要为未见类合成一批特征，拼到训练集里再训一个分类器。这部分代码最容易写错的是梯度回传的顺序和 critic 的迭代次数。

for epoch in range(cfg.epochs): for visual, attr, label in train_loader: # 1) 更新 critic，n_critic 次 for _ in range(cfg.n_critic): noise = torch.randn(visual.size(0), cfg.noise_dim, device=device) fake = G(attr, noise).detach() loss_d = critic_loss(D(visual, attr), D(fake, attr)) opt_d.zero_grad(); loss_d.backward(); opt_d.step() # 2) 更新生成器 noise = torch.randn(visual.size(0), cfg.noise_dim, device=device) fake = G(attr, noise) loss_g = -D(fake, attr).mean() + cfg.cls_weight * cls_loss(fake, label) opt_g.zero_grad(); loss_g.backward(); opt_g.step()

n_critic一般取 5 到 10，太小判别器跟不上，太大会模式坍塌。cls_weight是分类损失那一项的权重，生成器不光要骗过判别器，还要让合成特征能被分类器正确识别，这一项是生成式方法在 GZSL 上有效的关键，通常给 0.01 到 0.1。fake.detach()不能漏，漏了就是生成器的梯度污染判别器，训练会莫名其妙发散。每个 epoch 结束后要用生成器给未见类合成固定数量的特征，存下来供评测用，别在评测时现生成，那样结果不可复现。

4.3 评测链路：ZSL 与 GZSL 指标、训练命令

指标算错是这类项目最常见的问题，没有之一。ZSL 只算未见类的 top-1，GZSL 要分别算可见类准确率、未见类准确率，再取谐波均值。GZSL 里还有一个校准偏置的技巧，几乎所有能打的实现都会加。

@torch.no_grad() def evaluate(model, loader, attr_all, seen_idx, unseen_idx, gamma=1.0): correct_s, total_s, correct_u, total_u = 0, 0, 0, 0 for visual, _, label in loader: scores = model(visual, attr_all) # [B, C_all] scores[:, seen_idx] -= gamma # 校准：给可见类降权 pred = scores.argmax(dim=1) is_seen = torch.isin(label, torch.tensor(seen_idx)) correct_s += ((pred == label) & is_seen).sum().item() total_s += is_seen.sum().item() correct_u += ((pred == label) & ~is_seen).sum().item() total_u += (~is_seen).sum().item() acc_s = correct_s / max(total_s, 1) acc_u = correct_u / max(total_u, 1) H = 2 * acc_s * acc_u / max(acc_s + acc_u, 1e-8) return acc_s, acc_u, H

gamma是校准系数，给可见类的得分减去一个正数，抑制模型“什么都往见过的类上猜”的倾向。这个值要扫，常见在 0.5 到 2.0 之间，扫的时候盯着 H 而不是单边的准确率。attr_all必须是全部类别的属性矩阵，行号与标签 id 对齐，这是整段代码成立的前提。torch.isin那两行是为了把样本拆成可见、未见两组，不拆的话算出来的只是一个总体准确率，看不出问题。

训练命令本身没什么花头，先把依赖装好，然后从配置跑起：

python -m engine.train_zsl --config configs/attr_ale.yaml --gpu 0 python -m engine.train_zsl --config configs/attr_wgan_gzsl.yaml --gpu 0

第一条跑嵌入式基线，几十个 epoch 通常几分钟到十几分钟就完；第二条跑生成式，时间翻几倍，建议先小 epoch 数验证链路通不通，再放开跑。日志里要盯三个数：训练 loss、可见类准确率、未见类准确率。如果前两个都正常但第三个一直接近零，先别怀疑方法，去看后面的踩坑章。

5. 踩坑排查：五类让指标直接崩掉的问题

5.1 类别划分对不上：分数涨了，其实是换了考卷

现象是同一个方法，代码跑出来的未见类准确率比论文高十几个点，或者低得离谱，换个随机种子结果又变。原因八成是划分文件不一致，要么可见类、未见类的抽取方式跟论文不同，要么类别名排序规则不同导致属性矩阵错位。零样本学习的指标对划分极其敏感，同一份特征，换个划分，H 值能差出十个点。

解决方式是把划分文件当成实验的一部分固定下来，落盘成 json，记录类别名列表和文件哈希，每次实验在日志开头打印一遍。跟论文对比时，先确认两边用的是同一份划分，再谈超参。我现在的习惯是，任何一次指标异常，第一步就是打印划分文件的类别列表，而不是去改学习率。

5.2 特征归一化做了两遍：loss 正常但准确率掉一截

现象是训练 loss 收敛得挺漂亮，验证集准确率却比预期低五到十个点，怎么调参都上不去。原因是特征在提取阶段做过一次 L2 归一化，Dataset 里又做了一次，两次归一化叠加之后，特征模长被压到接近零，属性空间的投影几乎失去区分度。

排查方法是打印一批特征的模长分布，正常应该在 1 附近，如果普遍小于 0.5 就说明归一化过头了。解决方式很简单，归一化只在入口做一次，要么在提取脚本里做，要么在 Dataset 里做，二者选一，并且在配置里写清楚。这类问题不会有报错，只能靠指标异常倒推，属于典型的玄学问题，踩过一次之后就长记性了。

5.3 GZSL 里未见类准确率接近零：先查校准偏置

现象是可见类准确率能到七八十，未见类只有个位数，H 值惨不忍睹。原因不是模型没学到东西，而是 GZSL 测试时可见类的得分天然偏高，模型倾向于把所有样本判成见过的类。这是零样本学习里的经典偏差，不加校准几乎必然发生。

解决方式是加 calibrated stacking，给可见类的得分减一个偏置gamma，在验证集上扫这个值。另一个思路是在训练时做样本均衡，让可见类和生成出来的未见类特征数量大致相当。判断有没有生效，看混淆矩阵里未见类那一列的召回，如果从个位数涨到三四十，说明校准起作用了；如果还是不动，那就得回去查生成特征的质量。

5.4 属性矩阵和标签错位：训练 loss 一路下降，测试全崩

现象是训练集上的分类准确率能到九十多，测试的时候未见类准确率接近随机。原因是属性矩阵的行顺序和标签 id 的映射错位了，训练时属性向量和类别对不上，模型学到的是一堆错误的关联。这种错位往往很隐蔽，因为训练 loss 照样下降，只是学到了错的东西。

排查方式是在 Dataset 初始化时加断言：拿几个已知类别的属性向量，检查它们的最近邻是不是同类。更直接的办法是打印每个类别 id 对应的属性向量前几维，人工核对一两个。解决方式就是前面 3.1 里那套统一索引，类别名到属性行号只映射一次，所有文件都用这一套，别在中间环节重新编号。

5.5 生成式方法模式坍塌：H 值卡在某个数不动

现象是生成式方法训练几十个 epoch 之后，H 值停在某个数附近来回晃，生成的未见类特征方差很小，几乎都长一个样。原因是判别器太强，生成器只能输出少数几种能骗过判别器的样本，多样性丢失。

解决方式有几个方向：降低n_critic，给判别器加梯度惩罚，或者提高分类损失那一项的权重。诊断手段是统计每个未见类生成特征的类内方差，跟真实可见类特征比，差一个数量级就说明坍塌了。这类问题在生成式方法里很常见，我一般会先跑一个小规模实验，把生成特征的方差曲线画出来，确认没坍塌再放大训练。

6. 二次开发：把类别体系换成自己的

把仓库跑通只是开始，真正有价值的是换成自己的类别。步骤其实不复杂，但每一步都得较真。

先整理类别清单，每个类给一个稳定的英文或拼音标识，这份清单就是后面所有文件的索引起点。然后是属性表，这是最费劲的一步。三种常见来源：手工定义一批可解释的属性维度，逐类打 0 到 1 的分；用词向量或句向量对类别名做编码；用视觉-语言模型把类别描述编码成向量。三者的取舍大致如下。

视觉特征那边，用骨干网络批量过一遍图片，存成.npy，注意跟属性表用同一套类别 id。划分文件自己抽，固定种子，落盘。到这里数据就齐了。

改造完先别急着看指标，做一次 sanity check：把未见类的样本也放进训练集，跑一遍普通分类，如果准确率能到九十以上，说明数据管线和标签映射都没问题；如果这一步就崩了，那后面的零样本指标没有意义。这个检查我每次换数据集都会做，能省掉大量无效调参。配置层面，换兼容函数只需要改configs/里的模型字段，换损失同理，评测脚本不用动，这是这套代码结构带来的最大便利。

这个 sanity check 的习惯是被坑出来的。早些年我拿到一份新特征，直接上零样本训练，指标难看，调了三天超参，最后发现是属性表和标签错位。从那以后我每次接新数据，都强制先跑一遍全类监督分类，确认管线通了再谈零样本。希望帮到你。

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