sgad-codebooks

该数据集是 k-means 码本的规范存储库，用于特征量化任务。数据集中包含了多个数据集（如 iPAD 和 PhysAD）的码本，这些码本由不同编码器（如 DINOv2、DINOv3、V-JEPA）提取的特征经过 k-means 聚类生成。码本文件按 <数据集>/<编码器+特征>_<几何类型>[_<构建变体>]/<属性>_img<S>_k<K>.pt 的路径组织。主要规范集包括：iPAD 的 DINOv2 绝对特征码本（16 个属性，图像尺寸 224，K 值为 8192 等），以及 PhysAD 的 DINOv2 绝对特征码本（22 个子集，图像尺寸 448，K 值为 512 和 8192）。此外，还包含其他变体，如余弦几何、DINOv3、V-JEPA 管状特征等。每个 .pt 文件存储了 centroids 和包含完整构建元数据（编码器、窗口、K 值、几何类型、数据版本）的 meta 字典。该数据集可通过 HuggingFace 公共镜像获得，无需登录即可下载。This dataset is a canonical repository of k-means codebooks for feature quantization tasks. It contains codebooks from multiple datasets (e.g., iPAD and PhysAD), generated by k-means clustering on features extracted by different encoders (e.g., DINOv2, DINOv3, V-JEPA). Codebook files are organized by the path <dataset>/<encoder+feature>_<geometry_type>[_<build_variant>]/<attribute>_img<S>_k<K>.pt. Main canonical sets include: iPAD DINOv2 absolute feature codebooks (16 attributes, image size 224, K=8192, etc.), and PhysAD DINOv2 absolute feature codebooks (22 subsets, image size 448, K=512 and 8192). Other variants include cosine geometry, DINOv3, V-JEPA tubular features, etc. Each .pt file stores centroids and a meta dictionary containing complete build metadata (encoder, window, K, geometry type, data version). The dataset is available via the HuggingFace public mirror and can be downloaded without login.

原始信息汇总

数据集概述

sgad-codebooks 是一个用于存储 k-means 码本（codebooks）的规范数据集仓库，由 sgad-iclr 组织发布。该仓库中的码本按“它们是什么”而非“由哪个实验生成”进行组织，所有码本以 .pt 文件形式存储，每个文件包含 centroids 和一个包含完整构建来源信息的 meta 字典（编码器、窗口、K、几何结构、数据版本）。

目录结构与命名规则

码本存放路径遵循以下格式：

codebooks/<数据集>/<编码器+特征><几何结构>[<构建变体>]/<属性>_img<S>_k<K>.pt

例如：ipad/dinov2abs_euc/ 表示 iPAD 数据集、DINOv2 绝对特征、欧几里得几何结构的码本集合。

主要码本集合

规范集合（当前方法使用）

数据集	目录	内容	用途
iPAD	ipad/dinov2abs_euc/	16 个属性，DINOv2 ViT-S/14 绝对令牌，img224，K8192（r01/r04/s01 附带 K512/1024/4096）	板级 abs-abs 码本
PhysAD	physad/dinov2abs_euc/	22 个子集，DINOv2 ViT-S/14，img448，K512+K8192	PhysAD abs-abs 码本（0.979 结果）

绝对码本与窗口无关，可直接跨窗口形状复用（自 2026-08-27 起，元数据校验跳过 abs 类工件的 num_frames/context_length 检查）。

其他集合

目录	内容
ipad/dinov2abs_cos/、ipad/dinov3abs_{euc,cos}/	几何结构 / DINOv3 筛选
ipad/vjepa21tub_euc/	V-JEPA2.1 块嵌入管状令牌，img224；sklearn 与 cuVS 采样构建混合（_cuvs/_cuvsFULL 文件名后缀）
ipad/vjepa21tub_euc_cuvsFULL/	管状令牌，cuVS 全池 k-means（含 fs8/）——t034a 集合
ipad/vjepa21tub_euc_fullpool/、ipad/vjepa21tub_legacy_t033/	小型遗留集合
physad/vjepa21tub_euc/	管状令牌 img448 K512，命名为 nf6c4fs4st2（t034 规范分支）
physad/vjepa21tub_euc_cuvsFULL/、physad/vjepa21tub_euc_early/	cuVS 重建 / 同一内容的早期构建
physad/vjepa21tub_probes/	一次性几何/上下文探测产物

注意：旧任务路径（dumps/）下的文件是指向此树的符号链接，以保证历史脚本可用；历史 *_metarelaxed.pt 文件属于任务碎片而非正式集合。

构建方法

所有码本由一个统一的构建脚本生成（见 sgad-ipad 仓库）：scripts/analysis/ipad/build_shallow_tubelet_codebook.py

• DINO 绝对特征使用 --timm-model <timm id> 参数
• V-JEPA 管状令牌使用 --variant 参数
• 标准调用方式为 --fast-extract --gpu-kmeans --stream-kmeans
• 不推荐使用遗留的 sklearn MiniBatchKMeans 构建脚本（在大 K 值下会退化）

共享与访问

本仓库即为公开镜像，规范集合（ipad/dinov2abs_euc、physad/dinov2abs_euc、ipad/vjepa21tub_euc_cuvsFULL、physad/vjepa21tub_euc）及本 README 以相同布局公开。筛选/遗留/探针集合仅在本地保留。

下载无需令牌或账户，可通过以下命令将数据下载到批量存储：

uvx hf download sgad-iclr/sgad-codebooks --repo-type dataset --local-dir /path/on/bulk/storage/codebooks

