Practical overview
When it fits
Use it when you have query–document relevance examples and want to build a Python-based retrieval or ranking workflow tailored to your dataset.
Who it is for
- Developers building search for a custom collection of documents.
- Machine-learning practitioners preparing labeled query and document examples for retrieval or ranking.
Documented uses
- Fine-tune ColBERT, SPLADE or SparseEmbed for a domain-specific search dataset.
- Retrieve candidate documents and re-rank them with a fine-tuned model.
- Reuse computed embeddings rather than recomputing them.
Requirements & limits
The repository is public and licensed under MIT. The README documents installation with pip.
- ColBERT can be fine-tuned from a Sentence Transformer checkpoint; SPLADE and SparseEmbed require a masked-language-model checkpoint.
- The README describes support for CPU, GPU and MPS devices.
- Training examples must identify a query, a relevant document and an irrelevant document.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Fine-tune a ColBERT model
Train ColBERT on query, relevant-document and irrelevant-document triples and save a model checkpoint.
Before you start
- Install the neural-cherche Python package.
- Prepare training examples as (anchor, positive, negative) triples.
- Start from a Sentence Transformer checkpoint; the README example uses a neural-cherche ColBERT checkpoint.
- Use a CPU, GPU or MPS device.
Steps
Create the ColBERT model and select the device.
Create an optimizer for the model parameters.
Iterate over the training triples with the supplied utility and call train_colbert for each batch.
Save the model with save_pretrained when the desired training step is reached.
Expected outcome
A saved ColBERT checkpoint fine-tuned on the provided examples.
Guide limitations
- The documented training example is specific to ColBERT; SPLADE and SparseEmbed require a masked-language-model checkpoint.
- The example supplies training code but does not prescribe dataset size or training settings for a particular task.
Retrieve candidates and re-rank them with ColBERT
Use the documented retrieval example to retrieve candidate documents and score them with a ColBERT ranker.
Before you start
- Install neural-cherche and provide documents with an identifier and searchable fields.
- Load a ColBERT model checkpoint and configure a BM25 retriever and ColBERT ranker.
Steps
Encode the documents with the retriever and add their embeddings to its index.
Encode the queries for retrieval and ranking.
Retrieve candidate documents for each query.
Encode candidate documents with the ranker and score them against the ranking-query embeddings.
Expected outcome
Ranked candidate results with document identifiers and similarity scores.
Guide limitations
- The README example illustrates the workflow with a small document collection; it does not specify production-scale deployment or performance.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 16 October 2026
- Original website title
- raphaelsty/neural-cherche · Official homepage title · retained in its source language