Kaloscope-adapter-data

# Kaloscope Adapter Data 用于 **Kaloscope 画师风格适配器训练**的图像与元数据集，采用同画师、不同作品家族的目标图 / 参考图配对方式，可用于研究画师名称条件、参考图风格条件，以及 Krea2、MOSS 等生成模型的风格适配。 本仓库发布 `recent100-allartists` 数据快照：按画师原始图片数量分档，对超过 100 张的画师按上传时间倒序去重、顺延补足，保留小样本画师。包含图像 TAR 分片、Arrow 训练索引、配对示例、画师统计和筛选审计记录。底模、风格编码器和 adapter 权重需另行准备。 **下载需要申请并通过审核。** 请使用获批账号自己的 ModelScope Token 下载。详细操作见下文及 [使用指南](USAGE_ZH.md)。 ## 数据规模 以下图片和画师数量来自上传包内的 `report.json` 与 `train.arrow`，文件体积来自 ModelScope 文件清单（2026-10-25）。 | 统计口径 | 数量 | | --- | ---: | | 上游原始本地图片清单 | 7,105,244 张 | | 原始清单中可读、单一规范画师图片 | 7,082,460 张 / 44,136 位画师 | | 筛选后图片 `selected.arrow` | 3,570,817 张 / 44,136 位画师 | | 可配对训练索引 `train.arrow` | **3,570,414 张 / 44,093 位画师** | | 无法跨作品家族配对，单列记录 | 403 张 / 43 位画师 | | 选图扫描中跳过的重复或明显差分 | 399,075 张 | | 图像分片 | 331 个，`000.tar`–`330.tar` | | 图像分片总大小 | 1,324,665,886,720 字节，约 1.325 TB | | 元数据压缩包 | `meta.tar.gz`，915,209,234 字节，约 915 MB | **原始 710 万张是筛选来源口径，不是本仓库训练图像数量。** 3,570,414 是可用目标图片数；`pairs_epoch0.parquet` 为每个目标生成一条参考配对，包含同样数量的配对记录，不代表全部可能的组合。 每位可配对画师保留 2–100 张目标图，中位数为 90 张；最多 100 张不意味着每位画师恰好 100 张，也不自动保证训练采样频率相同。 ## 图像筛选规则 以**原始清单中的可读单画师图片数**分档，在去重、质量过滤和历史训练划分之前计数；不以旧的约 657 万张过滤后训练集计数。 | 单画师原始有效图片数 | 处理方式 | | --- | --- | | ≤50 张 | 全部保留，不做去重或额外质量过滤 | | 51–100 张 | 全部保留，不做去重或额外质量过滤 | | >100 张 | 按 `created_at` 降序扫描，重复或明显差分跳过，继续向更早图片补足 100 张，或直到候选耗尽 | - 时间戳为 Danbooru 的 **UTC 上传时间**，不保证等于作品创作时间；同时间戳按 `post_id` 降序排序。 - 超过 100 张的画师排除已识别的精确重复、近重复；父子 / 同源作品中的明显差分，需有 SIFT 与仿射对齐等视觉证据才合并。作品家族关联本身不等于重复。 - 只扫描获得最近 100 张所需的候选前缀，并非对原始全集穷尽去重；未关联或难以对齐的差分仍可能保留。≤100 张的画师按规则保留重复图。 - 不因历史评估身份排除画师。`reoen`、`murata_range`、`wanke` 均有 100 张进入训练索引。 - 所选图片只有一个作品家族的画师不能满足跨家族配对，记录于 `unpairable.parquet`，不进入 `train.arrow`。 ## 文件组成 ```text Kaloscope-adapter-data/ ├── README.md ├── USAGE_ZH.md ├── SHA256SUMS.txt ├── file_manifest.json ├── meta.tar.gz ├── 000.tar ├── 001.tar ├── ... └── 330.tar ``` 图像分片是各自可独立解压的普通 TAR，**不是分卷压缩包，不需要拼接**。包内图像使用原目录结构，例如： ```text mnt/data/danbooru2026/original/0908/10010908.webp ``` 这些分片不是直接包含 image/json 成对样本的 WebDataset 格式；图片标签和关联关系在元数据中。 `meta.tar.gz` 解压后目录为 `kaloscope3-adapter-recent100-allartists-20261023/`，主要内容如下： | 文件 | 用途 | | --- | --- | | `train.arrow` | 可配对训练图片索引，推荐的数据入口；Arrow IPC **file** 格式 | | `selected.arrow` / `unpairable.parquet` | 所有选中图片 / 不满足跨家族配对条件的图片 | | `groups.npz` | 画师在 `train.arrow` 中的连续行区间 `starts`、`ends`，左闭右开 | | `pairs_epoch0.parquet` | 首轮配对示例：目标 / 参考行号及对应 `post_id` | | `artist_counts.parquet` | 每位画师的原始数、选中数、可配对数和去重数量 | | `buckets.json` / `buckets_*.npy` | 数据构建阶段的候选宽高比桶及每行桶号 | | `policy.json` / `report.json` / `REPORT_ZH.txt` | 筛选规则、统计和实际训练使用说明 | | `decisions.parquet` / `visual_dedup_decisions.jsonl` | 原始行筛选与视觉去重审计记录 | | `hashes.json` / `verification.json` | 元数据文件指纹和构建验证结果 | `hashes.json` 中的 `inputs`、部分审计文件和 `original_path` 保留了原服务器路径，用于溯源；它们不要求下载者复建所有上游处理目录。路径迁移方法见 [使用指南](USAGE_ZH.md)。 ## 申请与下载 1. 登录 ModelScope，打开[本数据集页面](https://www.modelscope.cn/datasets/Heathcliff02/Kaloscope-adapter-data)，提交页面要求的访问申请，等待审核通过。 2. 在获批账号的访问令牌页面创建或取得自己的 Token。Token 用于身份认证，不能代替访问审批。 3. 安装 SDK，按下面的示例先下载元数据与第一个图像分片。该示例约下载 4.93 GB，不会下载全部图像。 ```bash python -m pip install "modelscope-hub>=0.1.8" pyarrow numpy pillow ``` 将以下内容保存为 `download_data.py` 后执行 `python download_data.py`；Token 在终端隐藏输入，不写入脚本： ```python from getpass import getpass from modelscope_hub import HubApi api = HubApi(token=getpass("ModelScope Token: "), endpoint="https://www.modelscope.cn") api.download_repo( "Heathcliff02/Kaloscope-adapter-data", repo_type="dataset", revision="master", local_dir="downloads", allow_patterns=[ "README.md", "USAGE_ZH.md", "SHA256SUMS.txt", "file_manifest.json", "meta.tar.gz", "000.tar", ], max_workers=2, ) ``` 全量下载时，将 `"000.tar"` 替换为 `"[0-9][0-9][0-9].tar"`。下载中断后可再次执行同一命令复用已下载文件。请核对本地最终有 **331 个图像 TAR**，不要将文件列表的第一页误当作完整数据。 全部压缩包约占 1.33 TB；保留 TAR 并同时解压图像时，建议预留约 3 TB 可用空间。可以逐分片处理，以降低同时占用。 出现 403 / 无权访问时，请检查申请是否通过、Token 是否属于获批账号、Token 是否有效。不要将别人的 Token 写入配置或公开工作流。 ## 训练使用与评估边界 - 同一配对要求：**同一规范画师、不同 `work_family_id`**；参考图用于提取风格条件，目标图及其内容标签用于训练生成模型。 - `pairs_epoch0.parquet` 可用于固定首轮复现；持续训练可重新抽取同画师、跨家族参考，避免每轮固定同一参考。本版不限制配对时间间隔。 - 多分辨率实践使用 512 / 768 / 1024 = **20% / 30% / 50%**，按宽高比分桶。小图允许放大到 512；768、1024 目标桶不放大。大图可以缩小进入更低分辨率池。 - **包内 `buckets_*.npy` 是允许放大的候选分桶，不等同于最终训练的高分辨率可用池。** 使用前需按原图宽高重新判断是否能无放大填满目标桶，详见使用指南。 - 按画师均衡抽样是训练采样器的职责。直接遍历全部行会让保留图片较多的画师获得更多训练次数；多分辨率时还应考虑各画师可用分辨率不同。 - 本版**没有独立 train/dev/test 隔离**；`legacy_split` 只保存旧划分，不能当作本版有效验证集。需要独立评估时，请先按画师或作品家族重划分，并重新生成配对。未见画师测试需排除该画师的全部训练图片。 ## 配套项目 | 资源 | 链接 | | --- | --- | | 解压、字段、读取与配对示例 | [USAGE_ZH.md](USAGE_ZH.md) | | Z3 训练代码 | [Chenkin-x/Kaloscope-adapter-trainer](https://github.com/Chenkin-x/Kaloscope-adapter-trainer) | | Adapter、风格编码器与画师原型库 | [ModelScope](https://www.modelscope.cn/models/Heathcliff02/Kaloscope-style-adapter) · [Hugging Face](https://huggingface.co/heathcliff01/Kaloscope-style-adapter) | | ComfyUI 推理节点与示例 | [Kaloscope-Style-adapter-Comfyui](https://github.com/Chenkin-x/Kaloscope-Style-adapter-Comfyui) | 训练仓库当前公开入口使用自己的 JSON manifest；本数据集的 Arrow 索引需要转换或接入数据读取器，不能直接替换配置中的 manifest 路径。多分辨率均衡采样也需在训练端接入。本仓库不包含训练器或预计算 latent / 文本特征缓存。 只进行 ComfyUI 出图无需下载这份训练数据；使用配套模型权重和推理节点即可。 ## 来源与许可说明 图像来源于项目整理的 Danbooru 本地快照，保留 `post_id`、画师标签与上传时间等溯源信息。仓库沿用现有的 Apache License 2.0 元数据标记；这不表示上传者拥有全部第三方画作版权，也不替代作品及上游来源各自的使用条件。申请通过表示获得本仓库访问权限。