google-research graph_embedding/metrics无监督嵌入质量评估指标库实战指南【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research本指南围绕 google-research 仓库中的 graph_embedding/metrics 模块展开该模块是论文《Unsupervised Embedding Quality Evaluation》arXiv:2305.16562的官方实现提供一套无需标签即可评估嵌入embedding表示质量的指标集。读完本文你将掌握该库的安装运行方式、七个核心指标的数学定义与源码实现细节、合成测试用例的行为解读以及如何在自监督学习SSL场景下用它检测表示坍缩representation collapse等退化现象。模块定位为什么需要无监督的嵌入质量评估在自监督学习Self-Supervised LearningSSL中模型学到的嵌入往往缺乏标签监督信号评估其质量是个经典难题。传统的做法需要借助下游任务线性探测、KNN 分类等间接衡量成本高且依赖任务选择。而 graph_embedding/metrics 提供了一套纯无监督的评估方案只输入嵌入矩阵本身dense matrix即可从谱结构、秩、行向量几何特性等多个角度量化表示质量从而在没有标注数据的情况下判断嵌入是否发生坍缩即所有样本被映射到同一个点或极低维子空间导致信息丢失嵌入的有效维度/秩是否合理嵌入的各向异性与谱衰减程度如何嵌入的簇结构是否清晰。从仓库结构看graph_embedding 目录下还包含 dmon、ddgk、huge、monet、persona、slaq、watch_your_step 等多个图嵌入相关子项目而 metrics 模块作为独立库存在可被任何嵌入方法复用。快速上手运行官方示例仓库在 graph_embedding/metrics/README.md 中给出了唯一一条运行命令。在仓库根目录执行# 从 google-research/ 根目录运行 python3 -m graph_embedding.metrics.example运行后程序会依次打印论文中使用的所有指标值。该命令实质上是执行 graph_embedding/metrics/example.py其运行逻辑如下构造三组合成数据作为测试用例zeros、ones、random对每组数据调用report_all_metrics批量计算全部指标按指标名排序后以case_name metric_name: value的格式逐行输出每组之间用*分隔。可调参数absl flags从 example.py 的源码可以看到两个命令行参数Flag类型默认值说明--n_pointsint1024嵌入矩阵的行数样本数 / 聚类数lower_bound0--n_dimsint128嵌入矩阵的列数特征维度lower_bound0例如想用 512 个样本、64 维嵌入验证指标表现可运行python3 -m graph_embedding.metrics.example --n_points512 --n_dims64批量计算入口report_all_metrics 与 SVD 预计算graph_embedding/metrics/metrics.py 是全部指标实现的载体核心入口是report_all_metrics(tensor)metrics.pydef report_all_metrics(tensor): Computes all metric values given a tensor and its SVD. # Pre-compute SVD for metric computations. u, s, _ np.linalg.svd(tensor, compute_uvTrue, full_matricesFalse) fns [ rankme, coherence, pseudo_condition_number, alpha_req, stable_rank, ne_sum, self_clustering, ] return dict((fn.__name__, fn(tensor, uu, ss)) for fn in fns)该函数有两个关键设计一次性预计算 SVD先对输入矩阵做一次np.linalg.svd(tensor, compute_uvTrue, full_matricesFalse)得到左奇异向量u与奇异值向量s再分发给各指标函数复用避免每个指标重复做分解大幅降低计算开销统一的函数签名约定所有指标函数都遵循(tensor, sNone, uNone, epsilon1e-12, **_ )的可选参数约定——调用方可以传入预计算的奇异值s或左奇异向量u以复用未传入时各函数会自行调用 SVD 兜底例如pseudo_condition_number在s is None时执行np.linalg.svd(tensor, compute_uvFalse)epsilon为数值稳定性常数默认1e-12用于防止除零或对数零值。返回值是一个Mapping[str, float]键为指标函数名值为对应指标值便于直接序列化或接入下游分析。七大指标逐一详解以下七个指标构成了论文《Unsupervised Embedding Quality Evaluation》的完整评估体系全部实现在 metrics.py 中。1. RankMe有效秩出处Garrido 等人《RankMe: Assessing the Downstream Performance of Pretrained Self-Supervised Representations by Their Rank》arXiv:2210.02885源码注释见 metrics.py。源码实现def rankme(tensor, sNone, epsilon1e-12, **_): if s is None: s np.linalg.svd(tensor, compute_uvFalse) p_ks s / np.sum(s epsilon) epsilon return np.exp(-np.sum(p_ks * np.log(p_ks)))原理先将奇异值归一化为概率分布p_ks并加epsilon保证非零再计算其香农熵的指数形式。直观理解若嵌入的各奇异值大小相近熵最大RankMe 值接近嵌入维度d表示信息分散、秩高若奇异值高度集中如坍缩到单一方向熵很小RankMe 接近 1。该指标可直接用于筛选预训练模型——RankMe 高通常意味着下游任务表现更好。2. Coherence一致性 / 相干性源码实现metrics.pydef coherence(tensor, uNone, **_): if u is None: u, _, _ np.linalg.svd(tensor, compute_uvTrue, full_matricesFalse) maxu np.linalg.norm(u, axis1).max() ** 2 return maxu * u.shape[0] / u.shape[1]原理基于左奇异向量矩阵u的行范数最大值。先求每行的L2范数并取最大者平方再乘以行数 / 列数作为归一化。该指标度量奇异向量在样本上的集中程度若某些奇异向量被少数样本主导行范数异常大Coherence 值偏高提示嵌入中存在极端样本或数据结构上的不均匀分布。3. Pseudo-condition number伪条件数源码实现metrics.pydef pseudo_condition_number(tensor, sNone, epsilon1e-12, **_): if s is None: s np.linalg.svd(tensor, compute_uvFalse) return s[-1] / (s[0] epsilon)原理取最小奇异值与最大奇异值之比分母加epsilon防止除零。经典条件数是s[0] / s[-1]越大越病态本指标取倒数形式值越接近 1 表示矩阵越各向同性、数值越稳定值接近 0 则说明最小奇异值远小于最大奇异值嵌入在某个方向上几乎坍缩。它衡量的是嵌入协方差谱的动态范围是对表示病态程度的快速诊断。4. Alpha-ReQ谱衰减指数出处Agrawal 等人《α-ReQ: Assessing representation quality in self-supervised learning by measuring eigenspectrum decay》NeurIPS 2022源码注释见 metrics.py。源码实现def alpha_req(tensor, sNone, epsilon1e-12, **_): if s is None: s np.linalg.svd(tensor, compute_uvFalse) n s.shape[0] s s epsilon features np.vstack([np.linspace(1, 0, n), np.ones(n)]).T a, _, _, _ np.linalg.lstsq(features, np.log(s), rcondNone) return a[0]原理将奇异值加epsilon后取对数对一条从 1 到 0 线性递减的斜坡linspace(1, 0, n)做最小二乘线性回归返回回归系数a[0]即斜率。该斜率刻画了特征谱的衰减速度绝对值越大说明奇异值从大到小衰减越快、信息越集中于少数主方向谱越尖接近 0 则谱相对平坦。论文中该指标与下游表示质量有较强的相关性可作为预训练质量的离线判据。5. Stable rank稳定秩源码实现metrics.pydef stable_rank(tensor, sNone, epsilon1e-12, **_): if s is None: s np.linalg.svd(tensor, compute_uvFalse) trace np.square(tensor).sum() denominator s[0] * s[0] epsilon return trace / denominator原理由矩阵分析中的经典概念而来。trace(tensor²)等于所有奇异值平方之和即 Frobenius 范数平方除以最大奇异值平方后得到的是一个对奇异值微小扰动不敏感的有效秩——它等于Σ sᵢ² / s₁²取值范围在 1完全坍缩到嵌入维度之间。相比硬秩非零奇异值个数稳定秩能平滑地反映实际起作用的维度有多少即使奇异值不为 0 也能捕捉到维度的虚胖。6. NESum归一化特征谱和出处He Ozay《Exploring the Gap between Collapsed Whitened Features in Self-Supervised Learning》ICML 2022具体见论文 Definition 4.1源码注释见 metrics.py。源码实现def ne_sum(tensor, epsilon1e-12, **_): cov_t np.cov(tensor.T) ei_t np.linalg.eigvalsh(cov_t) epsilon return (ei_t / ei_t[-1]).sum()原理先计算嵌入的协方差矩阵np.cov(tensor.T)维度为d×d用eigvalsh求出其特征值已升序排列加epsilon后以最大特征值ei_t[-1]做归一化再求和。该指标衡量协方差谱的平坦程度若所有特征值大小接近比值之和接近维度d表示白化程度高、表示信息充分若仅少数特征值占主导比值之和接近 1表示嵌入塌缩进低维子空间。论文用它刻画 SSL 中坍缩 vs 白化两个极端之间的连续状态。7. SelfCluster自聚类指标源码实现metrics.pydef self_clustering(tensor, epsilon1e-12, **_): tensor tensor epsilon tensor / np.linalg.norm(tensor, axis1)[:, np.newaxis] n, d tensor.shape expected n n * (n - 1) / d actual np.sum(np.square(tensor tensor.T)) return (actual - expected) / (n * n - expected)原理这是唯一一个不依赖奇异值、而是直接分析行向量几何关系的指标。步骤为先对每行做L2归一化加epsilon防除零再计算样本间的 Gram 矩阵tensor tensor.T并求所有元素平方和作为actual。expected是对各样本方向随机均匀分布这一零假设下actual的期望值对角项贡献n非对角项在d维球面上均匀分布时的期望为n(n-1)/d。最终结果将实际值相对于期望值做归一化范围约为 01接近0行向量方向接近均匀随机无多余簇结构对随机高斯嵌入通常如此接近1行向量高度一致全部同向表示嵌入坍缩或过度聚集。合成测试用例的行为解读example.py 构造了三组具有代表性的合成数据来演示指标行为cases { zeros: np.zeros((_N_POINTS.value, _N_DIMS.value)), ones: np.ones((_N_POINTS.value, _N_DIMS.value)), random: np.random.randn(_N_POINTS.value, _N_DIMS.value), }结合 metrics.py 的数学定义从源码逻辑可以推断三组用例各自的预期语义zeros全零矩阵代表极端坍缩的退化输入。所有奇异值为 0stable_rank约为 0self_clustering经epsilon扰动与行归一化后各行方向几乎一致值趋近 1rankme因概率分布集中于 epsilon 级数值而极低。它对应模型把一切映射到原点的最坏情况。ones全一矩阵代表秩为 1 的退化输入。所有样本是同一个方向向量仅有一个非零奇异值stable_rank d / n默认 1024×128 下约为 0.125、ne_sum接近 1、self_clustering接近 1。它对应模型把所有样本映射到同一方向的典型坍缩。random标准正态随机矩阵代表良态、高秩输入。以大概率满秩且各奇异值相对均匀rankme、stable_rank接近嵌入维度dne_sum接近dself_clustering接近 0伪条件数相对接近 1。它是理想表示的对照基准。因此运行示例程序不仅能验证库可用性也相当于一次指标的标定实验把真实嵌入的各项数值与上述三组基线的位置对比即可快速判断其质量区间。在自监督学习实践中的使用方式结合论文主题与源码结构该库的典型用法可以归纳为三类模型筛选在预训练多个候选模型后无需标注即可对各自的嵌入调用report_all_metrics用rankme、stable_rank、ne_sum等指标挑选信息量最充分的模型再对少数入选者做下游微调。坍缩监测在训练过程中周期性抽取嵌入批量计算self_clustering与pseudo_condition_number一旦self_clustering攀升、伪条件数趋近 0即可提前发现表示坍缩及时调整损失或正则化项。可复用的库接口由于report_all_metrics只接受一个numpy稠密矩阵任何产出(n_samples, d_dims)嵌入张量的系统图嵌入、视觉 SSL、文本表示等都可以直接调用。注意该库不依赖 TensorFlow/JAX仅需要numpy接入成本极低。引用与联系方式如果你在研究中使用了这些指标README 要求引用以下论文Tsitsulin, A., Munkhoeva, M., Perozzi, B., (2023). Unsupervised Embedding Quality Evaluation. arXiv preprint arXiv:2305.16562.BibTeX照录自 README.mdarticle{tsitsulin2023unsupervised, title{Unsupervised Embedding Quality Evaluation}, author{Tsitsulin, Anton and Munkhoeva, Marina and Perozzim Bryan}, journal{arXiv preprint arXiv:2305.16562}, year{2023} }此外metrics.py 源码注释中还引用了三个构成指标来源的关键工作RankMeGarrido 等arXiv:2210.02885、NESumHe OzayICML 2022、α-ReQAgrawal 等NeurIPS 2022如需深入理解各指标的推导可查阅对应论文。对实现有疑问或建议可按 README.md 中的信息联系作者 antontsitsul.in 或 bperozzigoogle.com。小结graph_embedding/metrics 是一个轻量、纯 numpy 实现、接口统一的无监督嵌入质量评估库report_all_metrics一次 SVD 计算七个指标example.py提供开箱即用的标定演示。无论你是研究自监督表示学习、图嵌入还是需要在无标签场景下监控表示质量这套指标集都能作为可靠、可复现的离线评估工具直接落地。【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
