Transformers documentation
ShieldGemma 2
Mô hình này được công bố trên HF papers vào ngày 2025-04-01 và được đóng góp cho Hugging Face Transformers vào ngày 2025-03-20.
ShieldGemma 2
Tổng quan
Mô hình ShieldGemma 2 được đề xuất trong một báo cáo kỹ thuật của Google. ShieldGemma 2, được xây dựng dựa trên Gemma 3, là một mô hình có 4 tỷ (4B) tham số, kiểm tra mức độ an toàn của cả hình ảnh tổng hợp và hình ảnh tự nhiên đối với các danh mục chính, giúp bạn xây dựng các bộ dữ liệu và mô hình vững chắc. Với sự bổ sung này vào gia đình các mô hình Gemma, các nhà nghiên cứu và nhà phát triển giờ đây có thể dễ dàng giảm thiểu rủi ro về nội dung gây hại trong các mô hình của họ trên các lĩnh vực gây hại chính được định nghĩa bên dưới:
- Không có nội dung khiêu dâm: Hình ảnh không được chứa nội dung mô tả các hành vi tình dục rõ ràng hoặc mô tả chi tiết (ví dụ: khiêu dâm, khỏa thân khiêu dâm, mô tả về cưỡng hiếp hoặc tấn công tình dục).
- Không có nội dung nguy hiểm: Hình ảnh không được chứa nội dung tạo điều kiện hoặc khuyến khích các hoạt động có thể gây ra thiệt hại trong thế giới thực (ví dụ: chế tạo súng và thiết bị nổ, cổ xúy cho chủ nghĩa khủng bố, hướng dẫn tự tử).
- Không có nội dung bạo lực/máu me: Hình ảnh không được chứa nội dung mô tả bạo lực gây sốc, giật gân hoặc vô cớ (ví dụ: máu me và thương tích quá mức, bạo lực vô cớ đối với động vật, chấn thương cực độ hoặc khoảnh khắc tử vong).
Chúng tôi khuyến nghị sử dụng ShieldGemma 2 như một bộ lọc đầu vào cho các mô hình ngôn ngữ thị giác, hoặc như một bộ lọc đầu ra của các hệ thống tạo ảnh. Để huấn luyện một mô hình an toàn hình ảnh vững chắc, chúng tôi đã tuyển chọn các bộ dữ liệu huấn luyện gồm ảnh tự nhiên và ảnh tổng hợp, sau đó điều chỉnh theo hướng dẫn (instruction-tune) Gemma 3 để chứng minh hiệu suất vượt trội.
Mô hình này được đóng góp bởi Ryan Mullins.
Ví dụ sử dụng
- ShieldGemma 2 cung cấp một Processor nhận vào một danh sách
imagesvà một danh sách tùy chọnpolicies, sau đó xây dựng một batch các prompt dưới dạng tích của hai danh sách này bằng cách sử dụng chat template được cung cấp. - Bạn có thể mở rộng các chính sách tích hợp sẵn của ShieldGemma bằng cách sử dụng đối số
custom_policiescủa Processor. Việc sử dụng cùng một khóa với một trong các chính sách tích hợp sẵn sẽ ghi đè chính sách đó bằng định nghĩa tùy chỉnh của bạn. - ShieldGemma 2 không hỗ trợ các khả năng cắt ảnh được sử dụng bởi Gemma 3.
Phân loại theo các Chính sách tích hợp
import requests
from PIL import Image
from transformers import AutoProcessor, ShieldGemma2ForImageClassification
model_id = "google/shieldgemma-2-4b-it"
model = ShieldGemma2ForImageClassification.from_pretrained(model_id, device_map="auto")
processor = AutoProcessor.from_pretrained(model_id)
url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg"
image = Image.open(requests.get(url, stream=True).raw)
inputs = processor(images=[image], return_tensors="pt").to(model.device)
output = model(**inputs)
print(output.probabilities)Phân loại theo Chính sách Tùy chỉnh
import requests
from PIL import Image
from transformers import AutoProcessor, ShieldGemma2ForImageClassification
model_id = "google/shieldgemma-2-4b-it"
model = ShieldGemma2ForImageClassification.from_pretrained(model_id, device_map="auto")
processor = AutoProcessor.from_pretrained(model_id)
url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg"
image = Image.open(requests.get(url, stream=True).raw)
custom_policies = {
"key_a": "description_a",
"key_b": "description_b",
}
inputs = processor(
images=[image],
custom_policies=custom_policies,
policies=["dangerous", "key_a", "key_b"],
return_tensors="pt",
).to(model.device)
output = model(**inputs)
print(output.probabilities)ShieldGemma2Processor
lớp transformers.ShieldGemma2Processor
< source >( image_processortokenizerchat_template = Noneimage_seq_length = 256policy_definitions = None**kwargs )
__call__
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext = None**kwargs: *<class 'transformers.models.shieldgemma2.processing_shieldgemma2.ShieldGemma2ProcessorKwargs'> )
Tham số
- images — Một hình ảnh duy nhất hoặc một danh sách các hình ảnh để đưa vào lô (batch).
- text — Không được hỗ trợ.
- videos — Không được hỗ trợ.
- audio — Không được hỗ trợ.
- kwargs — Một từ điển tùy chọn chứa các tham số theo tên để cấu hình bộ xử lý. Các giá trị có thể bao gồm:
custom_policies: Các định nghĩa policy bổ sung để mở rộngself.policy_definitionsđược truyền vào constructor. Lưu ý rằngcustom_policiescó chung key vớiself.policy_definitionssẽ ghi đè lên mô tả policypolicies: (Tùy chọn) một danh sách các khóa trong từ điển kết hợpself.policy_definitions | custom_policiescụ thể được quan tâm đối với các hình ảnh được cung cấp. Nếu rỗng hoặc None, các prompt sẽ được tạo cho mọi khóa trong từ điển kết hợp.
Tạo một lô đầu vào từ các hình ảnh được cung cấp.
ShieldGemma được huấn luyện để phân loại nội dung hình ảnh nhằm tuân thủ chính sách bằng cách sử dụng một cấu trúc prompt cụ thể. Bộ xử lý này tạo ra một lô các prompt như vậy từ các hình ảnh được cung cấp bằng cách:
- Tạo một danh sách các cuộc trò chuyện, mỗi cuộc trò chuyện cho một cặp
<image, policy>; - Chuyển đổi các cuộc trò chuyện này thành văn bản bằng cách sử dụng
self.apply_chat_template(); và - Mã hóa các cuộc trò chuyện và hình ảnh bằng các kỹ thuật tương tự như
Gemma3Processor.
ShieldGemma2Config
lớp transformers.ShieldGemma2Config
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemm_tokens_per_image: int = 256boi_token_index: int = 255999eoi_token_index: int = 256000image_token_index: int = 262144initializer_range: float = 0.02tie_word_embeddings: bool = False )
Tham số
- text_config (
Union[dict, ~configuration_utils.PreTrainedConfig], tùy chọn) — Đối tượng cấu hình hoặc từ điển của bộ khung văn bản. - vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig], tùy chọn) — Đối tượng cấu hình hoặc từ điển của bộ khung thị giác. - mm_tokens_per_image (
int, tùy chọn, mặc định là 256) — Số lượng token cho mỗi nhúng ảnh. - boi_token_index (
int, tùy chọn, mặc định là 255999) — Chỉ số token bắt đầu hình ảnh để bọc xung quanh prompt hình ảnh. - eoi_token_index (
int, tùy chọn, mặc định là 256000) — Chỉ số token kết thúc hình ảnh để bao quanh prompt hình ảnh. - image_token_index (
int, tùy chọn, mặc định là262144) — Chỉ số token hình ảnh được dùng làm ký tự thay thế cho các hình ảnh đầu vào. - initializer_range (
float, tùy chọn, mặc định là0.02) — Độ lệch chuẩn của truncated_normal_initializer để khởi tạo tất cả các ma trận trọng số. - tie_word_embeddings (
bool, tùy chọn) — Có nên liên kết các nhúng từ hay không. Mặc định là giá trị củatext_config.tie_word_embeddingsnếu không được đặt.
Đây là lớp cấu hình để lưu trữ cấu hình của một Shieldgemma2Model. Nó được sử dụng để khởi tạo một mô hình Shieldgemma2 theo các đối số được chỉ định, xác định kiến trúc của mô hình. Việc khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của google/shieldgemma-2-4b-it
Các đối tượng cấu hình kế thừa từ PreTrainedConfig và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ PreTrainedConfig để biết thêm thông tin.
Ví dụ:
>>> from transformers import ShieldGemma2ForConditionalGeneration, ShieldGemma2Config, SiglipVisionConfig, ShieldGemma2TextConfig
>>> # Initializing a Siglip-like vision config
>>> vision_config = SiglipVisionConfig()
>>> # Initializing a ShieldGemma2 Text config
>>> text_config = ShieldGemma2TextConfig()
>>> # Initializing a ShieldGemma2 gemma-3-4b style configuration
>>> configuration = ShieldGemma2Config(vision_config, text_config)
>>> # Initializing a model from the gemma-3-4b style configuration
>>> model = ShieldGemma2TextConfig(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configShieldGemma2ForImageClassification
lớp transformers.ShieldGemma2ForImageClassification
< source >( config: ShieldGemma2Config )
Tham số
- config (ShieldGemma2Config) — Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức from_pretrained() để tải trọng số mô hình.
Mô hình Shieldgemma2 với đầu phân loại hình ảnh phía trên, ví dụ cho ImageNet.
Mô hình này kế thừa từ PreTrainedModel. Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu, v.v.)
Mô hình này cũng là một lớp con của torch.nn.Module trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.FloatTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonetoken_type_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs )
Tham số
- input_ids (
torch.LongTensorcó dạng(batch_size, sequence_length), tùy chọn) — Chỉ số của các token trong chuỗi đầu vào theo từ điển. Mặc định, padding sẽ bị bỏ qua.Các chỉ số có thể được lấy bằng cách sử dụng AutoTokenizer. Xem PreTrainedTokenizer.encode() và PreTrainedTokenizer.call() để biết thêm chi tiết.
- pixel_values (
torch.FloatTensorcó shape(batch_size, num_channels, image_size, image_size), tùy chọn) — Các tensor tương ứng với các ảnh đầu vào. Giá trị pixel có thể được lấy bằng cách sử dụngimage_processor_class. Xemimage_processor_class.__call__để biết chi tiết (processor_classsử dụngimage_processor_classđể xử lý ảnh). - attention_mask (
torch.Tensorcó hình dạng(batch_size, sequence_length), tùy chọn) — Mặt nạ để tránh thực hiện chú ý trên các chỉ số token đệm. Các giá trị mặt nạ được chọn trong[0, 1]:- 1 cho các token không bị che,
- 0 cho các token bị che.
- position_ids (
torch.LongTensorcó hình dạng(batch_size, sequence_length), tùy chọn) — Chỉ số vị trí của các token trong mỗi chuỗi đầu vào trong các position embeddings. Được chọn trong khoảng[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, tuỳ chọn) — Các hidden-state đã tính trước (key và value trong các khối self-attention và cross-attention) có thể được sử dụng để tăng tốc giải mã tuần tự. Điều này thường bao gồmpast_key_valuesđược trả về bởi mô hình ở một giai đoạn giải mã trước đó, khiuse_cache=Truehoặcconfig.use_cache=True.Chỉ cho phép Cache instance làm đầu vào, xem hướng dẫn kv cache của chúng tôi. Nếu không truyền
past_key_values, DynamicCache sẽ được khởi tạo theo mặc định.Mô hình sẽ xuất ra cùng định dạng cache được đưa vào làm đầu vào.
Nếu
past_key_valuesđược sử dụng, người dùng được kỳ vọng chỉ nhậpinput_idschưa được xử lý (những phần chưa có trạng thái key value quá khứ được cung cấp cho mô hình này) có hình dạng(batch_size, unprocessed_length)thay vì toàn bộinput_idscó hình dạng(batch_size, sequence_length). - token_type_ids (
torch.LongTensorcó hình dạng(batch_size, sequence_length), tùy chọn) — Chỉ số token phân đoạn để chỉ định phần đầu và phần thứ hai của đầu vào. Các chỉ số được chọn trong[0, 1]:- 0 tương ứng với một token sentence A,
- 1 tương ứng với một token sentence B.
- inputs_embeds (
torch.FloatTensorcó hình dạng(batch_size, sequence_length, hidden_size), tùy chọn) — Tùy chọn, thay vì truyềninput_ids, bạn có thể chọn truyền trực tiếp một biểu diễn nhúng. Điều này hữu ích nếu bạn muốn kiểm soát nhiều hơn cách chuyển đổi các chỉ sốinput_idsthành các vector liên quan so với ma trận tra cứu nhúng nội bộ của mô hình. - labels (
torch.LongTensorcó shape(batch_size,), tùy chọn) — Nhãn để tính loss phân loại/hồi quy ảnh. Các chỉ số phải nằm trong[0, ..., config.num_labels - 1]. Nếuconfig.num_labels == 1, loss hồi quy sẽ được tính (Mean-Square loss). Nếuconfig.num_labels > 1, loss phân loại sẽ được tính (Cross-Entropy). - use_cache (
bool, tùy chọn) — Nếu đặt thànhTrue, các trạng thái key value củapast_key_valuessẽ được trả về và có thể được sử dụng để tăng tốc quá trình giải mã (xempast_key_values). - output_attentions (
bool, tùy chọn) — Có trả về các tensor attentions của tất cả các lớp attention hay không. Xemattentionstrong phần tensor được trả về để biết thêm chi tiết. - output_hidden_states (
bool, tùy chọn) — Có trả về trạng thái ẩn (hidden states) của tất cả các lớp hay không. Xemhidden_statestrong phần tensor trả về để biết thêm chi tiết. - return_dict (
bool, tùy chọn) — Có nên trả về một ModelOutput thay vì một tuple thông thường hay không. - logits_to_keep (
Union[int, torch.Tensor], tùy chọn, mặc định là0) — Nếu làint, tính logits chologits_to_keeptoken cuối. Nếu là0, tính logits cho tất cảinput_ids(trường hợp đặc biệt). Chỉ cần logits của token cuối cho quá trình sinh, và việc chỉ tính cho token đó có thể tiết kiệm bộ nhớ, điều này trở nên khá đáng kể với các chuỗi dài hoặc kích thước từ vựng lớn. Nếu làtorch.Tensor, phải là 1 chiều tương ứng với các chỉ số cần giữ trong chiều độ dài chuỗi. Điều này hữu ích khi sử dụng định dạng tensor đóng gói (một chiều duy nhất cho batch và độ dài chuỗi).
Phương thức forward của ShieldGemma2ForImageClassification ghi đè lên phương thức đặc biệt __call__.
Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, người dùng nên gọi instance của
Modulesau đó thay vì gọi hàm này, vì instanceModulesẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ lặng lẽ bỏ qua chúng.