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.2).

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

Mô hình này đã được đóng góp cho Hugging Face Transformers vào ngày 2026-04-02.

Gemma4

Tổng quan

Gemma 4 là một mô hình đa phương thức với các biến thể được huấn luyện trước và tinh chỉnh theo chỉ thị, có sẵn ở các kích thước tham số E2B, E4B, 31B và 26B-A4B (MoE). Các mô hình Gemma 4 cung cấp những khả năng sau:

Lý luận: Tất cả các mô hình trong họ này được thiết kế như những bộ suy luận có khả năng cao, với các chế độ suy nghĩ có thể cấu hình.
Đa phương thức mở rộng: Xử lý văn bản, hình ảnh với hỗ trợ tỷ lệ khung hình và độ phân giải thay đổi (tất cả các mô hình), video và âm thanh (được hỗ trợ sẵn trên các mô hình E2B và E4B).
Tăng cửa sổ ngữ cảnh: Các mô hình nhỏ có cửa sổ ngữ cảnh 128K, trong khi các mô hình khác hỗ trợ 256K.
Nâng cao khả năng lập trình & Agentic: Đạt được những cải thiện đáng kể trên các benchmark lập trình cùng với hỗ trợ gọi hàm tích hợp sẵn, thúc đẩy các tác nhân tự chủ có năng lực cao.
Hỗ trợ System Prompt bản địa: Gemma 4 giới thiệu hỗ trợ tích hợp cho vai trò system, cho phép các cuộc hội thoại có cấu trúc và khả năng kiểm soát tốt hơn.

Bạn có thể tìm thấy tất cả các checkpoint gốc của Gemma 4 trong bản phát hành Gemma 4.

Mô hình Gemma4 Vision

Sự khác biệt chính so với các phiên bản Gemma trước đây về thị giác là thiết kế mới để xử lý các hình ảnh có kích thước khác nhau bằng cách sử dụng số lượng token cố định. Không giống như nhiều mô hình nén mọi hình ảnh thành một hình vuông cố định (ví dụ 224×224), Gemma 4 giữ nguyên tỷ lệ khung hình tự nhiên của hình ảnh trong khi điều chỉnh kích thước cho phù hợp. Có một số ràng buộc cần tuân thủ:

Tổng số pixel phải nằm trong phạm vi ngân sách patch
Cả chiều cao và chiều rộng đều phải chia hết cho 48 (= kích thước patch 16 × nhân pooling 3)

Gemma 4 không áp dụng chuẩn hóa mean/std ImageNet tiêu chuẩn mà nhiều mô hình thị giác khác sử dụng. Lớp nhúng patch của chính mô hình sẽ xử lý việc tỷ lệ cuối cùng bên trong (chuyển các giá trị sang khoảng [-1, 1]).

Số lượng “soft tokens” (còn gọi là vision tokens) mà một image processor có thể tạo ra là có thể cấu hình. Các tùy chọn được hỗ trợ được liệt kê bên dưới và mặc định là 280 soft tokens cho mỗi ảnh.

Token mềm	Các bản vá (trước khi gộp)	Diện tích ảnh xấp xỉ
70	630	~161K pixel
140	1,260	~323K pixel
280	2,520	~645K pixel
560	5,040	~1,3 triệu pixel
1,120	10,080	~2,6 triệu pixel

Để mã hóa thông tin vị trí cho từng patch trong ảnh, Gemma 4 sử dụng bảng nhúng vị trí 2D được học. Bảng vị trí lưu trữ tối đa 10.240 vị trí trên mỗi trục, cho phép mô hình xử lý các ảnh rất lớn. Mỗi vị trí là một vector được học có cùng kích thước chiều với nhúng patch. 2D RoPE mà Gemma 4 sử dụng xoay độc lập một nửa số chiều của đầu chú ý cho trục x và nửa còn lại cho trục y. Điều này cho phép mô hình hiểu các mối quan hệ không gian như “phía trên”, “phía dưới”, “bên trái” và “bên phải”.

Nhúng theo từng lớp (PLE)

Gemma 4 giới thiệu hệ thống Per-Layer Embeddings (PLE), đưa một tín hiệu dư thừa bổ trợ vào từng lớp decoder, thay vì chỉ dựa vào một embedding duy nhất được chia sẻ tại đầu vào.

PLE kết hợp hai thành phần được cộng lại và nhân với 1/√2 trước khi được đưa vào mỗi lớp decoder:

Token-identity (get_per_layer_inputs): tra cứu input_ids trong embed_tokens_per_layer, một Gemma4TextScaledWordEmbedding nhân với √(hidden_size_per_layer_input). Đầu ra được đóng gói được định dạng lại từ [batch, seq, num_hidden_layers * hidden_size_per_layer_input] thành [batch, seq, num_hidden_layers, hidden_size_per_layer_input].
Nhận thức ngữ cảnh (project_per_layer_inputs): chiếu inputs_embeds qua per_layer_model_projection (một lớp Linear), nhân với 1/√(hidden_size), định dạng lại thành [batch, seq, num_layers, ple_dim], và chuẩn hóa bằng per_layer_projection_norm (RMSNorm).

Khi cả hai thành phần đều khả dụng, đầu vào cuối cùng cho từng lớp là (token_identity + context_aware) * (1/√2). Đối với đầu vào đa phương thức mà input_ids không khả dụng, chỉ sử dụng phép chiếu nhận thức ngữ cảnh.

Ví dụ sử dụng

Ví dụ dưới đây minh họa cách tạo văn bản dựa trên hình ảnh bằng Pipeline hoặc lớp 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))

Gọi hàm

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))

Âm thanh (Chỉ E2B và 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

Tổng quan

Mô hình Gemma4 Vision

Nhúng theo từng lớp (PLE)

Ví dụ sử dụng

Gọi hàm

Âm thanh (Chỉ E2B và E4B)

Gemma4AudioConfig

lớp transformers.Gemma4AudioConfig

Gemma4VisionConfig

lớp transformers.Gemma4VisionConfig

Gemma4TextConfig

lớp transformers.Gemma4TextConfig

Gemma4Config

lớp transformers.Gemma4Config

Gemma4AudioFeatureExtractor

lớp transformers.Gemma4AudioFeatureExtractor

__call__

Gemma4ImageProcessorPil

lớp transformers.Gemma4ImageProcessorPil

preprocess

Gemma4ImageProcessor

lớp transformers.Gemma4ImageProcessor

preprocess

Gemma4VideoProcessor

class transformers.Gemma4VideoProcessor

preprocess

Gemma4Processor

lớp transformers.Gemma4Processor

__call__

Gemma4PreTrainedModel

lớp transformers.Gemma4PreTrainedModel

forward

Gemma4AudioModel

class transformers.Gemma4AudioModel

forward

Gemma4VisionModel

lớp transformers.Gemma4VisionModel

forward

Gemma4TextModel

lớp transformers.Gemma4TextModel

forward

Gemma4ForCausalLM

lớp transformers.Gemma4ForCausalLM

forward

Gemma4Model

lớp transformers.Gemma4Model

forward

Gemma4ForConditionalGeneration

lớp transformers.Gemma4ForConditionalGeneration

forward

call

call