# Kaloscope 3.0 Preview — v1 画师分类版本

本目录包含完整主干、风格投影头和 44,129 类画师分类头的 FP32 safetensors 权重（约 625 MB），不含优化器、训练缓存或原始图像。许可沿用根目录 [DINOv3 License](../LICENSE.md)。

## 安装到 ComfyUI

需先安装包含分类归一化修正的 [comfyui-kaloscope](https://github.com/spawner1145/comfyui-kaloscope) 版本。对应修正为 [PR #6](https://github.com/spawner1145/comfyui-kaloscope/pull/6)，已验证提交 `8315d80`。PR 合并前，可在插件目录运行以下命令使用经过验证的修正版，然后重启 ComfyUI：

```bash
git fetch https://github.com/222222222l/comfyui-kaloscope.git fix/dinov3-normalized-artist-head
git switch --detach 8315d80
```

若插件目录有本地修改，请先自行保存；合并后可更新插件主分支使用。

将本目录的以下三个文件下载到同一个目录，例如 `ComfyUI/models/kaloscope/kaloscope3-v1-artist/`：

- `model.safetensors`：完整推理模型，无需原始 `best.pt`。
- `config.json`：架构、512 输入、池化、分类归一化和权重文件选择。
- `class_mapping.csv`：`class_id,class_name`，严格对应 44,129 个输出的顺序。

在 Kaloscope 模型加载节点选择该目录，使用画师推理节点输出分类结果。特征节点默认仍输出原有 256 维风格向量，可另选 1536 维主干特征。向量计算余弦相似度前应做 L2 归一化。

**旧插件不支持本分类头的归一化配置；仅下载权重和配置而不更新插件，会产生不正确的 logits。** 根目录的 `config.json` 服务原始无分类头模型，请勿用它覆盖本目录配置。

## 推理约定

EXIF 校正 → 透明区域白底合成 → RGB → 短边等比例缩放至 512 → 中心裁剪 512×512 → ImageNet 均值/标准差归一化。无拉伸。

主干为 DINOv3 ViT-B/16，v1 step 46000。池化为 CLS + mean patch，1536 维。分类头训练时冻结主干和风格投影头；推理公式：

```python
head_input = torch.nn.functional.normalize(pooled_features.float(), dim=-1) * (1536 ** 0.5)
logits = head(head_input)  # Linear(1536, 44129)
scores = logits.float().softmax(dim=-1)
```

该归一化只用于分类分支，不能把归一化后的特征送入原有风格投影头。分类顺序以 `class_mapping.csv` 为准。

## 训练与验证

| 项目 | 数值 |
|---|---|
| 分类头检查点 | epoch 26，按开发集画师宏平均 Top-1 选模，min_delta=0.001 |
| 训练图片 | 1,850,168，按画师最近年份组取样 |
| 输出类别 | 44,129 位训练集画师 |
| 开发集 | 39,369 张，支持 17,485 位画师 |
| 开发集 Top-1 | 88.6738% |
| 开发集 Top-5 | 93.3933% |
| 开发集画师宏平均 Top-1 | 86.7614% |
| 优化器 | AdamW，学习率 0.003，weight decay 0.01 |
| 损失 | CE，label smoothing 0.1，类别权重为训练数量平方根的倒数并均值归一化 |
| batch / seed | 2048（4 GPU × 512）/ 20261006 |

26,644 个输出类别没有近期开发集样本；以上指标不代表所有输出类别均已独立验证。封存的 5% 测试集未使用，训练与开发集按作品族隔离。原始风格检索指标见[根目录模型卡](../README.md)，不可与分类准确率直接比较。

输出概率未经校准，没有未知画师拒识能力，不能作为作品归属的确定性结论。稀疏画师识别显著弱于样本充足的画师。

权重来源及 SHA-256 见 [provenance.json](provenance.json)，导出一致性验证见 [inference_verification.json](inference_verification.json)。