Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,135 @@
+---
+language:
+- kbp
+license: apache-2.0
+base_model: openai/whisper-small
+tags:
+- automatic-speech-recognition
+- whisper
+- kabiye
+- kbp
+- low-resource
+- peft
+- lora
+datasets:
+- wilderness_asr/KBPRCV_whisper_dataset
+metrics:
+- wer
+pipeline_tag: automatic-speech-recognition
+model-index:
+- name: whisper-small-kbp
+  results:
+  - task:
+      type: automatic-speech-recognition
+      name: Automatic Speech Recognition
+    dataset:
+      type: wilderness_asr/KBPRCV_whisper_dataset
+      name: KBPRCV Whisper Dataset (kabiyè)
+    metrics:
+    - type: wer
+      value: XX.X
+      name: Test WER
+---
+
+# Whisper Small — Kabiyè (kbp)
+
+Ce modèle est une version de [`openai/whisper-small`](https://huggingface.co/openai/whisper-small) affinée (*fine-tuned*) pour la reconnaissance automatique de la parole (ASR) en **kabiyè** (code ISO 639-3 : `kbp`), une langue gur parlée principalement au Togo.
+
+Le modèle a été entraîné avec la méthode **PEFT / LoRA**, puis les poids de l'adaptateur ont été **fusionnés** (`merge_and_unload`) dans le modèle de base : ce dépôt contient donc un `WhisperForConditionalGeneration` complet, utilisable directement sans dépendance à la librairie `peft`.
+
+> Un adaptateur LoRA autonome (non fusionné, plus léger) est également disponible séparément : `<HF_USERNAME>/whisper-small-kbp-lora-adapter`.
+
+## Description du modèle
+
+- **Modèle de base** : `openai/whisper-small` (244M paramètres)
+- **Langue** : kabiyè (`kbp`)
+- **Tâche** : transcription audio → texte (`transcribe`)
+- **Méthode de fine-tuning** : PEFT / LoRA (`r=32`, `lora_alpha=64`, `target_modules=["q_proj","v_proj"]`, `lora_dropout=0.05`), poids fusionnés avec le modèle de base après entraînement
+- **Note sur le token de langue** : le kabiyè ne faisant pas partie des langues nativement supportées par Whisper, aucun token de langue Whisper natif n'a été forcé (`forced_decoder_ids=None`) ; le modèle a appris l'association audio → texte kabiyè directement via le fine-tuning supervisé.
+
+## Utilisation
+
+```python
+from transformers import WhisperForConditionalGeneration, WhisperProcessor
+import torch, librosa
+
+repo_id = "<HF_USERNAME>/whisper-small-kbp"
+
+processor = WhisperProcessor.from_pretrained(repo_id)
+model = WhisperForConditionalGeneration.from_pretrained(repo_id)
+model.config.forced_decoder_ids = None
+
+audio, sr = librosa.load("mon_clip.wav", sr=16000)
+input_features = processor(audio, sampling_rate=sr, return_tensors="pt").input_features
+
+with torch.no_grad():
+    predicted_ids = model.generate(input_features, max_new_tokens=225)
+
+transcription = processor.batch_decode(predicted_ids, skip_special_tokens=True)[0]
+print(transcription)
+```
+
+Avec le pipeline `transformers` :
+
+```python
+from transformers import pipeline
+
+asr = pipeline("automatic-speech-recognition", model="<HF_USERNAME>/whisper-small-kbp")
+print(asr("mon_clip.wav"))
+```
+
+## Données d'entraînement
+
+- **Source** : corpus `KBPRCV_whisper_dataset` (projet Wilderness ASR), constitué de lectures audio de textes bibliques en kabiyè.
+- **Volume** : 7 923 clips audio, soit environ **21h39** d'audio total.
+- **Format** : paires audio (`.wav`, 16 kHz) / transcription, décrites dans un fichier `manifest.jsonl` avec les champs `audio_filepath`, `text`, `duration`, `language`, `book`, `chapter`, `verse_index`.
+- **Répartition** : ~90% entraînement / ~5% validation / ~5% test, split stratifié par livre biblique (`book`) pour préserver l'homogénéité thématique des sous-ensembles.
+
+## Procédure d'entraînement
+
+| Hyperparamètre | Valeur |
+|---|---|
+| Modèle de base | `openai/whisper-small` |
+| Méthode | LoRA (PEFT) |
+| `r` | 32 |
+| `lora_alpha` | 64 |
+| `target_modules` | `q_proj`, `v_proj` |
+| `lora_dropout` | 0.05 |
+| Batch size (train) | 16 |
+| Learning rate | 1e-3 |
+| Epochs | 10 |
+| Précision | fp16, chargement de base en 8-bit pendant l'entraînement |
+| Métrique de sélection | WER (validation) |
+| Matériel | GPU unique (Google Colab, T4/A100) |
+
+## Résultats d'évaluation
+
+| Split | WER (%) |
+|---|---|
+| Validation | *à compléter après entraînement* |
+| Test | *à compléter après entraînement* |
+
+*(Les valeurs ci-dessus sont des emplacements à renseigner une fois l'entraînement terminé — voir la section 16 du notebook d'entraînement.)*
+
+## Limites et biais connus
+
+- Le corpus d'entraînement est constitué exclusivement de **lectures de textes bibliques** : le vocabulaire, le registre de langue et la prosodie du modèle sont donc fortement influencés par ce domaine, et les performances peuvent se dégrader sur de la parole spontanée, conversationnelle, ou sur d'autres domaines (actualités, discours technique, etc.).
+- Le corpus provient probablement d'un nombre limité de locuteurs/lecteurs : la robustesse aux variations d'accent, de dialecte ou de bruit ambiant n'est pas garantie.
+- Le kabiyè n'étant pas une langue supportée nativement par Whisper, aucune connaissance linguistique préalable spécifique à cette langue n'a été transférée via le token de langue ; toute la capacité de reconnaissance vient du fine-tuning sur ce corpus.
+- Les clips de plus de 30 secondes ont été exclus de l'entraînement (limite native de Whisper).
+
+## Citation
+
+Si vous utilisez ce modèle, merci de citer le modèle de base Whisper :
+
+```bibtex
+@misc{radford2022whisper,
+  title={Robust Speech Recognition via Large-Scale Weak Supervision},
+  author={Radford, Alec and Kim, Jong Wook and Xu, Tao and Brockman, Greg and McLeavey, Christine and Sutskever, Ilya},
+  year={2022},
+  eprint={2212.04356},
+  archivePrefix={arXiv}
+}
+```
+
+ainsi que le corpus d'entraînement `KBPRCV_whisper_dataset` (projet Wilderness ASR).