Persian_G2P / README.md
Neura's picture
Upload README.md
2bd9669 verified
|
Raw History Blame Contribute Delete
4.87 kB
---
language:
- fa
tags:
- g2p
- grapheme-to-phoneme
- persian
- farsi
- text-to-speech
- tts
- phonetics
- speech-synthesis
- seq2seq
library_name: transformers
pipeline_tag: translation
---
# Neura Persian G2P (`Neurai/Persian_G2P`)
Welcome to the **Neura Persian G2P (Grapheme-to-Phoneme)** model repository by [Neurai](https://huggingface.co/Neurai). This Sequence-to-Sequence (`Seq2SeqLM`) model converts Persian (Farsi) text orthography (graphemes) into accurate phonetic transcriptions (phonemes), serving as an essential frontend component for Text-to-Speech (TTS), Automatic Speech Recognition (ASR), and Persian NLP pipelines.
## Overview
Written Persian omits short vowels (*a*, *e*, *o*) in everyday orthography and relies heavily on context for grammatical constructs such as the *Ezafe* (`-e` / `-ye`), silent letters (e.g., *vav* in «خواهر»), and colloquial pronunciations. `Neurai/Persian_G2P` handles both formal and conversational Persian sentences to output reliable phonetic sequences.
* **Developed by:** [Neurai (Neura.info)](https://huggingface.co/Neurai)
* **Model Repository:** [Neurai/Persian_G2P](https://huggingface.co/Neurai/Persian_G2P)
* **Architecture:** `AutoModelForSeq2SeqLM` (Transformers)
* **Language:** Persian (`fa`)
* **Task:** Grapheme-to-Phoneme (G2P) / Phonetic Transcription
## Installation
Install the required dependencies using `pip`:
```bash
pip install torch transformers gradio
```
## Usage
### Python Inference
You can run inference directly using `transformers` and `torch`:
```python
import torch
from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
MODEL_ID = "Neurai/Persian_G2P"
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForSeq2SeqLM.from_pretrained(MODEL_ID).to(device)
model.eval()
def text_to_phoneme(text: str) -> str:
if not text.strip():
return ""
with torch.no_grad():
inputs = tokenizer(
text,
return_tensors="pt",
padding=True,
truncation=True
).to(device)
outputs = model.generate(
**inputs,
max_new_tokens=128,
do_sample=False
)
return tokenizer.decode(outputs[0], skip_special_tokens=True)
sample_text = "نه بابا چی میگی این عدده نه هزار رو پانصد و بیست و نه هست"
phonemes = text_to_phoneme(sample_text)
print("Grapheme:", sample_text)
print("Phoneme :", phonemes)
```
### Gradio Web Demo
Launch an interactive web interface locally with Gradio:
```python
import gradio as gr
import torch
from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
MODEL_ID = "Neurai/Persian_G2P"
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForSeq2SeqLM.from_pretrained(MODEL_ID).to(device)
model.eval()
def generate(text):
if not text.strip():
return ""
with torch.no_grad():
inputs = tokenizer(
text,
return_tensors="pt",
padding=True,
truncation=True
).to(device)
outputs = model.generate(
**inputs,
max_new_tokens=128,
do_sample=False
)
return tokenizer.decode(outputs[0], skip_special_tokens=True)
demo = gr.Interface(
fn=generate,
inputs=gr.Textbox(
lines=4,
label="Grapheme",
value="نه بابا چی میگی این عدده نه هزار رو پانصد و بیست و نه هست"
),
outputs=gr.Textbox(lines=4, label="Phoneme"),
title="Neura Persian G2P"
)
demo.launch()
```
## Limitations & Considerations
* **Sequence Length:** The default generation configuration uses `max_new_tokens=128`. For very long paragraphs, split input text into sentence-level chunks before running inference.
* **Homographs:** Context-dependent Persian homographs (words spelled identically with different meanings and pronunciations) rely on surrounding sentence context for accurate disambiguation.
* **Out-of-Vocabulary Terms:** Rare foreign loanwords, technical jargon, or uncommon named entities may occasionally produce fallback phonetic approximations.
## Citation
If you use this model in your research, TTS pipeline, or production system, please cite:
```bibtex
@misc{neurai_persian_g2p_model,
author = {Neurai},
title = {Neura Persian G2P: Neural Grapheme-to-Phoneme Model for Persian},
year = {2025},
publisher = {Hugging Face},
url = {https://huggingface.co/Neurai/Persian_G2P}
}
```
## License
Please refer to the repository metadata and `LICENSE` file in [Neurai/Persian_G2P](https://huggingface.co/Neurai/Persian_G2P) for usage and redistribution permissions.