Transformers documentation

Gemma4

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

تمت مساهمة هذا النموذج في Hugging Face Transformers في 2026-04-02.

Gemma4

نظرة عامة

نموذج Gemma 4 هو نموذج متعدد الوسائط يتوفر بنسخ مُدرَّبة مسبقًا ونسخ مُهيَّأة عبر التعليمات، بأحجام معلمات E2B وE4B و31B و26B-A4B (MoE). توفر نماذج Gemma 4 القدرات التالية:

الاستدلال: جميع النماذج في هذه العائلة مصممة لتكون مستدلّةً عالية القدرات، مع أوضاع تفكير قابلة للضبط.
الأنماط متعددة الوسائط الموسّعة: يعالج النص، والصورة مع دعم نسب أبعاد ودقة متغيرة (جميع النماذج)، والفيديو، والصوت (مدمج أصليًا في نموذجي E2B وE4B).
نافذة سياق موسّعة: تتميز النماذج الصغيرة بنافذة سياق بحجم 128K، بينما تدعم النماذج الأخرى حجم 256K.
قدرات البرمجة والوكلاء المحسّنة: يحقق تحسينات ملحوظة في اختبارات البرمجة المعيارية إلى جانب دعم مدمج لاستدعاء الدوال، مما يمكّن وكلاء مستقلين ذوي قدرات عالية.
دعم أصلي لموجّه النظام: تقدّم Gemma 4 دعماً مدمجاً لدور النظام، مما يتيح محادثات أكثر تنظيماً وقابلية للتحكم.

يمكنك العثور على جميع نقاط التفتيش الأصلية لنموذج Gemma 4 ضمن إصدار Gemma 4.

نموذج Gemma4 Vision

الفرق الرئيسي عن إصدارات Gemma السابقة الخاصة بالرؤية هو التصميم الجديد لمعالجة الصور ذات الأحجام المختلفة باستخدام عدد ثابت من الرموز ضمن ميزانية محددة. على عكس العديد من النماذج التي تضغط كل صورة في مربع ثابت (مثل 224×224)، يحافظ Gemma 4 على نسبة الأبعاد الطبيعية للصورة مع ضبط حجمها بشكل مناسب. هناك قيود قليلة يجب الالتزام بها:

يجب أن يتناسب إجمالي عدد البكسلات ضمن ميزانية الباتش
يجب أن يكون كل من الارتفاع والعرض قابلين للقسمة على 48 (= حجم البقعة 16 × نواة التجميع 3)

لا يطبّق Gemma 4 عملية تطبيع المتوسط/الانحراف المعياري القياسية الخاصة بـ ImageNet التي تستخدمها العديد من نماذج الرؤية الأخرى. يتولى طبقة تضمين الباتش الخاصة بالنموذج نفسها معالجة المقياس النهائي داخلياً (عن طريق إزاحة القيم إلى النطاق [-1, 1]).

يمكن ضبط عدد "الرموز الناعمة" (المعروفة أيضاً برموز الرؤية) التي يمكن لمعالج الصور إنتاجها. الخيارات المدعومة موضحة أدناه، والافتراضي هو 280 رمزاً ناعماً لكل صورة.

رموز ناعمة	التعديلات (قبل التجميع)	المساحة التقريبية للصورة
70	630	~161 ألف بكسل
140	1,260	~323 ألف بكسل
280	2,520	~645K بكسل
560	5,040	~1.3 مليون بكسل
1,120	10,080	~2.6 مليون بكسل

لتشفير المعلومات المكانية لكل رقعة في الصورة، يستخدم Gemma 4 جدول تضمينات موضعية ثنائي الأبعاد متعلّم. يخزّن جدول المواضع ما يصل إلى 10,240 موضعًا لكل محور، مما يتيح للنموذج التعامل مع صور كبيرة جدًا. كل موضع هو متجه متعلّم بأبعاد مطابقة لأبعاد تضمين الرقعة. يقوم RoPE ثنائي الأبعاد الذي يستخدمه Gemma 4 بتدوير نصف أبعاد رأس الانتباه بشكل مستقل للمحور السيني (x)، والنصف الآخر للمحور الصادي (y). وهذا يتيح للنموذج فهم العلاقات المكانية مثل "فوق"، "تحت"، "يسار"، و"يمين".

تضمينات لكل طبقة (PLE)

يُقدّم Gemma 4 نظام التضمينات لكل طبقة (PLE) الذي يُدخل إشارة متبقية مساعدة إلى كل طبقة من طبقات المُفكّك، بدلاً من الاعتماد حصرياً على تضمين مشترك واحد عند المدخل.

تجمع PLE بين مكوّنين يُجمَعان ويُضربان في 1/√2 قبل إمداد كل طبقة من طبقات المُفكِّك بهما:

