Fine-tuned BANKING77 intent classifier with model card

README.md

@@ -0,0 +1,129 @@
+---
+license: mit
+language: en
+library_name: transformers
+pipeline_tag: text-classification
+base_model: BAAI/bge-small-en-v1.5
+tags:
+  - intent-classification
+  - customer-support
+  - banking
+  - banking77
+datasets:
+  - PolyAI/banking77
+metrics:
+  - f1
+  - accuracy
+model-index:
+  - name: banking77-intent-classifier
+    results:
+      - task:
+          type: text-classification
+          name: Intent Classification
+        dataset:
+          type: banking77
+          name: BANKING77
+        metrics:
+          - type: f1
+            name: Macro F1
+            value: 0.9245
+          - type: accuracy
+            name: Accuracy
+            value: 0.9247
+---
+
+# banking77-intent-classifier
+
+A 77-class banking intent classifier, fine-tuned from
+[`BAAI/bge-small-en-v1.5`](https://huggingface.co/BAAI/bge-small-en-v1.5) on
+[BANKING77](https://github.com/PolyAI-LDN/task-specific-datasets).
+
+Given a customer message such as *"my card still hasn't arrived after two weeks"*, it predicts
+the intent (`card_arrival`) so the request can be routed automatically.
+
+## Results
+
+| Metric | Value |
+|---|---|
+| Macro F1 | **0.9245** |
+| Accuracy | **0.9247** |
+| Top-3 accuracy | 0.974 |
+| Inference | ~0.34 ms per request |
+
+Evaluated on the official BANKING77 test split (3080 requests, 40 per intent), scored
+once, at the end. Model selection used a stratified 10 % validation split carved out of the
+training data.
+
+## An honest note on what this model is for
+
+**This model was beaten by a simpler approach, and that is the interesting part.**
+
+It was trained as the third rung of a deliberate ladder, to measure what fine-tuning actually
+buys over cheaper alternatives on this dataset:
+
+| Approach | Macro F1 | Training cost |
+|---|---|---|
+| TF-IDF (word + char n-grams) → logistic regression | 0.915 | 23 s, CPU |
+| **Frozen `bge-small` embeddings → logistic regression** | **0.935** | 54 s, CPU |
+| This model — `bge-small` fine-tuned end to end | 0.9245 | ~215 s, GPU |
+
+Using the *same encoder frozen*, with nothing but a logistic regression on top, scores higher.
+The gap held across five training runs spanning three random seeds, which scored between
+0.9245 and 0.9307 (mean ≈ 0.927). Runs vary by a few tenths of a point even at a fixed seed,
+because GPU kernel scheduling and multi-worker data loading are not bit-deterministic — so the
+comparison rests on the spread of runs rather than on any single number.
+
+Two plausible reasons:
+
+1. `bge-small` is contrastively pre-trained for semantic similarity. Grouping semantically
+   similar sentences is more or less what intent classification is, so its embedding space
+   already arrives close to the right shape — and fine-tuning distorts a geometry that was
+   already good.
+2. 10 003 examples across 77 intents is roughly 130 per class. That is thin for updating 33 M
+   parameters, and the model reaches a memorised training loss before it generalises further.
+
+An earlier version of this model, trained without a validation split, drove training loss to
+0.037 and scored 0.9295 — marginally higher than the properly regularised model published
+here. That version was overfit, and comparing it against a regularised alternative would have
+proved nothing. The lower, honest number is the one reported.
+
+**If you want the best model for this task, use frozen embeddings with a linear head.** This
+checkpoint is published for reproducibility and as a documented negative result.
+
+## Usage
+
+```python
+from transformers import pipeline
+
+classifier = pipeline("text-classification", model="functionX86/banking77-intent-classifier")
+classifier("my card still hasn't arrived after two weeks")
+# [{'label': 'card_arrival', 'score': 0.98}]
+```
+
+## Training
+
+| Setting | Value |
+|---|---|
+| Base model | `BAAI/bge-small-en-v1.5` (33 M parameters) |
+| Max sequence length | 64 tokens |
+| Epochs | up to 15, early stopping on validation macro-F1 (patience 3) |
+| Batch size | 32 |
+| Learning rate | 5e-5, 10 % warmup, weight decay 0.01 |
+| Precision | fp16 |
+| Hardware | one NVIDIA RTX 3050 Ti (4 GB) |
+
+The 64-token cap comes from the data: the 95th percentile of BANKING77 requests is 29 words,
+so it truncates almost nothing while running roughly four times faster than the default 256.
+
+## Limitations
+
+- **English only**, and trained on retail banking requests. It will not transfer to another
+  domain without retraining.
+- **Several BANKING77 intents genuinely overlap** — `card_arrival` vs `card_delivery_estimate`,
+  `top_up_failed` vs `top_up_reverted`, and the whole identity-verification cluster. A share of
+  the residual error is label ambiguity that no model can resolve.
+- **Raw softmax scores are not calibrated.** For any use that depends on a confidence
+  threshold, fit a temperature on held-out data first — on the frozen-embedding variant this
+  reduced expected calibration error from 0.110 to 0.012 without changing a single prediction.
+- Trained on public research data, not on real customer messages, and never evaluated for
+  fairness across customer segments. Not suitable for production use as-is.

config.json

@@ -0,0 +1,188 @@
+{
+  "add_cross_attention": false,
+  "architectures": [
+    "BertForSequenceClassification"
+  ],
+  "attention_probs_dropout_prob": 0.1,
+  "bos_token_id": null,
+  "classifier_dropout": null,
+  "dtype": "float32",
+  "eos_token_id": null,
+  "hidden_act": "gelu",
+  "hidden_dropout_prob": 0.1,
+  "hidden_size": 384,
+  "id2label": {
+    "0": "Refund_not_showing_up",
+    "1": "activate_my_card",
+    "2": "age_limit",
+    "3": "apple_pay_or_google_pay",
+    "4": "atm_support",
+    "5": "automatic_top_up",
+    "6": "balance_not_updated_after_bank_transfer",
+    "7": "balance_not_updated_after_cheque_or_cash_deposit",
+    "8": "beneficiary_not_allowed",
+    "9": "cancel_transfer",
+    "10": "card_about_to_expire",
+    "11": "card_acceptance",
+    "12": "card_arrival",
+    "13": "card_delivery_estimate",
+    "14": "card_linking",
+    "15": "card_not_working",
+    "16": "card_payment_fee_charged",
+    "17": "card_payment_not_recognised",
+    "18": "card_payment_wrong_exchange_rate",
+    "19": "card_swallowed",
+    "20": "cash_withdrawal_charge",
+    "21": "cash_withdrawal_not_recognised",
+    "22": "change_pin",
+    "23": "compromised_card",
+    "24": "contactless_not_working",
+    "25": "country_support",
+    "26": "declined_card_payment",
+    "27": "declined_cash_withdrawal",
+    "28": "declined_transfer",
+    "29": "direct_debit_payment_not_recognised",
+    "30": "disposable_card_limits",
+    "31": "edit_personal_details",
+    "32": "exchange_charge",
+    "33": "exchange_rate",
+    "34": "exchange_via_app",
+    "35": "extra_charge_on_statement",
+    "36": "failed_transfer",
+    "37": "fiat_currency_support",
+    "38": "get_disposable_virtual_card",
+    "39": "get_physical_card",
+    "40": "getting_spare_card",
+    "41": "getting_virtual_card",
+    "42": "lost_or_stolen_card",
+    "43": "lost_or_stolen_phone",
+    "44": "order_physical_card",
+    "45": "passcode_forgotten",
+    "46": "pending_card_payment",
+    "47": "pending_cash_withdrawal",
+    "48": "pending_top_up",
+    "49": "pending_transfer",
+    "50": "pin_blocked",
+    "51": "receiving_money",
+    "52": "request_refund",
+    "53": "reverted_card_payment?",
+    "54": "supported_cards_and_currencies",
+    "55": "terminate_account",
+    "56": "top_up_by_bank_transfer_charge",
+    "57": "top_up_by_card_charge",
+    "58": "top_up_by_cash_or_cheque",
+    "59": "top_up_failed",
+    "60": "top_up_limits",
+    "61": "top_up_reverted",
+    "62": "topping_up_by_card",
+    "63": "transaction_charged_twice",
+    "64": "transfer_fee_charged",
+    "65": "transfer_into_account",
+    "66": "transfer_not_received_by_recipient",
+    "67": "transfer_timing",
+    "68": "unable_to_verify_identity",
+    "69": "verify_my_identity",
+    "70": "verify_source_of_funds",
+    "71": "verify_top_up",
+    "72": "virtual_card_not_working",
+    "73": "visa_or_mastercard",
+    "74": "why_verify_identity",
+    "75": "wrong_amount_of_cash_received",
+    "76": "wrong_exchange_rate_for_cash_withdrawal"
+  },
+  "initializer_range": 0.02,
+  "intermediate_size": 1536,
+  "is_decoder": false,
+  "label2id": {
+    "Refund_not_showing_up": 0,
+    "activate_my_card": 1,
+    "age_limit": 2,
+    "apple_pay_or_google_pay": 3,
+    "atm_support": 4,
+    "automatic_top_up": 5,
+    "balance_not_updated_after_bank_transfer": 6,
+    "balance_not_updated_after_cheque_or_cash_deposit": 7,
+    "beneficiary_not_allowed": 8,
+    "cancel_transfer": 9,
+    "card_about_to_expire": 10,
+    "card_acceptance": 11,
+    "card_arrival": 12,
+    "card_delivery_estimate": 13,
+    "card_linking": 14,
+    "card_not_working": 15,
+    "card_payment_fee_charged": 16,
+    "card_payment_not_recognised": 17,
+    "card_payment_wrong_exchange_rate": 18,
+    "card_swallowed": 19,
+    "cash_withdrawal_charge": 20,
+    "cash_withdrawal_not_recognised": 21,
+    "change_pin": 22,
+    "compromised_card": 23,
+    "contactless_not_working": 24,
+    "country_support": 25,
+    "declined_card_payment": 26,
+    "declined_cash_withdrawal": 27,
+    "declined_transfer": 28,
+    "direct_debit_payment_not_recognised": 29,
+    "disposable_card_limits": 30,
+    "edit_personal_details": 31,
+    "exchange_charge": 32,
+    "exchange_rate": 33,
+    "exchange_via_app": 34,
+    "extra_charge_on_statement": 35,
+    "failed_transfer": 36,
+    "fiat_currency_support": 37,
+    "get_disposable_virtual_card": 38,
+    "get_physical_card": 39,
+    "getting_spare_card": 40,
+    "getting_virtual_card": 41,
+    "lost_or_stolen_card": 42,
+    "lost_or_stolen_phone": 43,
+    "order_physical_card": 44,
+    "passcode_forgotten": 45,
+    "pending_card_payment": 46,
+    "pending_cash_withdrawal": 47,
+    "pending_top_up": 48,
+    "pending_transfer": 49,
+    "pin_blocked": 50,
+    "receiving_money": 51,
+    "request_refund": 52,
+    "reverted_card_payment?": 53,
+    "supported_cards_and_currencies": 54,
+    "terminate_account": 55,
+    "top_up_by_bank_transfer_charge": 56,
+    "top_up_by_card_charge": 57,
+    "top_up_by_cash_or_cheque": 58,
+    "top_up_failed": 59,
+    "top_up_limits": 60,
+    "top_up_reverted": 61,
+    "topping_up_by_card": 62,
+    "transaction_charged_twice": 63,
+    "transfer_fee_charged": 64,
+    "transfer_into_account": 65,
+    "transfer_not_received_by_recipient": 66,
+    "transfer_timing": 67,
+    "unable_to_verify_identity": 68,
+    "verify_my_identity": 69,
+    "verify_source_of_funds": 70,
+    "verify_top_up": 71,
+    "virtual_card_not_working": 72,
+    "visa_or_mastercard": 73,
+    "why_verify_identity": 74,
+    "wrong_amount_of_cash_received": 75,
+    "wrong_exchange_rate_for_cash_withdrawal": 76
+  },
+  "layer_norm_eps": 1e-12,
+  "max_position_embeddings": 512,
+  "model_type": "bert",
+  "num_attention_heads": 12,
+  "num_hidden_layers": 12,
+  "pad_token_id": 0,
+  "position_embedding_type": "absolute",
+  "problem_type": "single_label_classification",
+  "tie_word_embeddings": true,
+  "transformers_version": "5.16.1",
+  "type_vocab_size": 2,
+  "use_cache": false,
+  "vocab_size": 30522
+}

model.safetensors

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

tokenizer_config.json

@@ -0,0 +1,18 @@
+{
+  "backend": "tokenizers",
+  "clean_up_tokenization_spaces": true,
+  "cls_token": "[CLS]",
+  "do_basic_tokenize": true,
+  "do_lower_case": true,
+  "is_local": false,
+  "local_files_only": false,
+  "mask_token": "[MASK]",
+  "model_max_length": 512,
+  "never_split": null,
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "strip_accents": null,
+  "tokenize_chinese_chars": true,
+  "tokenizer_class": "BertTokenizer",
+  "unk_token": "[UNK]"
+}