UEmbed-2B-MLX-8bit

8-bit MLX quantization of the dense text-embedding tower of Alibaba-NLP/UEmbed-2B, packaged for Apple silicon. UEmbed-2B is built on the Qwen3.5 text architecture; this pack runs it natively with mlx-lm and produces L2-normalized dense embeddings that track the upstream PyTorch reference (see Verification below).

At a glance

Source	Alibaba-NLP/UEmbed-2B @ e7501a4d1be34ac4c7f8d1565cbeaa5b3f5b41b3
Format	MLX
Quantization	8-bit, group size 64
Disk size	2.0 GB

Variants

Variant	Quantization	Size	Status
UEmbed-2B-MLX-8bit (this repo)	8-bit, gs 64	2.0 GB	public
UEmbed-2B-MLX-4bit	4-bit, gs 32	1.3 GB	public

Verification (2026-08-11, M-series Mac)

• Quantization gate (this pack): worst cosine-vs-bf16 0.9996; retrieval ordering PASS (margins >0.2)
• bf16 port parity: MLX bf16 vs upstream torch (transformers 5.4.0, shipped Qwen35Embedder, fp32): cosine >= 0.99998 on all 6 fixed parity inputs; retrieval sims match (matched pairs 0.77/0.74, distractors ~0).

Usage

Requires: mlx-lm with qwen3_5 support (git main as of 2026-08-11; newer than the 0.31.3 release).

from mlx_lm import load
import mlx.core as mx
model, tok = load("majentik/UEmbed-2B-MLX-8bit")
def embed(text, instruction="Represent the user's input."):
    ids = tok.apply_chat_template(
        [{"role": "system", "content": instruction}, {"role": "user", "content": text}],
        add_generation_prompt=True, enable_thinking=False)
    h = model.model(mx.array([ids]))[0, -1, :].astype(mx.float32)
    return h / mx.sqrt((h * h).sum())

Embedding contract: messages=[system(instruction), user(text)]; tokenizer.apply_chat_template(add_generation_prompt=True, enable_thinking=False); dense embedding = final-norm hidden state at the LAST prompt token, L2-normalized. (Upstream appends 16 EOS and pools at last-16 — identical under causal attention.) Default instruction: "Represent the user's input."

Scope — DENSE TEXT embeddings v1: the pack contains the Qwen3.5 text tower only (the upstream repo's visual tower and SPLADE sparse heads are NOT included; use upstream for image/video/sparse). Checkpoint keys normalized from the upstream tripled prefix (model.language_model.language_model.language_model.*) to the standard text layout.

Reproduce

Prerequisite: the upstream checkpoint stores the text tower under a tripled prefix (model.language_model.language_model.language_model.*); normalize the keys to the standard Qwen3.5 text layout first, then convert the normalized checkpoint:

mlx_lm.convert --hf-path <normalized-UEmbed-2B> \
  --mlx-path UEmbed-2B-MLX-8bit \
  -q --q-bits 8 --q-group-size 64

License

CC-BY-4.0, inherited from the upstream Alibaba-NLP/UEmbed-2B. Attribution: this pack is a derivative of UEmbed-2B by Alibaba-NLP, redistributed with modifications (text-tower extraction, key normalization, 8-bit MLX quantization) under the terms of the CC-BY-4.0 license.