تشغيل Gemma مع ميزة "تحوُّل الوجوه إلى تعابير"

عرض على ai.google.dev التشغيل في Google Colab التشغيل في Kaggle فتح في Vertex AI عرض المصدر على GitHub

إنّ إنشاء النصوص وتلخيص المحتوى وتحليله هي بعض المهام التي يمكنك إنجازها باستخدام نماذج Gemma المتاحة للجميع. يوضّح لك هذا البرنامج التعليمي كيفية البدء في تشغيل Gemma باستخدام Hugging Face Transformers باستخدام كل من إدخال النص والصورة لإنشاء محتوى نصي. توفّر مكتبة Transformers Python واجهة برمجة تطبيقات للوصول إلى نماذج الذكاء الاصطناعي التوليدي المُدرَّبة مسبقًا، بما في ذلك Gemma. لمزيد من المعلومات، اطّلِع على مستندات Transformers.

ضبط إعدادات الجهاز

قبل البدء في هذا البرنامج التعليمي، أكمل الخطوات التالية:

  • يمكنك الوصول إلى Gemma من خلال تسجيل الدخول إلى Hugging Face والنقر على أوافق على الترخيص لنموذج Gemma.
  • اختَر وقت تشغيل Colab يتضمّن موارد كافية لتشغيل نموذج Gemma بالحجم الذي تريده. مزيد من المعلومات
  • أنشئ رمزًا مميّزًا للوصول إلى Hugging Face وأضِفه إلى بيئة Colab.

ضبط رمز الدخول

أضِف رمز الدخول إلى Colab لتفعيل تنزيل نماذج Gemma من موقع Hugging Face الإلكتروني. استخدِم ميزة الأسرار في Colab لحفظ الرمز المميّز بشكل آمن بدون إضافته إلى الرمز البرمجي الذي تعمل عليه.

لإضافة رمز الدخول إلى Hugging Face كبيانات سرية، اتّبِع الخطوات التالية:

  1. افتح علامة التبويب "الأسرار" من خلال النقر على رمز المفتاح في الجانب الأيمن من الواجهة، أو انقر على الأدوات > لوحة الأوامر، واكتب secrets، ثم اضغط على Enter.
  2. انقر على إضافة مفتاح سرّي جديد لإضافة إدخال مفتاح سرّي جديد.
  3. في حقل الاسم، أدخِل HF_TOKEN.
  4. في حقل القيمة، أدخِل نص رمز الدخول إلى Hugging Face.
  5. في الحقل إذن الوصول إلى دفتر الملاحظات، انقر على زر التبديل لتفعيل إذن الوصول.

بعد إدخال رمز الدخول كـ HF_TOKEN والقيمة، يمكنك الوصول إليه وضبطه في بيئة دفتر ملاحظات Colab باستخدام الرمز التالي:

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)

تثبيت حِزم Python

ثبِّت مكتبات Hugging Face المطلوبة لتشغيل نموذج Gemma وتقديم الطلبات.

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

# Install a transformers version that supports Gemma 3 (>= 4.51.3)
%pip install "transformers>=4.51.3"

إنشاء نص من نص

إنّ تقديم طلب إلى أحد نماذج Gemma للحصول على رد نصي هو أبسط طريقة لاستخدام Gemma، وهي تعمل مع جميع خيارات Gemma تقريبًا. يوضّح هذا القسم كيفية استخدام مكتبة Hugging Face Transformers لتحميل نموذج Gemma وإعداده لإنشاء نص من نص.

تحميل النموذج

استخدِم مكتبتَي torch وtransformers لإنشاء مثيل لفئة pipeline لتنفيذ نموذج باستخدام Gemma. عند استخدام نموذج لإنشاء ناتج أو اتّباع توجيهات، اختَر نموذجًا معدَّلاً للتعليمات (IT)، والذي يتضمّن عادةً it في سلسلة معرّف النموذج. باستخدام العنصر pipeline، يمكنك تحديد نوع Gemma الذي تريد استخدامه، ونوع المهمة التي تريد تنفيذها، وتحديدًا "text-generation" لإنشاء نص من نص، كما هو موضّح في مثال الرمز التالي:

import torch
from transformers import pipeline

