MLX Embeddings
github.com/blaizzy/mlx-embeddings- Category
- AI Tools
- Rank
- No. 1465Tools index
Previous survey · No. 1375 ·
- Pricing
- Open Source
- Type
- TOOL
- Builder
- blaizzy
- GitHub
- 443 stars
- Latest release
- v0.1.0
- Date
About
Run vision and language embedding models locally on Mac using MLX — fast on-device retrieval for Apple Silicon.
What it does
MLX Embeddings loads supported transformer checkpoints and produces normalized numeric representations for text, images, or mixed inputs. It can process one item or batches, compare similarity, rerank documents, and run masked-language or classification tasks. Models may come from a local directory or the Hugging Face Hub.
Why it's ranked here
Its strongest case is practical breadth within one Python package. The documented architecture set spans established text encoders, newer embedding models, multimodal retrieval, reranking, and PII classification. That scope is tempered by explicit pooling restrictions and an unfinished vision interpolation path, so model compatibility still requires checking.
What's good
The package handles text embeddings, image-text matching, multimodal embeddings, reranking, and batch similarity workflows. It normalizes text representations and supports mean, first-token, maximum, and last-token pooling. The conversion tooling can quantize supported layers with several formats, preserve vision layers when requested, and upload converted artifacts to Hugging Face.
Tradeoffs
The declared target is Mac, and installation requires Python 3.10 or newer plus MLX and related model libraries. Prompt-aware, concatenated, weighted-mean, and square-root-length pooling are unsupported. SigLIP positional interpolation is also unimplemented. Remote model identifiers trigger Hugging Face downloads, while gated repositories require authentication. GPLv3 may constrain proprietary redistribution choices.
How to use it well
Use it when a Python application needs embeddings, similarity scoring, multimodal retrieval, reranking, or classification with one of the supported architectures. Start with a documented checkpoint, validate its pooling configuration, then batch inputs where practical. Use the converter when storage or memory calls for quantization. It does not supply vector storage or an index, so pair it with a separate retrieval layer.
Technical notes+
mlx_embeddings/utils.py resolves local paths or downloads selected model files from Hugging Face, imports architecture modules from configuration, loads safetensors recursively, applies supported quantization metadata, sanitizes weights, and returns an evaluated model with a tokenizer or processor. mlx_embeddings/convert.py converts, quantizes, dequantizes, saves, and optionally uploads model artifacts. mlx_embeddings/models/pooling.py implements cls, mean, max, and lasttoken pooling while explicitly rejecting prompt-aware and several Sentence Transformers pooling modes. mlx_embeddings/models/siglip.py raises NotImplementedError for positional interpolation. pyproject.toml defines setuptools packaging, Python requirements, optional extras, and two console entry points.
Observed
- License
- GNU General Public License v3
- Primary language
- Python
- Installation
- Published Python package installable with pip as mlx-embeddings
- Python support
- Requires Python 3.10 or newer; classifiers list Python 3.10 through 3.13
- Interfaces
- Python library plus console entry points for CLI use and model conversion
- Platform support
- The project description targets running models locally on Mac
- Model sources
- Accepts local model directories or Hugging Face repository identifiers
- Core dependencies
- MLX, MLX-VLM, Transformers with SentencePiece, and huggingface-hub
Read from README.md, pyproject.toml, requirements.txt, mlx_embeddings/utils.py, mlx_embeddings/convert.py, mlx_embeddings/version.py, mlx_embeddings/__init__.py, mlx_embeddings/tokenizer_utils.py, mlx_embeddings/colvision_processor.py, mlx_embeddings/models/base.py, mlx_embeddings/models/bert.py, mlx_embeddings/models/lfm2.py, mlx_embeddings/models/qwen3.py, mlx_embeddings/models/siglip.py, mlx_embeddings/models/pooling.py.
What it can do
Generate text embeddings from natural language
Text or natural language prompts → Vector embeddings
Generate image embeddings from visual content
Images or visual media → Vector embeddings
Perform semantic search on text content
Query text and text corpus → Ranked search results
Perform visual similarity search
Query image and image collection → Similar images ranked by relevance
Run embedding models locally on Apple Silicon
Vision or language models → Local model execution without cloud dependencies
Process multimodal content for retrieval
Combined text and image data → Unified embedding representations
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.