--- license: other license_name: accentik-openrail-m-public-attribution license_link: https://huggingface.co/TeraSpace/accentik/blob/main/LICENSE library_name: transformers language: - ru base_model: deepvk/RuModernBERT-small tags: - russian - accentuation - word-stress - custom-code - pytorch - safetensors --- ## 💜 Support Accentik If Accentik is useful to you, consider supporting its development. Thank you for your support! | Currency | Donation address | | :--- | :--- | | **ETH** | `0x19766c207F82303c3998976d852DB82e8Dcc5d77` | | **GRAM (TON)** | `UQDYx1blVO8H31APnRUXVg2uTXV--wXX8HdTyKxnOKQciPQj` | | **SOL** | `DvBjAqaj4AYWi3JBMcW4FmXsaU4Nu6yjxrox4XJZ6o6Z` | | **Tether USDt (TRON / TRC20)** | `TZ6QeYZSr2h22rzGqQZQZTMzWYVPdUej1y` | | **BTC** | `bc1q2l0xdlylqpweu4sm3y53f95g0nazcm8yu42gkq` | --- # Accentik — audio v3 Accentik adds Russian word-stress marks to text. It inserts `+` before the stressed vowel in Russian words with more than one vowel, using the surrounding text to resolve ambiguous words. ```text Input: на двери в замок висел замок. Output: на двер+и в з+амок вис+ел зам+ок. ``` This update refines word-stress prediction using acoustic labels and contextual replay, and adds an optional parallel head for **е → ё placement**. Ё placement is experimental and **disabled by default**. Aggregate reference results, label provenance and known regressions are recorded in [evaluation.json](evaluation.json). Russian dialogue labels were generated by RUAccent, so their scores measure agreement with those labels. The model has **35.05 million parameters**, a single encoder pass, and parallel vowel classification. It uses [deepvk/RuModernBERT-small](https://huggingface.co/deepvk/RuModernBERT-small) with learned word-stress and local-context residual heads plus a ё head sharing the same encoder pass. Inference uses PyTorch and Transformers, without a dictionary, morphological analyzer, RUAccent installation, or autoregressive decoding. ## Installation ```bash pip install "torch>=2.6" "transformers>=5.15.1,<6" "safetensors>=0.4.3" "numpy>=1.24" ``` Tested with Python 3.10, PyTorch 2.9.0 and Transformers 5.15.1. CPU and CUDA are supported. The encoder uses PyTorch SDPA; installing `flash-attn` is unnecessary. ## Load with Transformers The repository includes the inference code, matched tokenizer, config and one FP32 `model.safetensors` file, approximately 140 MB. The first call loads the bundled tokenizer from the same repository revision as the weights. ```python import torch from transformers import AutoModel torch.set_num_threads(2) # Optional: avoids excessive CPU thread overhead. model = AutoModel.from_pretrained( "TeraSpace/accentik", trust_remote_code=True, ).eval() text = "на двери в замок висел замок." print(model.accentuate(text)) ``` For CUDA, move the model before inference: ```python model = model.to("cuda") print(model.accentuate("Он уже закончил работу.")) ``` The text API uses BF16 autocast on CUDA and FP32 on CPU. Keep the model weights in FP32 when using these examples. For a reproducible deployment, pass an explicit Hub commit hash as `revision=` when loading the model. Its automatically loaded tokenizer follows that revision. ## Optional ё placement ```python text = "Все мои соседи здесь, и все готово." print(model.accentuate(text)) # Stress only; original letters preserved. print(model.accentuate(text, restore_yo=True)) # Experimental ё placement. # Все мо+и сос+еди здесь, и всё гот+ово. ``` The same `restore_yo` option works with `accentuate_batch`, `annotate` and `annotate_many`. The validation-selected threshold is `0.8`; override it with `yo_threshold=0.9` if desired. Confidence scores are uncalibrated, so increasing the threshold is not a guarantee of correct spelling. The ё head can invent letters (for example, `висел` → `висёл`) or miss ё, especially in ambiguous contexts and compounds. It can also disagree with the stress head. Keep it disabled when source spelling must remain exact. Existing `ё`/`Ё` characters are always preserved; enabling the option only permits `е` → `ё` and `Е` → `Ё`. Single-vowel words can receive ё without receiving a new stress mark. This release uses no runtime dictionary or word blacklist. ## Batch inference and manual stress ```python texts = [ "Для платья купили атлас.", "В старом з+амке тихо.\nМолоко́ на столе. English. 2+2=4.", ] for result in model.accentuate_batch(texts): print(result) ``` Existing manual `+` marks before Russian vowels and combining acute marks after vowels override model decisions. The original markers remain in the output. Capitalization, punctuation, spaces, line breaks, mathematical plus signs, English text are preserved. The original `е`/`ё` spelling is preserved when `restore_yo=False` (the default). New stress marks are added only to Russian words with at least two vowels. For decisions and confidence scores: ```python result = model.annotate("Он уже закончил работу.") print(result["text"]) for word in result["words"]: print(word["word"], word["position"], word["confidence"], word["supplied"]) ``` Word decisions also include single-vowel words for ё prediction; `add_stress` indicates whether a new stress mark was added, and `yo_candidates` lists positions, uncalibrated probabilities and restoration decisions. `start`, `end` and `position` are character offsets in the input after removing stress markers; `end` is exclusive. Confidence is an uncalibrated softmax score, not an estimated correctness probability. Manually supplied stress has `confidence=None` and `supplied=True`. You can supply the tokenizer explicitly with `tokenizer=AutoTokenizer.from_pretrained("TeraSpace/accentik", trust_remote_code=True)` to any text method. Use the same revision as the model. ## Long texts and offline use Text is processed in whole-word windows of at most **512 tokens**. Longer inputs split at whitespace, retain all source characters and use token-budget batching. Context across window boundaries is limited. A single unbroken token sequence that cannot fit the window raises an error instead of silently truncating it. Download a complete snapshot once, then load it locally: ```python from huggingface_hub import snapshot_download from transformers import AutoModel folder = snapshot_download("TeraSpace/accentik") model = AutoModel.from_pretrained( folder, trust_remote_code=True, local_files_only=True, ).eval() print(model.accentuate("Для платья купили атлас.")) ``` The repository also contains a command-line script: ```bash python inference.py --text "на двери в замок висел замок." python inference.py --input input.txt --output accented.txt --device cuda python inference.py --text "Все готово." --restore-yo --yo-threshold 0.8 ``` The previous release remains available with `revision="experimental-context-v2"` when loading from the Hub. Pin a commit or tag for reproducible behavior. ## License and attribution Accentik is available without a license fee or royalty for personal and commercial use, subject to [LICENSE](LICENSE) and [LICENSE-OPENRAIL](LICENSE-OPENRAIL). Donations are optional. **Public projects using Accentik must give visible credit**, whether commercial or noncommercial. Put the credit in the project's public README, documentation, product page or comparable public description, with a link where supported: > Russian word stress powered by [Accentik by TeraSpace](https://huggingface.co/TeraSpace/accentik). For a derivative model, use “based on Accentik by TeraSpace.” Private internal use does not require a public announcement. You do not need to credit each individual annotated text. Redistributing the model or code requires retaining the license and notices. These terms do not require publishing your application's source code. The upstream RuModernBERT material retains its Apache 2.0 license; see [NOTICE](NOTICE) and [LICENSE-APACHE-2.0](LICENSE-APACHE-2.0). The repository uses a custom attribution license and is not licensed as MIT or Apache 2.0 as a whole.