تحسين Gemma لمهام الرؤية باستخدام Hugging Face Transformers وQLoRA

يرشدك هذا الدليل إلى كيفية تحسين Gemma على مجموعة بيانات مخصّصة من الصور والنصوص لمهمّة متعلقة بالرؤية (إنشاء أوصاف المنتجات) باستخدام Transformers وTRL من Hugging Face. ستتعرّف على ما يلي:

  • ما هو Quantized Low-Rank Adaptation (QLoRA)؟
  • إعداد بيئة التطوير
  • إنشاء مجموعة بيانات التحسين وإعدادها لمهام الرؤية
  • تحسين Gemma باستخدام TRL وSFTTrainer
  • اختبِر استنتاج النموذج وأنشئ أوصاف المنتجات من الصور والنصوص.

ما هو Quantized Low-Rank Adaptation (QLoRA)؟

يوضّح هذا الدليل استخدام التكييف الكمي منخفض الترتيب (QLoRA)، والذي برز كطريقة شائعة لتحسين النماذج اللغوية الكبيرة بكفاءة، لأنّه يقلل من متطلبات الموارد الحسابية مع الحفاظ على الأداء العالي. في QloRA، يتم تقليل عدد الأرقام في النموذج المدّرب مسبقًا إلى 4 بت ويتم تجميد الأوزان. بعد ذلك، يتم إرفاق طبقات المحوِّل القابلة للتدريب (LoRA) ويتم تدريب طبقات المحوِّل فقط. بعد ذلك، يمكن دمج قيم مُحوِّل البيانات مع النموذج الأساسي أو الاحتفاظ بها كمحوِّل بيانات منفصل.

إعداد بيئة التطوير

الخطوة الأولى هي تثبيت مكتبات Hugging Face، بما في ذلك TRL، ومجموعات البيانات لتحسين النموذج المفتوح.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0" tensorboard torchvision

# Install Gemma release branch from Hugging Face
%pip install "transformers>=4.51.3"

# Install Hugging Face libraries
%pip install  --upgrade \
  "datasets==3.3.2" \
  "accelerate==1.4.0" \
  "evaluate==0.4.3" \
  "bitsandbytes==0.45.3" \
  "trl==0.15.2" \
  "peft==0.14.0" \
  "pillow==11.1.0" \
  protobuf \
  sentencepiece

قبل أن تتمكّن من بدء التدريب، عليك التأكّد من قبول بنود استخدام Gemma. يمكنك قبول الترخيص على Hugging Face من خلال النقر على الزر "الموافقة والوصول إلى المستودع" في صفحة النموذج على الرابط: http://huggingface.co/google/gemma-3-4b-pt (أو صفحة النموذج المناسبة لنموذج Gemma المزوّد بميزة الرؤية الذي تستخدمه).

بعد قبول الترخيص، ستحتاج إلى رمز Hugging Face Token صالح للوصول إلى النموذج. إذا كنت تستخدم Google Colab، يمكنك استخدام رمز Hugging Face بشكل آمن باستخدام أسرار Colab، وإلا يمكنك ضبط الرمز المميّز مباشرةً في طريقة login. تأكَّد أيضًا من أنّ الرمز المميّز يتضمّن إذن الوصول للكتابة، وذلك عند نقل النموذج إلى Hub أثناء عملية التدريب.

from google.colab import userdata
from huggingface_hub import login

# Login into Hugging Face Hub
hf_token = userdata.get('HF_TOKEN') # If you are running inside a Google Colab
login(hf_token)

إنشاء مجموعة بيانات التحسين وإعدادها

عند تحسين النماذج اللغوية الكبيرة، من المهم معرفة حالة الاستخدام والمهمة التي تريد حلّها. يساعدك ذلك في إنشاء مجموعة بيانات لتحسين نموذجك. إذا لم تكن قد حدّدت حالة الاستخدام بعد، ننصحك بالعودة إلى لوحة الرسم.

على سبيل المثال، يركّز هذا الدليل على حالة الاستخدام التالية:

  • تحسين نموذج Gemma لإنشاء أوصاف منتجات موجزة ومحسّنة لتحسين محركات البحث لمنصّة للتجارة الإلكترونية، مصمّمة خصيصًا للبحث على الأجهزة الجوّالة

