Update README.md

readme update based on the code

README.md

@@ -1,199 +1,254 @@
 ---
-library_name: transformers
-tags: []
+language: fa
+base_model: Qwen/Qwen2.5-14B-Instruct
+datasets:
+- safora/PersianSciQA-Extractive
+tags:
+- qwen
+- question-answering
+- persian
+- farsi
+- qlora
+- scientific-documents
+license: apache-2.0
 ---
 
-# Model Card for Model ID
+# PersianSciQA-Qwen2.5-14B: A QLoRA Fine-Tuned Model for Scientific Extractive QA in Persian
 
-<!-- Provide a quick summary of what the model is/does. -->
+## Model Description
 
+This repository contains the **PersianSciQA-Qwen2.5-14B** model, a fine-tuned version of `Qwen/Qwen2.5-14B-Instruct` specialized for **extractive question answering on scientific texts in the Persian language**.
 
+The model was trained using the QLoRA method for efficient parameter-tuning. Its primary function is to analyze a given scientific `context` and answer a `question` based **solely** on the information within that context.
 
-## Model Details
+A key feature of its training is the strict instruction to output the exact phrase `CANNOT_ANSWER` if the context does not contain the information required to answer the question. This makes the model a reliable tool for closed-domain, evidence-based QA tasks.
 
-### Model Description
+## How to Use
 
-<!-- Provide a longer summary of what this model is. -->
+To use this model, you must follow the specific prompt template it was trained on. The prompt enforces the model's role as a scientific assistant and its strict answering policy.
 
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+Here is a complete example using the `transformers` library:
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-### Model Sources [optional]
+# Set the model ID
+model_id = "safora/PersianSciQA-Qwen2.5-14B"
 
-<!-- Provide the basic links for the model. -->
+# Load the tokenizer and model
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    torch_dtype=torch.bfloat16,
+    device_map="auto"
+)
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+# 1. Define the prompt template (MUST match the training format)
+prompt_template = (
+    'شما یک دستیار متخصص در زمینه اسناد علمی هستید. وظیفه شما این است که به سوال پرسیده شده، **فقط و فقط** بر اساس متن زمینه (Context) ارائه شده پاسخ دهید. پاسخ شما باید دقیق و خلاصه باشد.\n\n'
+    '**دستورالعمل مهم:** اگر اطلاعات لازم برای پاسخ دادن به سوال در متن زمینه وجود ندارد، باید **دقیقا** عبارت "CANNOT_ANSWER" را به عنوان پاسخ بنویسید و هیچ توضیح اضافه‌ای ندهید.\n\n'
+    '**زمینه (Context):**\n---\n{context}\n---\n\n'
+    '**سوال (Question):**\n{question}\n\n'
+    '**پاسخ (Answer):** '
+)
 
-## Uses
+# 2. Provide your context and question
+context = "سلول‌های خورشیدی پروسکایت به دلیل هزینه تولید پایین و بازدهی بالا، به عنوان یک فناوری نوظهور مورد توجه قرار گرفته‌اند. بازدهی آزمایشگاهی این سلول‌ها به بیش از ۲۵ درصد رسیده است، اما پایداری طولانی‌مدت آن‌ها همچنان یک چالش اصلی محسوب می‌شود."
+question = "بازدهی سلول‌های خورشیدی پروسکایت در آزمایشگاه چقدر است؟"
+# Example of a question that cannot be answered from the context:
+# question = "این سلول ها اولین بار در چه سالی ساخته شدند؟"
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+# 3. Format the prompt
+prompt = prompt_template.format(context=context, question=question)
 
-### Direct Use
+# 4. Generate the response
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+generation_output = model.generate(
+    **inputs,
+    max_new_tokens=128,
+    eos_token_id=tokenizer.eos_token_id,
+    pad_token_id=tokenizer.eos_token_id
+)
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+# Decode and print the output
+response = tokenizer.decode(generation_output[0], skip_special_tokens=True)
 
