Soe Vinorm is an effective Vietnamese text normalization toolkit designed for use in Text-to-Speech (TTS) and NLP pipelines. It detects and expands non-standard words (NSWs) such as numbers, dates, abbreviations, etc., converting them into their spoken forms. This project is based on the paper Non-Standard Vietnamese Word Detection and Normalization for Text-to-Speech.
# Clone the repository
git clone https://github.com/vinhdq842/soe-vinorm.git
cd soe-vinorm
# Install dependencies including development dependencies (using uv)
uv sync --dev# Install using uv
uv add soe-vinorm
# Or using pip
pip install soe-vinorm# Install directly from GitHub
uv pip install git+https://github.com/vinhdq842/soe-vinorm.gitAfter installation, you can use the soe-vinorm command directly from the terminal:
# Normalize text from a file
soe-vinorm -i input.txt -o output.txt
# Process with progress bar
soe-vinorm -i input.txt -o output.txt --show-progress
# Use parallel processing (4 workers)
soe-vinorm -i input.txt -o output.txt --n-jobs 4 --show-progress
# Normalization options
soe-vinorm -i input.txt --no-expand-sequence --no-expand-urle
# Read from stdin and write to stdout
echo "Năm 2021" | soe-vinorm
# Show help
soe-vinorm --helpBasic usage
from soe_vinorm import SoeNormalizer
normalizer = SoeNormalizer()
text = "Từ năm 2021 đến nay, đây là lần thứ 3 Bộ Công an xây dựng thông tư để quy định liên quan đến mẫu hộ chiếu, giấy thông hành."
# Single
result = normalizer.normalize(text)
print(result)
# Output: Từ năm hai nghìn không trăm hai mươi mốt đến nay , đây là lần thứ ba Bộ Công an xây dựng thông tư để quy định liên quan đến mẫu hộ chiếu , giấy thông hành .
# Batch
results = normalizer.batch_normalize([text] * 5, n_jobs=5)
print(results)Quick function usage
from soe_vinorm import normalize_text
text = "1kg dâu 25 quả, giá 700.000 - Trung bình 30.000đ/quả"
result = normalize_text(text)
print(result)
# Output: một ki lô gam dâu hai mươi lăm quả , giá bảy trăm nghìn - Trung bình ba mươi nghìn đồng trên quảfrom soe_vinorm import batch_normalize_texts
texts = [
"Công trình cao 7,9 m bằng chất liệu đồng nguyên chất với trọng lượng gần 7 tấn, bệ tượng cao 3,6 m",
"Một trường ĐH tại TP.HCM ghi nhận số nguyện vọng đăng ký vào trường tăng kỷ lục, với trên 178.000.",
"Theo phương án của Ban Quản lý dự án đường sắt, Bộ Xây dựng, tuyến đường sắt đô thị Thủ Thiêm - Long Thành có chiều dài khoảng 42 km, thiết kế đường đôi, khổ đường 1.435 mm, tốc độ thiết kế 120 km/giờ.",
"iPhone 16 Pro hiện có giá 999 USD cho phiên bản bộ nhớ 128 GB, và 1.099 USD cho bản 256 GB. Trong khi đó, mẫu 16 Pro Max có dung lượng khởi điểm 256 GB với giá 1.199 USD.",
]
# Process multiple texts in parallel (4 worker processes)
results = batch_normalize_texts(texts, n_jobs=4)
for original, normalized in zip(texts, results):
print(f"Original: {original}")
print(f"Normalized: {normalized}")
print("-" * 50)Output:
Original: Công trình cao 7,9 m bằng chất liệu đồng nguyên chất với trọng lượng gần 7 tấn, bệ tượng cao 3,6 m
Normalized: Công trình cao bảy phẩy chín mét bằng chất liệu đồng nguyên chất với trọng lượng gần bảy tấn , bệ tượng cao ba phẩy sáu mét
--------------------------------------------------
Original: Một trường ĐH tại TP.HCM ghi nhận số nguyện vọng đăng ký vào trường tăng kỷ lục, với trên 178.000.
Normalized: Một trường Đại học tại Thành phố Hồ Chí Minh ghi nhận số nguyện vọng đăng ký vào trường tăng kỷ lục , với trên một trăm bảy mươi tám nghìn .
--------------------------------------------------
Original: Theo phương án của Ban Quản lý dự án đường sắt, Bộ Xây dựng, tuyến đường sắt đô thị Thủ Thiêm - Long Thành có chiều dài khoảng 42 km, thiết kế đường đôi, khổ đường 1.435 mm, tốc độ thiết kế 120 km/giờ.
Normalized: Theo phương án của Ban Quản lý dự án đường sắt , Bộ Xây dựng , tuyến đường sắt đô thị Thủ Thiêm - Long Thành có chiều dài khoảng bốn mươi hai ki lô mét , thiết kế đường đôi , khổ đường một nghìn bốn trăm ba mươi lăm mi li mét , tốc độ thiết kế một trăm hai mươi ki lô mét trên giờ .
--------------------------------------------------
Original: iPhone 16 Pro hiện có giá 999 USD cho phiên bản bộ nhớ 128 GB, và 1.099 USD cho bản 256 GB. Trong khi đó, mẫu 16 Pro Max có dung lượng khởi điểm 256 GB với giá 1.199 USD.
Normalized: iPhone mười sáu Pro hiện có giá chín trăm chín mươi chín U Ét Đê cho phiên bản bộ nhớ một trăm hai mươi tám ghi ga bai , và một nghìn không trăm chín mươi chín U Ét Đê cho bản hai trăm năm mươi sáu ghi ga bai . Trong khi đó , mẫu mười sáu Pro Max có dung lượng khởi điểm hai trăm năm mươi sáu ghi ga bai với giá một nghìn một trăm chín mươi chín U Ét Đê .
--------------------------------------------------
Normalization options (v0.3)
from soe_vinorm import SoeNormalizer, batch_normalize_texts, normalize_text
# By default, expand_sequence and expand_urle are True
normalizer = SoeNormalizer(expand_sequence=False, expand_urle=False)
text = "iPhone 16 Pro hiện có giá 999 USD cho phiên bản bộ nhớ 128 GB. Liên hệ example@example.com để mua."
# Single
result = normalizer.normalize(text)
print(result)
# Output: iPhone mười sáu Pro hiện có giá chín trăm chín mươi chín USD cho phiên bản bộ nhớ một trăm hai mươi tám ghi ga bai . Liên hệ example@example.com để mua .
result = normalize_text(text, expand_sequence=True, expand_urle=False)
print(result)
# Output: iPhone mười sáu Pro hiện có giá chín trăm chín mươi chín U Ét Đê cho phiên bản bộ nhớ một trăm hai mươi tám ghi ga bai . Liên hệ example@example.com để mua .
# Batch
texts = [text] * 5
results = normalizer.batch_normalize(texts, n_jobs=2, show_progress=True)
print(results)
# Output: ['iPhone mười sáu Pro hiện có giá chín trăm chín mươi chín USD cho phiên bản bộ nhớ một trăm hai mươi tám ghi ga bai . Liên hệ example@example.com để mua .', ...]
results = batch_normalize_texts(texts, n_jobs=2, expand_sequence=False, expand_urle=True)
print(results)
# Output: ['iPhone mười sáu Pro hiện có giá chín trăm chín mươi chín USD cho phiên bản bộ nhớ một trăm hai mươi tám ghi ga bai . Liên hệ i xam pi le a còng i xam pi le chấm com để mua .', ...]Load from pre-downloaded weights (v0.3)
!git lfs install
!git clone https://huggingface.co/vinhdq842/soe-vinorm model-repo
from soe_vinorm import SoeNormalizer
normalizer = SoeNormalizer(model_path="model-repo")- Extra spaces, ASCII art, emojis, HTML entities, unspoken words, etc., are removed.
- A regex-based tokenizer is then used to split the sentence into tokens.
- A sequence tagger is used to extract non-standard words (NSWs) and categorize them into 18 different types.
- These NSWs can later be verbalized properly according to their types.
- The sequence tagger can be any sequence labeling model; this implementation uses a Conditional Random Field due to limited data.
- With the NSWs detected in Stage 1 and their respective types, regex-based expanders are applied to produce normalized results.
- Each NSW type has its own dedicated expander.
- The normalized results are then inserted back into the original sentence, resulting in the desired normalized sentence.
- Foreign NSWs are currently kept as-is.
- Abbreviation expansion model
- v0.1: Quantized PhoBERT model combined with a Vietnamese abbreviation dictionary.
- v0.2: A small neural network, also incorporating a Vietnamese abbreviation dictionary.
Due to the inherent characteristics of ML models, i.e., their tendency to learn data-specific quirks (in this case, from newspaper articles), this library can make basic errors on spontaneous text (e.g., arbitrarily composed text without context).
Run all tests with:
pytest tests- Vinh Dang (vinhdq842@gmail.com)
MIT License