README.md

---

language:
- ba
license: apache-2.0
pretty_name: BashkirRoBERTa NER
library_name: onnxruntime
pipeline_tag: token-classification
tags:
- bashkir
- named-entity-recognition
- person
- onnx
- onnxruntime
- low-resource
---


# BashkirRoBERTa NER

> ONNX models for finding person names in Bashkir text, with a compact CPU default.

## Overview

BashkirRoBERTa NER is a person-name tagger fine-tuned from the BashkirRoBERTa
masked-language encoder. It recognizes people (`PER`) and returns spans in the
original text. The release includes FP32 and dynamically quantized INT8 ONNX
graphs, the original SentencePiece tokenizer, and a small standalone runtime.
The INT8 model is the default for CPU use.

| At a glance | |
| --- | --- |
| Task | Bashkir person named entity recognition (`PER`) |
| Default artifact | `onnx/model_int8.onnx` |
| Source | A Bashkir-language encoder and person-entity training annotations |
| Version / license | v1 / Apache-2.0 |

## Contents

### Files and Configurations

| File | Purpose | Size |
| --- | --- | ---: |
| **`onnx/model_int8.onnx`** | CPU default, dynamic INT8 | 82.4 MB |

| `onnx/model_fp32.onnx` | FP32 reference with PyTorch tag parity | 200.3 MB |

| `spm_bashkir_bert_16k.model` | SentencePiece tokenizer | 0.59 MB |

| `runtime.py` | Word alignment, BIO spans, character offsets | — |

| `config.json` | Architecture, label order, runtime contract | — |

| `benchmark_summary.json` | Aggregate evaluation without source text | — |

| `example.py` | Download and run the default model | — |

| `META.json` | Release passport and artifact hashes | — |

| `LICENSE` | Full license text | — |

| `SHA256SUMS` | Checksums of the public files | — |



### Model Architecture



| Property | Value |

| --- | --- |

| Encoder | BashkirRoBERTa, eight Pre-LayerNorm Transformer blocks |

| Head | Linear word-level classifier |

| Labels | `O`, `B-PER`, `I-PER` |

| Tokenization | SentencePiece, first piece of each original word is labeled |

| Input | `input_ids`, int64, dynamic batch and sequence dimensions |

| Output | `logits`, float, `[batch, sequence, 3]` |

| Maximum context | 256 SentencePiece tokens, including boundary tokens |



### Examples



Outputs below were produced by the included INT8 runtime:



| Input | Found people |

| --- | --- |

| `Рәми Ғарипов һәм Мостай Кәрим тураһында һөйләштек.` | `Рәми Ғарипов`; `Мостай Кәрим` |

| `Мәрйәм менән Илнур мәктәпкә китте.` | `Мәрйәм`; `Илнур` |

| `Өфө ҡалаһында яңы мәктәп асылды.` | None |



## Method



```text

BashkirRoBERTa base encoder

  ├── 1. tokenization with first-subword alignment mapping

  ├── 2. fine-tune token classification head on Bashkir person-entity corpus

  ├── 3. export FP32 ONNX inference graph

  └── 4. dynamic INT8 quantization & word-level BIO decoding

```



The encoder was fine-tuned with Bashkir person-entity annotations; its encoder

layers and classification head changed. The original masked-language ONNX graph

cannot be combined with this head to reproduce the release. Training data and

evaluation text are not included. The tokenizer and first-subword alignment are

provided so ONNX scores can be mapped back to complete words.



### Benchmark



On a held-out, human-verified person-entity set, exact person-span micro F1 is

**0.8594** for FP32 and **0.8589** for INT8 when run one sentence at a time

through the included adapter. FP32 makes no word-tag changes relative to the

PyTorch checkpoint. The separately authored 100-sentence stress suite gives span F1

**0.9294** (FP32) and **0.9231** (INT8), with 92 sentences entirely correct in

each format. The stress suite is a targeted diagnostic, not an estimate of

population accuracy. Dynamic INT8 outputs can vary slightly with batch

composition; the figures above use the public single-sentence runtime. Counts

and the BIO scoring convention are in

[`benchmark_summary.json`](benchmark_summary.json).



## Quality and Use



Use this model to find mentions of people in Bashkir text, including inflected

names and multiword names. The `runtime.py` adapter returns each span with

character offsets. `predict_tokens` also accepts pre-tokenized words for

evaluation workflows. The default INT8 graph is smaller while preserving nearly

all of the observed gold-set score; FP32 is available when exact checkpoint

parity matters.



### Limitations



- Only person entities are labeled. Places and organizations have no output class.

- Rare names can be missed. Long names and adjacent people can be split or merged.

- Names inside institution names can be mistaken for person mentions.

- Inputs beyond the context limit are truncated; the runtime reports `truncated: true`.

- Word boundaries from noisy OCR, unusual punctuation, and mixed writing systems

  can differ from the training tokenization.

- The authored stress suite is too small and structured to replace the held-out

  human-verified benchmark.



## Related Resources



- [BashkirRoBERTa](https://huggingface.co/failed09/bashkir-roberta) is the

  underlying masked-language model; use it for fill-mask work and new fine-tuning

  tasks rather than person-name extraction.



## Usage



```bash

pip install onnxruntime sentencepiece numpy huggingface_hub

```



```python

import sys

from huggingface_hub import snapshot_download



model_dir = snapshot_download(

    "failed09/bashkir-roberta-ner",

    allow_patterns=["onnx/model_int8.onnx", "spm_bashkir_bert_16k.model",

                    "config.json", "runtime.py"],

)

sys.path.insert(0, model_dir)

from runtime import BashkirPersonNER



ner = BashkirPersonNER(model_dir)

print(ner.predict("Рәми Ғарипов һәм Мостай Кәрим тураһында һөйләштек."))

```



For the FP32 graph, download `onnx/model_fp32.onnx` as well and construct

`BashkirPersonNER(model_dir, precision="fp32")`. The included `example.py`

runs the default configuration.



## License



The model weights, tokenizer and runtime are distributed under the

[Apache-2.0 license](https://huggingface.co/failed09/bashkir-roberta-ner/blob/main/LICENSE). The model is fine-tuned from

[BashkirRoBERTa](https://huggingface.co/failed09/bashkir-roberta), which is also

released under Apache-2.0. Training texts and benchmark sentences are not

included; rights in the original texts remain with their respective owners.

Contact the maintainer through the Hub for provenance or removal requests.



## Citation



```bibtex

@software{failed09_bashkir_roberta_ner_2026,

  title = {BashkirRoBERTa NER},

  author = {failed09},

  year = {2026},

  publisher = {Hugging Face},

  url = {https://huggingface.co/failed09/bashkir-roberta-ner},

  note = {ONNX person named entity recognition for Bashkir}

}

```



## Open Bashkir Data and Sources 🐝



This release is part of an open-source effort to support the development,

preservation and practical use of the Bashkir language. Other related models,

datasets and tools are available on the author's Hugging Face profile.



The author does not claim ownership or authorship of the source texts or other

materials used to derive this release; rights and licensing remain with the

original authors, publishers and dataset providers. Source texts are not

redistributed in this repository, so users should follow the licenses and

attribution requirements of the relevant upstream resources.