-[More Information Needed]
+# The generated text will be after the prompt
+answer = response.split("**پاسخ (Answer):**")[-1].strip()
+print(answer)
+# Expected output: به بیش از ۲۵ درصد رسیده است
+# For the unanswerable question, expected output: CANNOT_ANSWER
 
-### Downstream Use [optional]
+Training Details
+Model
+The base model is Qwen/Qwen2.5-14B-Instruct, a highly capable instruction-tuned large language model.
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+Dataset
+The model was fine-tuned on the safora/PersianSciQA-Extractive dataset. This dataset contains triplets of (context, question, model_answer) derived from Persian scientific documents. The dataset is split into:
 
-[More Information Needed]
+Train: Used for training the model.
 
-### Out-of-Scope Use
+Validation: Used for evaluating the model during training epochs.
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+Test: A held-out set reserved for final model evaluation.
 
-[More Information Needed]
+Fine-Tuning Procedure
+The model was fine-tuned using the QLoRA (Quantized Low-Rank Adaptation) method, which significantly reduces memory usage while maintaining high performance. The training was performed using the trl and peft libraries.
 
-## Bias, Risks, and Limitations
+Hyperparameters
+The following key hyperparameters were used during training:
+Parameter	Value
+LoRA Configuration	
+r (Rank)	16
+lora_alpha	32
+lora_dropout	0.05
+target_modules	q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
+Training Arguments	
+learning_rate	2e-5
+optimizer	paged_adamw_32bit
+lr_scheduler_type	cosine
+num_train_epochs	1
+per_device_train_batch_size	1
+gradient_accumulation_steps	8
+effective_batch_size	8
+quantization	4-bit (nf4)
+compute_dtype	bfloat16
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+Of course. Based on your Python script, here is a professional, scientific, and community-focused README.md file for your Hugging Face model card. This is designed for maximum clarity and reusability.
 
-[More Information Needed]
+Markdown
 
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
+---
+language: fa
+base_model: Qwen/Qwen2.5-14B-Instruct
+datasets:
+- safora/PersianSciQA-Extractive
+tags:
+- qwen
+- question-answering
+- persian
+- farsi
+- qlora
+- scientific-documents
+---
 
-## Glossary [optional]
+# PersianSciQA-Qwen2.5-14B: A QLoRA Fine-Tuned Model for Scientific Extractive QA in Persian
 
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+## Model Description
 
-[More Information Needed]
+This repository contains the **PersianSciQA-Qwen2.5-14B** model, a fine-tuned version of `Qwen/Qwen2.5-14B-Instruct` specialized for **extractive question answering on scientific texts in the Persian language**.
 
-## More Information [optional]
+The model was trained using the QLoRA method for efficient parameter-tuning. Its primary function is to analyze a given scientific `context` and answer a `question` based **solely** on the information within that context.
 
-[More Information Needed]
+A key feature of its training is the strict instruction to output the exact phrase `CANNOT_ANSWER` if the context does not contain the information required to answer the question. This makes the model a reliable tool for closed-domain, evidence-based QA tasks.
 
-## Model Card Authors [optional]
+## How to Use
 
-[More Information Needed]
+To use this model, you must follow the specific prompt template it was trained on. The prompt enforces the model's role as a scientific assistant and its strict answering policy.
 
-## Model Card Contact
+Here is a complete example using the `transformers` library:
 
