readme: full model card with bidi/LFM2.5 details and PyLate usage

README.md

@@ -1,16 +1,112 @@
-# LFM2.5 ColBERT Preview
+---
+language:
+- en
+- es
+- de
+- fr
+- it
+- pt
+- ar
+- sv
+- 'no'
+- ja
+- ko
+tags:
+- liquid
+- lfm2
+- lfm2.5
+- edge
+- ColBERT
+- PyLate
+- sentence-transformers
+- sentence-similarity
+- feature-extraction
+pipeline_tag: sentence-similarity
+library_name: PyLate
+license: other
+license_name: lfm1.0
+license_link: LICENSE
+---
+
+<center>
+  <div style="text-align: center;">
+    <img
+      src="https://cdn-uploads.huggingface.co/production/uploads/61b8e2ba285851687028d395/7_6D7rWrLxp2hb6OHSV1p.png"
+      alt="Liquid AI"
+      style="width: 100%; max-width: 100%; height: auto; display: inline-block; margin-bottom: 0.5em; margin-top: 0.5em;"
+    />
+  </div>
+  <div style="display: flex; justify-content: center; gap: 0.5em;">
+    <a href="https://playground.liquid.ai/"><strong>Try LFM</strong></a> •
+    <a href="https://docs.liquid.ai/lfm/getting-started/welcome"><strong>Docs</strong></a> •
+    <a href="https://leap.liquid.ai/"><strong>LEAP</strong></a> •
+    <a href="https://discord.com/invite/liquid-ai"><strong>Discord</strong></a>
+  </div>
+</center>
+
+<br>
+
+# LFM2.5-ColBERT-350M
+
+LFM2.5-ColBERT-350M is a multilingual late-interaction retriever and the first bidirectional ColBERT in the LFM family. Built on the LFM2.5-350M-Base backbone with bidirectional patches, it converts each token into a vector and matches queries word-by-word via MaxSim, giving higher accuracy and better generalization than single-vector retrievers — at the cost of a larger index.
+
+- **Strong multilingual & cross-lingual performance** across 11 languages.
+- **Word-level matching** via late interaction for higher accuracy on hard queries.
+- **Small footprint** (350M params) — runs cheaply almost anywhere.
+- **Drop-in PyLate compatibility** for indexing, retrieval, and reranking.
+
+Pair it with [LFM2.5-Embedding-350M](https://huggingface.co/LiquidAI/LFM2.5-Embedding-350M) (the matching dense bi-encoder) when you want the smallest, fastest index; pick this ColBERT when accuracy matters more than storage.
+
+## 📄 Model details
+
+Late-interaction retrievers preserve much of the **expressivity** of cross-encoders while retaining the **efficiency** of bi-encoders — in practice, they retrieve at scale and rank at the same time.
+
+Especially well-suited for **short-context** search: product catalogs, FAQ knowledge bases, support docs, and other collections that need to be searched quickly, cheaply, and reliably across languages.
+
+| Property              | **LFM2.5-ColBERT-350M** |
+| --------------------- | ----------------------- |
+| **Total parameters**  | ~353M                   |
+| **Layers**            | 17 (10 conv + 6 attn + 1 dense) |
+| **Context length**    | 32,768 tokens           |
+| **Vocabulary size**   | 64,402                  |
+| **Training precision**| BF16                    |
+| **License**           | LFM Open License v1.0   |
+
+**Document length:** 512 tokens &nbsp;&nbsp; **Query length:** 32 tokens
+
+**Output dimensionality:** 128 per token &nbsp;&nbsp; **Similarity function:** MaxSim
+
+**Supported languages:** English, Spanish, German, French, Italian, Portuguese, Arabic, Swedish, Norwegian, Japanese, Korean.
+
+```text
+ColBERT(
+  (0): Transformer({'max_seq_length': 511, 'do_lower_case': False}) with Transformer model: Lfm2BidirectionalModel
+  (1): Dense({'in_features': 1024, 'out_features': 128, 'bias': False, 'activation_function': 'torch.nn.modules.linear.Identity'})
+)
+```
+
+### Architecture: bidirectional LFM2.5
+
+LFM2.5-ColBERT-350M starts from **LFM2.5-350M-Base** — Liquid's newer mid-trained LFM2.5 checkpoint — and applies a small set of bidirectional patches that adapt the hybrid LFM2 backbone from causal language modeling to full-context encoding:
+
+- **Attention mask:** the causal mask becomes a pad-only **bidirectional** mask, so every token can attend to the full sequence.
+- **Short convolutions:** the LFM2 short-conv layers become **non-causal**, mixing information symmetrically rather than only from the past.
 
-A multilingual late-interaction (ColBERT-style) retriever built on the LFM2 backbone, patched for bidirectional attention. Compatible with [PyLate](https://github.com/lightonai/pylate).
+This preserves the efficiency of the LFM2 architecture while producing the full-context representations that retrieval tasks need. The patches are shipped in `modeling_lfm2_bidirectional.py` inside this repo and are applied automatically when you load with `trust_remote_code=True` — see below.
 
-- **Backbone:** LFM2 350M (causal LM patched to encoder-style attention)
-- **Similarity:** MaxSim (late interaction)
-- **Output dimensionality:** 128 per token
-- **Query length:** 32 tokens
-- **Document length:** 512 tokens
-- **Query prefix:** `[Q] ` &nbsp; **Document prefix:** `[D] ` (handled automatically by PyLate)
-- **Source checkpoint:** `output/train_1811379_colbert-ft-s2/best`
+### Training
 
-## Usage
+Three-stage recipe shared with the bi-encoder companion:
+
+1. **Large-scale contrastive pretraining** on curated multi-domain English pairs.
+2. **Multilingual and cross-lingual distillation** from a strong teacher across all 11 supported languages.
+3. **Final fine-tuning** on hard-mined negatives.
+
+The training data combines curated internal data with open-source English retrieval datasets. LLM-based translation of queries and documents was used to expand multilingual and cross-lingual pairs in stages 2 and 3. The staged structure follows LightOn's LateOn / DenseOn releases.
+
+This ColBERT receives **less explicit cross-lingual data** than [LFM2.5-Embedding-350M](https://huggingface.co/LiquidAI/LFM2.5-Embedding-350M), because cross-lingual retrieval emerges more naturally in late-interaction setups and benefits less from additional supervision.
+
+## 🏃 How to run
 
 Install PyLate:
 
@@ -18,32 +114,78 @@ Install PyLate:
 pip install -U pylate
 ```
 
-### Retrieval (indexing + search)
+### Retrieval
+
+Use this model with PyLate to index and retrieve documents. The index uses [FastPLAID](https://github.com/lightonai/fast-plaid) for efficient similarity search.
+
+#### Indexing documents
 
 ```python
 from pylate import indexes, models, retrieve
 
+# Step 1: Load the ColBERT model (trust_remote_code applies the bidirectional patches)
 model = models.ColBERT(
     model_name_or_path="LiquidAI/LFM2.5-ColBERT-350M",
     trust_remote_code=True,
 )
 model.tokenizer.pad_token = model.tokenizer.eos_token
 
-index = indexes.PLAID(index_folder="pylate-index", index_name="index", override=True)
+# Step 2: Initialize the PLAID index
+index = indexes.PLAID(
+    index_folder="pylate-index",
+    index_name="index",
+    override=True,  # Overwrites any existing index with the same name
+)
 
+# Step 3: Encode the documents
 documents_ids = ["1", "2", "3"]
 documents = ["document 1 text", "document 2 text", "document 3 text"]
 
-documents_embeddings = model.encode(documents, batch_size=32, is_query=False, show_progress_bar=True)
-index.add_documents(documents_ids=documents_ids, documents_embeddings=documents_embeddings)
+documents_embeddings = model.encode(
+    documents,
+    batch_size=32,
+    is_query=False,
+    show_progress_bar=True,
+)
+
+# Step 4: Add document embeddings to the index
+index.add_documents(
+    documents_ids=documents_ids,
+    documents_embeddings=documents_embeddings,
+)
+```
+
+You don't have to rebuild the index every time. Reload an existing index by instantiating it with the same folder/name and `override=False`:
 
+```python
+index = indexes.PLAID(
+    index_folder="pylate-index",
+    index_name="index",
+)
+```
+
+#### Retrieving top-k documents
+
+```python
 retriever = retrieve.ColBERT(index=index)
-queries_embeddings = model.encode(["query for document 3", "query for document 1"], batch_size=32, is_query=True)
-scores = retriever.retrieve(queries_embeddings=queries_embeddings, k=10)
+
+queries_embeddings = model.encode(
+    ["query for document 3", "query for document 1"],
+    batch_size=32,
+    is_query=True,
+    show_progress_bar=True,
+)
+
+scores = retriever.retrieve(
+    queries_embeddings=queries_embeddings,
+    k=10,
+)
 ```
 
 ### Reranking
 
+For reranking on top of a first-stage pipeline, no index is needed:
+
 ```python
 from pylate import rank, models
 
@@ -53,21 +195,42 @@ model = models.ColBERT(
 )
 
 queries = ["query A", "query B"]
-documents = [["document A", "document B"], ["document 1", "document C", "document B"]]
-documents_ids = [[1, 2], [1, 3, 2]]
+documents = [
+    ["document A", "document B"],
+    ["document 1", "document C", "document B"],
+]
+documents_ids = [
+    [1, 2],
+    [1, 3, 2],
+]
 
 queries_embeddings = model.encode(queries, is_query=True)
 documents_embeddings = model.encode(documents, is_query=False)
 
-reranked = rank.rerank(
+reranked_documents = rank.rerank(
     documents_ids=documents_ids,
     queries_embeddings=queries_embeddings,
     documents_embeddings=documents_embeddings,
 )
 ```
 
-`trust_remote_code=True` is required: it loads `modeling_lfm2_bidirectional.py`, which replaces the causal attention mask and short-conv padding with their non-causal equivalents. Without it the model will silently use causal attention and produce poor embeddings.
+> **Note on `trust_remote_code`.** Loading requires `trust_remote_code=True` so the repo's `modeling_lfm2_bidirectional.py` can replace the causal attention mask and short-conv padding with their non-causal equivalents. Without it the model will silently use causal attention and produce poor retrieval embeddings.
+
+## 📈 Performance
+
+Detailed multilingual and cross-lingual NanoBEIR benchmarks are coming. Internally this checkpoint outperforms the previous [LFM2-ColBERT-350M](https://huggingface.co/LiquidAI/LFM2-ColBERT-350M) on multilingual NanoBEIR.
 
-### Note on FlashAttention-2
+## 📬 Contact
 
-`attn_implementation="flash_attention_2"` is intentionally rejected at load time (`disable_flash_attention` in `config.json`). ColBERT query expansion pads queries with mask tokens that have `attention_mask=0` but are still scored in MaxSim; FA2's unpadding cannot compute embeddings for those positions, which severely degrades retrieval quality (~10 ndcg@10 points on NanoBEIR). Use the default `sdpa` (or `eager`).
+Questions or feedback? [Join our Discord](https://discord.com/invite/liquid-ai).
+
+## Citation
+
+```
+@misc{PyLate,
+  title={PyLate: Flexible Training and Retrieval for Late Interaction Models},
+  author={Chaffin, Antoine and Sourty, Raphaël},
+  url={https://github.com/lightonai/pylate},
+  year={2024}
+}
+```