Upload gemma_3_4b_it-lora-r32-hau-eng LoRA adapter

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,216 @@
+---
+library_name: peft
+base_model: google/gemma-3-4b-it
+language:
+- ha
+- en
+tags:
+- translation
+- african-languages
+- scientific-translation
+- afriscience-mt
+- lora
+- peft
+- gemma
+license: apache-2.0
+pipeline_tag: translation
+model-index:
+- name: gemma_3_4b_it-lora-r32-hau-eng
+  results:
+  - task:
+      type: translation
+    metrics:
+    - name: BLEU (test)
+      type: bleu
+      value: 40.46
+    - name: chrF (test)
+      type: chrf
+      value: 59.83
+    - name: SSA-COMET (test)
+      type: comet
+      value: 65.03
+---
+
+# gemma_3_4b_it-lora-r32-hau-eng
+
+[![Model on HF](https://huggingface.co/datasets/huggingface/badges/raw/main/model-on-hf-sm.svg)](https://huggingface.co/AfriScience-MT/gemma_3_4b_it-lora-r32-hau-eng)
+
+This is a **LoRA adapter** for the AfriScience-MT project, enabling efficient scientific machine translation for African languages.
+
+## Adapter Description
+
+| Property | Value |
+|----------|-------|
+| **Base Model** | [google/gemma-3-4b-it](https://huggingface.co/google/gemma-3-4b-it) |
+| **Translation Direction** | Hausa → English |
+| **LoRA Rank (r)** | 32 |
+| **LoRA Alpha** | 64 |
+| **Training Method** | QLoRA (4-bit quantization) |
+| **Domain** | Scientific/Academic texts |
+
+### Why LoRA?
+
+LoRA (Low-Rank Adaptation) enables efficient fine-tuning by training only a small number of additional parameters. This adapter adds only **~16.0M parameters** to the base model while achieving strong translation performance.
+
+## Evaluation Results
+
+Performance on the AfriScience-MT test set:
+
+| Split | BLEU | chrF | SSA-COMET |
+|-------|------|------|-----------|
+| Validation | 43.28 | 62.36 | 66.33 |
+| **Test** | **40.46** | **59.83** | **65.03** |
+
+**Metrics explanation:**
+- **BLEU**: Measures n-gram overlap with reference translations (0-100, higher is better)
+- **chrF**: Character-level F-score, robust for morphologically rich languages (0-100, higher is better)
+- **SSA-COMET**: Neural metric trained for Sub-Saharan African languages, shown as percentage (0-100, higher is better) ([McGill-NLP/ssa-comet-stl](https://huggingface.co/McGill-NLP/ssa-comet-stl))
+
+## Usage
+
+### Quick Start
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+from peft import PeftModel
+import torch
+
+# Configure 4-bit quantization (recommended for memory efficiency)
+bnb_config = BitsAndBytesConfig(
+    load_in_4bit=True,
+    bnb_4bit_compute_dtype=torch.bfloat16,
+    bnb_4bit_quant_type="nf4",
+    bnb_4bit_use_double_quant=True,
+)
+
+# Load base model
+base_model = AutoModelForCausalLM.from_pretrained(
+    "google/gemma-3-4b-it",
+    quantization_config=bnb_config,
+    device_map="auto",
+    torch_dtype=torch.bfloat16,
+)
+tokenizer = AutoTokenizer.from_pretrained("google/gemma-3-4b-it")
+
+# Load LoRA adapter
+adapter_name = "AfriScience-MT/gemma_3_4b_it-lora-r32-hau-eng"
+model = PeftModel.from_pretrained(base_model, adapter_name)
+model.eval()
+
+# Prepare translation prompt
+source_text = "Climate change significantly impacts agricultural productivity in sub-Saharan Africa."
+instruction = "Translate the following Hausa scientific text to English."
+
+# Format for Gemma chat template
+messages = [{"role": "user", "content": f"{instruction}\n\n{source_text}"}]
+prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+
+# Generate translation
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+with torch.no_grad():
+    outputs = model.generate(
+        **inputs,
+        max_new_tokens=256,
+        num_beams=5,
+        early_stopping=True,
+        pad_token_id=tokenizer.pad_token_id,
+    )
+
+# Decode only the generated part
+generated = outputs[0][inputs["input_ids"].shape[1]:]
+translation = tokenizer.decode(generated, skip_special_tokens=True)
+print(translation)
+```
+
+### Without Quantization (Full Precision)
+
+```python
+# For GPUs with sufficient memory (>24GB for larger models)
+base_model = AutoModelForCausalLM.from_pretrained(
+    "google/gemma-3-4b-it",
+    device_map="auto",
+    torch_dtype=torch.bfloat16,
+)
+model = PeftModel.from_pretrained(base_model, "AfriScience-MT/gemma_3_4b_it-lora-r32-hau-eng")
+```
+
+## Training Details
+
+### Hyperparameters
+
+| Parameter | Value |
+|-----------|-------|
+| LoRA Rank (r) | 32 |
+| LoRA Alpha | 64 |
+| LoRA Dropout | 0.05 |
+| Target Modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
+| Epochs | 3 |
+| Batch Size | 2 |
+| Learning Rate | 2e-04 |
+| Max Sequence Length | 512 |
+| Gradient Accumulation | 4 |
+
+### Hardware Requirements
+
+| Configuration | VRAM Required |
+|---------------|---------------|
+| 4-bit (QLoRA) | ~8-12 GB |
+| 8-bit | ~16-20 GB |
+| Full precision | ~24-40 GB |
+
+
+## Reproducibility
+
+To reproduce this adapter:
+
+```bash
+# Clone the AfriScience-MT repository
+git clone https://github.com/afriscience-mt/afriscience-mt.git
+cd afriscience-mt
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run LoRA training
+python -m afriscience_mt.scripts.run_lora_training \
+    --data_dir ./data \
+    --source_lang hau \
+    --target_lang eng \
+    --model_name google/gemma-3-4b-it \
+    --model_type gemma \
+    --lora_rank 32 \
+    --output_dir ./output \
+    --num_epochs 3 \
+    --batch_size 4 \
+    --load_in_4bit
+```
+
+## Limitations
+
+- **Domain Specificity**: Optimized for scientific/academic texts; may underperform on casual or colloquial language.
+- **Language Direction**: Only supports Hausa → English translation.
+- **Base Model Required**: Must be used with the [google/gemma-3-4b-it](https://huggingface.co/google/gemma-3-4b-it) base model.
+- **Context Length**: Maximum context is model-dependent; longer texts should be chunked.
+
+## Citation
+
+If you use this adapter, please cite the AfriScience-MT project:
+
+```bibtex
+@inproceedings{afriscience-mt-2025,
+  title={AfriScience-MT: Machine Translation for African Scientific Literature},
+  author={AfriScience-MT Team},
+  year={2025},
+  url={https://github.com/afriscience-mt/afriscience-mt}
+}
+```
+
+## License
+
+This adapter is released under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).
+
+## Acknowledgments
+
+- Base model: [google/gemma-3-4b-it](https://huggingface.co/google/gemma-3-4b-it)
+- LoRA implementation: [PEFT](https://github.com/huggingface/peft)
+- Evaluation: [SSA-COMET](https://huggingface.co/McGill-NLP/ssa-comet-stl) for African language assessment

adapter_config.json

@@ -0,0 +1,46 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": null,
+  "base_model_name_or_path": "google/gemma-3-4b-it",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 32,
+  "lora_bias": false,
+  "lora_dropout": 0.05,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "peft_type": "LORA",
+  "peft_version": "0.18.1",
+  "qalora_group_size": 16,
+  "r": 32,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": [
+    "up_proj",
+    "q_proj",
+    "v_proj",
+    "down_proj",
+    "k_proj",
+    "gate_proj",
+    "o_proj"
+  ],
+  "target_parameters": null,
+  "task_type": "CAUSAL_LM",
+  "trainable_token_indices": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false
+}

adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bab93192a40dabf2f46bb79b43f249a6075f78d42d05153f9f07ca710e100b65
+size 262406656

added_tokens.json

@@ -0,0 +1,3 @@
+{
+  "<image_soft_token>": 262144
+}

chat_template.jinja

@@ -0,0 +1,47 @@
+{{ bos_token }}
+{%- if messages[0]['role'] == 'system' -%}
+    {%- if messages[0]['content'] is string -%}
+        {%- set first_user_prefix = messages[0]['content'] + '
+
+' -%}
+    {%- else -%}
+        {%- set first_user_prefix = messages[0]['content'][0]['text'] + '
+
+' -%}
+    {%- endif -%}
+    {%- set loop_messages = messages[1:] -%}
+{%- else -%}
+    {%- set first_user_prefix = "" -%}
+    {%- set loop_messages = messages -%}
+{%- endif -%}
+{%- for message in loop_messages -%}
+    {%- if (message['role'] == 'user') != (loop.index0 % 2 == 0) -%}
+        {{ raise_exception("Conversation roles must alternate user/assistant/user/assistant/...") }}
+    {%- endif -%}
+    {%- if (message['role'] == 'assistant') -%}
+        {%- set role = "model" -%}
+    {%- else -%}
+        {%- set role = message['role'] -%}
+    {%- endif -%}
+    {{ '<start_of_turn>' + role + '
+' + (first_user_prefix if loop.first else "") }}
+    {%- if message['content'] is string -%}
+        {{ message['content'] | trim }}
+    {%- elif message['content'] is iterable -%}
+        {%- for item in message['content'] -%}
+            {%- if item['type'] == 'image' -%}
+                {{ '<start_of_image>' }}
+            {%- elif item['type'] == 'text' -%}
+                {{ item['text'] | trim }}
+            {%- endif -%}
+        {%- endfor -%}
+    {%- else -%}
+        {{ raise_exception("Invalid content type") }}
+    {%- endif -%}
+    {{ '<end_of_turn>
+' }}
+{%- endfor -%}
+{%- if add_generation_prompt -%}
+    {{'<start_of_turn>model
+'}}
+{%- endif -%}

special_tokens_map.json

@@ -0,0 +1,33 @@
+{
+  "boi_token": "<start_of_image>",
+  "bos_token": {
+    "content": "<bos>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "eoi_token": "<end_of_image>",
+  "eos_token": {
+    "content": "<eos>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "image_token": "<image_soft_token>",
+  "pad_token": {
+    "content": "<pad>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "unk_token": {
+    "content": "<unk>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  }
+}

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4667f2089529e8e7657cfb6d1c19910ae71ff5f28aa7ab2ff2763330affad795
+size 33384568

tokenizer.model

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1299c11d7cf632ef3b4e11937501358ada021bbdf7c47638d13c0ee982f2e79c
+size 4689074