-[More Information Needed]
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# Set the model ID
+model_id = "safora/PersianSciQA-Qwen2.5-14B"
+
+# Load the tokenizer and model
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    torch_dtype=torch.bfloat16,
+    device_map="auto"
+)
+
+# 1. Define the prompt template (MUST match the training format)
+prompt_template = (
+    'شما یک دستیار متخصص در زمینه اسناد علمی هستید. وظیفه شما این است که به سوال پرسیده شده، **فقط و فقط** بر اساس متن زمینه (Context) ارائه شده پاسخ دهید. پاسخ شما باید دقیق و خلاصه باشد.\n\n'
+    '**دستورالعمل مهم:** اگر اطلاعات لازم برای پاسخ دادن به سوال در متن زمینه وجود ندارد، باید **دقیقا** عبارت "CANNOT_ANSWER" را به عنوان پاسخ بنویسید و هیچ توضیح اضافه‌ای ندهید.\n\n'
+    '**زمینه (Context):**\n---\n{context}\n---\n\n'
+    '**سوال (Question):**\n{question}\n\n'
+    '**پاسخ (Answer):** '
+)
+
+# 2. Provide your context and question
+context = "سلول‌های خورشیدی پروسکایت به دلیل هزینه تولید پایین و بازدهی بالا، به عنوان یک فناوری نوظهور مورد توجه قرار گرفته‌اند. بازدهی آزمایشگاهی این سلول‌ها به بیش از ۲۵ درصد رسیده است، اما پایداری طولانی‌مدت آن‌ها همچنان یک چالش اصلی محسوب می‌شود."
+question = "بازدهی سلول‌های خورشیدی پروسکایت در آزمایشگاه چقدر است؟"
+# Example of a question that cannot be answered from the context:
+# question = "این سلول ها اولین بار در چه سالی ساخته شدند؟"
+
+# 3. Format the prompt
+prompt = prompt_template.format(context=context, question=question)
+
+# 4. Generate the response
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+generation_output = model.generate(
+    **inputs,
+    max_new_tokens=128,
+    eos_token_id=tokenizer.eos_token_id,
+    pad_token_id=tokenizer.eos_token_id
+)
+
+# Decode and print the output
+response = tokenizer.decode(generation_output[0], skip_special_tokens=True)
+
+# The generated text will be after the prompt
+answer = response.split("**پاسخ (Answer):**")[-1].strip()
+print(answer)
+# Expected output: به بیش از ۲۵ درصد رسیده است
+# For the unanswerable question, expected output: CANNOT_ANSWER
+Training Details
+Model
+The base model is Qwen/Qwen2.5-14B-Instruct, a highly capable instruction-tuned large language model.
+
+Dataset
+The model was fine-tuned on the safora/PersianSciQA-Extractive dataset. This dataset contains triplets of (context, question, model_answer) derived from Persian scientific documents. The dataset is split into:
+
+Train: Used for training the model.
+
+Validation: Used for evaluating the model during training epochs.
+
+Test: A held-out set reserved for final model evaluation.
+
+Fine-Tuning Procedure
+The model was fine-tuned using the QLoRA (Quantized Low-Rank Adaptation) method, which significantly reduces memory usage while maintaining high performance. The training was performed using the trl and peft libraries.
+
+Hyperparameters
+The following key hyperparameters were used during training:
+
+Parameter	Value
+LoRA Configuration	
+r (Rank)	16
+lora_alpha	32
+lora_dropout	0.05
+target_modules	q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
+Training Arguments	
+learning_rate	2e-5
+optimizer	paged_adamw_32bit
+lr_scheduler_type	cosine
+num_train_epochs	1
+per_device_train_batch_size	1
+gradient_accumulation_steps	8
+effective_batch_size	8
+quantization	4-bit (nf4)
+compute_dtype	bfloat16
+
+
+Evaluation
+The model's performance has not yet been formally evaluated on the held-out test split. The test split of the safora/PersianSciQA-Extractive dataset, containing 1049 samples, is available for this purpose. Community contributions to evaluate and benchmark this model are welcome.
+
+Citation
+If you use this model in your research or work, please cite it as follows:
+
+Code snippet
+
+@misc{persiansciqa_qwen2.5_14b,
+  author = {jolfaei,safora},
+  title = {PersianSciQA-Qwen2.5-14B: A QLoRA Fine-Tuned Model for Scientific Extractive QA in Persian},
+  year = {2025},
+  publisher = {Hugging Face},
+  journal = {Hugging Face Model Hub},
+  howpublished = {\url{[https://huggingface.co/safora/PersianSciQA-Qwen2.5-14B](https://huggingface.co/safora/PersianSciQA-Qwen2.5-14B)}}
+}