哆啦A梦：网络的深度目标识别与嵌入模型

🚀 快速入门

# 创建并激活环境
python -m venv doraemon
source doraemon/bin/activate

# 安装Doraemon
pip install doraemon-torch

# 如果需要以可编辑模式安装（用于开发）
pip install -e .

📢 最新动态

• 🎁 2025年11月7日：Doraemon论文发布；如果您发现该项目对您的研究或开发有帮助，欢迎在<ahref='#citation'>引用我们的论文。
• 🎁 2025年3月16日：Doraemon v0.1.0版本发布
• 🎁 2024年10月1日：基于内容的图像检索（CBIR）：我们从Kaggle和天池收集了一个产品数据集，并提供了完整的训练、端到端验证和可视化流程。请查看ImageRetrieval.md
• 🎁 2024年4月1日：人脸识别：基于清理后的MS-Celeb-1M-v1c数据集，包含超过7万个ID和360万张图片，并通过LFW进行了验证。包括ArcFace、CircleLoss和MagFace等损失函数。
• 🎁 2023年6月1日：图像分类（IC）：使用牛津-IIIT宠物数据集。支持为不同层设置不同的学习率、难例挖掘、多标签和单标签训练、错误案例分析、GradCAM可视化、自动标注以辅助半监督训练，以及针对特定类别的数据增强。请参阅ImageClassification.md

✨ 亮点

• 优化算法：多种优化技术以提升模型训练效率，包括SGD、Adam和SAM（Sharpness-Aware Minimization）。

• 数据增强：多种数据增强技术以提高模型鲁棒性，如CutOut、Color-Jitter和Copy-Paste等。

• 正则化：防止过拟合并提升模型泛化的技术，包括Label Smoothing、OHEM、Focal Loss和Mixup。

• 可视化：集成的可视化工具，用于理解模型决策过程，特色功能为GradCAM。

• 个性化数据增强：通过类特定增强，为特定类别应用专属的数据增强方法。

• 个性化超参数调优：利用层特定学习率为不同层设置不同的学习率。

🚀 部署API

Doraemon提供极其简单却强大的部署选项：

• 本地API推理：只需一个权重文件（*.pt）即可部署模型——一条命令即可完成高性能本地推理的设置
• 无缝HuggingFace集成：轻松部署至Huggingface生态，全面支持：
  • AutoModel.from_pretrained()
  • AutoProcessor.from_pretrained()
  • 以及所有标准的Hugging Face API接口

有关详细的部署说明和即用示例，请参阅我们的部署指南。

📚 教程

如需特定任务的详细指导，请参考以下资源：

• 图像分类：如果您正在进行图像分类任务，请参阅文档：图像分类。

• 图像检索：对于图像检索任务，请参阅文档：图像检索。

• 人脸识别：敬请期待。

📊 数据集

Doraemon集成了以下数据集，方便用户快速开始训练：

• 图像检索：可在HuggingFace上找到电商产品数据集
• 人脸识别：可在HuggingFace上找到MS-Celeb-1M-v1c数据集
• 图像分类：可在HuggingFace上找到牛津-IIIT宠物数据集

🧩 支持的模型

Doraemon现已通过与Timm集成，支持1000多种模型：

• timm.list_models(pretrained=True)中的所有模型
• 包括CLIP、SigLIP、DeiT、BEiT、MAE、EVA、DINO等众多模型

模型性能基准测试可通过比较以下指标帮助您选择最合适的模型：

• 推理速度
• 训练效率
• 不同数据集上的准确率
• 参数量与性能之间的权衡

有关详细的基准测试结果，请参阅@huggingface/pytorch-image-models#1933

引用

@misc{du2025visual,
      title={DORAEMON: A Unified Library for Visual Object Modeling and Representation Learning at Scale}, 
      author={Ke Du and Yimin Peng and Chao Gao and Fan Zhou and Siqiao Xue},
      year={2025},
      journal={arXiv preprint arXiv:2511.04394},
      url={https://arxiv.org/abs/2511.04394}, 
}

Doraemon 快速上手指南

Doraemon (Deep Object Recognition And Embedding Model Of Networks) 是一个统一的视觉对象建模与表示学习库，支持图像分类、人脸识别和内容图像检索等任务。它集成了 Timm 的 1000+ 模型，并提供丰富的优化算法、数据增强及可视化工具。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux / macOS / Windows
• Python 版本: 3.10 或更高
• PyTorch 版本: 2.0+
• 核心依赖:
  • torchmetrics >= 0.11.4
  • timm >= 0.9.16
  • opencv-python >= 4.7.0

提示：国内用户建议在安装依赖时配置清华或阿里镜像源以加速下载。

安装步骤

推荐使用虚拟环境进行隔离安装。

1. 创建并激活虚拟环境

   python -m venv doraemon
   # Linux/macOS
   source doraemon/bin/activate
   # Windows
   doraemon\Scripts\activate
   

2. 安装 Doraemon

   直接通过 pip 安装稳定版：

   pip install doraemon-torch
   

   或者，如果您需要修改源码进行开发，可克隆仓库后以可编辑模式安装：

   git clone https://github.com/wuji3/Doraemon.git
   cd Doraemon
   pip install -e .
   

基本使用

Doraemon 的设计旨在简化部署与推理流程。以下是两种最常用的快速启动方式。

1. 本地单文件推理

只需一个权重文件 (*.pt) 即可进行高性能本地推理。

from doraemon import AutoModel, AutoProcessor

# 加载预训练模型和处理器
model = AutoModel.from_pretrained("path/to/your/model.pt")
processor = AutoProcessor.from_pretrained("path/to/your/model.pt")

# 准备图像数据 (假设 image 为 PIL Image 或 numpy array)
inputs = processor(image)

# 执行推理
outputs = model(inputs)
predictions = outputs.softmax(dim=1)

2. Hugging Face 生态集成

Doraemon 完美兼容 Hugging Face transformers 风格接口，可直接加载托管在 HF 上的模型。

from transformers import AutoModel, AutoProcessor

# 直接从 Hugging Face Hub 加载
model = AutoModel.from_pretrained("wuji3/doraemon-resnet50")
processor = AutoProcessor.from_pretrained("wuji3/doraemon-resnet50")

# 后续推理步骤同上

进阶任务指引

针对不同任务，Doraemon 提供了详细的文档支持：

• 图像分类: 参考 doraemon/models/classifier/README.md
• 图像检索 (CBIR): 参考 doraemon/models/representation/README_CBIR.md
• 人脸识别: 支持 ArcFace, CircleLoss 等损失函数，基于 MS-Celeb-1M-v1c 数据集验证。