هوية الرموز (get_per_layer_inputs): يبحث عن input_ids في embed_tokens_per_layer، وهو Gemma4TextScaledWordEmbedding يضرب الناتج في √(hidden_size_per_layer_input). يُعاد تشكيل المخرجات المعبأة من [batch, seq, num_hidden_layers * hidden_size_per_layer_input] إلى [batch, seq, num_hidden_layers, hidden_size_per_layer_input].
الواعي بالسياق (project_per_layer_inputs): يُسقط inputs_embeds عبر per_layer_model_projection (طبقة خطية)، ثم يضربها في 1/√(hidden_size)، ويعيد تشكيلها إلى [batch, seq, num_layers, ple_dim]، ويقيّسها باستخدام per_layer_projection_norm (RMSNorm).

عند توفر المكوّنين معًا، يكون المدخل النهائي لكل طبقة هو (token_identity + context_aware) * (1/√2). أما في المدخلات متعددة الوسائط التي لا يتوفر فيها input_ids، فيُستخدم الإسقاط الواعي بالسياق فقط.

أمثلة على الاستخدام

يُظهر المثال أدناه كيفية توليد النص بناءً على صورة باستخدام Pipeline أو فئة AutoModel.

from transformers import pipeline


pipeline = pipeline(
    task="image-text-to-text",
    model="google/gemma-4-E2B-it",
)
pipeline(
    images="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg",
    text="<|image|>\n\nWhat is shown in this image?"
)

</hfoption> <hfoption id="AutoModel">

from transformers import AutoModelForImageTextToText, AutoProcessor


model = AutoModelForImageTextToText.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-it",
    padding_side="left"
)

messages = [
    {
        "role": "user", "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
]
inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    add_generation_prompt=True,
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

output = model.generate(**inputs, max_new_tokens=50, cache_implementation="static")
print(processor.decode(output[0][input_len:], skip_special_tokens=True))

استدعاء الدوال

from transformers import AutoModelForCausalLM, AutoProcessor


WEATHER_TOOL = {
    "type": "function",
    "function": {
        "name": "get_n_day_weather_forecast",
        "description": "Get an N-day weather forecast",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
                "format": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The temperature unit to use",
                },
                "num_days": {
                    "type": "integer",
                    "description": "The number of days to forecast",
                },
            },
            "required": ["location", "format", "num_days"],
        },
    },
}

messages = [
    {
        "role": "user",
        "content": "What's the weather like the next 3 days in San Francisco, CA (using F)?",
    },
]

model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-it",
    padding_side="left"
)

text = processor.apply_chat_template(
    messages,
    tools=[WEATHER_TOOL],
    tokenize=False,
    add_generation_prompt=True,
)

inputs = processor(text=text, return_tensors="pt").to(model.device)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=200)
print(processor.decode(outputs[0][input_len:], skip_special_tokens=False))

الصوت (E2B و E4B فقط)

from transformers import AutoModelForMultimodalLM, AutoProcessor


messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Please transcribe the following audio:"},
            {
                "type": "audio",
                "url": "https://huggingface.co/datasets/eustlb/audio-samples/resolve/main/dude_where_is_my_car.wav",
            },
        ],
    }
]

model = AutoModelForMultimodalLM.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-it",
    padding_side="left"
)

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

input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=200)
print(processor.decode(outputs[0][input_len:], skip_special_tokens=False))

Transformers

Gemma4

نظرة عامة

نموذج Gemma4 Vision

تضمينات لكل طبقة (PLE)

أمثلة على الاستخدام

استدعاء الدوال

الصوت (E2B و E4B فقط)

Gemma4AudioConfig

فئة transformers.Gemma4AudioConfig

Gemma4VisionConfig

فئة transformers.Gemma4VisionConfig

Gemma4TextConfig

فئة transformers.Gemma4TextConfig

Gemma4Config

فئة transformers.Gemma4Config

Gemma4AudioFeatureExtractor

فئة transformers.Gemma4AudioFeatureExtractor

__call__

Gemma4ImageProcessorPil

فئة transformers.Gemma4ImageProcessorPil

preprocess

Gemma4ImageProcessor

فئة transformers.Gemma4ImageProcessor

preprocess

Gemma4VideoProcessor

فئة transformers.Gemma4VideoProcessor

preprocess

Gemma4Processor

فئة transformers.Gemma4Processor

__call__

Gemma4PreTrainedModel

فئة transformers.Gemma4PreTrainedModel

forward

Gemma4AudioModel

فئة transformers.Gemma4AudioModel

forward

Gemma4VisionModel

فئة transformers.Gemma4VisionModel

forward

Gemma4TextModel

فئة transformers.Gemma4TextModel

forward

Gemma4ForCausalLM

فئة transformers.Gemma4ForCausalLM

forward

Gemma4Model

فئة transformers.Gemma4Model

forward

Gemma4ForConditionalGeneration

فئة transformers.Gemma4ForConditionalGeneration

forward

call

call