--- title: Kaloscope3.0-preview canonical_url: "https://www.modelscope.cn/models/Heathcliff02/Kaloscope3.0-preview" md_url: "https://www.modelscope.cn/models/Heathcliff02/Kaloscope3.0-preview.md" repository: Heathcliff02/Kaloscope3.0-preview chinese_name: "Kaloscope-万花筒3.0预览版" last_updated: 2026-10-06 license: other pipeline_tag: vision-efficient-tuning tasks: - vision-efficient-tuning parameters: 156.3M tensor_type: - F32 library_name: - pytorch - safetensors language: - zh downloads: 8 stars: 0 tags: - computer-vision - image-classification - image-feature-extraction - image-retrieval - dinov3 - anime - art-style --- # Kaloscope3.0-preview > Kaloscope3.0-preview - Heathcliff02 在 ModelScope 开源的模型。Kaloscope 3.0 Preview Heathcliff02/Kaloscope3.0-preview 是 ModelScope 魔搭社区上的 156.3M 参数vision-efficient-tuning模型，采用 other 许可。 - **Repository**: Heathcliff02/Kaloscope3.0-preview - **License**: other - **Tasks**: vision-efficient-tuning - **Parameters**: 156.3M - **Tags**: computer-vision, image-classification, image-feature-extraction, image-retrieval, dinov3, anime, art-style - **Downloads**: 8 - **Stars**: 0 - **Last updated**: 2026-10-06 Source: https://www.modelscope.cn/models/Heathcliff02/Kaloscope3.0-preview --- # Kaloscope 3.0 Preview Kaloscope 3.0 Preview 是面向动漫插画的画师识别、图像表征与风格检索模型。模型以 DINOv3 ViT-B/16 为基础，利用已有画师标注和图像发布时间学习视觉相似度，输出 256 维检索向量；新增的 v1 分类版本在冻结表征后训练线性分类头，可直接输出 44,129 位画师的分类分数。 本次初版对应全量训练的第 **46,000 步最佳检查点**。它可以用于相似插画检索、参考图库匹配，以及基于带标注图库的画师候选检索。原始 `best.pt` 不含分类头；现新增 [v1 画师分类版本](v1-artist-classifier/README.md)，在冻结此主干与投影头后，另行训练 44,129 类画师线性分类头。 ## 模型概述 | 项目 | 配置 | | --- | --- | | 版本 | 3.0 Preview；2026-10-06 增补 v1 画师分类头 | | 基础模型 | DINOv3 ViT-B/16，LVD-1689M 预训练权重 | | 输入 | RGB，短边等比例缩放至 512，再中心裁剪为 512×512 | | 主干图像表征 | CLS token 与 patch token 均值拼接，1536 维 | | 投影头 | Linear(1536,1536) → GELU → Linear(1536,256) | | 推荐检索向量 | 投影头输出，256 维，经 L2 归一化后计算余弦相似度 | | 分类头 | 原始 `best.pt` 无；新增 `v1-artist-classifier/` 提供 44,129 类分类头 | | 参数量 | 原始表征模型 88,423,938；含分类头 156,250,211（含训练温度与偏置） | | 发布候选 | `sigmoid_year_v1_20261002/best.pt`，step 46000 | | 代码 | [kaloscope-dinov3](https://github.com/Chenkin-x/kaloscope-dinov3)，本说明核对版本 `95ade97` | ## 与历史版本的关系 [Kaloscope 2.0](https://huggingface.co/heathcliff01/Kaloscope2.0) 采用 LSNet，面向固定画师类别输出分类概率。3.0 Preview 改用 DINOv3 图像编码器和相似度学习，支持为新增图库提取向量，建立或扩充检索索引。 旧版模型卡报告的 90.13% 是分类 Top-1；本说明分别报告原始表征的图库检索指标和新增分类头的闭集分类指标。历史版本与本版的数据、类别范围和评估协议不同，不能据此计算版本提升幅度。本分类版本需使用配套标签表及支持分类输入归一化的插件，不能沿用旧版 LSNet 配置。 ## 训练数据与配对策略 本次使用本地 Danbooru2026 数据，经既有筛选、去重及作品族划分后，参与训练的样本共 **6,569,159 张**。监督信息来自已有单画师标注、发布时间和年份分组；没有额外生成标签或合成训练图像。 采样同时覆盖完整训练数据和稀疏画师：一半锚点按全量数据遍历，另一半按画师及年份组均衡采样，再为锚点配对图像。年份组用于采样均衡；正负关系仍按每对图像的时间差判断。 - **正样本**：同画师、发布时间相差不超过 365 天，且属于不同作品族。 - **负样本**：不同单画师，且属于不同作品族。 - **忽略**：图像自身、同作品族，以及同画师但时间相差超过 365 天的配对。 - 缺少合格正样本的锚点仍被保留，其显式配对使用不同画师样本，不把该配对伪装成正样本。 发布时间是创作时期的代理，可能与实际绘制时间不同。“同画师、近时间”是风格弱监督信号，不是人工验证的风格相同标签。不同画师也可能具有相似风格，因此此目标仍带有画师身份偏置。 预处理包括 EXIF 方向校正、透明背景合成到白色、转为 RGB、短边缩放和中心裁剪。编码器内部执行 ImageNet 均值/标准差归一化。正式版本未使用随机裁剪或拉伸；中心裁剪仍可能截去长宽比极端图像的边缘内容。 ## 训练配置 | 项目 | 数值 | | --- | --- | | GPU | 8× NVIDIA H100 80GB | | 精度 | BF16 混合精度 | | Batch size | 每卡 256，全局真实配对池 2048 | | 优化器 | AdamW | | 初始学习率 | 主干 2e-5；投影头 2e-4；温度与偏置 1e-3 | | 权重衰减 / 梯度裁剪 | 0.05 / 1.0 | | Warmup | 1000 步 | | 可训练主干范围 | 最后 4 个 Transformer block（8–11）及最终归一化层 | | 随机种子 | 20261004 | | 检查点选择 | 开发集跨内容、按画师宏平均的 temporal Hit@10 | | 结束状态 | 第 52,000 步触发验证集平台期早停，完整运行约 32 小时 | 训练采用带可学习温度和偏置的成对 sigmoid 损失。令归一化图像向量为 `z`，有效配对标签为 `y∈{+1,-1}`，则每个 batch 的损失为： ```text sum_valid_pairs softplus(-y_ij * (temperature * cosine(z_i, z_j) + bias)) / global_batch ``` ## 模型表现 以下为 **step 46000 的 256 维投影向量**在固定开发集上的结果，使用 L2 归一化和余弦相似度排序。 | 指标 | 结果 | | --- | ---: | | 常规图库画师检索 Top-1 | 95.23% | | 跨内容图库画师检索 Top-1 | 83.29% | | 常规图库 temporal Hit@10 | 96.50% | | 跨内容 temporal Hit@1 | 60.86% | | 跨内容、按画师宏平均 temporal Hit@10（选模指标） | 87.78% | **评估范围与指标定义：** - Gallery 共 16,217 张，来自训练划分；常规评估有 1,972 个有效开发集 query，覆盖 512 位训练中见过的画师。 - 跨内容评估有 1,137 个有效 query，覆盖 365 位画师。query 与候选必须都有角色和作品标注，并且角色标签无交集、作品标签无交集。它衡量基于现有标签过滤后的跨内容检索，不保证图像所有语义内容完全不同。 - 画师 Top-1：最高相似度候选与 query 的画师相同。它不是分类头准确率，也不要求该候选满足近年份约束。 - Temporal Hit@K：前 K 个候选中至少一个与 query 同画师且发布时间相差不超过 365 天。 - 宏平均先在每位画师内部计算命中率，再对画师平均。只统计候选足够且存在合格 temporal 正样本的 query，因此这些指标不能代表没有近年参考图的查询。 同一面板上，原始 DINOv3 主干的常规画师 Top-1 为 31.85%，跨内容画师 Top-1 为 10.38%，跨内容宏平均 temporal Hit@10 为 18.18%。此对照比较的是原始主干特征与微调后的投影特征，表征维数也不同。 ### kNN 画师投票评估 在上述固定面板上，进一步测试了不同邻居数的画师标签投票。kNN 是基于参考图库的检索与投票，不会为模型添加训练过的分类头。下表均使用主线 **256 维投影向量**。 | 邻居数 k | 常规：均匀投票 | 常规：相似度加权 | 跨内容：均匀投票 | 跨内容：相似度加权 | | --- | ---: | ---: | ---: | ---: | | 1 | 95.23% | 95.23% | 83.29% | 83.29% | | 5 | 95.99% | 96.45% | 82.15% | **84.08%** | | 10 | **96.10%** | 96.60% | 78.63% | 83.55% | | 20 | 95.59% | **96.65%** | 70.89% | 81.62% | 表中为查询图像的画师预测正确率。均匀投票平票时，选择距离最近的并列画师；相似度加权使用固定权重 `exp(cosine / 0.07)`。四种 k 的有效查询数相同：常规 1,972 张、跨内容 1,137 张；沿用前述有效 query 条件，k=20 另外要求至少 20 个允许候选。 跨内容条件下，加权 k=5 在本次设置中表现最好；继续扩大邻域会混入更多其他画师。可将 **256D + 余弦相似度 + 加权 k=5** 作为应用验证的起点，但这一选择尚未经过独立测试或显著性验证。 ### KMeans 聚类评估 采用**球面 KMeans**：图像向量先做 L2 归一化，以余弦相似度分配簇，每轮重新归一化中心。只使用 16,217 张 gallery 图像拟合中心，再对 1,972 张开发集 query 分配簇。画师及年份组标签不参与中心拟合，只用于事后评估；画师预测时，每个簇的画师身份由 gallery 的多数标签决定。 簇数测试 128、256、512、1024，每种使用随机初始化种子 11、22、33，最多迭代 100 轮。三种表征共 **36 组全部收敛**。512 簇是参照本面板画师数量的诊断设置，不是自动发现的最优风格数量。 **512 簇下的表征比较**（三个种子的均值 ± 样本标准差）： | 表征 | Query 画师 ARI | Query 画师 AMI | Gallery 簇标签映射后的 query 画师准确率 | | --- | ---: | ---: | ---: | | 原始 DINOv3 主干，1536D | 0.1026 ± 0.0047 | 0.1781 ± 0.0049 | 13.78% ± 0.50 个百分点 | | 主线主干，1536D | 0.5997 ± 0.0157 | 0.6977 ± 0.0119 | 70.33% ± 1.41 个百分点 | | **主线投影，256D** | **0.7670 ± 0.0177** | **0.8343 ± 0.0087** | **82.78% ± 1.58 个百分点** | ARI 与 AMI 衡量聚类和画师标签的一致程度，并校正随机一致性；越高表示越接近标签分组，不能解释为人工风格评分。 **主线 256D 在不同簇数下的结果**（三个种子的平均值）： | 簇数 | Query 画师 ARI | Query 画师纯度 | 簇映射后的 query 画师准确率 | Query 年份组 ARI | Gallery 余弦轮廓系数 | | --- | ---: | ---: | ---: | ---: | ---: | | 128 | 0.2399 | 33.13% | 22.33% | 0.1570 | 0.0732 | | 256 | 0.4554 | 56.34% | 47.67% | 0.3120 | 0.1114 | | 512 | 0.7670 | 85.70% | 82.78% | 0.5630 | **0.1662** | | 1024 | **0.7711** | **95.96%** | **93.32%** | **0.6602** | 0.1239 | 纯度用 query 标签统计每个簇的多数画师占比，仅作为评估指标；它通常随簇数增大而上升，不宜单独用于选择簇数。轮廓系数在固定抽取的 2,048 张 gallery 图像上计算。增加到 1024 簇提高了画师识别及年份组一致性，但画师 ARI 增幅有限、轮廓系数下降，因此不能据此声称整体分组更自然。 512 簇与 1024 簇的不同初始化之间，query 分配的平均 ARI 分别为 0.7228、0.7492，局部簇边界仍有变化。部署时应保存拟合中心；本面板的簇数也不能直接套用到全量数万画师图库。 ### 聚类可视化 ![主线 256 维特征的 KMeans 聚类：左侧 512 簇，右侧 1024 簇](assets/kmeans_256d_comparison.png) [高清 PNG](assets/kmeans_256d_comparison.png) · [SVG 版本](assets/kmeans_256d_comparison.svg) 每个点是一张图像，合计 18,189 张；同色表示同簇，左右颜色编号各自独立。两幅图共享同一套坐标：归一化的 256D 特征经 PCA 降到 50 维，再用 t-SNE 投影到二维（随机种子 42，perplexity 40，1000 次迭代）。gallery 和 query 共同参与的仅是这一步可视化，query 没有参与原始 KMeans 中心拟合。 图中展示的是**聚类种子 11 的单次结果**：512 簇画师 ARI 为 0.781、簇映射准确率为 83.37%；1024 簇分别为 0.775、93.46%。它们与上表三个种子的平均值口径不同。聚类来自原始 256 维空间，二维图上的间距、岛状结构不能直接解释为真实风格距离或天然风格类别。 上述结果支持主线表征具有较强的**画师相关分组能力**，尚未通过人工图像审阅验证跨画师的纯风格聚类效果。年份组也只是元数据分组，不等同于已确认的风格阶段。评估仍限于训练已见画师的开发面板，未使用封存测试集。 ## 原始表征模型使用方法 安装本项目的 PyTorch 推理依赖，在仓库根目录执行下列示例。以下示例针对根目录的原始 `best.pt`，使用项目内 `dinov3.finetune.temporal.model.Encoder` 提取表征。新增分类模型的 ComfyUI 用法见后文；两种文件均不是通用 Transformers 分类 Pipeline 格式。 ```bash git clone https://github.com/Chenkin-x/kaloscope-dinov3.git cd kaloscope-dinov3 # 安装与本机 CUDA 匹配的 torch/torchvision，再安装以下依赖 pip install numpy Pillow omegaconf ``` 下面的示例对应训练产物 `best.pt` 格式，其中包含 `model_config` 和 `model`。若上传时转换为 safetensors，需要同时提供配置并调整加载代码。 ```python import numpy as np import torch import torch.nn.functional as F from torchvision import transforms from dinov3.finetune.data import rgb_loader from dinov3.finetune.temporal.model import Encoder device = "cuda" if torch.cuda.is_available() else "cpu" # 训练检查点含优化器/RNG等状态；仅加载自己训练或可信来源的文件。 checkpoint = torch.load("best.pt", map_location="cpu", weights_only=False) config = dict(checkpoint["model_config"]) config["weights"] = None # 完整微调权重已在检查点内，无需重新下载基础权重 model = Encoder(config, initialize=False) model.load_state_dict(checkpoint["model"], strict=True) model = model.to(device).eval() spatial = transforms.Compose([transforms.Resize(512), transforms.CenterCrop(512)]) @torch.inference_mode() def encode(path): image = spatial(rgb_loader(path)) x = torch.from_numpy(np.array(image, copy=True)).permute(2, 0, 1) # uint8、0..255；Encoder 内部归一化，外部不要重复 Normalize。 output = model(x.unsqueeze(0).to(device)) backbone = F.normalize(output[:, :1536].float(), dim=-1) embedding = F.normalize(output[:, 1536:].float(), dim=-1) return embedding, backbone query, _ = encode("query.png") reference, _ = encode("reference.png") print("cosine similarity:", (query @ reference.T).item()) ``` `Encoder.eval()` 的原始输出是 **1792 维**拼接张量：前 1536 维是主干特征，后 256 维是投影向量；请拆分后分别归一化。上述公开指标使用后 256 维，不是整个拼接张量。温度和偏置是训练参数，余弦检索不需要应用它们。 已在 PyTorch 2.11.0+cu128 环境中用正式 `best.pt` 和真实图像验证：权重严格加载全部匹配，输入 `[1,3,512,512]`，输出 `[1,1792]`，拆分后的投影向量为 `[1,256]`，数值有限且归一化后范数为 1。详细记录见 [inference_verification.json](inference_verification.json)。 建立图库时，为所有参考图保存同一版本的向量以及对应画师、图像 ID 等元信息，再按相似度检索。相似度值不是校准后的画师置信度或风格概率；拒识阈值、多个参考图的画师聚合规则需要在实际业务数据上单独验证。不同模型版本生成的向量应重建索引，不能直接混用。 ## 适用范围与限制 本版主要服务于动漫插画的参考图检索和表征研究。模型可能利用配色、题材、构图及画师相关线索；跨内容评估只能部分约束这些混淆，尚不能声称完全解耦风格和内容。照片、设计图、漫画页面、强裁剪、灰度输入及罕见风格的效果不包含在上述验证结论中。 检索画师候选依赖图库覆盖度，分类候选受 44,129 类输出范围限制；两者均不能用于作品归属的确定性判断。新增分类版本与兼容插件要求见下节；本版未提供生成模型或 IP-Adapter 接口。推理延迟和部署显存尚未单独基准测试。 ## v1 画师分类头（2026-10-06） [v1-artist-classifier/](v1-artist-classifier/README.md) 提供完整的纯推理 safetensors 模型，包含 v1 第 **46,000 步主干**、原有风格投影头和新增的 **44,129 类画师分类头**，无需另行合并 `best.pt`。分类头采用第 **26 轮**最佳检查点；训练期间主干和风格投影头均冻结，因此原有 256 维风格特征保持不变。 ### 分类结构与训练 分类头使用 1536 维 CLS + mean patch 特征，经 **FP32 L2 归一化并乘以 √1536** 后送入 `Linear(1536, 44129)`。这一预处理只作用于分类分支，原有风格投影头仍接收未经此归一化的主干特征。 ```python head_input = torch.nn.functional.normalize(pooled_features.float(), dim=-1) * (1536 ** 0.5) logits = head(head_input) scores = logits.float().softmax(dim=-1) ``` | 项目 | 配置 | | --- | --- | | 训练范围 | 仅分类头；冻结主干与风格投影头 | | 训练样本 | 1,850,168 张，按各画师最近年份组选取 | | 输出类别 | 44,129 位训练集画师，类别顺序见 `class_mapping.csv` | | 优化器 | AdamW，初始学习率 0.003，weight decay 0.01 | | 损失 | 交叉熵，label smoothing 0.1；类别权重为训练数量平方根的倒数并均值归一化 | | Batch size | 2048（4 GPU × 每卡 512） | | 随机种子 | 20261006 | | 检查点选择 | 开发集按画师宏平均 Top-1，最小改进阈值 0.001；选中 epoch 26 | ### 分类评估 | 开发集指标 | 结果 | | --- | ---: | | Top-1 | **88.6738%** | | Top-5 | **93.3933%** | | 按画师宏平均 Top-1 | **86.7614%** | 评估包含 **39,369 张图、17,485 位画师**，每次预测在全部 44,129 个输出类别之间竞争。另有 **26,644 类没有近期开发集样本**，因此这些结果不能表述为所有 44,129 位画师均已得到独立验证。训练与开发集按作品族隔离；封存的 5% 测试集未使用。分类开发集参与了选模，不能替代独立测试。 这里的分类准确率与前文依赖参考图库的检索 Top-1 不同，不能直接比较。分类输出是**未经校准的闭集 softmax 分数**，没有未知画师拒识机制；少样本画师效果明显弱于样本充足的画师。 ### 下载与 ComfyUI 使用 | 用途 | 权重与配置 | 输出 | | --- | --- | --- | | 原始表征模型 | 根目录 `best.pt` + `config.json` | 风格与主干特征，无分类头 | | v1 分类模型 | `v1-artist-classifier/` 下的三个文件 | 44,129 类画师分数，并保留原有风格特征 | 分类模型请下载以下三个文件，放入同一个文件夹： ```text ComfyUI/models/kaloscope/kaloscope3-v1-artist/ ├── model.safetensors ├── config.json └── class_mapping.csv ``` - [完整推理权重](v1-artist-classifier/model.safetensors)（约 625 MB） - [分类模型配置](v1-artist-classifier/config.json) - [画师类别映射](v1-artist-classifier/class_mapping.csv) **插件必须包含 [推理修正 PR #6](https://github.com/spawner1145/comfyui-kaloscope/pull/6)**，支持 `classifier_input_normalization: "l2_sqrt_dim"`。旧加载器会忽略该字段，直接将原始特征送入分类头，无法复现正确的分类输出。已验证插件提交为 `8315d80ad58347ea119ffe7e415af2e6a42a6463`；使用该修正版的方法见[分类模型安装说明](v1-artist-classifier/README.md)。 在 Kaloscope 模型加载节点选择上述目录，再使用画师推理节点。特征提取节点默认仍输出 256 维风格向量，也可选取 1536 维主干特征。输入沿用 EXIF 校正、透明白底合成、短边等比例缩放至 512 后中心裁剪，禁止拉伸；ImageNet 归一化由插件预处理完成。 根目录和分类子目录的 `config.json` 指向不同权重，请勿混用。模型包不包含训练图像、优化器或特征缓存。 ### 导出与兼容性验证 - 插件 38 项回归测试通过，权重严格加载，类别映射与训练输出顺序一致。 - 8 张真实图像的 FP32/BF16 Top-5 均与原训练实现一致；BF16 logits 和投影输出完全一致，FP32 最大 logits 差异约 0.000039。 - 1,024 个开发集缓存特征的分类 logits 完全一致。若省略分类归一化，其中 12 个 Top-1 预测会改变。 上述检查用于验证导出与推理一致性，不是重新进行全量性能评估。详见 [验证记录](v1-artist-classifier/inference_verification.json) 和 [权重来源与 SHA-256](v1-artist-classifier/provenance.json)。原有检索评估及聚类图仍对应 v1 表征。 ## 许可与引用 本模型基于 Meta DINOv3 微调，随附 [DINOv3 License](LICENSE.md)；使用和再分发遵循该协议。请同时阅读[官方协议](https://ai.meta.com/resources/models-and-libraries/dinov3-license/)。训练图像及其相关权利不随模型说明或权重许可转授。 基础模型与方法：[DINOv3 官方仓库](https://github.com/facebookresearch/dinov3)、[DINOv3 论文](https://arxiv.org/abs/2508.10104)。历史版本：[Kaloscope 2.0 模型说明](https://huggingface.co/heathcliff01/Kaloscope2.0)。 ## 更新记录 - 2026-10-06：新增 v1 的 44,129 类冻结主干分类头，提供完整 safetensors、配置、标签映射、分类开发集指标与插件推理修正说明。 - 基础架构更新为 DINOv3 ViT-B/16，输入分辨率 512×512。 - 使用画师与近时间图像配对学习，输出 256 维检索向量。 - 提供常规与跨内容开发集检索结果，保留独立封存测试集。 - 补充 kNN 投票、三种表征的多簇数 KMeans 对照，以及 512/1024 簇二维可视化。 - 初版选用全量训练 step 46000 检查点；后续消融通过验证后再单独更新版本。