يستخدِم هذا الدليل مجموعة البيانات philschmid/amazon-product-descriptions-vlm، وهي مجموعة بيانات تتضمّن أوصاف منتجات Amazon، بما في ذلك صور المنتجات وفئات المنتجات.

يتيح Hugging Face TRL إجراء محادثات متعددة الوسائط. الجزء المهم هو دور "الصورة"، الذي يُعلم فئة المعالجة بتحميل الصورة. يجب أن تتّبع البنية ما يلي:

{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}

يمكنك الآن استخدام مكتبة Hugging Face Datasets لتحميل مجموعة البيانات وإنشاء نموذج طلب دمج الصورة واسم المنتج والفئته وإضافة رسالة نظام. تتضمّن مجموعة البيانات صورًا على أنّها عناصرPil.Image.

from datasets import load_dataset
from PIL import Image

# System message for the assistant
system_message = "You are an expert product description writer for Amazon."

# User prompt that combines the user query and the schema
user_prompt = """Create a Short Product description based on the provided <PRODUCT> and <CATEGORY> and image.
Only return description. The description should be SEO optimized and for a better mobile search experience.

<PRODUCT>
{product}
</PRODUCT>

<CATEGORY>
{category}
</CATEGORY>
"""

# Convert dataset to OAI messages
def format_data(sample):
    return {
        "messages": [
            {
                "role": "system",
                "content": [{"type": "text", "text": system_message}],
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": user_prompt.format(
                            product=sample["Product Name"],
                            category=sample["Category"],
                        ),
                    },
                    {
                        "type": "image",
                        "image": sample["image"],
                    },
                ],
            },
            {
                "role": "assistant",
                "content": [{"type": "text", "text": sample["description"]}],
            },
        ],
    }

def process_vision_info(messages: list[dict]) -> list[Image.Image]:
    image_inputs = []
    # Iterate through each conversation
    for msg in messages:
        # Get content (ensure it's a list)
        content = msg.get("content", [])
        if not isinstance(content, list):
            content = [content]

        # Check each content element for images
        for element in content:
            if isinstance(element, dict) and (
                "image" in element or element.get("type") == "image"
            ):
                # Get the image and convert to RGB
                if "image" in element:
                    image = element["image"]
                else:
                    image = element
                image_inputs.append(image.convert("RGB"))
    return image_inputs

# Load dataset from the hub
dataset = load_dataset("philschmid/amazon-product-descriptions-vlm", split="train")

# Convert dataset to OAI messages
# need to use list comprehension to keep Pil.Image type, .mape convert image to bytes
dataset = [format_data(sample) for sample in dataset]

print(dataset[345]["messages"])

تحسين Gemma باستخدام TRL وSFTTrainer

أصبحت الآن جاهزًا لإجراء تحسينات على النموذج. تسهِّل أداة SFTTrainer من Hugging Face TRL الإشراف على تحسين النماذج اللغوية الكبيرة المفتوحة. ‫SFTTrainer هي فئة فرعية من Trainer من مكتبة transformers وتتيح جميع الميزات نفسها، بما في ذلك التسجيل والتقييم وتسجيل نقاط التفتيش، ولكنها تضيف ميزات إضافية لتسهيل الاستخدام، بما في ذلك:

  • تنسيق مجموعة البيانات، بما في ذلك تنسيقات المحادثات والتعليمات
  • التدريب على عمليات الإكمال فقط، مع تجاهل الطلبات
  • تجميع مجموعات البيانات لتدريب أكثر فعالية
  • إتاحة ميزة "التحسين الدقيق باستخدام المَعلمات" (PEFT) بما في ذلك QloRA
  • إعداد النموذج وبرنامج تقسيم النصوص لإجراء تحسينات على المحادثات (مثل إضافة رموز خاصة)

تحمِّل الرموز البرمجية التالية نموذج Gemma وبرنامج تقسيم الكلمات من Hugging Face وتُنشئ إعدادات التقليل.

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText, BitsAndBytesConfig

# Hugging Face model id
model_id = "google/gemma-3-4b-pt" # or `google/gemma-3-12b-pt`, `google/gemma-3-27-pt`

# Check if GPU benefits from bfloat16
if torch.cuda.get_device_capability()[0] < 8:
    raise ValueError("GPU does not support bfloat16, please use a GPU that supports bfloat16.")