pipeline = pipeline(
    task="text-generation",
    model="google/gemma-3-4b-it",
    device=0, # "cuda" for Colab, "msu" for iOS devices
    torch_dtype=torch.bfloat16
)

لا يتيح نموذج Gemma سوى عدد قليل من task إعدادات الإنشاء. لمزيد من المعلومات عن إعدادات task المتاحة، يُرجى الاطّلاع على مستندات Hugging Face Pipelines task(). استخدِم نوع بيانات الشعلة torch.bfloat16 لتقليل دقة النموذج وموارد الحوسبة المطلوبة، بدون التأثير بشكل كبير في جودة ناتج النموذج. بالنسبة إلى الإعداد device، يمكنك استخدام "cuda" في Colab أو "msu" لأجهزة iOS، أو يمكنك ضبط هذا الإعداد على 0 (صفر) لتحديد وحدة معالجة الرسومات الأولى على نظامك. لمزيد من المعلومات عن استخدام فئة Pipeline، يُرجى الاطّلاع على مستندات Pipelines في Hugging Face.

تشغيل ميزة "إنشاء النص"

بعد تحميل نموذج Gemma وضبطه في عنصر pipeline، يمكنك إرسال طلبات إلى النموذج. يعرض مثال الرمز البرمجي التالي طلبًا أساسيًا باستخدام المَعلمة text_inputs:

pipeline(text_inputs="roses are red")

[{'generated_text': 'roses are red, violets are blue, \ni love you more than you ever knew.\n\n**Explanation'}]

استخدام نموذج طلب

عند إنشاء محتوى باستخدام طلبات أكثر تعقيدًا، استخدِم نموذج طلب لتنظيم طلبك. يتيح لك نموذج الطلب تحديد الإدخالات من أدوار معيّنة، مثل user أو model، وهو تنسيق مطلوب لإدارة تفاعلات المحادثات المتعددة الأدوار مع نماذج Gemma. يوضّح نموذج الرمز التالي كيفية إنشاء نموذج طلب لـ Gemma:

messages = [
    [
        {
            "role": "system",
            "content": [{"type": "text", "text": "You are a helpful assistant."},]
        },
        {
            "role": "user",
            "content": [{"type": "text", "text": "Roses are red..."},]
        },
    ],
]

pipeline(messages, max_new_tokens=50)

إنشاء نص من بيانات الصورة

بدءًا من Gemma 3، بالنسبة إلى أحجام النماذج 4B والإصدارات الأحدث، يمكنك استخدام بيانات الصور كجزء من طلبك. يوضّح هذا القسم كيفية استخدام مكتبة Transformers لتحميل نموذج Gemma وإعداده لاستخدام بيانات الصور وإدخال النصوص من أجل إنشاء نصوص كناتج.

تحميل النموذج

عند تحميل نموذج Gemma لاستخدامه مع بيانات الصور، يمكنك ضبط مثيل Transformer pipeline خصيصًا لاستخدامه مع الصور. على وجه الخصوص، يجب اختيار إعدادات مسار بيانات يمكنها التعامل مع البيانات المرئية من خلال ضبط المَعلمة task على "image-text-to-text"، كما هو موضّح في مثال الرمز البرمجي التالي:

import torch
from transformers import pipeline

pipeline = pipeline(
    task="image-text-to-text", # required for image input
    model="google/gemma-3-4b-it",
    device=0,
    torch_dtype=torch.bfloat16
)

تشغيل ميزة "إنشاء النص"

بعد ضبط نموذج Gemma للتعامل مع إدخال الصور باستخدام مثيل pipeline، يمكنك إرسال طلبات تتضمّن صورًا إلى النموذج. استخدِم الرمز المميز <start_of_image> لإضافة الصورة إلى نص طلبك. يعرض مثال الرمز البرمجي التالي طلبًا أساسيًا باستخدام المَعلمة pipeline:

pipeline(
    "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg",
    text="<start_of_image> What is shown in this image?"
)

[{'input_text': '<start_of_image> What is shown in this image?',
  'generated_text': '<start_of_image> What is shown in this image?\n\nThis image showcases a traditional Indian Thali. A Thali is a platter that contains a variety'}]

استخدام نموذج طلب

