meshackbahati/kikuyu-asr

Kikuyu ASR - speech recognition for Kikuyu using MMS-300M, QLoRA, KenLM, and ONNX # Kikuyu ASR — Automatic Speech Recognition for Kikuyu (Gikuyu) Fine-tunes Meta AI's **MMS-300M** on 754 hours of Kikuyu speech using **QLoRA**, integrates a **KenLM 3-gram** language model for beam search rescoring, and targets edge deployment via **ONNX + INT8 quantization**. Designed to run on consumer GPUs (16 GB VRAM). --- ## Pipeline ```mermaid flowchart LR A["Audio In (16 kHz mono)"] --> B["MMS-300M wav2vec2 CTC"] B --> C["Beam Search + KenLM 3-gram"] C --> D["Text Out (Kikuyu)"] B -.-> E["QLoRA (rank 64)"] E -.-> F["ONNX INT8 (~350 MB)"] ``` ## Overview | Component | Detail | |-----------|--------| | **Base Model** | `facebook/mms-300m` (300M params, wav2vec2 CTC) | | **Tokenizer** | Built from `facebook/mms-1b-all` vocab (MMS-300M has no tokenizer files) | | **Fine-Tuning** | QLoRA (4-bit NF4, LoRA rank 64, task_type=FEATURE_EXTRACTION) | | **Training Data** | 754 h Kikuyu (Anv-ke/kikuyu, gated) | | **LM Decoding** | KenLM 3-gram + pyctcdecode beam search | | **Edge Format** | ONNX with INT8 dynamic quantization (~350 MB) | | **Runtime** | Google Colab T4 GPU, isolated conda env `asr_env` | | **Dependencies** | transformers >=4.36.0, =4.36.0, =3.0.0,<4.0.0' accelerate peft bitsandbytes audiomentations pyctcdecode onnx onnxruntime pandas soundfile kenlm # Set your HF token (get one at huggingface.co): import os; os.environ["HF_TOKEN"] = "hf_your_token_here" ``` **Quick start — Bash:** ```bash export ASR_ENV_NAME=my_env # optional, defaults to "asr_env" bash setup.sh # one-time env creation bash run_pipeline.sh all # full pipeline ``` ## Local Setup ### 1. Install Dependencies ```bash pip install -r requirements.txt ``` ### 2. Download Data The dataset `Anv-ke/kikuyu` has a single config (`default`) with splits `train`, `validation`, and `test`. Both read (scripted) and spontaneous (unscripted) speech are mixed within each split. ```python from datasets import load_dataset # Training: t …