README.md

---
license: other
license_name: offchain-studio-source-license-1.0
license_link: https://ai.basement.dev/license
library_name: transformers
pipeline_tag: token-classification
base_model: amsintelligence/masker
base_model_relation: finetune
datasets:
  - ai4privacy/pii-masking-openpii-1m
language:
  - bg
  - cs
  - da
  - de
  - el
  - en
  - es
  - et
  - fi
  - fr
  - hr
  - hu
  - it
  - lt
  - lv
  - nl
  - pl
  - pt
  - ro
  - sk
  - sl
  - sr
  - sv
tags:
  - token-classification
  - pii
  - pii-detection
  - pii-masking
  - redaction
  - privacy
  - on-device
  - onnx
  - coreml
  - distillation
metrics:
  - f1
model-index:
  - name: masker-mini
    results:
      - task:
          type: token-classification
          name: PII span detection
        dataset:
          name: pii-masking-openpii-1m (validation)
          type: ai4privacy/pii-masking-openpii-1m
        metrics:
          - type: f1
            name: Strict span F1
            value: 0.965
          - type: f1
            name: Typed F1
            value: 0.991
          - type: recall
            name: Leak-safe recall
            value: 0.998
---

# Masker Mini

**Masker-mini** is the on-device sibling of
[**masker**](https://huggingface.co/amsintelligence/masker): a 6-layer distilled
PII detector for **23 European languages** that keeps ~99% of the teacher's
strict-span F1 while shrinking to as little as **17 MB** (4-bit Core ML).

It runs fully offline, no PII leaves the device.

| artifact                            | format                   | size      | strict F1 |
| ----------------------------------- | ------------------------ | --------- | --------- |
| `model.safetensors`                 | PyTorch fp16             | 68 MB     | 0.965     |
| `onnx/model_fp16.onnx`              | ONNX fp16 (portable)      | 68 MB     | 0.965     |
| `onnx/model_int4.onnx`              | ONNX 4-bit (ONNX Runtime) | **22 MB** | 0.965     |
| `coreml/masker_mini_4bit.mlpackage` | Core ML 4-bit (Apple NE)  | **17 MB** | 0.965     |

## Model type & training

Masker Mini is a **6-layer BERT-architecture token classifier** (hidden size 384,
12 heads, ~35.6M parameters), a MiniLM-class encoder. It is trained by **knowledge
distillation** from `masker`.

After distillation the vocabulary was frequency-pruned,
shrinking the embedding table to land the whole network at ~35.6M parameters.

Three deployment artifacts are provided:

- **ONNX fp16** (68 MB): portable, runs anywhere via ONNX Runtime
  (Android / iOS / web / server); numerically identical to the PyTorch model.
- **ONNX 4-bit** (22 MB): weight-only block quantization (`MatMulNBits` +
  `GatherBlockQuantized`) of the Linear layers _and_ the embedding table. Needs
  ONNX Runtime ≥ 1.18 for the 4-bit ops; 99.8% token-faithful to fp16.
- **Core ML, 4-bit palettized** (17 MB): weight-only k-means palettization for
  the Apple Neural Engine (iOS 18 / macOS 15+). Palettization is effectively
  lossless here (Δ strict F1 = −0.0002 vs fp16).

It emits the **same 12 entity types** as
[masker](https://huggingface.co/amsintelligence/masker) (48 BIOES labels + `O`)
and slots into the same rules-layer pipeline for structured PII.

## Usage

For a plain PyTorch / Transformers quick start, the snippet on the
[masker](https://huggingface.co/amsintelligence/masker) card runs unchanged, just
point it at `amsintelligence/masker-mini`.

What this repo is actually for is the two on-device builds:

**ONNX Runtime** (portable for Android, iOS, web, server)

```python
import onnxruntime as ort, numpy as np
from transformers import AutoTokenizer

tok = AutoTokenizer.from_pretrained("amsintelligence/masker-mini")
sess = ort.InferenceSession("onnx/model_fp16.onnx")
text = "Stuur de factuur naar Sanne de Groot in Utrecht."
feed = {k: v.astype(np.int64) for k, v in tok(text, return_tensors="np").items()}
logits = sess.run(None, feed)[0]        # [1, seq_len, 49] BIOES logits -> argmax + decode
```

For the smallest portable build, swap in `onnx/model_int4.onnx` (22 MB, 4-bit) —
same inputs/outputs, needs ONNX Runtime ≥ 1.18.

**Core ML**, add `coreml/masker_mini_4bit.mlpackage` to an Xcode target.

Inputs `input_ids`, `attention_mask`, `token_type_ids`
(`Int32`, fixed length 256); output `logits`. The BIOES→span decode is the same
handful of lines shown on the masker card.

## Evaluation

openpii-1m validation, span-level, boundary-exact. **In-distribution — see
Limitations.** Numbers below are the **4-bit Core ML** build (fp16/PyTorch are
within ±0.001).

**Overall:** strict F1 **0.965** · typed F1 0.991 · leak-safe recall 0.998.
Distillation gap vs the masker teacher (0.982): **−0.007**.

**Per-type strict F1**

| entity        | F1    | entity          | F1    |
| ------------- | ----- | --------------- | ----- |
| DATE          | 0.999 | AGE             | 0.969 |
| EMAIL         | 0.999 | BUILDING_NUMBER | 0.969 |
| CREDIT_CARD   | 0.999 | CITY            | 0.954 |
| PHONE         | 0.998 | STREET_NAME     | 0.922 |
| GOVERNMENT_ID | 0.998 | GIVEN_NAME      | 0.910 |
| ZIP_CODE      | 0.994 | SURNAME         | 0.900 |

**By language**

| split                          | strict F1     |
| ------------------------------ | ------------- |
| English                        | 0.974         |
| Non-English (22 langs, pooled) | 0.971         |
| Dutch (flagship)               | 0.968         |
| Per-language range             | 0.960 - 0.983 |

## Limitations & biases

- **This is a compressed model.** It trails the full-size masker by ~0.7 strict-F1
  points, and the loss is not uniform: it lands almost entirely on `GIVEN_NAME` /
  `SURNAME`, plus `CITY` / `STREET_NAME` from the reduced 64K vocabulary. Structured
  types (email, phone, IDs, cards, dates) stay ≥ 0.99. The one language-specific
  soft spot is Dutch person-name boundaries (_tussenvoegsels_). If you need the top
  half-point back, use masker.
- Scores are **in-distribution** (synthetic openpii), treat them as an upper
  bound, measure on your own text, and design for residual leakage rather than
  assuming full coverage.

## Credits & attribution

Distilled from **masker**, which is itself a derivative of:

- **Backbone / tokenizer lineage:** [`microsoft/mdeberta-v3-base`](https://huggingface.co/microsoft/mdeberta-v3-base)
  by Microsoft; **MIT License** (masker-mini reuses mDeBERTa's SentencePiece
  tokenizer). DeBERTaV3: He, Gao & Chen, 2021
  ([arXiv:2111.09543](https://arxiv.org/abs/2111.09543)).
- **Training data:** [`ai4privacy/pii-masking-openpii-1m`](https://huggingface.co/datasets/ai4privacy/pii-masking-openpii-1m)
  by **Ai4Privacy**; **CC-BY-4.0**. Attribution required; please retain this
  credit in downstream use.

## License

Licensed under the **Offchain Studio Source License, Version 1.0**, a
source-available license. Full terms: <https://ai.basement.dev/license>.

Commercial-license requests: `licensing@basement.dev`.

See the accompanying **`NOTICE`** file; its Required
Notice line _MASKER-MINI © 2026 Offchain Studio_ must be retained in
redistribution.

The underlying components keep their own (attribution-only) terms, retained in
Credits above: the mDeBERTa lineage is **MIT** and the openpii training data is
**CC-BY-4.0**.

## Citation

```bibtex
@software{masker_mini,
  title  = {masker-mini: on-device PII detection for 23 European languages},
  year   = {2026},
  note   = {6-layer distillation of masker (mDeBERTa-v3); ONNX + Core ML},
  url    = {https://huggingface.co/amsintelligence/masker-mini}
}
```