Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,80 @@
+---
+license: mit
+tags:
+- executorch
+- xnnpack
+- pte
+- on-device
+- text-ranking
+- text-classification
+base_model:
+- BAAI/bge-reranker-base
+---
+# bge-reranker-base — ExecuTorch
+
+A cross-encoder reranker: a query and one document in, one relevance score out. The second
+stage of on-device retrieval — an embedding model fetches candidates cheaply, this reads
+each candidate together with the query and scores it properly.
+
+- **Source**: BAAI/bge-reranker-base — 278M parameters, 12 XLM-RoBERTa layers, hidden 768, 250k vocabulary
+- **License**: MIT
+- **Input**: `input_ids` and `attention_mask`, both `[1, 512]` int64
+- **Output**: `[1, 1]` fp32 — the raw logit. `sigmoid(x)` maps it to 0..1 and does not
+  change the ordering.
+
+## Variants
+
+| build | file | size (MB) | worst score error vs eager | Mac median (ms)* |
+|---|---|---|---|---|
+| fp32 | `rerank_bge_reranker_base_xnnpack_fp32.pte` | 1112.4 | 0.0000 logits | 76.9 |
+| fp16 | `rerank_bge_reranker_base_xnnpack_fp16.pte` | 556.4 | 0.0185 logits | 169.4 |
+| Core ML (fp16, iOS) | `rerank_bge_reranker_base_coreml_all.pte` | 556.6 | 0.0458 logits | 19.7 |
+
+\*Mac arm64, single process, median of 10, one query-document pair at 512 tokens — a
+reference point for relative cost, not a device number. PyTorch eager fp32 on the same
+machine: 54.7 ms.
+
+Correlation is not reported because it cannot be: the output is a single number, and the
+correlation of a one-element vector is undefined. The column above is the error in the
+units the model is used in — logits — over 6 real query-document pairs, and every build
+listed reproduces eager's ranking order exactly.
+
+## What it does, on the shipped fp32 build
+
+Query: *"How many people live in Berlin?"*
+
+| rank | score | document |
+|---|---|---|
+| 1 | +10.308 | ベルリンの人口はおよそ350万人です。 |
+| 2 | +10.302 | In 2019 the city recorded 3.7 million residents within its metropolitan area. |
+| 3 | +9.940 | Berlin has a population of 3,520,031 registered inhabitants in an area of 891.82 km². |
+| 4 | -2.708 | The capital of France is Paris, a city of about 2.1 million people. |
+| 5 | -6.198 | Berlin is well known for its museums, its nightlife and its history. |
+| 6 | -10.194 | Water boils at 100 degrees Celsius at sea level. |
+
+The narrowest gap between adjacent ranks here is 0.0057 logits — the top two both answer the question, so their order is a coin toss and a build that swapped them would not be wrong.
+
+## It ranks across languages
+
+The candidate list above includes a Japanese passage that answers the English query. This
+model puts it **first**; ms-marco-MiniLM-L6, the English-only reranker on this shelf, scores
+the same passage -10.96 and puts it fifth of six. That is what the 250k-token
+vocabulary buys, and it is also why this file is 12 times larger.
+
+## Not shipped
+
+- **int8 (dynamic) is not shipped**: at 856.1 MB it is larger than the fp16 build's 556.4 MB, and its score error is 0.5776 logits. Dynamic int8 quantizes the linear weights and leaves the token embedding table in fp32; fp16 halves that table too.
+
+## Verification
+
+```bash
+python convert/export_rerank.py bge_reranker_base
+python convert/check_rerank.py bge_reranker_base fp32
+```
+
+The check has two halves. One is agreement with the model run in eager, in logits and in
+ranking order. The other is that the ranking is useful at all: the passage that answers the
+question has to outscore a passage about the same subject that does not — agreement alone
+would pass a build that ranked by document length in both arms.
+
+(conversion scripts: [executorch-models](https://github.com/john-rocky/executorch-models))