🤖 راهنمای قالب Fine-tuning

این یک قالب کلی برای Fine-tuning مدل‌های زبانی مانند Gemma و LLaMA است که برای هر پروژه‌ای قابل استفاده است.

📁 فایل‌ها

• finetune_template.ipynb: نوتبوک اصلی قالب
• train.json: نمونه فایل دیتاست (فرمت شما ممکن است متفاوت باشد)

---

🚀 نحوه استفاده

مرحله 1: کپی کردن قالب

برای شروع یک پروژه جدید، فایل finetune_template.ipynb را کپی کنید:

cp finetune_template.ipynb my_project_finetune.ipynb

مرحله 2: شخصی‌سازی تنظیمات پروژه

سلول اول نوتبوک را باز کنید و تنظیمات را مطابق پروژه خود تغییر دهید:

PROJECT_CONFIG = {
    "project_name": "my-finetuned-model",  # ✏️ نام پروژه
    "model_name": "google/gemma-2-2b-it",  # ✏️ مدل مورد نظر
    "dataset_file": "train.json",  # ✏️ نام فایل دیتاست
    "prompt_field": "prompt",  # ✏️ نام فیلد ورودی در JSON
    "completion_field": "completion",  # ✏️ نام فیلد خروجی در JSON
    # ...
}

مرحله 3: تنظیم فرمت Prompt

مهم‌ترین بخش! تابع format_instruction را در سلول 4 مطابق با نیاز پروژه خود بنویسید.

نمونه‌های مختلف:

1️⃣ Translation Task

def format_instruction(sample):
    instruction = f"""<start_of_turn>user
Translate the following text from English to Persian:

{sample['english']}
<end_of_turn>
<start_of_turn>model
{sample['persian']}<end_of_turn>"""
    return instruction

2️⃣ Question Answering

def format_instruction(sample):
    instruction = f"""<start_of_turn>user
Context: {sample['context']}

Question: {sample['question']}
<end_of_turn>
<start_of_turn>model
{sample['answer']}<end_of_turn>"""
    return instruction

3️⃣ Text Classification

def format_instruction(sample):
    instruction = f"""<start_of_turn>user
Classify the sentiment of the following text as Positive, Negative, or Neutral:

{sample['text']}
<end_of_turn>
<start_of_turn>model
{sample['sentiment']}<end_of_turn>"""
    return instruction

4️⃣ Named Entity Recognition (NER)

def format_instruction(sample):
    entities = json.dumps(sample['entities'], ensure_ascii=False)
    instruction = f"""<start_of_turn>user
Extract all named entities (Person, Location, Organization) from the following text:

{sample['text']}
<end_of_turn>
<start_of_turn>model
{entities}<end_of_turn>"""
    return instruction

5️⃣ Summarization

def format_instruction(sample):
    instruction = f"""<start_of_turn>user
Summarize the following text in 2-3 sentences:

{sample['long_text']}
<end_of_turn>
<start_of_turn>model
{sample['summary']}<end_of_turn>"""
    return instruction

6️⃣ Code Generation

def format_instruction(sample):
    instruction = f"""<start_of_turn>user
Write a Python function based on this description:

{sample['description']}
<end_of_turn>
<start_of_turn>model
```python
{sample['code']}
```<end_of_turn>"""
    return instruction

مرحله 4: تنظیم تابع Test

تابع test_model در سلول 14 را هم مطابق با format_instruction تغییر دهید تا بتوانید مدل را تست کنید.

مرحله 5: اجرا

سلول‌ها را به ترتیب اجرا کنید:

1. ✅ تنظیمات پروژه
2. ✅ نصب کتابخانه‌ها
3. ✅ بارگذاری دیتاست
4. ✅ تنظیم format
5. ✅ بارگذاری مدل
6. ✅ Training
7. ✅ تست

---

📊 فرمت‌های مختلف دیتاست

فرمت 1: Prompt-Completion (ساده)

[
  {
    "prompt": "سوال یا درخواست",
    "completion": "پاسخ یا خروجی"
  }
]

فرمت 2: Instruction-Input-Output

[
  {
    "instruction": "دستورالعمل کلی",
    "input": "ورودی خاص",
    "output": "خروجی مورد انتظار"
  }
]

فرمت 3: Chat Format (مکالمه‌ای)

[
  {
    "messages": [
      {"role": "user", "content": "پیام کاربر"},
      {"role": "assistant", "content": "پاسخ دستیار"}
    ]
  }
]

فرمت 4: Complex JSON Output

[
  {
    "input": "متن ورودی",
    "output": {
      "field1": "value1",
      "field2": "value2",
      "nested": {
        "key": "value"
      }
    }
  }
]

---

🎯 انتخاب مدل مناسب

وظیفه	مدل توصیه شده	دلیل
Translation	Gemma 2B / 9B	قابلیت خوب برای چند زبانه
Question Answering	Gemma 2B / LLaMA 7B	فهم متن و استدلال
Classification	Gemma 270M / 2B	کافی برای وظایف ساده
Code Generation	Gemma 9B / LLaMA 7B	نیاز به دقت بالا
Summarization	Gemma 2B	تعادل خوب
Chat/Dialogue	Gemma 2B-IT / 9B-IT	بهینه برای مکالمه

