TensorFlow Similarity: Metric Learning for Humans
TensorFlow Similarity is a TensorFLow library for similarity learning also known as metric learning and contrastive learning.
TensorFlow Similarity is still in beta.
Introduction
Tensorflow Similarity offers state-of-the-art algorithms for metric learning and all the necessary components to research, train, evaluate, and serve similarity-based models.
With TensorFlow Similarity you can train and serve models that find similar items (such as images) in a large corpus of examples. For example, as visible above, you can train a similarity model to find and cluster similar looking images of cats and dogs from the Oxford IIIT Pet Dataset by only training on a few classes. To train your own similarity model see this notebook.
Metric learning is different from traditional classification as it's objective is different. The model learns to minimize the distance between similar examples and maximize the distance between dissimilar examples, in a supervised or self-supervised fashion. Either way, TensorFlow Similarity provides the necessary losses, metrics, samplers, visualizers, and indexing sub-system to make this quick and easy.
Currently, TensorFlow Similarity supports supervised training. In future releases, it will support semi-supervised and self-supervised training.
To learn more about the benefits of using similarity training, you can check out the blog post.
What's new
- [Aug 21]: Interactive embedding
projector()added. See this notebook - [Aug 21]:
CircleLoss()added - [Aug 21]:
PNLoss()added. - [Aug 21]:
MultiSimilarityLoss()added.
For previous changes - see the release changelog
Getting Started
Installation
Use pip to install the library
pip install tensorflow_similarity
Documentation
The detailed and narrated notebooks are a good way to get started with TensorFlow Similarity. There is likely to be one that is similar to your data or your problem (if not, let us know). You can start working with the examples immediately in Google Colab by clicking the Google Colab icon.
For more information about specific functions, you can check the API documentation
For contributing to the project please check out the contribution guidelines
Minimal Example: MNIST similarity
Here is a bare bones example demonstrating how to train a TensorFlow Similarity model on the MNIST data. This example illustrates some of the main components provided by TensorFlow Similarity and how they fit together. Please refer to the hello_world notebook for a more detailed introduction.
Preparing data
TensorFlow Similarity provides data samplers, for various dataset types, that balance the batches to ensure smoother training. In this example, we are using the multi-shot sampler that integrate directly from the TensorFlow dataset catalog.
from tensorflow_similarity.samplers import TFDatasetMultiShotMemorySampler
# Data sampler that generates balanced batches from MNIST dataset
sampler = TFDatasetMultiShotMemorySampler(dataset_name='mnist', classes_per_batch=10)
Building a Similarity model
Building a TensorFlow Similarity model is similar to building a standard Keras model, except the output layer is usually a MetricEmbedding() layer that enforces L2 normalization and the model is instantiated as a specialized subclass SimilarityModel() that supports additional functionality.
from tensorflow.keras import layers
from tensorflow_similarity.layers import MetricEmbedding
from tensorflow_similarity.models import SimilarityModel
# Build a Similarity model using standard Keras layers
inputs = layers.Input(shape=(28, 28, 1))
x = layers.experimental.preprocessing.Rescaling(1/255)(inputs)
x = layers.Conv2D(64, 3, activation='relu')(x)
x = layers.Flatten()(x)
x = layers.Dense(64, activation='relu')(x)
outputs = MetricEmbedding(64)(x)
# Build a specialized Similarity model
model = SimilarityModel(inputs, outputs)
Training model via contrastive learning
To output a metric embedding, that are searchable via approximate nearest neighbor search, the model needs to be trained using a similarity loss. Here we are using the MultiSimilarityLoss(), which is one of the most efficient loss functions.
from tensorflow_similarity.losses import MultiSimilarityLoss
# Train Similarity model using contrastive loss
model.compile('adam', loss=MultiSimilarityLoss())
model.fit(sampler, epochs=5)
Building images index and querying it
Once the model is trained, reference examples must indexed via the model index API to be searchable. After indexing, you can use the model lookup API to search the index for the K most similar items.
from tensorflow_similarity.visualization import viz_neigbors_imgs
# Index 100 embedded MNIST examples to make them searchable
sx, sy = sampler.get_slice(0,100)
model.index(x=sx, y=sy, data=sx)
# Find the top 5 most similar indexed MNIST examples for a given example
qx, qy = sampler.get_slice(3713, 1)
nns = model.single_lookup(qx[0])
# Visualize the query example and its top 5 neighbors
viz_neigbors_imgs(qx[0], qy[0], nns)
Supported Algorithms
Supervised Losses
- Triplet Loss
- PN Loss
- Multi Sim Loss
- Circle Loss
Metrics
Tensorflow Similarity offers many of the most common metrics used for classification and retrieval evaluation. Including:
| Name | Type | Description |
|---|---|---|
| Precision | Classification | |
| Recall | Classification | |
| F1 Score | Classification | |
| [email protected] | Retrieval | |
| Binary NDCG | Retrieval |
Citing
Please cite this reference if you use any part of TensorFlow similarity in your research:
@article{EBSIM21,
title={TensorFlow Similarity: A Usuable, High-Performance Metric Learning Library},
author={Elie Bursztein, James Long, Shun Lin, Owen Vallis, Francois Chollet},
journal={Fixme},
year={2021}
}
Disclaimer
This is not an official Google product.
![[REQUEST] TFDatasetMultiShotMemorySampler for custom datasets](https://avatars.githubusercontent.com/u/72462823?v=4)
1.9k Jan 09, 2023
42 Jul 25, 2022
13 Sep 17, 2022
40 Oct 07, 2022
21 Dec 12, 2022
274 Dec 06, 2022
19 Dec 17, 2022
1 Jan 27, 2022
6 Aug 16, 2022
30 Jan 04, 2023
36 Oct 31, 2022
96 Nov 25, 2022
37 Dec 13, 2022
252 Dec 11, 2022
104 Jan 04, 2023
41 Jan 04, 2023
305 Dec 30, 2022
1 Oct 09, 2021
42 Oct 07, 2022
228 Dec 29, 2022