عند إنشاء محتوى باستخدام طلبات أكثر تعقيدًا، استخدِم نموذج طلب لتنظيم طلبك. يتيح لك نموذج الطلب تحديد الإدخالات من أدوار معيّنة، مثل user أو model، وهو تنسيق مطلوب لإدارة تفاعلات المحادثات المتعددة الأدوار مع نماذج Gemma. يوضّح نموذج الرمز التالي كيفية إنشاء نموذج طلب لـ Gemma:

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "This image shows"},
        ],
    },
]

pipeline(text=messages, max_new_tokens=50, return_full_text=False)

يمكنك تضمين صور متعددة في طلبك من خلال إدراج إدخالات "type": "image", إضافية في قائمة content.

إنشاء نص من البيانات الصوتية

باستخدام Gemma 3n، يمكنك استخدام بيانات صوتية كجزء من طلبك. يوضّح هذا القسم كيفية استخدام مكتبة Transformers لتحميل نموذج Gemma وضبطه لاستخدام بيانات الصوت والنص المُدخَل من أجل إنشاء نص مُخرَج.

تثبيت حِزم Python

يجب توفّر إصدار حديث من مكتبات Transformers لاستخدام إدخال الصوت مع Gemma. ثبِّت مكتبات Hugging Face لتشغيل نموذج Gemma وتقديم الطلبات باستخدام بيانات الصوت كما هو موضّح أدناه.

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

# Install a transformers version that supports Gemma 3n (>= 4.53)
%pip install "transformers>=4.53.0"

تحميل النموذج

عند تحميل نموذج Gemma لاستخدامه مع البيانات الصوتية، يمكنك ضبط مثيل Transformer خصيصًا لاستخدامه مع البيانات الصوتية. على وجه الخصوص، يجب تحديد العنصرين processor وmodel باستخدام الفئتين AutoProcessor وAutoModelForImageTextToText، كما هو موضّح في مثال الرمز التالي:

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText

GEMMA_MODEL_ID = "google/gemma-3n-E4B-it"

processor = AutoProcessor.from_pretrained(GEMMA_MODEL_ID, device_map="auto")
model = AutoModelForImageTextToText.from_pretrained(
            GEMMA_MODEL_ID, torch_dtype="auto", device_map="auto")

استخدام نموذج طلب

عند إنشاء محتوى يتضمّن صوتًا، استخدِم نموذج طلب لتنظيم طلبك. يتيح لك نموذج الطلب تحديد الإدخالات من أدوار معيّنة، مثل user أو model، وهو تنسيق مطلوب لإدارة تفاعلات المحادثات المتعددة الأدوار مع نماذج Gemma. يوضّح نموذج الرمز التالي كيفية إنشاء نموذج طلب لـ Gemma باستخدام إدخال بيانات صوتية:

messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "https://ai.google.dev/gemma/docs/audio/roses-are.wav"},
            {"type": "text", "text": "Transcribe this audio and complete the statement"},
        ]
    }
]

يمكنك تضمين ملفات صوتية متعددة في طلبك من خلال تضمين إدخالات "type": "audio", إضافية في قائمة content. إذا كنت تستخدم بيانات صوتية في الطلب بدون نموذج، استخدِم بنية <audio_soft_token> في نص الطلب.

تشغيل ميزة "إنشاء النص"

بعد ضبط نموذج Gemma باستخدام كائن processor وكائن model، وإنشاء طلب باستخدام بيانات صوتية من خلال نموذج طلب، يمكنك إرسال الطلب لإنشاء الناتج. يعرض مثال الرمز البرمجي التالي طلبًا باستخدام نموذج محادثة، وإنشاء الناتج، وفك ترميز الردّ:

input_ids = processor.apply_chat_template(
        messages,
        add_generation_prompt=True,
        tokenize=True, return_dict=True,
        return_tensors="pt",
)
input_ids = input_ids.to(model.device, dtype=model.dtype)

# Generate output from the model
outputs = model.generate(**input_ids, max_new_tokens=128)

# decode and print the output as text
text = processor.batch_decode(
    outputs,
    skip_special_tokens=False,
    clean_up_tokenization_spaces=False
)
print(text[0])

الخطوات التالية

يمكنك إنشاء المزيد واستكشاف المزيد باستخدام نماذج Gemma: