docs/training.md

Training guide

Abjad fine-tuning uses MLX-VLM LoRA on Apple Silicon. The repository keeps previous adapters and datasets so old experiments remain reproducible; new runs should use a new output name instead of overwriting a previous adapter.

1. Prepare data

Start with manually verified JSONL. Copy configs/data_list.example.txt and edit the paths for the run. For a small correction run, a single JSONL file is enough:

cp configs/data_list.example.txt configs/data_list.local.txt

Review the rows before training, especially Arabic names, Arabic-Indic digits, tables, stamps, and signatures.

2. Run LoRA

The low-level entry point is:

.venv/bin/python run_lora_training.py \
  --model mlx-community/Qwen3-VL-4B-Instruct-4bit \
  --dataset dataset/abjad_0_2/train_compact.jsonl \
  --output adapters/abjad_0_3_domain.safetensors \
  --iters 300 \
  --image-size 224 \
  --max-seq-length 1024

The command writes training_status.json and logs/lora_training.log. Checkpoints are saved during the run. Use --resume-adapter only when the new run intentionally continues the same adapter lineage.

3. Verify before fusion

Evaluate on pages that were not used for training. Look for:

• omitted or duplicated phrases;
• Arabic and Western digit confusion;
• wrong names or diacritics;
• reading-order errors in columns and tables;
• watermark, stamp, and signature contamination;
• output that stops early because of the token limit.

Do not fuse an adapter only because the training loss decreased. Keep the best checkpoint based on held-out OCR quality and the document types that matter to the deployment.

4. Fuse for standalone inference

The current fused model was created from the final selected adapter and can be run with --no-adapter. Keep the adapter backup separately so the fusion can be audited or repeated.

5. Publishing checklist

Before uploading a model or dataset:

1. Remove private filesystem paths and tokens.
2. Confirm every source document may be redistributed.
3. State the base model, training method, cumulative row count, and overlap caveat.
4. Include a test example and known limitations.
5. Never claim zero OCR errors; report evaluation results on a fixed held-out set.