# Define model init arguments
model_kwargs = dict(
    attn_implementation="eager", # Use "flash_attention_2" when running on Ampere or newer GPU
    torch_dtype=torch.bfloat16, # What torch dtype to use, defaults to auto
    device_map="auto", # Let torch decide how to load the model
)

# BitsAndBytesConfig int-4 config
model_kwargs["quantization_config"] = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=model_kwargs["torch_dtype"],
    bnb_4bit_quant_storage=model_kwargs["torch_dtype"],
)

# Load model and tokenizer
model = AutoModelForImageTextToText.from_pretrained(model_id, **model_kwargs)
processor = AutoProcessor.from_pretrained("google/gemma-3-4b-it")

يتيح SFTTrainer دمجًا مضمّنًا مع peft، ما يسهّل ضبط النماذج اللغوية الكبيرة بكفاءة باستخدام QLoRA. ما عليك سوى إنشاء LoraConfig وتقديمه إلى المدرب.

from peft import LoraConfig

peft_config = LoraConfig(
    lora_alpha=16,
    lora_dropout=0.05,
    r=16,
    bias="none",
    target_modules="all-linear",
    task_type="CAUSAL_LM",
    modules_to_save=[
        "lm_head",
        "embed_tokens",
    ],
)

قبل أن تتمكّن من بدء عملية التدريب، عليك تحديد المَعلمة الفائقة التي تريد استخدامها في SFTConfig وcollate_fn مخصّص للتعامل مع معالجة الرؤية. يحوّل collate_fn الرسائل التي تحتوي على نص وصور إلى تنسيق يمكن للنموذج فهمه.

from trl import SFTConfig

args = SFTConfig(
    output_dir="gemma-product-description",     # directory to save and repository id
    num_train_epochs=1,                         # number of training epochs
    per_device_train_batch_size=1,              # batch size per device during training
    gradient_accumulation_steps=4,              # number of steps before performing a backward/update pass
    gradient_checkpointing=True,                # use gradient checkpointing to save memory
    optim="adamw_torch_fused",                  # use fused adamw optimizer
    logging_steps=5,                            # log every 5 steps
    save_strategy="epoch",                      # save checkpoint every epoch
    learning_rate=2e-4,                         # learning rate, based on QLoRA paper
    bf16=True,                                  # use bfloat16 precision
    max_grad_norm=0.3,                          # max gradient norm based on QLoRA paper
    warmup_ratio=0.03,                          # warmup ratio based on QLoRA paper
    lr_scheduler_type="constant",               # use constant learning rate scheduler
    push_to_hub=True,                           # push model to hub
    report_to="tensorboard",                    # report metrics to tensorboard
    gradient_checkpointing_kwargs={
        "use_reentrant": False
    },  # use reentrant checkpointing
    dataset_text_field="",                      # need a dummy field for collator
    dataset_kwargs={"skip_prepare_dataset": True},  # important for collator
)
args.remove_unused_columns = False # important for collator

# Create a data collator to encode text and image pairs
def collate_fn(examples):
    texts = []
    images = []
    for example in examples:
        image_inputs = process_vision_info(example["messages"])
        text = processor.apply_chat_template(
            example["messages"], add_generation_prompt=False, tokenize=False
        )
        texts.append(text.strip())
        images.append(image_inputs)

    # Tokenize the texts and process the images
    batch = processor(text=texts, images=images, return_tensors="pt", padding=True)

    # The labels are the input_ids, and we mask the padding tokens and image tokens in the loss computation
    labels = batch["input_ids"].clone()

    # Mask image tokens
    image_token_id = [
        processor.tokenizer.convert_tokens_to_ids(
            processor.tokenizer.special_tokens_map["boi_token"]
        )
    ]
    # Mask tokens for not being used in the loss computation
    labels[labels == processor.tokenizer.pad_token_id] = -100
    labels[labels == image_token_id] = -100
    labels[labels == 262144] = -100

    batch["labels"] = labels
    return batch

لديك الآن كلّ الوحدات الأساسية التي تحتاج إليها لإنشاء SFTTrainer لبدء تدريب النموذج.

from trl import SFTTrainer

trainer = SFTTrainer(
    model=model,
    args=args,
    train_dataset=dataset,
    peft_config=peft_config,
    processing_class=processor,
    data_collator=collate_fn,
)

ابدأ التدريب من خلال استدعاء طريقة train().

# Start training, the model will be automatically saved to the Hub and the output directory
trainer.train()

