README.md

---
language:
- en
license: apache-2.0
tags:
- sentence-transformers
- sentence-similarity
- feature-extraction
- generated_from_trainer
- dataset_size:2130621
- loss:ContrastiveLoss
base_model: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
widget:
- source_sentence: Kim Chol-sam
  sentences:
  - Stankevich Sergey Nikolayevich
  - Kim Chin-So’k
  - Julen Lopetegui Agote
- source_sentence: دينا بنت عبد الحميد
  sentences:
  - Alexia van Amsberg
  - Anthony Nicholas Colin Maitland Biddulph, 5th Baron Biddulph
  - Dina bint Abdul-Hamíd
- source_sentence: Մուհամեդ բեն Նաիֆ Ալ Սաուդ
  sentences:
  - Karpov Anatoly Evgenyevich
  - GNPower Mariveles Coal Plant [former]
  - Muhammed bin Nayef bin Abdul Aziz Al Saud
- source_sentence: Edward Gnehm
  sentences:
  - Шауэрте, Хартмут
  - Ханзада Филипп, Эдинбург герцогі
  - AFX
- source_sentence: Schori i Lidingö
  sentences:
  - Yordan Canev
  - ကားပေါ့ အန်နာတိုလီ
  - BYSTROV, Mikhail Ivanovich
pipeline_tag: sentence-similarity
library_name: sentence-transformers
metrics:
- cosine_accuracy
- cosine_accuracy_threshold
- cosine_f1
- cosine_f1_threshold
- cosine_precision
- cosine_recall
- cosine_ap
- cosine_mcc
model-index:
- name: Graphlet-AI/eridu
  results:
  - task:
      type: binary-classification
      name: Binary Classification
    dataset:
      name: sentence transformers paraphrase multilingual MiniLM L12 v2
      type: sentence-transformers-paraphrase-multilingual-MiniLM-L12-v2
    metrics:
    - type: cosine_accuracy
      value: 0.9885216725241056
      name: Cosine Accuracy
    - type: cosine_accuracy_threshold
      value: 0.7183246612548828
      name: Cosine Accuracy Threshold
    - type: cosine_f1
      value: 0.9824706124974221
      name: Cosine F1
    - type: cosine_f1_threshold
      value: 0.7085607051849365
      name: Cosine F1 Threshold
    - type: cosine_precision
      value: 0.9782229269572558
      name: Cosine Precision
    - type: cosine_recall
      value: 0.9867553479166427
      name: Cosine Recall
    - type: cosine_ap
      value: 0.9971022799526896
      name: Cosine Ap
    - type: cosine_mcc
      value: 0.9739458779668466
      name: Cosine Mcc
---

# Graphlet-AI/eridu

Deep fuzzy matching people and company names for multilingual entity resolution using representation learning... that incorporates a deep understanding of people and company names and can work _much better_ than string distance methods!

