Add MLX 6-bit conversion of BAAI/AREX-Turbo with evaluation against bf16

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,176 @@
+---
+library_name: mlx
+license: apache-2.0
+pipeline_tag: text-generation
+base_model: BAAI/AREX-Turbo
+language:
+- en
+tags:
+- agent
+- deep-research
+- reasoning
+- tool-use
+- long-context
+- qwen3.5
+- dense
+- image-text-to-text
+- mlx
+---
+
+# mlx-community/AREX-Turbo-6bit
+
+[BAAI/AREX-Turbo](https://huggingface.co/BAAI/AREX-Turbo) converted to MLX and quantized to
+**6-bit**, for inference on Apple Silicon.
+
+Converted with `mlx-vlm` 0.6.8 (`mlx` 0.32.0).
+
+## Quantization
+
+| | |
+|---|---|
+| Requested bits | 6 |
+| Group size | 64 |
+| Mode | affine |
+| **Effective bits per weight** | **7.2** |
+| On-disk size | 3.8 GB |
+
+The effective figure exceeds 6 because `mlx-vlm` **leaves the vision tower
+in bf16 by design** and quantizes only the language model — the vision encoder is
+a small share of the weights but disproportionately sensitive to quantization
+error. Verified on this conversion:
+
+```
+language_model: QuantizedLinear x186, QuantizedEmbedding x1   <- 6-bit
+vision_tower  : Linear x50, LayerNorm x25, Conv3d x1          <- bf16
+```
+
+## Evaluation
+
+All numbers below were measured against the **unquantized bf16 source** on an
+M2 Pro (32 GB), greedy decoding throughout.
+
+### Distributional fidelity (teacher-forced, deterministic)
+
+Perplexity over 204 tokens of held-out text spanning prose, code, legal and
+scientific registers; top-1 agreement and KL are computed per position over the
+full next-token distribution. These are the numbers to judge quantization by —
+they involve no sampling and no decoding choices.
+
+| Metric | This model (6-bit) | bf16 reference |
+|---|---|---|
+| Perplexity | 3.0213 | 3.0171 |
+| Perplexity ratio | **1.0014** | 1.000 |
+| Top-1 agreement with bf16 | **0.9902** | — |
+| KL(bf16 ‖ quant) | **0.002364** nats/token | 0 |
+
+### Generation agreement vs bf16
+
+Greedy (`temperature=0.0`) continuations, scored against the bf16 output as
+reference.
+
+| Metric | Score |
+|---|---|
+| BLEU | 65.02 |
+| chrF | 78.83 |
+| ROUGE-1 / ROUGE-L | 0.7682 / 0.7682 |
+| Exact match | 3/6 |
+
+**Read these as agreement, not quality.** bf16 is the reference here, not ground
+truth, so a divergence is only a defect if the quantized answer is *worse*. It
+is not always: on `17 * 23` the bf16 model started a long derivation while the
+6-bit model answered `391` directly — a mismatch that counts against BLEU
+while being the better response. That is why the two sections below exist.
+
+### Task accuracy (ground truth, no judge)
+
+Pass rate on 8 short prompts with verifiable answers (arithmetic, factual
+recall, sorting). Deterministic — this is the only layer that measures
+correctness rather than similarity.
+
+| | Accuracy |
+|---|---|
+| bf16 | 7/8 |
+| **6-bit** | **7/8** |
+
+### Judged quality (LLM-as-judge, blind)
+
+18 open-ended prompts graded by `claude-sonnet-5`. The judge never sees which
+model produced which answer. Pairwise comparisons are run **twice with positions
+swapped**; a verdict counts only if the judge picks the same model both times,
+and disagreements are reported as `inconsistent` rather than resolved silently.
+Absolute grades are averaged over 2 repeats per answer.
+
+| Metric | bf16 | 6-bit |
+|---|---|---|
+| Absolute quality (1-5) | 4.778 ± 0.083 | 4.583 ± 0.153 |
+| Pairwise wins | 1 | 2 |
+| Ties | 8 | |
+| Inconsistent (judge flipped) | 7 | |
+
+Gap of **0.195** against combined judge noise of **0.236** →
+**indistinguishable from bf16**.
+
+Judge noise is not negligible and is reported rather than hidden: grading the
+same bf16 model across separate runs varied by ~0.17 on this scale. Differences
+smaller than the combined SEM should not be read as a ranking.
+
+### Across all variants
+
+| Variant | bpw | PPL ratio | Top-1 agree | KL | BLEU | Accuracy | Judge (1-5) | Size |
+|---|---|---|---|---|---|---|---|---|
+| 4-bit | 5.347 | 1.1158 | 0.9265 | 0.052755 | 49.52 | 8/8 | 4.583 | 2.9 GB |
+| 6-bit | 7.2 | 1.0014 | 0.9902 | 0.002364 | 65.02 | 7/8 | 4.583 | 3.8 GB |
+| 8-bit | 9.053 | 0.997 | 0.9951 | 0.000691 | 82.65 | 7/8 | 4.694 | 4.8 GB |
+
+BLEU against bf16 falls from 82.7 (8-bit) to 49.5 (4-bit), while task accuracy
+and judged quality stay flat. Judged quality is statistically indistinguishable
+from bf16 at every bit width tested. KL divergence from bf16 drops ~76x across
+that same range.
+
+### Throughput (M2 Pro, 32 GB, 128-token decode)
+
+Hardware-specific; will differ on other chips.
+
+| Variant | Decode tok/s | Peak RAM |
+|---|---|---|
+| bf16 (source) | 18.2 | 9.229 GB |
+| 4-bit | 60.9 | 3.677 GB |
+| 6-bit | 44.5 | 4.917 GB |
+| 8-bit | 34.7 | 6.152 GB |
+
+### What was not measured
+
+No standard task benchmarks (MMLU, GSM8K, agentic/tool-use evals) were run. The
+accuracy layer above is 8 short prompts, not a benchmark. The vision path
+was checked for coherence on sample images but not scored. The source model is
+agent/deep-research oriented, and none of its agentic capabilities were
+evaluated here — if that is your use case, measure on your own data.
+
+## Usage
+
+```bash
+pip install mlx-vlm
+```
+
+```python
+from mlx_vlm import load, generate
+from mlx_vlm.prompt_utils import apply_chat_template
+from mlx_vlm.utils import load_config
+
+model, processor = load("mlx-community/AREX-Turbo-6bit")
+config = load_config("mlx-community/AREX-Turbo-6bit")
+
+prompt = apply_chat_template(processor, config, "What can you do?", num_images=0)
+print(generate(model, processor, prompt, max_tokens=256, verbose=False).text)
+```
+
+With an image:
+
+```python
+prompt = apply_chat_template(processor, config, "Describe this image.", num_images=1)
+out = generate(model, processor, prompt, image=["<path-or-url>"], max_tokens=256)
+print(out.text)
+```
+
+See the [original model card](https://huggingface.co/BAAI/AREX-Turbo) for capabilities,
+intended use and limitations. All credit for the model belongs to its authors.

chat_template.jinja

@@ -0,0 +1,154 @@
+{%- set image_count = namespace(value=0) %}
+{%- set video_count = namespace(value=0) %}
+{%- macro render_content(content, do_vision_count, is_system_content=false) %}
+    {%- if content is string %}
+        {{- content }}
+    {%- elif content is iterable and content is not mapping %}
+        {%- for item in content %}
+            {%- if 'image' in item or 'image_url' in item or item.type == 'image' %}
+                {%- if is_system_content %}
+                    {{- raise_exception('System message cannot contain images.') }}
+                {%- endif %}
+                {%- if do_vision_count %}
+                    {%- set image_count.value = image_count.value + 1 %}
+                {%- endif %}
+                {%- if add_vision_id %}
+                    {{- 'Picture ' ~ image_count.value ~ ': ' }}
+                {%- endif %}
+                {{- '<|vision_start|><|image_pad|><|vision_end|>' }}
+            {%- elif 'video' in item or item.type == 'video' %}
+                {%- if is_system_content %}
+                    {{- raise_exception('System message cannot contain videos.') }}
+                {%- endif %}
+                {%- if do_vision_count %}
+                    {%- set video_count.value = video_count.value + 1 %}
+                {%- endif %}
+                {%- if add_vision_id %}
+                    {{- 'Video ' ~ video_count.value ~ ': ' }}
+                {%- endif %}
+                {{- '<|vision_start|><|video_pad|><|vision_end|>' }}
+            {%- elif 'text' in item %}
+                {{- item.text }}
+            {%- else %}
+                {{- raise_exception('Unexpected item type in content.') }}
+            {%- endif %}
+        {%- endfor %}
+    {%- elif content is none or content is undefined %}
+        {{- '' }}
+    {%- else %}
+        {{- raise_exception('Unexpected content type.') }}
+    {%- endif %}
+{%- endmacro %}
+{%- if not messages %}
+    {{- raise_exception('No messages provided.') }}
+{%- endif %}
+{%- if tools and tools is iterable and tools is not mapping %}
+    {{- '<|im_start|>system\n' }}
+    {{- "# Tools\n\nYou have access to the following functions:\n\n<tools>" }}
+    {%- for tool in tools %}
+        {{- "\n" }}
+        {{- tool | tojson }}
+    {%- endfor %}
+    {{- "\n</tools>" }}
+    {{- '\n\nIf you choose to call a function ONLY reply in the following format with NO suffix:\n\n<tool_call>\n<function=example_function_name>\n<parameter=example_parameter_1>\nvalue_1\n</parameter>\n<parameter=example_parameter_2>\nThis is the value for the second parameter\nthat can span\nmultiple lines\n</parameter>\n</function>\n</tool_call>\n\n<IMPORTANT>\nReminder:\n- Function calls MUST follow the specified format: an inner <function=...></function> block must be nested within <tool_call></tool_call> XML tags\n- Required parameters MUST be specified\n- You may provide optional reasoning for your function call in natural language BEFORE the function call, but NOT after\n- If there is no function call available, answer the question like normal with your current knowledge and do not tell the user about function calls\n</IMPORTANT>' }}
+    {%- if messages[0].role == 'system' %}
+        {%- set content = render_content(messages[0].content, false, true)|trim %}
+        {%- if content %}
+            {{- '\n\n' + content }}
+        {%- endif %}
+    {%- endif %}
+    {{- '<|im_end|>\n' }}
+{%- else %}
+    {%- if messages[0].role == 'system' %}
+        {%- set content = render_content(messages[0].content, false, true)|trim %}
+        {{- '<|im_start|>system\n' + content + '<|im_end|>\n' }}
+    {%- endif %}
+{%- endif %}
+{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
+{%- for message in messages[::-1] %}
+    {%- set index = (messages|length - 1) - loop.index0 %}
+    {%- if ns.multi_step_tool and message.role == "user" %}
+        {%- set content = render_content(message.content, false)|trim %}
+        {%- if not(content.startswith('<tool_response>') and content.endswith('</tool_response>')) %}
+            {%- set ns.multi_step_tool = false %}
+            {%- set ns.last_query_index = index %}
+        {%- endif %}
+    {%- endif %}
+{%- endfor %}
+{%- if ns.multi_step_tool %}
+    {{- raise_exception('No user query found in messages.') }}
+{%- endif %}
+{%- for message in messages %}
+    {%- set content = render_content(message.content, true)|trim %}
+    {%- if message.role == "system" %}
+        {%- if not loop.first %}
+            {{- raise_exception('System message must be at the beginning.') }}
+        {%- endif %}
+    {%- elif message.role == "user" %}
+        {{- '<|im_start|>' + message.role + '\n' + content + '<|im_end|>' + '\n' }}
+    {%- elif message.role == "assistant" %}
+        {%- set reasoning_content = '' %}
+        {%- if message.reasoning_content is string %}
+            {%- set reasoning_content = message.reasoning_content %}
+        {%- else %}
+            {%- if '</think>' in content %}
+                {%- set reasoning_content = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
+                {%- set content = content.split('</think>')[-1].lstrip('\n') %}
+            {%- endif %}
+        {%- endif %}
+        {%- set reasoning_content = reasoning_content|trim %}
+        {%- if loop.index0 > ns.last_query_index %}
+            {{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content + '\n</think>\n\n' + content }}
+        {%- else %}
+            {{- '<|im_start|>' + message.role + '\n' + content }}
+        {%- endif %}
+        {%- if message.tool_calls and message.tool_calls is iterable and message.tool_calls is not mapping %}
+            {%- for tool_call in message.tool_calls %}
+                {%- if tool_call.function is defined %}
+                    {%- set tool_call = tool_call.function %}
+                {%- endif %}
+                {%- if loop.first %}
+                    {%- if content|trim %}
+                        {{- '\n\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                    {%- else %}
+                        {{- '<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                    {%- endif %}
+                {%- else %}
+                    {{- '\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                {%- endif %}
+                {%- if tool_call.arguments is defined %}
+                    {%- for args_name, args_value in tool_call.arguments|items %}
+                        {{- '<parameter=' + args_name + '>\n' }}
+                        {%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}
+                        {{- args_value }}
+                        {{- '\n</parameter>\n' }}
+                    {%- endfor %}
+                {%- endif %}
+                {{- '</function>\n</tool_call>' }}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "tool" %}
+        {%- if loop.previtem and loop.previtem.role != "tool" %}
+            {{- '<|im_start|>user' }}
+        {%- endif %}
+        {{- '\n<tool_response>\n' }}
+        {{- content }}
+        {{- '\n</tool_response>' }}
+        {%- if not loop.last and loop.nextitem.role != "tool" %}
+            {{- '<|im_end|>\n' }}
+        {%- elif loop.last %}
+            {{- '<|im_end|>\n' }}
+        {%- endif %}
+    {%- else %}
+        {{- raise_exception('Unexpected message role.') }}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|im_start|>assistant\n' }}
+    {%- if enable_thinking is defined and enable_thinking is false %}
+        {{- '<think>\n\n</think>\n\n' }}
+    {%- else %}
+        {{- '<think>\n' }}
+    {%- endif %}
+{%- endif %}

config.json

@@ -0,0 +1,120 @@
+{
+    "architectures": [
+        "Qwen3_5ForConditionalGeneration"
+    ],
+    "dtype": "bfloat16",
+    "hidden_size": 2560,
+    "image_token_id": 248056,
+    "model_type": "qwen3_5",
+    "quantization": {
+        "group_size": 64,
+        "bits": 6,
+        "mode": "affine"
+    },
+    "quantization_config": {
+        "group_size": 64,
+        "bits": 6,
+        "mode": "affine"
+    },
+    "text_config": {
+        "attention_bias": false,
+        "attention_dropout": 0.0,
+        "attn_output_gate": true,
+        "bos_token_id": null,
+        "dtype": "bfloat16",
+        "eos_token_id": 248044,
+        "full_attention_interval": 4,
+        "head_dim": 256,
+        "hidden_act": "silu",
+        "hidden_size": 2560,
+        "initializer_range": 0.02,
+        "intermediate_size": 9216,
+        "layer_types": [
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention",
+            "linear_attention",
+            "linear_attention",
+            "linear_attention",
+            "full_attention"
+        ],
+        "linear_conv_kernel_dim": 4,
+        "linear_key_head_dim": 128,
+        "linear_num_key_heads": 16,
+        "linear_num_value_heads": 32,
+        "linear_value_head_dim": 128,
+        "mamba_ssm_dtype": "float32",
+        "max_position_embeddings": 262144,
+        "mlp_only_layers": [],
+        "model_type": "qwen3_5_text",
+        "mtp_num_hidden_layers": 1,
+        "mtp_use_dedicated_embeddings": false,
+        "num_attention_heads": 16,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 4,
+        "pad_token_id": null,
+        "partial_rotary_factor": 0.25,
+        "rms_norm_eps": 1e-06,
+        "rope_parameters": {
+            "mrope_interleaved": true,
+            "mrope_section": [
+                11,
+                11,
+                10
+            ],
+            "partial_rotary_factor": 0.25,
+            "rope_theta": 10000000,
+            "rope_type": "default"
+        },
+        "tie_word_embeddings": true,
+        "use_cache": true,
+        "vocab_size": 248320
+    },
+    "tie_word_embeddings": true,
+    "transformers_version": "5.2.0",
+    "video_token_id": 248057,
+    "vision_config": {
+        "deepstack_visual_indexes": [],
+        "depth": 24,
+        "dtype": "bfloat16",
+        "hidden_act": "gelu_pytorch_tanh",
+        "hidden_size": 1024,
+        "in_channels": 3,
+        "initializer_range": 0.02,
+        "intermediate_size": 4096,
+        "model_type": "qwen3_5",
+        "num_heads": 16,
+        "num_position_embeddings": 2304,
+        "out_hidden_size": 2560,
+        "patch_size": 16,
+        "spatial_merge_size": 2,
+        "temporal_patch_size": 2
+    },
+    "vision_end_token_id": 248054,
+    "vision_start_token_id": 248053
+}

configuration.json

@@ -0,0 +1 @@
+{"framework": "pytorch", "task": "text-generation", "allow_remote": true}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9e50b980bbcae9ae33cc3e03f9720fcc27940e4ba9a8694ba0522f4171780cbf
+size 4085496931

preprocessor_config.json

@@ -0,0 +1,21 @@
+{
+    "size": {
+        "longest_edge": 16777216,
+        "shortest_edge": 65536
+    },
+    "patch_size": 16,
+    "temporal_patch_size": 2,
+    "merge_size": 2,
+    "image_mean": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "image_std": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "processor_class": "Qwen3VLProcessor",
+    "image_processor_type": "Qwen2VLImageProcessorFast"
+}

processor_config.json

@@ -0,0 +1,50 @@
+{
+  "image_processor": {
+    "do_convert_rgb": true,
+    "do_normalize": true,
+    "do_rescale": true,
+    "image_mean": [
+      0.5,
+      0.5,
+      0.5
+    ],
+    "image_processor_type": "Qwen3VLImageProcessor",
+    "image_std": [
+      0.5,
+      0.5,
+      0.5
+    ],
+    "max_pixels": 16777216,
+    "merge_size": 2,
+    "min_pixels": 65536,
+    "patch_size": 16,
+    "rescale_factor": 0.00392156862745098,
+    "temporal_patch_size": 2
+  },
+  "processor_class": "Qwen3VLProcessor",
+  "video_processor": {
+    "do_convert_rgb": true,
+    "do_normalize": true,
+    "do_rescale": true,
+    "fps": 2.0,
+    "image_mean": [
+      0.5,
+      0.5,
+      0.5
+    ],
+    "image_std": [
+      0.5,
+      0.5,
+      0.5
+    ],
+    "max_frames": 768,
+    "max_pixels": 25165824,
+    "merge_size": 2,
+    "min_frames": 4,
+    "min_pixels": 4096,
+    "patch_size": 16,
+    "rescale_factor": 0.00392156862745098,
+    "temporal_patch_size": 2,
+    "video_processor_type": "Qwen3VLVideoProcessor"
+  }
+}

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:06b9509352d2af50381ab2247e083b80d32d5c0aba91c272ca9ff729b6a0e523
+size 19989325

tokenizer_config.json

@@ -0,0 +1,33 @@
+{
+  "add_prefix_space": false,
+  "audio_bos_token": "<|audio_start|>",
+  "audio_eos_token": "<|audio_end|>",
+  "audio_token": "<|audio_pad|>",
+  "backend": "tokenizers",
+  "bos_token": null,
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "image_token": "<|image_pad|>",
+  "is_local": true,
+  "local_files_only": false,
+  "model_max_length": 262144,
+  "model_specific_special_tokens": {
+    "audio_bos_token": "<|audio_start|>",
+    "audio_eos_token": "<|audio_end|>",
+    "audio_token": "<|audio_pad|>",
+    "image_token": "<|image_pad|>",
+    "video_token": "<|video_pad|>",
+    "vision_bos_token": "<|vision_start|>",
+    "vision_eos_token": "<|vision_end|>"
+  },
+  "pad_token": "<|endoftext|>",
+  "pretokenize_regex": "(?i:'s|'t|'re|'ve|'m|'ll|'d)|[^\\r\\n\\p{L}\\p{N}]?[\\p{L}\\p{M}]+|\\p{N}| ?[^\\s\\p{L}\\p{M}\\p{N}]+[\\r\\n]*|\\s*[\\r\\n]+|\\s+(?!\\S)|\\s+",
+  "processor_class": "Qwen3VLProcessor",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null,
+  "video_token": "<|video_pad|>",
+  "vision_bos_token": "<|vision_start|>",
+  "vision_eos_token": "<|vision_end|>"
+}

video_preprocessor_config.json

@@ -0,0 +1,21 @@
+{
+    "size": {
+        "longest_edge": 25165824,
+        "shortest_edge": 4096
+    },
+    "patch_size": 16,
+    "temporal_patch_size": 2,
+    "merge_size": 2,
+    "image_mean": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "image_std": [
+        0.5,
+        0.5,
+        0.5
+    ],
+    "processor_class": "Qwen3VLProcessor",
+    "video_processor_type": "Qwen3VLVideoProcessor"
+}