jina-reranker-v3-mlx

MLX port of jina-reranker-v3, a 0.6B parameter multilingual listwise reranker optimized for Apple Silicon. Features native MLX implementation with 100% matching of rank scores and embeddings to the original implementation. No transformers library required.

Installation

pip install -r requirements.txt

Usage

Basic Example

from rerank import MLXReranker

# Initialize the reranker
reranker = MLXReranker()

# Your query and documents
query = "What are the health benefits of green tea?"
documents = [
    "Green tea contains antioxidants called catechins that may help reduce inflammation and protect cells from damage.",
    "El precio del café ha aumentado un 20% este año debido a problemas en la cadena de suministro.",
    "Studies show that drinking green tea regularly can improve brain function and boost metabolism.",
    "Basketball is one of the most popular sports in the United States.",
    "绿茶富含儿茶素等抗氧化剂，可以降低心脏病风险，还有助于控制体重。",
    "Le thé vert est riche en antioxydants et peut améliorer la fonction cérébrale.",
]

# Rerank documents
results = reranker.rerank(query, documents)

# Results are sorted by relevance score (highest first)
for result in results:
    print(f"Score: {result['relevance_score']:.4f}")
    print(f"Document: {result['document'][:100]}...")
    print()

API Reference

reranker.rerank(
    query: str,                      # Search query
    documents: List[str],            # Documents to rank
    top_n: Optional[int] = None,     # Return only top N (default: all)
    return_embeddings: bool = False, # Include doc embeddings (default: False)
)

Returns: List of dicts with keys:

document: Original document text
relevance_score: Float score (higher = more relevant)
index: Position in input documents list
embedding: Document embedding (if return_embeddings=True)

Advanced Usage

# Get only top 3 results
top_results = reranker.rerank(query, documents, top_n=3)

# Get embeddings for further processing
results_with_embeddings = reranker.rerank(query, documents, return_embeddings=True)
for result in results_with_embeddings:
    embedding = result['embedding']  # numpy array of shape (512,)
    # Use embedding for downstream tasks...

Custom Model Path

# If model files are in a different location
reranker = MLXReranker(
    model_path="/path/to/model",
    projector_path="/path/to/projector.safetensors"
)

Citation

If you find jina-reranker-v3 useful in your research, please cite the original paper:

@misc{wang2025jinarerankerv3lateinteractiondocument,
      title={jina-reranker-v3: Last but Not Late Interaction for Document Reranking},
      author={Feng Wang and Yuqing Li and Han Xiao},
      year={2025},
      eprint={2509.25085},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2509.25085},
}