News

• [2021-9-6]: v0.0.0 has been released.

Introduction

GeDML is an easy-to-use generalized deep metric learning library, which contains:

• State-of-the-art DML algorithms: We contrain 18+ losses functions and 6+ sampling strategies, and divide these algorithms into three categories (i.e., collectors, selectors, and losses).
• Bridge bewteen DML and SSL: We attempt to bridge the gap between deep metric learning and self-supervised learning through specially designed modules, such as collectors.
• Auxiliary modules to assist in building: We also encapsulates the upper interface for users to start programs quickly and separates the codes and configs for managing hyper-parameters conveniently.

Installation

Pip

pip install gedml

Framework

This project is modular in design. The pipeline diagram is as follows:

Code structure

• _debug: Debug files.
• demo: Demos of configuration files.
• docs: Documentation.
• src: Source code.
  • core: Losses, selectors, collectors, etc.
  • client: Tmux manager.
  • config: Config files including link, convert, assert and params.
  • launcher: Manager, Trainer, Tester, etc.
  • recorder: Recorder.

Method

Collectors

Losses

classifier-based

pair-based

proxy-based

Selectors

Quickstart

Please set the environment variable WORKSPACE first to indicate where to manage your project.

Initialization

Use ConfigHandler to create all objects.

config_handler = ConfigHandler()
config_handler.get_params_dict()
objects_dict = config_handler.create_all()

Start

Use manager to automatically call trainer and tester.

manager = utils.get_default(objects_dict, "managers")
manager.run()

Directly use trainer and tester.

trainer = utils.get_default(objects_dict, "trainers")
tester = utils.get_default(objects_dict, "testers")
recorder = utils.get_default(objects_dict, "recorders")

# start to train
utils.func_params_mediator(
    [objects_dict],
    trainer.__call__
)

# start to test
metrics = utils.func_params_mediator(
    [
        {"recorders": recorder},
        objects_dict,
    ],
    tester.__call__
)

Document

For more information, please refer to:

📖 👉 Docs

Some specific guidances:

• How to write config
• How to define custom module
• ...

Configs

We will continually update the optimal parameters of different configs in TsinghuaCloud

Code Reference

• KevinMusgrave / pytorch-metric-learning
• KevinMusgrave / powerful-benchmarker
• Confusezius / Deep-Metric-Learning-Baselines
• facebookresearch / moco
• PatrickHua / SimSiam
• ujjwaltiwari / Deep_Variational_Metric_Learning
• idstcv / SoftTriple
• wzzheng / HDML
• google-research / simclr
• kunhe / FastAP-metric-learning
• wy1iu / LargeMargin_Softmax_Loss
• tjddus9597 / Proxy-Anchor-CVPR2020
• facebookresearch / deit

TODO:

• assert parameters
• distributed methods and Non-distributed methods!!!
• write github action to automate unit-test, package publish and docs building.
• add cross-validation splits protocol.