码本路径通过配置/命令行显式传递，因此目录树可放置在任何位置（但不能在仓库内或配额受限的家目录中）。

搜集汇总

数据集介绍

构建方式

在自监督表征学习与向量量化研究的脉络中，码本的规范化构建与统一存储成为支撑可复现实验的关键基础设施。sgad-codebooks数据集通过单一构建脚本scripts/analysis/ipad/build_shallow_tubelet_codebook.py统一生成所有k-means码本，该脚本支持通过--timm-model参数指定DINO系列模型的绝对令牌特征提取，并通过--variant参数适配V-JEPA管状嵌入变体，标准调用方式结合--fast-extract、--gpu-kmeans与--stream-kmeans以实现高效大规模聚类。每个.pt文件不仅保存centroids聚类中心，还内嵌包含编码器、窗口、K值、几何度量及数据版本等完整构建溯源信息的meta字典，镜像上仅发布规范集合，屏幕实验、遗留集与探针产物保留于本地。

特点

该数据集的核心特质在于其以“本质属性”而非实验来源组织码本的结构化分类体系，所有码本依据数据集名称、编码器与特征类型、几何度量及构建变体逐层归档。规范集合涵盖iPAD与PhysAD两个数据集上基于DINOv2 ViT-S/14绝对令牌的欧氏距离码本，其中iPAD提供16种属性、图像尺寸224、K8192及若干辅助K值，PhysAD则包含22个子集、图像尺寸448、K512与K8192的组合，后者对应0.979的评测结果。绝对令牌码本具备窗口无关性，自2026年8月27日起跨码本元数据校验跳过帧数与上下文长度检查，可直接跨窗口形状复用，显著提升迁移效率。

使用方法

使用该数据集时，研究者可通过Hugging Face平台以无令牌或账号限制的方式下载公共镜像sgad-iclr/sgad-codebooks，建议将码本树存放于大容量存储路径而非代码仓库或配额受限的主目录，下载命令采用uvx hf download并指定--repo-type dataset与--local-dir参数。由于码本路径通过配置文件或命令行参数显式传入，该树结构可灵活部署于任意位置，仅需确保从codebooks/目录向下可读。在新增或重建规范集合后，应使用hf upload命令将对应本地目录及README同步至镜像，保持相对路径一致，以维持规范集合的完整性与可追溯性。

背景与挑战

背景概述

在自监督视觉表征与智能异常检测的交叉领域，如何将稠密视觉特征凝练为可复用的离散码本，一直是提升检测效率与泛化能力的关键议题。sgad-codebooks数据集由sgad-iclr团队于2026年前后构建并持续维护，汇聚了面向iPAD与PhysAD两大基准的规范化k-means码本，涵盖DINOv2、DINOv3与V-JEPA2.1等多种编码器在不同几何度量与特征粒度下的产物。该数据集以“按本质而非实验”的组织逻辑，为绝对令牌与管状令牌的跨窗口复用提供了统一存储范式，其公开镜像与版本化构建流程对工业异常检测、表征离散化及跨任务迁移研究具有显著的基准价值。

当前挑战

该数据集所应对的核心领域挑战在于，工业异常检测场景中正常样本的分布建模需兼顾高维稠密特征的类内紧凑性与跨窗口、跨分辨率的通用性，而传统逐任务构建的码本在窗口形状变化时往往失效，导致重复计算与结果不可比。构建过程中则面临大规模K值下聚类退化、多编码器特征尺度与几何度量难以统一、以及历史任务碎片与规范化存储之间的路径兼容问题；同时，cuVS与sklearn等不同后端采样策略的混合使用，亦对码本元数据的一致性与可追溯性提出了严格要求。

常用场景

经典使用场景

在视觉异常检测与跨模态表征学习领域，sgad-codebooks作为k-means码本规范化仓库，其经典使用场景在于为基于DINOv2、V-JEPA等自监督编码器提取的绝对令牌特征提供统一、可复用的聚类中心集合。研究者可直接调用`ipad/dinov2abs_euc`或`physad/dinov2abs_euc`等规范集，将图像特征量化为离散码字，进而构建浅层管状码本表示，服务于无监督异常定位与分割任务。该数据集通过预构建的K8192等大规模码本，避免了重复训练聚类模型的算力开销，使特征量化流程标准化，成为方法迭代中稳定的特征离散化基础设施。

解决学术问题

该数据集有效解决了学术研究中码本构建可复现性差、跨窗口特征复用困难以及大规模聚类退化等常见问题。其预构建的绝对码本独立于时间窗口，研究人员得以跨不同窗口形状直接复用，消除了因窗口配置变动而重复聚类的不确定性。同时，明确摒弃在K值较大时易退化的MiniBatchKMeans旧脚本，采用cuVS与GPU加速的流式聚类，保障了码本质量与构建效率。通过存储完整构建溯源信息，该数据集增强了实验的可追溯性，为异常检测领域的方法比较与结果复现提供了可靠基准。

衍生相关工作

围绕sgad-codebooks衍生出一系列经典工作，包括基于DINOv2绝对令牌的iPAD与PhysAD异常检测流程、采用V-JEPA2.1管状特征的混合sklearn与cuVS构建方案，以及针对几何度量与编码器版本的系统性筛选研究。后续工作进一步拓展至DINOv3几何屏、V-JEPA2.1全池cuVS重建及早期构建对比，形成了从码本生成、特征量化到异常评分的完整方法链。这些工作不仅验证了跨编码器码本复用的可行性，也推动了浅层管状表示在自监督异常检测中的标准化进程。