MTEB

Evaluates embedding models against a standardized task hierarchy (AbsTask base class) spanning retrieval, classification, clustering, reranking, pair classification, and semantic textual similarity. Each task type implements task-specific evaluation logic with custom metrics, enabling models to be benchmarked across diverse embedding use cases in a single evaluation run. The framework abstracts task-specific scorer implementations while maintaining consistent metadata and result serialization.

Provides language-aware task metadata and dataset selection enabling evaluation of embedding models across 112+ languages and cross-lingual scenarios. Tasks are tagged with language codes and domain information, allowing filtering and evaluation of multilingual models on language-specific or cross-lingual retrieval/classification tasks. The framework handles language-specific dataset loading and metric computation without requiring model-level language handling.

Serializes evaluation results to standardized JSON format compatible with leaderboard ingestion, including model metadata, task results, metrics, and evaluation metadata (date, MTEB version). Results are stored in a hierarchical structure with per-task and aggregated metrics. The framework supports result loading from JSON files or Hugging Face Hub, enabling result sharing and leaderboard submission. Model cards can be automatically generated from results.

Provides a CLI (via Click or argparse) enabling batch evaluation of models on benchmarks without writing Python code. Supports commands for running benchmarks, submitting results, and viewing leaderboard results. CLI handles model loading, benchmark selection, result serialization, and optional leaderboard submission. Enables integration with CI/CD pipelines and automated evaluation workflows. Supports configuration files for reproducible evaluation setups.

Defines pre-curated benchmark suites (e.g., MTEB, MTEB-Lite, RTEB) as collections of specific tasks with fixed configurations, enabling reproducible model comparisons across the community. Benchmarks are defined in mteb/benchmarks/benchmarks.py and can be retrieved via get_benchmark() API, which returns a Benchmark object containing task instances, metadata, and execution parameters. This abstraction decouples benchmark definition from evaluation logic.

Defines an encoder protocol (encode() method signature) that abstracts model-specific implementation details, enabling evaluation of any embedding model (SentenceTransformers, instruction-tuned models, custom implementations) through a unified interface. Models are wrapped in encoder classes (e.g., SentenceTransformerEncoder, InstructionBasedEncoder) that implement the protocol, handle batching, and manage model loading. This decouples task evaluation logic from model-specific code paths.

Implements task-specific evaluators (e.g., RetrievalEvaluator, ClassificationEvaluator, ClusteringEvaluator) that compute metrics appropriate to each task type using embeddings and ground truth labels. Metrics include NDCG, MAP, F1, NMI, and others depending on task. Results are aggregated per-task and across benchmarks, with support for weighted averaging and stratified analysis by language or domain. Results are serialized to standardized JSON format for leaderboard submission.

Implements caching mechanisms to avoid recomputing embeddings across multiple evaluation runs, storing embeddings in local cache (typically .cache/mteb_embeddings/) keyed by model name and dataset. Supports batch processing with configurable batch sizes to manage memory usage during encoding. Lazy loading of datasets from Hugging Face Hub with optional local caching reduces network overhead. These optimizations enable faster iteration during model development and reduce API calls for remote models.

Provides a Streamlit-based web application (mteb/leaderboard/app.py) that visualizes benchmark results, enabling filtering by model, task, language, and domain. The leaderboard loads results from JSON files or Hugging Face Hub, renders interactive tables with sortable columns, and generates comparison plots. Benchmark selector UI allows users to switch between MTEB, MTEB-Lite, and RTEB suites. Results can be submitted via model cards and are automatically ingested into the leaderboard.

Maintains a centralized model registry (mteb/models.py) with metadata for 100+ embedding models, including model name, organization, parameters, and encoder wrapper type. Models are registered with their encoder class (SentenceTransformerEncoder, InstructionBasedEncoder, etc.) and can be retrieved via get_model() API. Model metadata includes embedding dimension, max sequence length, and instruction support, enabling automatic model selection and configuration.

Loads evaluation datasets from Hugging Face Hub (via datasets library) with automatic caching and preprocessing. Tasks define dataset identifiers and splits (train/test), and the framework handles downloading, caching, and formatting data into task-specific structures (queries, documents, labels). Supports lazy loading to minimize memory overhead. Datasets are cached locally to avoid repeated downloads, with optional offline mode for environments without internet access.

Provides an AbsTask base class that defines the task interface (load_data(), run(), evaluate() methods) and metadata structure (task name, description, languages, domains). New tasks inherit from AbsTask and override load_data() to define dataset loading and evaluate() to implement task-specific evaluation logic. Task metadata is automatically extracted and used for filtering, result aggregation, and leaderboard organization. This design enables community contributions of new tasks without modifying core evaluation logic.