نکته: مدل‌های -it (instruction-tuned) برای وظایف instruction-following بهینه شده‌اند.

---

⚙️ تنظیمات بهینه

برای دیتاست کوچک (< 500 نمونه)

{
    "num_epochs": 5,
    "batch_size": 2,
    "learning_rate": 3e-4,
    "lora_r": 16,
}

برای دیتاست متوسط (500-2000 نمونه)

{
    "num_epochs": 3,
    "batch_size": 4,
    "learning_rate": 2e-4,
    "lora_r": 32,
}

برای دیتاست بزرگ (> 2000 نمونه)

{
    "num_epochs": 2,
    "batch_size": 8,
    "learning_rate": 1e-4,
    "lora_r": 64,
}

---

🐛 رفع مشکلات

❌ Out of Memory (OOM)

# راه‌حل 1: کاهش batch size
"batch_size": 1,

# راه‌حل 2: افزایش gradient accumulation
"gradient_accumulation_steps": 8,

# راه‌حل 3: مدل کوچکتر
"model_name": "google/gemma-2-270m-it",

❌ Training خیلی کند

# تست با دیتاست کوچکتر
data = data[:100]

# کاهش epoch
"num_epochs": 1,

❌ دقت پایین

# افزایش epoch
"num_epochs": 5,

# افزایش LoRA rank
"lora_r": 32,

# کاهش learning rate
"learning_rate": 1e-4,

# بررسی کیفیت دیتاست

❌ مدل تکرار می‌کند

# در text generation:
repetition_penalty=1.5,  # افزایش از 1.2

# کاهش temperature
temperature=0.5,  # کاهش از 0.7

---

📈 ارزیابی مدل

روش‌های ارزیابی:

1. تست دستی: چند نمونه تصادفی را تست کنید
2. Evaluation set: از 10% دیتاست برای ارزیابی استفاده کنید
3. Metrics:
   • برای Classification: Accuracy, F1-Score
   • برای Generation: BLEU, ROUGE (برای ترجمه و خلاصه‌سازی)
   • برای QA: Exact Match, F1

نمونه کد ارزیابی:

from sklearn.metrics import accuracy_score, f1_score

# برای classification
predictions = []
ground_truth = []

for sample in test_data:
    pred = test_model(sample['input'])
    predictions.append(pred)
    ground_truth.append(sample['output'])

accuracy = accuracy_score(ground_truth, predictions)
f1 = f1_score(ground_truth, predictions, average='weighted')

print(f"Accuracy: {accuracy:.2%}")
print(f"F1-Score: {f1:.2%}")

---

🔄 Workflow پیشنهادی

1. آماده‌سازی دیتاست
   ↓
2. تست با 10% دیتاست و 1 epoch
   ↓
3. بررسی خروجی و تنظیم prompt
   ↓
4. Training با 50% دیتاست و 2 epoch
   ↓
5. ارزیابی و تنظیم hyperparameters
   ↓
6. Training نهایی با کل دیتاست
   ↓
7. تست کامل و دیپلوی

---

💡 نکات مهم

✅ Do's

• همیشه با دیتاست کوچک شروع کنید
• فرمت prompt را با دقت طراحی کنید
• نمونه‌های متنوع در دیتاست داشته باشید
• مدل را با ورودی‌های مختلف تست کنید
• مدل را قبل از Training ذخیره کنید
• از version control (git) استفاده کنید

❌ Don'ts

• بلافاصله با کل دیتاست شروع نکنید
• hyperparameters را همزمان تغییر ندهید
• دیتاست نامتعادل نداشته باشید
• prompt را بیش از حد پیچیده نکنید
• فراموش نکنید که مدل را evaluate کنید

---

📦 دیپلوی مدل

استفاده لوکال:

from peft import AutoPeftModelForCausalLM
from transformers import AutoTokenizer

model = AutoPeftModelForCausalLM.from_pretrained("./finetuned-model-final")
tokenizer = AutoTokenizer.from_pretrained("./finetuned-model-final")

API با Flask:

from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/predict', methods=['POST'])
def predict():
    data = request.json
    result = generator(data['input'])
    return jsonify({'output': result})

app.run(host='0.0.0.0', port=5000)

Gradio Interface:

import gradio as gr

def predict(text):
    return test_model(text)

demo = gr.Interface(fn=predict, inputs="text", outputs="text")
demo.launch()

---

🎓 منابع آموزشی

• Hugging Face Documentation
• LoRA Paper
• Instruction Tuning Guide
• PEFT Library

---

📞 پشتیبانی

اگر مشکلی داشتید:

1. راهنمای رفع مشکلات در نوتبوک را بخوانید
2. نسخه کتابخانه‌ها را بررسی کنید
3. GPU را بررسی کنید
4. مدل کوچکتر را امتحان کنید

---

موفق باشید! 🚀