README.md

---
base_model: rasyosef/roberta-medium-amharic
datasets:
- rasyosef/Amharic-Passage-Retrieval-Dataset-V2
library_name: PyLate
license: mit
metrics:
- accuracy
pipeline_tag: text-retrieval
tags:
- ColBERT
- PyLate
- sentence-transformers
- feature-extraction
- generated_from_trainer
- dataset_size:118938
- loss:Contrastive
model-index:
- name: ColBERT-Amharic-Medium
  results:
  - task:
      type: information-retrieval
      name: Information Retrieval
    dataset:
      name: Amharic Passage Retrieval Dataset V2
      type: rasyosef/Amharic-Passage-Retrieval-Dataset-V2
    metrics:
    - type: cosine_recall@5
      value: 0.882
      name: Cosine Recall@5
    - type: cosine_recall@10
      value: 0.913
      name: Cosine Recall@10
    - type: cosine_ndcg@10
      value: 0.811
      name: Cosine Ndcg@10
    - type: cosine_mrr@10
      value: 0.778
      name: Cosine Mrr@10
---

# ColBERT-Amharic-Medium

This is a [PyLate](https://github.com/lightonai/pylate) model finetuned from [rasyosef/roberta-medium-amharic](https://huggingface.co/rasyosef/roberta-medium-amharic). It was introduced in the paper [The Multilingual Curse at the Retrieval Layer: Evidence from Amharic](https://huggingface.co/papers/2605.24556).

The official code repository is available at [rasyosef/amharic-neural-ir](https://github.com/rasyosef/amharic-neural-ir).

The model maps sentences & paragraphs to sequences of 128-dimensional dense vectors and can be used for semantic textual similarity and passage retrieval using the MaxSim operator.

## Model Details

### Model Description
- **Model Type:** PyLate model (ColBERT-style)
- **Base model:** [rasyosef/roberta-medium-amharic](https://huggingface.co/rasyosef/roberta-medium-amharic)
- **Document Length:** 256 tokens
- **Query Length:** 32 tokens
- **Output Dimensionality:** 128 tokens
- **Similarity Function:** MaxSim
- **Language:** Amharic
- **License:** MIT

### Model Sources

- **Paper:** [The Multilingual Curse at the Retrieval Layer: Evidence from Amharic](https://huggingface.co/papers/2605.24556)
- **Repository:** [rasyosef/amharic-neural-ir](https://github.com/rasyosef/amharic-neural-ir)
- **Documentation:** [PyLate Documentation](https://lightonai.github.io/pylate/)

### Full Model Architecture

```
ColBERT(
  (0): Transformer({'max_seq_length': 255, 'do_lower_case': False}) with Transformer model: XLMRobertaModel 
  (1): Dense({'in_features': 512, 'out_features': 128, 'bias': False, 'activation_function': 'torch.nn.modules.linear.Identity'})
)
```

## Usage
First install the PyLate library:

```bash
pip install -U "pylate[voyager]"
```

### Retrieval

PyLate provides a streamlined interface to index and retrieve documents using ColBERT models. The index leverages the Voyager HNSW index to efficiently handle document embeddings and enable fast retrieval.

#### Indexing documents

First, load the ColBERT model and initialize the Voyager index, then encode and index your documents:

```python
from pylate import indexes, models, retrieve

# Step 1: Load the ColBERT model
model = models.ColBERT(
    model_name_or_path="rasyosef/colbert-amharic-medium",
)

# Step 2: Initialize the Voyager index
index = indexes.Voyager(
    index_folder="pylate-index",
    index_name="index",
    override=True,  # This overwrites the existing index if any
)

# Step 3: Encode the documents
documents_ids = ["1", "2", "3", "4", "5"]
documents = [
  "አስመላሽ ተካ ለኢትዮጵያ ቋንቋዎች የማሽን ትርጉም አገልግሎት የሚያቀርበው ልሳን ኩባንያ ተባባሪ መሥራች ነው። መቀመጫውን በርሊን ያደረገው ልሳን በሥራው ከአርቴፊሺያል ኢንተለጀንስ ጋር በጥብቅ ይተሳሰራል። አስመላሽ የአንድ ለአንድ እንግዳ ነው። አሜሪካ እና ቻይና ስለሚወዳደሩበት ቴክኖሎጂ እና ለአፍሪካ ስለሚኖረው ፋይዳ እሸቴ በቀለ አነጋግሮታል።",
  "ከተደጋጋሚ መሬት መንቀጥቀጥ በኋላ አፋር ክልል እሳት ከመሬት ውስጥ ሲፈላ ታይቷል፡፡ ከመሬት ውስጥ እሳትና ጭስ የሚተፋው እንፋሎቱ ዛሬ ማለዳውን 11 ሰዓት ግድም ከከባድ ፍንዳታ በኋላየተስተዋለ መሆኑን የአከባቢው ነዋሪዎች እና ባለስልጣናት ለዶቼ ቬለ ተናግረዋል፡፡ አለት የሚያፈናጥር እሳት ነው የተባለው እንፋሎቱ በክልሉ ጋቢረሱ (ዞን 03) ዱለቻ ወረዳ ሰጋንቶ ቀበሌ መከሰቱን የገለጹት የአከባቢው የአይን እማኞች ከዋናው ፍንዳታ በተጨማሪ በዙሪያው ተጨማሪ ፍንዳታዎች መታየት ቀጥሏል ባይ ናቸው፡፡",
  "በማዕከላዊ ኢትዮጵያ ክልል ሃድያ ዞን ጊቤ ወረዳ በሚገኙ 12 ቀበሌዎች መሠረታዊ የመንግሥት አገልግሎት መስጫ ተቋማት በሙሉና በከፊል በመዘጋታቸው መቸገራቸውን ነዋሪዎች አመለከቱ። ከባለፈው ዓመት ጀምሮ የጤና፣ የትምህርት እና የግብር አሰባሰብ ሥራዎች በየአካባቢያቸው እየተከናወኑ አለመሆናቸውንም ለዶቼ ቬለ ተናግረዋል።",
  "የሕዝብ ተወካዮች ምክር ቤት አባል እና የቋሚ ኮሚቴ ሰብሳቢ የነበሩት አቶ ክርስቲያን ታደለ እና የአማራ ክልል ምክር ቤት አባል የሆኑት አቶ ዮሐንስ ቧያለው ከቃሊቲ ወደ ቂሊንጦ ማረሚያ ቤት መዛወራቸውን ጠበቃቸው ተናገሩ።",
  "ከ15 የተባበሩት መንግሥታት የጸጥታ ጥበቃ ምክር ቤት አባላት መካከል ትላንት ዓርብ በነበረው ድምጽ አሰጣጥ ዘጠኙ የውሳኔ ሐሳቡን ደግፈዋል። የውሳኔ ሐሳቡ ያገኘው የድጋፍ ድምጽ ለመጽደቅ ከሚያስፈልገው ዝቅተኛው ነው። ስድስት ሀገራት ማለትም ሩሲያ፣ ቻይና፣ አልጄሪያ፣ ሴራ ሊዮን፣ ሶማሊያ እና ፓኪስታን ድምጸ ተዓቅቦ አድርገዋል።", 
]

documents_embeddings = model.encode(
    documents,
    batch_size=32,
    is_query=False,  # Ensure that it is set to False to indicate that these are documents, not queries
    show_progress_bar=True,
)

# Step 4: Add document embeddings to the index by providing embeddings and corresponding ids
index.add_documents(
    documents_ids=documents_ids,
    documents_embeddings=documents_embeddings,
)
```

#### Retrieving top-k documents for queries

Once the documents are indexed, you can retrieve the top-k most relevant documents for a given set of queries:

```python
# Step 1: Initialize the ColBERT retriever
retriever = retrieve.ColBERT(index=index)

# Step 2: Encode the queries
queries_embeddings = model.encode(
    [
      "የጸጥታ ጥበቃው ምክር ቤት በደቡብ ሱዳን ላይ የተጣለውን የጦር መሣሪያ ማዕቀብ ለዓመት አራዘመ", 
      "የተደጋገመው የመሬት መንቀጥቀጥና የእሳተ ገሞራ ምልክት በአፋር ክልል"
    ],
    batch_size=32,
    is_query=True,
    show_progress_bar=True,
)

# Step 3: Retrieve top-k documents
scores = retriever.retrieve(
    queries_embeddings=queries_embeddings,
    k=10,  # Retrieve the top 10 matches for each query
)
```

### Reranking
If you only want to use the ColBERT model to perform reranking without building an index, you can simply use the rank function:

```python
from pylate import rank, models

queries = [
    "የጸጥታ ጥበቃው ምክር ቤት በደቡብ ሱዳን ላይ የተጣለውን የጦር መሣሪያ ማዕቀብ ለዓመት አራዘመ",
]

documents = [
  [
    "አስመላሽ ተካ ለኢትዮጵያ ቋንቋዎች የማሽን ትርጉም አገልግሎት የሚያቀርበው ልሳን ኩባንያ ተባባሪ መሥራች ነው። መቀመጫውን በርሊን ያደረገው ልሳን በሥራው ከአርቴፊሺያል ኢንተለጀንስ ጋር በጥብቅ ይተሳሰራል። አስመላሽ የአንድ ለአንድ እንግዳ ነው። አሜሪካ እና ቻይና ስለሚወዳደሩበት ቴክኖሎጂ እና ለአፍሪካ ስለሚኖረው ፋይዳ እሸቴ በቀለ አነጋግሮታል።",
    "በማዕከላዊ ኢትዮጵያ ክልል ሃድያ ዞን ጊቤ ወረዳ በሚገኙ 12 ቀበሌዎች መሠረታዊ የመንግሥት አገልግሎት መስጫ ተቋማት በሙሉና በከፊል በመዘጋታቸው መቸገራቸውን ነዋሪዎች አመለከቱ። ከባለፈው ዓመት ጀምሮ የጤና፣ የትምህርት እና የግብር አሰባሰብ ሥራዎች በየአካባቢያቸው እየተከናወኑ አለመሆናቸውንም ለዶቼ ቬለ ተናግረዋል።",
    "የሕዝብ ተወካዮች ምክር ቤት አባል እና የቋሚ ኮሚቴ ሰብሳቢ የነበሩት አቶ ክርስቲያን ታደለ እና የአማራ ክልል ምክር ቤት አባል የሆኑት አቶ ዮሐንስ ቧያለው ከቃሊቲ ወደ ቂሊንጦ ማረሚያ ቤት መዛወራቸውን ጠበቃቸው ተናገሩ።",
    "ከተደጋጋሚ መሬት መንቀጥቀጥ በኋላ አፋር ክልል እሳት ከመሬት ውስጥ ሲፈላ ታይቷል፡፡ ከመሬት ውስጥ እሳትና ጭስ የሚተፋው እንፋሎቱ ዛሬ ማለዳውን 11 ሰዓት ግድም ከከባድ ፍንዳታ በኋላየተስተዋለ መሆኑን የአከባቢው ነዋሪዎች እና ባለስልጣናት ለዶቼ ቬለ ተናግረዋል፡፡ አለት የሚያፈናጥር እሳት ነው የተባለው እንፋሎቱ በክልሉ ጋቢረሱ (ዞን 03) ዱለቻ ወረዳ ሰጋንቶ ቀበሌ መከሰቱን የገለጹት የአከባቢው የአይን እማኞች ከዋናው ፍንዳታ በተጨማሪ በዙሪያው ተጨማሪ ፍንዳታዎች መታየት ቀጥሏል ባይ ናቸው፡፡",
    "ከ15 የተባበሩት መንግሥታት የጸጥታ ጥበቃ ምክር ቤት አባላት መካከል ትላንት ዓርብ በነበረው ድምጽ አሰጣጥ ዘጠኙ የውሳኔ ሐሳቡን ደግፈዋል። የውሳኔ ሐሳቡ ያገኘው የድጋፍ ድምጽ ለመጽደቅ ከሚያስፈልገው ዝቅተኛው ነው። ስድስት ሀገራት ማለትም ሩሲያ፣ ቻይና፣ አልጄሪያ፣ ሴራ ሊዮን፣ ሶማሊያ እና ፓኪስታን ድምጸ ተዓቅቦ አድርገዋል።", 
  ] 
]

documents_ids = [
    [1, 2, 3, 4, 5],
]

model = models.ColBERT(
    model_name_or_path="rasyosef/colbert-amharic-medium",
)

queries_embeddings = model.encode(
    queries,
    is_query=True,
)

documents_embeddings = model.encode(
    documents,
    is_query=False,
)

reranked_documents = rank.rerank(
    documents_ids=documents_ids,
    queries_embeddings=queries_embeddings,
    documents_embeddings=documents_embeddings,
)
```

## Evaluation

| Metric              | Value      |
|:--------------------|:-----------|
| cosine_recall@5   | 0.882     |
| cosine_recall@10  | 0.913     |
| **cosine_ndcg@10**  | **0.811** |
| cosine_mrr@10       | 0.778     |

## Training Details

### Training Dataset

- **Name:** [rasyosef/Amharic-Passage-Retrieval-Dataset-V2](https://huggingface.co/datasets/rasyosef/Amharic-Passage-Retrieval-Dataset-V2)
- **Size:** 118,938 training samples
- **Loss:** `pylate.losses.contrastive.Contrastive`

### Training Hyperparameters

- `per_device_train_batch_size`: 32
- `learning_rate`: 1e-05
- `num_train_epochs`: 4
- `fp16`: True

## Citation

```bibtex
@inproceedings{alemneh2026amharicir,
  title     = {The Multilingual Curse at the Retrieval Layer: Evidence from Amharic},
  author    = {Alemneh, Yosef Worku and Mekonnen, Kidist Amde and de Rijke, Maarten},
  booktitle = {Proceedings of the 1st Workshop on Multilinguality in the Era of Large Language Models (MeLLM), ACL 2026},
  year      = {2026},
}
```