Update README.md

README.md

@@ -3,7 +3,7 @@ language:
   - en
 license: apache-2.0
 library_name: transformers
-pipeline_tag: token-classification
+pipeline_tag: text-generation
 tags:
   - named-entity-recognition
   - ner
@@ -11,6 +11,7 @@ tags:
   - decoder-only
   - lora
   - conll2003
+  - information-extraction
 base_model: Qwen/Qwen2.5-0.5B-Instruct
 datasets:
   - lhoestq/conll2003
@@ -20,24 +21,24 @@ datasets:
 
 ## Model Description
 
-This project is a fine-tuned **decoder-only Named Entity Recognition (NER) model** based on [`Qwen/Qwen2.5-0.5B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct).
+**Qwen-NER-Decoder** is a fine-tuned decoder-only Named Entity Recognition (NER) model based on [Qwen/Qwen2.5-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct).
 
-The model is trained to identify and extract named entities from English text and return them in structured JSON format.
+The model identifies and extracts named entities from English text and generates structured JSON output.
 
-It recognizes four standard CoNLL-2003 entity categories:
+It is fine-tuned on the CoNLL-2003 English Named Entity Recognition dataset and recognizes four entity categories:
 
 - **PER** – Person
 - **ORG** – Organization
 - **LOC** – Location
 - **MISC** – Miscellaneous
 
-The model uses **Low-Rank Adaptation (LoRA)** for parameter-efficient fine-tuning.
+The model uses **Low-Rank Adaptation (LoRA)** for parameter-efficient fine-tuning. The Hugging Face repository contains the LoRA adapter, so it must be loaded together with its original base model.
 
 ## Model Details
 
 | Property | Details |
 |---|---|
-| Model Name | English NER Decoder |
+| Model Name | Qwen-NER-Decoder |
 | Base Model | Qwen/Qwen2.5-0.5B-Instruct |
 | Architecture | Decoder-only Transformer |
 | Fine-tuning Method | LoRA |
@@ -48,33 +49,44 @@ The model uses **Low-Rank Adaptation (LoRA)** for parameter-efficient fine-tunin
 | Language | English |
 | Task | Named Entity Recognition |
 | Output Format | JSON |
+| Training Framework | PyTorch, Transformers, PEFT |
 
 ## Dataset
 
-The model was fine-tuned using the **CoNLL-2003 English Named Entity Recognition dataset**.
+The model was fine-tuned using the [CoNLL-2003 English NER dataset](https://huggingface.co/datasets/lhoestq/conll2003).
 
-Dataset: [`lhoestq/conll2003`](https://huggingface.co/datasets/lhoestq/conll2003)
+Dataset repository: `lhoestq/conll2003`
 
 The dataset contains English sentences annotated with BIO-style named entity labels.
 
-The four entity categories are PER, ORG, LOC, and MISC.
+The four entity categories are:
+
+| Label | Description |
+|---|---|
+| PER | Person |
+| ORG | Organization |
+| LOC | Location |
+| MISC | Miscellaneous |
 
 ## Training Configuration
 
 The model was fine-tuned using LoRA with the following configuration:
 
-- Base model: Qwen2.5-0.5B-Instruct
-- LoRA rank: 8
-- LoRA alpha: 16
-- LoRA dropout: 0.05
-- Target modules: q_proj, k_proj, v_proj, o_proj
-- Training epochs: 1
-- Training samples: Up to 8,000
-- Validation samples: 1,000
-- Training precision: FP16
-- Optimizer: AdamW
+| Configuration | Value |
+|---|---|
+| Base Model | Qwen2.5-0.5B-Instruct |
+| LoRA Rank | 8 |
+| LoRA Alpha | 16 |
+| LoRA Dropout | 0.05 |
+| Target Modules | q_proj, k_proj, v_proj, o_proj |
+| Training Epochs | 1 |
+| Training Samples | Up to 8,000 |
+| Validation Samples | 1,000 |
+| Training Precision | FP16 |
+| Optimizer | AdamW |
+| Training Environment | Kaggle GPU |
 
-The training was performed using a Kaggle GPU environment.
+LoRA adapts selected attention projection layers without updating all the parameters of the original base model.
 
 ## Evaluation Results
 
@@ -89,11 +101,13 @@ The model was evaluated on a quick test subset of 100 English sentences using ex
 | False Positives | 17 |
 | False Negatives | 36 |
 
-**Note:** These results represent the 100-sample evaluation subset, not the complete test dataset. They should not be interpreted as a full-dataset benchmark.
+**Evaluation note:** These results represent the 100-sample evaluation subset, not the complete test dataset. They should not be interpreted as a full-dataset benchmark.
 
 Additional manually selected English sentences were used to inspect entity extraction behavior.
 
-## Example
+## Example Predictions
+
+### Example 1
 
 **Input:**
 
@@ -118,7 +132,7 @@ Elon Musk founded SpaceX.
 }
 ```
 
-Another example:
+### Example 2
 
 **Input:**
 
@@ -131,6 +145,10 @@ Barack Obama visited Microsoft headquarters in Seattle.
 ```json
 {
   "entities": [
+    {
+      "text": "Barack Obama",
+      "type": "PER"
+    },
     {
       "text": "Microsoft",
       "type": "ORG"
@@ -143,71 +161,152 @@ Barack Obama visited Microsoft headquarters in Seattle.
 }
 ```
 
-## Intended Use
-
-This model is intended for:
-
-- English named entity extraction.
-- Natural Language Processing (NLP) applications.
-- Information extraction systems.
-- Text analysis and document processing.
-- Educational and research projects.
-- Integration with sentiment classification systems.
-
-## Limitations
-
-- The model may occasionally miss named entities.
-- Some entities may receive incorrect classifications.
-- Entity boundaries and spelling may occasionally be incorrect.
-- Performance can vary across different domains and writing styles.
-- The reported evaluation score is based on a limited 100-sample test subset.
-- The model is not intended to replace human verification in critical applications.
+*Examples illustrate the intended output structure.*
 
 ## How to Use
 
-Install the required libraries:
+### 1. Install Dependencies
 
 ```bash
-pip install transformers peft accelerate torch
+pip install torch transformers peft accelerate safetensors
 ```
 
-Load the base model and LoRA adapter:
+### 2. Load the Base Model and LoRA Adapter
 
 ```python
 import torch
 from transformers import AutoTokenizer, AutoModelForCausalLM
-from peft import PeftModel
-
-BASE_MODEL = "Qwen/Qwen2.5-0.5B-Instruct"
+from peft import PeftConfig, PeftModel
 
-# Replace with your Hugging Face repository ID
 ADAPTER_MODEL = "ullahhafeez321/Qwen-NER-Decoder"
 
-tokenizer = AutoTokenizer.from_pretrained(ADAPTER_MODEL)
+# Read the original base model from the adapter configuration
+adapter_config = PeftConfig.from_pretrained(ADAPTER_MODEL)
+BASE_MODEL = adapter_config.base_model_name_or_path
 
+# Load tokenizer from the base model
+tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL)
+
+if tokenizer.pad_token_id is None:
+    tokenizer.pad_token = tokenizer.eos_token
+
+# Load the original Qwen base model
 base_model = AutoModelForCausalLM.from_pretrained(
     BASE_MODEL,
-    torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
+    torch_dtype=(
+        torch.float16 if torch.cuda.is_available()
+        else torch.float32
+    ),
     device_map="auto"
 )
 
+# Attach the fine-tuned LoRA adapter
 model = PeftModel.from_pretrained(
     base_model,
     ADAPTER_MODEL
 )
 
 model.eval()
+
+print("Qwen NER model loaded successfully!")
 ```
 
-The adapter must be loaded together with its original base model.
+### 3. Run Inference
+
+The prompt used during inference should follow the same instruction and output format used during fine-tuning.
+
+The following is an illustrative JSON extraction example:
+
+```python
+sentence = "Albert Einstein worked at Princeton University."
+
+prompt = f"""
+Extract named entities from the following sentence.
+
+Entity types:
+PER = Person
+ORG = Organization
+LOC = Location
+MISC = Miscellaneous
+
+Return only a JSON array:
+
+[
+  {{"text": "entity name", "type": "PER"}}
+]
+
+If no entities are found, return [].
+
+Sentence: {sentence}
+
+Entities:
+"""
+
+inputs = tokenizer(
+    prompt,
+    return_tensors="pt",
+    truncation=True,
+    max_length=1024
+)
+
+input_device = model.get_input_embeddings().weight.device
+inputs = {
+    key: value.to(input_device)
+    for key, value in inputs.items()
+}
+
+with torch.inference_mode():
+    outputs = model.generate(
+        **inputs,
+        max_new_tokens=150,
+        do_sample=False,
+        pad_token_id=tokenizer.pad_token_id,
+        eos_token_id=tokenizer.eos_token_id
+    )
+
+generated_tokens = outputs[0][inputs["input_ids"].shape[1]:]
+
+result = tokenizer.decode(
+    generated_tokens,
+    skip_special_tokens=True
+)
+
+print(result)
+```
+
+**Note:** This example demonstrates the inference process. For the best results, use the exact prompt template and target format used to train the uploaded adapter.
+
+## Intended Use
+
+This model is intended for:
+
+- English named entity recognition.
+- Natural Language Processing applications.
+- Information extraction systems.
+- Text analysis and document processing.
+- Educational and research projects.
+- Integration with sentiment classification systems.
+- Applications that require structured entity extraction.
+
+## Limitations
+
+- The model may occasionally miss named entities.
+- Some entities may receive incorrect classifications.
+- Entity boundaries and spelling may occasionally be incorrect.
+- Performance can vary across different domains and writing styles.
+- The reported evaluation score is based on a limited 100-sample test subset.
+- The model is intended for English text and may not perform reliably on other languages.
+- The model is not intended to replace human verification in critical applications.
 
 ## Model Architecture
 
-This project uses a decoder-only Transformer architecture.
+This project uses a decoder-only Transformer architecture based on Qwen2.5-0.5B-Instruct.
 
 The model generates structured entity extraction results from an English input sentence.
 
-LoRA fine-tuning adapts selected attention projection layers without updating all the original base-model parameters.
+LoRA fine-tuning adapts selected attention projection layers while preserving the original base model weights.
+
+The uploaded Hugging Face repository contains the fine-tuned adapter rather than a complete standalone model checkpoint.
 
 ## Future Improvements
 
@@ -216,6 +315,7 @@ LoRA fine-tuning adapts selected attention projection layers without updating al
 - Evaluate performance on the complete test dataset.
 - Improve entity boundary detection.
 - Expand evaluation across different English text domains.
+- Improve inference consistency and structured JSON generation.
 - Integrate with an encoder-only BERT sentiment classification model.
 
 ## Acknowledgements
@@ -226,10 +326,14 @@ LoRA fine-tuning adapts selected attention projection layers without updating al
 
 ## License
 
-Please refer to the base model and dataset licenses before redistributing or using this fine-tuned adapter.
+The adapter repository declares the Apache-2.0 license. Please also review the original base model and dataset licenses and their respective usage conditions before redistribution or commercial use.
 
 ---
 
 **Project:** English Named Entity Recognition using a Decoder-only Transformer with LoRA Fine-tuning.
 
+**Model Repository:** `ullahhafeez321/Qwen-NER-Decoder`
+
+**Base Model:** `Qwen/Qwen2.5-0.5B-Instruct`
+
 **Frameworks:** PyTorch, Transformers, PEFT, Hugging Face Datasets.