This is a [sentence-transformers](https://www.SBERT.net) model finetuned from [sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2) for person and company name matching using the [Open Sanctions matcher training data](https://www.opensanctions.org/docs/pairs/). It maps sentences & paragraphs to a 384-dimensional dense vector space and can be used as part of a deep, fuzzy entity resolution process.

NOTE: this model is a work in progress. It is not yet ready for production use!

## Model Details

### TLDR: 5 Lines of Code

```python
from sentence_transformers import SentenceTransformer


# Download from the 🤗 Hub
model = SentenceTransformer("Graphlet-AI/eridu")

names = [
    "Russell Jurney",
    "Russ Jurney",
    "Русс Джерни",
]

embeddings = model.encode(names)
print(embeddings.shape)
# [3, 384]

# Get the similarity scores for the embeddings
similarities = model.similarity(embeddings, embeddings)
print(similarities.shape)
# [3, 3]

print(similarities.numpy())
# [[0.9999999  0.99406826 0.99406105]
#  [0.9940683  1.         0.9969202 ]
#  [0.99406105 0.9969202  1.        ]]
```

### Project Eridu Overview

This project is a deep fuzzy matching system for person and company names for entity resolution using representation learning. It is designed to match people and company names across languages and character sets, using a pre-trained text embedding model from HuggingFace that we fine-tune using contrastive learning on 2 million labeled pairs of person and company names from the [Open Sanctions Matcher training data](https://www.opensanctions.org/docs/pairs/). The project includes a command-line interface (CLI) utility for training the model and comparing pairs of names using cosine similarity.

Matching people and company names is an intractable problem using traditional parsing based methods: there is too much variation across cultures and jurisdictions to solve the problem by humans programming. This results in complex, cost prohibitive enterprise solutions for name matching like [IBM InfoSphere Global Name Management](https://www.ibm.com/products/ibm-infosphere-global-name-management). Machine learning is used on problems like this one of cultural relevance, where the time to manually programming a solution appproaches infinity, to automatically write a program. Since 2008 there has been an explosion of deep learning methods that automate feature engineering via representation learning methods including such as text embeddings.

This project loads the pre-trained [paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2) paraphrase model from HuggingFace and fine-tunes it for the name matching task using contrastive learning on more than 2 million labeled pairs of matching and non-matching (just as important) person and company names from the [Open Sanctions Matcher training data](https://www.opensanctions.org/docs/pairs/) to create a deep fuzzy matching system for entity resolution.

This model is available on HuggingFace Hub as [Graphlet-AI/eridu](https://huggingface.co/Graphlet-AI/eridu) and can be used in any Python project using the [Sentence Transformers](https://sbert.net/) library in five lines of code. The model is designed to be used for entity resolution tasks, such as matching people and company names across different languages and character sets when matching records.

### Model Description

- **Model Type:** Sentence Transformer
- **Base model:** [sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2) <!-- at revision 86741b4e3f5cb7765a600d3a3d55a0f6a6cb443d -->
- **Maximum Sequence Length:** 128 tokens
- **Output Dimensionality:** 384 dimensions
- **Similarity Function:** Cosine Similarity
<!-- - **Training Dataset:** Unknown -->
- **Language:** en
- **License:** apache-2.0

### Model Sources

- **Documentation:** [Graphlet-AI/eridu Documentation](https://github.com/Graphlet-AI/eridu)
- **Repository:** [Graphlet-AI/eridu on GitHub](https://github.com/Graphlet-AI/eridu)
- **Hugging Face:** [Graphlet-AI/eridu on Hugging Face](https://huggingface.co/Graphlet-AI/eridu)
- **PyPi Package:** [Graphlet-AI/eridu on PyPi](https://pypi.org/project/eridu/)

### Full Model Architecture

```
SentenceTransformer(
  (0): Transformer({'max_seq_length': 128, 'do_lower_case': False}) with Transformer model: BertModel 
  (1): Pooling({'word_embedding_dimension': 384, 'pooling_mode_cls_token': False, 'pooling_mode_mean_tokens': True, 'pooling_mode_max_tokens': False, 'pooling_mode_mean_sqrt_len_tokens': False, 'pooling_mode_weightedmean_tokens': False, 'pooling_mode_lasttoken': False, 'include_prompt': True})
)
```

## Usage

### Direct Usage (Sentence Transformers)

First install the Sentence Transformers library:

```bash
pip install -U sentence-transformers
```

Then you can load this model and run inference.

```python
from sentence_transformers import SentenceTransformer

# Download from the 🤗 Hub
model = SentenceTransformer("Graphlet-AI/eridu")

# Run inference
sentences = [
    'Schori i Lidingö',
    'Yordan Canev',
    'ကားပေါ့ အန်နာတိုလီ',
]
embeddings = model.encode(sentences)
print(embeddings.shape)
# [3, 384]

# Get the similarity scores for the embeddings
similarities = model.similarity(embeddings, embeddings)
print(similarities.shape)
# [3, 3]
```

<!--
### Direct Usage (Transformers)

<details><summary>Click to see the direct usage in Transformers</summary>

</details>
-->

<!--
### Downstream Usage (Sentence Transformers)

You can finetune this model on your own dataset.

<details><summary>Click to expand</summary>

</details>
-->

<!--
### Out-of-Scope Use

*List how the model may foreseeably be misused and address what users ought not to do with the model.*
-->

## Evaluation

### Metrics

#### Binary Classification

- Dataset: `sentence-transformers-paraphrase-multilingual-MiniLM-L12-v2`
- Evaluated with [<code>BinaryClassificationEvaluator</code>](https://sbert.net/docs/package_reference/sentence_transformer/evaluation.html#sentence_transformers.evaluation.BinaryClassificationEvaluator)

| Metric                    | Value      |
|:--------------------------|:-----------|
| cosine_accuracy           | 0.9885     |
| cosine_accuracy_threshold | 0.7183     |
| cosine_f1                 | 0.9825     |
| cosine_f1_threshold       | 0.7086     |
| cosine_precision          | 0.9782     |
| cosine_recall             | 0.9868     |
| **cosine_ap**             | **0.9971** |
| cosine_mcc                | 0.9739     |

<!--
## Bias, Risks and Limitations

*What are the known or foreseeable issues stemming from this model? You could also flag here known failure cases or weaknesses of the model.*
-->

<!--
### Recommendations

*What are recommendations with respect to the foreseeable issues? For example, filtering explicit content.*
-->

## Training Details

### Training Dataset

#### Unnamed Dataset

- Size: 2,130,621 training samples
- Columns: <code>sentence1</code>, <code>sentence2</code>, and <code>label</code>
- Approximate statistics based on the first 1000 samples:

  |         | sentence1                                                                        | sentence2                                                                        | label                                                          |
  |:--------|:---------------------------------------------------------------------------------|:---------------------------------------------------------------------------------|:---------------------------------------------------------------|
  | type    | string                                                                           | string                                                                           | float                                                          |
  | details | <ul><li>min: 3 tokens</li><li>mean: 9.32 tokens</li><li>max: 57 tokens</li></ul> | <ul><li>min: 3 tokens</li><li>mean: 9.16 tokens</li><li>max: 54 tokens</li></ul> | <ul><li>min: 0.0</li><li>mean: 0.34</li><li>max: 1.0</li></ul> |

- Samples:

  | sentence1                         | sentence2                           | label            |
  |:----------------------------------|:------------------------------------|:-----------------|
  | <code>캐스린 설리번</code>              | <code>Kathryn D. Sullivanová</code> | <code>1.0</code> |
  | <code>ଶିବରାଜ ଅଧାଲରାଓ ପାଟିଲ</code> | <code>Aleksander Lubocki</code>     | <code>0.0</code> |
  | <code>Пырванов, Георги</code>     | <code>アナトーリー・セルジュコフ</code>          | <code>0.0</code> |

- Loss: [<code>ContrastiveLoss</code>](https://sbert.net/docs/package_reference/sentence_transformer/losses.html#contrastiveloss) with these parameters:

  ```json
  {
      "distance_metric": "SiameseDistanceMetric.COSINE_DISTANCE",
      "margin": 0.5,
      "size_average": true
  }
  ```

### Evaluation Dataset

#### Unnamed Dataset

- Size: 2,663,276 evaluation samples
- Columns: <code>sentence1</code>, <code>sentence2</code>, and <code>label</code>
- Approximate statistics based on the first 1000 samples:

  |         | sentence1                                                                         | sentence2                                                                         | label                                                          |
  |:--------|:----------------------------------------------------------------------------------|:----------------------------------------------------------------------------------|:---------------------------------------------------------------|
  | type    | string                                                                            | string                                                                            | float                                                          |
  | details | <ul><li>min: 3 tokens</li><li>mean: 9.34 tokens</li><li>max: 102 tokens</li></ul> | <ul><li>min: 4 tokens</li><li>mean: 9.11 tokens</li><li>max: 100 tokens</li></ul> | <ul><li>min: 0.0</li><li>mean: 0.33</li><li>max: 1.0</li></ul> |

- Samples:

  | sentence1                             | sentence2                              | label            |
  |:--------------------------------------|:---------------------------------------|:-----------------|
  | <code>Ева Херман</code>               | <code>I Xuan Karlos</code>             | <code>0.0</code> |
  | <code>Кличков Андрій Євгенович</code> | <code>Андрэй Яўгенавіч Клычкоў</code>  | <code>1.0</code> |
  | <code>Кинах А.</code>                 | <code>Senator John Hickenlooper</code> | <code>0.0</code> |

- Loss: [<code>ContrastiveLoss</code>](https://sbert.net/docs/package_reference/sentence_transformer/losses.html#contrastiveloss) with these parameters:

  ```json
  {
      "distance_metric": "SiameseDistanceMetric.COSINE_DISTANCE",
      "margin": 0.5,
      "size_average": true
  }
  ```

### Training Hyperparameters

#### Non-Default Hyperparameters

- `eval_strategy`: epoch
- `per_device_train_batch_size`: 768
- `per_device_eval_batch_size`: 768
- `gradient_accumulation_steps`: 4
- `learning_rate`: 3e-05
- `weight_decay`: 0.01
- `num_train_epochs`: 4
- `warmup_ratio`: 0.1
- `fp16`: True
- `load_best_model_at_end`: True
- `optim`: adafactor

#### All Hyperparameters

<details><summary>Click to expand</summary>

- `overwrite_output_dir`: False
- `do_predict`: False
- `eval_strategy`: epoch
- `prediction_loss_only`: True
- `per_device_train_batch_size`: 768
- `per_device_eval_batch_size`: 768
- `per_gpu_train_batch_size`: None
- `per_gpu_eval_batch_size`: None
- `gradient_accumulation_steps`: 4
- `eval_accumulation_steps`: None
- `torch_empty_cache_steps`: None
- `learning_rate`: 3e-05
- `weight_decay`: 0.01
- `adam_beta1`: 0.9
- `adam_beta2`: 0.999
- `adam_epsilon`: 1e-08
- `max_grad_norm`: 1.0
- `num_train_epochs`: 4
- `max_steps`: -1
- `lr_scheduler_type`: linear
- `lr_scheduler_kwargs`: {}
- `warmup_ratio`: 0.1
- `warmup_steps`: 0
- `log_level`: passive
- `log_level_replica`: warning
- `log_on_each_node`: True
- `logging_nan_inf_filter`: True
- `save_safetensors`: True
- `save_on_each_node`: False
- `save_only_model`: False
- `restore_callback_states_from_checkpoint`: False
- `no_cuda`: False
- `use_cpu`: False
- `use_mps_device`: False
- `seed`: 42
- `data_seed`: None
- `jit_mode_eval`: False
- `use_ipex`: False
- `bf16`: False
- `fp16`: True
- `fp16_opt_level`: O1
- `half_precision_backend`: auto
- `bf16_full_eval`: False
- `fp16_full_eval`: False
- `tf32`: None
- `local_rank`: 0
- `ddp_backend`: None
- `tpu_num_cores`: None
- `tpu_metrics_debug`: False
- `debug`: []
- `dataloader_drop_last`: False
- `dataloader_num_workers`: 0
- `dataloader_prefetch_factor`: None
- `past_index`: -1
- `disable_tqdm`: False
- `remove_unused_columns`: True
- `label_names`: None
- `load_best_model_at_end`: True
- `ignore_data_skip`: False
- `fsdp`: []
- `fsdp_min_num_params`: 0
- `fsdp_config`: {'min_num_params': 0, 'xla': False, 'xla_fsdp_v2': False, 'xla_fsdp_grad_ckpt': False}
- `tp_size`: 0
- `fsdp_transformer_layer_cls_to_wrap`: None
- `accelerator_config`: {'split_batches': False, 'dispatch_batches': None, 'even_batches': True, 'use_seedable_sampler': True, 'non_blocking': False, 'gradient_accumulation_kwargs': None}
- `deepspeed`: None
- `label_smoothing_factor`: 0.0
- `optim`: adafactor
- `optim_args`: None
- `adafactor`: False
- `group_by_length`: False
- `length_column_name`: length
- `ddp_find_unused_parameters`: None
- `ddp_bucket_cap_mb`: None
- `ddp_broadcast_buffers`: False
- `dataloader_pin_memory`: True
- `dataloader_persistent_workers`: False
- `skip_memory_metrics`: True
- `use_legacy_prediction_loop`: False
- `push_to_hub`: False
- `resume_from_checkpoint`: None
- `hub_model_id`: None
- `hub_strategy`: every_save
- `hub_private_repo`: None
- `hub_always_push`: False
- `gradient_checkpointing`: False
- `gradient_checkpointing_kwargs`: None
- `include_inputs_for_metrics`: False
- `include_for_metrics`: []
- `eval_do_concat_batches`: True
- `fp16_backend`: auto
- `push_to_hub_model_id`: None
- `push_to_hub_organization`: None
- `mp_parameters`:
- `auto_find_batch_size`: False
- `full_determinism`: False
- `torchdynamo`: None
- `ray_scope`: last
- `ddp_timeout`: 1800
- `torch_compile`: False
- `torch_compile_backend`: None
- `torch_compile_mode`: None
- `include_tokens_per_second`: False
- `include_num_input_tokens_seen`: False
- `neftune_noise_alpha`: None
- `optim_target_modules`: None
- `batch_eval_metrics`: False
- `eval_on_start`: False
- `use_liger_kernel`: False
- `eval_use_gather_object`: False
- `average_tokens_across_devices`: False
- `prompts`: None
- `batch_sampler`: batch_sampler
- `multi_dataset_batch_sampler`: proportional

</details>

### Training Logs

| Epoch      | Step     | Training Loss | Validation Loss | sentence-transformers-paraphrase-multilingual-MiniLM-L12-v2_cosine_ap |
|:----------:|:--------:|:-------------:|:---------------:|:---------------------------------------------------------------------:|
| -1         | -1       | -             | -               | 0.7140                                                                |
| 0.7207     | 500      | 0.038         | -               | -                                                                     |
| 0.9989     | 693      | -             | 0.0028          | 0.9911                                                                |
| 1.4425     | 1000     | 0.0128        | -               | -                                                                     |
| 1.9989     | 1386     | -             | 0.0021          | 0.9956                                                                |
| 2.1643     | 1500     | 0.0084        | -               | -                                                                     |
| 2.8850     | 2000     | 0.0065        | -               | -                                                                     |
| 2.9989     | 2079     | -             | 0.0015          | 0.9968                                                                |
| 3.6068     | 2500     | 0.0056        | -               | -                                                                     |
| **3.9989** | **2772** | **-**         | **0.0014**      | **0.9971**                                                            |

- The bold row denotes the saved checkpoint.

### Framework Versions

- Python: 3.12.9
- Sentence Transformers: 3.4.1
- Transformers: 4.51.3
- PyTorch: 2.7.0+cu126
- Accelerate: 1.6.0
- Datasets: 3.6.0
- Tokenizers: 0.21.1

## Citation

### BibTeX

#### Sentence Transformers

```bibtex
@inproceedings{reimers-2019-sentence-bert,
    title = "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks",
    author = "Reimers, Nils and Gurevych, Iryna",
    booktitle = "Proceedings of the 2019 Conference on Empirical Methods in Natural Language Processing",
    month = "11",
    year = "2019",
    publisher = "Association for Computational Linguistics",
    url = "https://arxiv.org/abs/1908.10084",
}
```

#### ContrastiveLoss

```bibtex
@inproceedings{hadsell2006dimensionality,
    author={Hadsell, R. and Chopra, S. and LeCun, Y.},
    booktitle={2006 IEEE Computer Society Conference on Computer Vision and Pattern Recognition (CVPR'06)},
    title={Dimensionality Reduction by Learning an Invariant Mapping},
    year={2006},
    volume={2},
    number={},
    pages={1735-1742},
    doi={10.1109/CVPR.2006.100}
}
```

<!--
## Glossary

*Clearly define terms in order to be accessible across audiences.*
-->

<!--
## Model Card Authors

*Lists the people who create the model card, providing recognition and accountability for the detailed work that goes into its construction.*
-->

<!--
## Model Card Contact

*Provides a way for people who have updates to the Model Card, suggestions, or questions, to contact the Model Card authors.*
-->