# Save the final model again to the Hugging Face Hub
trainer.save_model()

قبل أن تتمكّن من اختبار النموذج، احرص على تحرير الذاكرة.

# free the memory again
del model
del trainer
torch.cuda.empty_cache()

عند استخدام QLoRA، يتم تدريب المحوِّلات فقط وليس النموذج الكامل. وهذا يعني أنّه عند حفظ النموذج أثناء التدريب، يتم حفظ أوزان المُحوِّل فقط وليس النموذج الكامل. إذا كنت تريد حفظ النموذج الكامل، ما يسهّل استخدامه مع مجموعات عرض مثل vLLM أو TGI، يمكنك دمج أوزان المُحوِّل في أوزان النموذج باستخدام الطريقة merge_and_unload ثم حفظ النموذج باستخدام الطريقة save_pretrained. يؤدي ذلك إلى حفظ نموذج تلقائي يمكن استخدامه للاستنتاج.

from peft import PeftModel

# Load Model base model
model = AutoModelForImageTextToText.from_pretrained(model_id, low_cpu_mem_usage=True)

# Merge LoRA and base model and save
peft_model = PeftModel.from_pretrained(model, args.output_dir)
merged_model = peft_model.merge_and_unload()
merged_model.save_pretrained("merged_model", safe_serialization=True, max_shard_size="2GB")

processor = AutoProcessor.from_pretrained(args.output_dir)
processor.save_pretrained("merged_model")

اختبار الاستنتاج من النماذج وإنشاء أوصاف المنتجات

بعد انتهاء عملية التدريب، عليك تقييم النموذج واختباره. يمكنك تحميل عيّنات مختلفة من مجموعة بيانات الاختبار وتقييم النموذج على هذه العيّنات.

import torch

# Load Model with PEFT adapter
model = AutoModelForImageTextToText.from_pretrained(
  args.output_dir,
  device_map="auto",
  torch_dtype=torch.bfloat16,
  attn_implementation="eager",
)
processor = AutoProcessor.from_pretrained(args.output_dir)

يمكنك اختبار الاستنتاج من خلال تقديم اسم المنتج وفئة المنتج وصورته. يتضمّن sample شخصية كرتونية مشهورة.

import requests
from PIL import Image

# Test sample with Product Name, Category and Image
sample = {
  "product_name": "Hasbro Marvel Avengers-Serie Marvel Assemble Titan-Held, Iron Man, 30,5 cm Actionfigur",
  "category": "Toys & Games | Toy Figures & Playsets | Action Figures",
  "image": Image.open(requests.get("https://m.media-amazon.com/images/I/81+7Up7IWyL._AC_SY300_SX300_.jpg", stream=True).raw).convert("RGB")
}

def generate_description(sample, model, processor):
    # Convert sample into messages and then apply the chat template
    messages = [
        {"role": "system", "content": [{"type": "text", "text": system_message}]},
        {"role": "user", "content": [
            {"type": "image","image": sample["image"]},
            {"type": "text", "text": user_prompt.format(product=sample["product_name"], category=sample["category"])},
        ]},
    ]
    text = processor.apply_chat_template(
        messages, tokenize=False, add_generation_prompt=True
    )
    # Process the image and text
    image_inputs = process_vision_info(messages)
    # Tokenize the text and process the images
    inputs = processor(
        text=[text],
        images=image_inputs,
        padding=True,
        return_tensors="pt",
    )
    # Move the inputs to the device
    inputs = inputs.to(model.device)

    # Generate the output
    stop_token_ids = [processor.tokenizer.eos_token_id, processor.tokenizer.convert_tokens_to_ids("<end_of_turn>")]
    generated_ids = model.generate(**inputs, max_new_tokens=256, top_p=1.0, do_sample=True, temperature=0.8, eos_token_id=stop_token_ids, disable_compile=True)
    # Trim the generation and decode the output to text
    generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
    output_text = processor.batch_decode(
        generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
    )
    return output_text[0]

# generate the description
description = generate_description(sample, model, processor)
print(description)

الملخّص والخطوات التالية

تناول هذا الدليل التعليمي كيفية ضبط نموذج Gemma لمهام الرؤية باستخدام TRL وQLoRA، وتحديدًا لإنشاء أوصاف المنتجات. اطّلِع على المستندات التالية بعد ذلك: