Transformers documentation
ShieldGemma 2
이 모델은 2025-04-01에 HF papers에 게시되었으며, 2025-03-20에 Hugging Face Transformers에 기여되었습니다.
ShieldGemma 2
개요
ShieldGemma 2 모델은 Google의 기술 보고서에 제안되었습니다. Gemma 3를 기반으로 구축된 ShieldGemma 2는 40억(4B) 파라미터 모델로, 합성 이미지와 자연 이미지의 안전성을 주요 범주에 대해 검사하여 견고한 데이터셋과 모델을 구축하는 데 도움을 줍니다. Gemma 모델 계열에 이 모델이 추가됨에 따라, 연구자와 개발자는 아래에서 정의된 주요 유해 영역 전반에 걸쳐 모델 내 유해 콘텐츠의 위험을 쉽게 최소화할 수 있습니다:
- 성적으로 노골적인 콘텐츠 없음: 이미지는 노골적이거나 생생한 성행위를 묘사하는 콘텐츠(예: 포르노, 에로틱한 나체, 강간 또는 성폭행 묘사)를 포함해서는 안 됩니다.
- 위험한 콘텐츠 없음: 이미지는 현실 세계에서 해를 끼칠 수 있는 활동을 촉진하거나 장려하는 내용을 포함해서는 안 됩니다(예: 화기 및 폭발물 제조, 테러리즘 선전, 자살 방법 안내).
- 폭력/피해 묘사 금지: 이미지는 충격적, 선정적, 또는 과도한 폭력(예: 과도한 피와 내장 노출, 동물에 대한 불필요한 폭력, 극단적인 부상 또는 사망 장면)을 묘사하는 내용을 포함해서는 안 됩니다.
시각 언어 모델의 입력 필터 또는 이미지 생성 시스템의 출력 필터로 ShieldGemma 2 사용을 권장합니다. 견고한 이미지 안전성 모델을 학습하기 위해 자연 이미지와 합성 이미지로 구성된 학습 데이터셋을 선별하고, Gemma 3을 지시 튜닝하여 뛰어난 성능을 입증했습니다.
이 모델은 Ryan Mullins님이 기여했습니다.
사용 예시
- ShieldGemma 2는
images목록과 선택적인policies목록을 입력으로 받아, 제공된 chat template을 사용하여 이 두 목록의 곱으로 프롬프트 배치(batch)를 구성하는 Processor를 제공합니다. - Processor의
custom_policies인수를 통해 ShieldGemma의 내장 정책을 확장할 수 있습니다. 내장 정책 중 하나와 동일한 키를 사용하면 해당 정책이 사용자 정의 내용으로 덮어쓰기됩니다. - ShieldGemma 2는 Gemma 3에서 사용되는 이미지 크롭 기능을 지원하지 않습니다.
내장 정책과의 분류
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)커스텀 정책 대비 분류
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
class 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'> )
매개변수
- images — 배치에 포함할 단일 이미지 또는 이미지 목록.
- text — 지원되지 않습니다.
- videos — 지원되지 않습니다.
- audio — 지원되지 않습니다.
- kwargs — 프로세서를 구성하기 위한 선택적 키워드 인자 사전입니다. 가능한 값은 다음과 같습니다:
custom_policies: 생성자에 전달되는self.policy_definitions를 보완하는 추가 정책 정의입니다.custom_policies가self.policy_definitions와 동일한 키를 공유하는 경우, 해당 정책 설명을 덮어씁니다.policies: (선택) 제공된 이미지와 관련하여self.policy_definitions | custom_policies의 결합된 dictionary에서 특별히 관심 있는 키의 목록입니다. 비어 있거나 None인 경우, 결합된 dictionary의 모든 키에 대해 프롬프트가 생성됩니다.
제공된 이미지에서 입력 배치(batch)를 생성합니다.
ShieldGemma는 특정 프롬프트 구성을 사용하여 정책 준수 여부를 판단하기 위해 이미지 콘텐츠를 분류하도록 학습되었습니다. 이 프로세서는 제공된 이미지에서 다음과 같은 방식으로 해당 프롬프트의 배치(batch)를 생성합니다:
- 각
<image, policy>쌍에 하나씩, 대화 목록을 생성합니다; self.apply_chat_template()를 사용하여 이러한 대화를 텍스트로 변환하고Gemma3Processor와 동일한 기법을 사용하여 대화와 이미지를 인코딩합니다.
ShieldGemma2Config
class 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 )
매개변수
- text_config (
Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 텍스트 백본의 config 객체 또는 사전입니다. - vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 비전 백본의 config 객체 또는 사전입니다. - mm_tokens_per_image (
int, 선택, 기본값 256) — 이미지 임베딩당 토큰 수입니다. - boi_token_index (
int, 선택 사항, 기본값 255999) — 이미지 프롬프트를 감싸기 위한 begin-of-image 토큰 인덱스입니다. - eoi_token_index (
int, 선택 사항, 기본값 256000) — 이미지 프롬프트를 감싸기 위한 end-of-image 토큰 인덱스입니다. - image_token_index (
int, 선택 사항, 기본값262144) — 입력 이미지용으로 플레이스홀더로 사용되는 이미지 토큰 인덱스입니다. - initializer_range (
float, 선택 사항, 기본값0.02) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다. - tie_word_embeddings (
bool, 선택 사항) — 워드 임베딩을 묶을지 여부입니다. 설정되지 않은 경우text_config.tie_word_embeddings의 값을 기본값으로 사용합니다.
이것은 Shieldgemma2Model의 설정을 저장하기 위한 설정 클래스입니다. 지정된 인자에 따라 Shieldgemma2 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 설정을 인스턴스화하면 google/shieldgemma-2-4b-it과 유사한 설정이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
예:
>>> 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
class transformers.ShieldGemma2ForImageClassification
< source >( config: ShieldGemma2Config )
매개변수
- config (ShieldGemma2Config) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
ImageNet과 같은 작업에 사용할 수 있도록 이미지 분류 헤드가 위에 있는 Shieldgemma2 모델.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
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 )
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- pixel_values (
torch.FloatTensor, shape(batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은image_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은image_processor_class.__call__를 참조하세요 (processor_class는 이미지 처리에image_processor_class를 사용합니다). - attention_mask (
torch.Tensor형상이(batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요?[0, 1]:- 마스크되지 않은 토큰에 대해 1
- 마스크된 토큰에 대해 0
- position_ids (
torch.LongTensor의 shape(batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는past_key_values디코딩의 이전 단계에서 모델이 반환한use_cache=True또는config.use_cache=True.입력으로 Cache 인스턴스만 허용되며, kv cache 가이드를 참고하세요.
past_key_values가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.
past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은input_ids만 입력해야 하며, 이때의 shape은(batch_size, unprocessed_length)입니다. shape이(batch_size, sequence_length)인 전체input_ids를 입력하지 않습니다. - token_type_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 입력의 첫 번째 및 두 번째 부분을 나타내는 세그먼트 토큰 인덱스. 인덱스는[0, 1]:- 0은 sentence A 토큰에 해당합니다.
- 1은 sentence B 토큰에 해당합니다.
- inputs_embeds (
torch.FloatTensor, shape(batch_size, sequence_length, hidden_size), 선택) —input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다input_ids인덱스를 관련 벡터로 변환하는 방식에 대한 더 세밀한 제어가 필요한 경우 유용합니다. - labels (
torch.LongTensor, shape(batch_size,), 선택 사항) — 이미지 분류/회귀 손실을 계산하는 데 사용되는 라벨입니다. 인덱스는[0, ..., config.num_labels - 1]범위에 있어야 합니다.config.num_labels == 1인 경우 회귀 손실(평균 제곱 오차)이 계산되고,config.num_labels > 1인 경우 분류 손실(교차 엔트로피)이 계산됩니다. - use_cache (
bool, 선택 사항) —True로 설정하면past_key_values키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(past_key_values참조). - output_attentions (
bool, 선택 사항) — 모든 attention 레이어의 attentions 텐서를 반환할지 여부. 자세한 내용은 반환 텐서 섹션의attentions항목을 참조하세요. - output_hidden_states (
bool, 선택 사항) — 모든 레이어의 hidden states를 반환할지 여부입니다. 자세한 내용은 반환되는 텐서 중hidden_states항목을 참고하세요. - return_dict (
bool, 선택) — 일반 튜플 대신 ModelOutput를 반환할지 여부. - logits_to_keep (
Union[int, torch.Tensor], 선택 사항, 기본값0) —int인 경우, 마지막logits_to_keep토큰에 대한 logits를 계산합니다.0인 경우, 모든input_ids에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다.torch.Tensor인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 패킹된 텐서 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.
ShieldGemma2ForImageClassification의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.