touhou_guess

东方 Project 人物识别（Touhou Who）

一个用于识别东方 Project 角色的多标签分类模型。仓库包含训练、推理、数据集管理、去重与可视化等工具，并整理了可复现的目录结构。

目录结构

.
├─ src/
│  ├─ data/                      # 角色与翻译表
│  │  ├─ characters.json
│  │  ├─ trans.json
│  │  └─ cn-jp.json
│  ├─ training/                  # 训练脚本
│  │  └─ train.py
│  ├─ inference/                 # 推理脚本
│  │  ├─ inference_gui.py
│  │  └─ inference_cli.py
│  ├─ apps/                       # Web 管理工具
│  │  ├─ dataset_manager.py
│  │  └─ templates/
│  ├─ dataset/                    # 数据集清理/修复/验证
│  └─ dedup/                      # 去重与相似图像工具
├─ data/
│  └─ datasets/
│     └─ touhou-embeddings-dataset/
│        ├─ labels.csv
│        └─ images/
│           ├─ train/
│           └─ val/
├─ runs/
│  ├─ output/                     # 训练权重与曲线
│  └─ logs/                       # 运行日志
├─ tools/
│  ├─ plot_training_metrics.py
│  └─ debug/
│     └─ test_func/               # 调试/临时数据
└─ third_party/
   └─ Fast-Danbooru-Dataset-DL/   # 第三方数据集下载工具（独立 README）

快速开始

1) 安装依赖

建议使用 Python 3.8+，直接安装依赖：

pip install -r requirements.txt

2) 准备数据

数据集路径固定为：

data/datasets/touhou-embeddings-dataset/
  └─ touhou-embeddings-dataset/
    ├─ labels.csv
    └─ images/
      ├─ train/
      └─ val/

如果你使用第三方下载器，请先参考其说明文档并将数据整理到上述目录。

3) 训练

运行：

python src/training/train.py

训练输出会保存到：

runs/output/
  ├─ best_model.pth
  ├─ model_epoch_*.pth
  └─ training_state.pth

4) 推理（GUI）

python src/inference/inference_gui.py

5) 推理（CLI）

python src/inference/inference_cli.py --image <path> --threshold 0.3 --top-n 10

如果 runs/output 下没有 best_model.pth，CLI 会自动尝试加载最新的 model_epoch_*.pth。

启动爬虫（第三方工具）

爬虫代码位于 third_party/Fast-Danbooru-Dataset-DL 目录。请先阅读其 README，然后运行：

python third_party/Fast-Danbooru-Dataset-DL/app.py

或者在 Windows 下直接执行：

third_party/Fast-Danbooru-Dataset-DL/launch.bat

数据集工具

• 清理缺失文件记录：

  python src/dataset/clean_dataset.py
  

• 修复图片目录（train/val 对齐）：

  python src/dataset/fix_image_locations.py
  

• 调整训练/验证分割：

  python src/dataset/adjust_train_val_split.py
  

• 验证标签合法性：

  python src/dataset/validate_labels.py
  

• 从中间结果补充数据：

  python src/dataset/enrich_dataset.py
  

去重与相似图像工具

• 精确 MD5 去重：

  python src/dedup/remove_duplicates_md5.py
  

• 感知哈希（dHash）去重：

  python src/dedup/remove_duplicate_images_dhash.py
  

• 两张图像哈希距离检查：

  python src/dedup/check_hash_distance.py
  

• 相似图像可视化审查：

  python src/dedup/visualize_similar_images.py
  

数据集 Web 管理

python src/apps/dataset_manager.py

提供图片浏览、标签编辑、批量删除等功能，模板位于 src/apps/templates。

模型结构简介

主干使用 ConvNeXt-B（timm 实现），分类头替换为多标签输出，训练损失为 BCEWithLogitsLoss。

说明

• src/data 下为角色与翻译表。
• runs/output 为训练输出目录。
• third_party/Fast-Danbooru-Dataset-DL 为第三方工具，遵循其自身许可证与使用说明。

致谢

特别感谢以下贡献者和资源：

• Preacher 提供了本项目使用的数据集 Touhou Embeddings Dataset。
• Secret Sealing Club 提供了爬虫代码 Fast-Danbooru-Dataset-DL，用于数据集的下载与管理。
• preacher 和 renko_1055：感谢 preacher 提供了大量数据支持，感谢 renko_1055 提供了高效的爬虫工具。

你们的贡献使得本项目得以顺利进行，特别感谢！