Transformers documentation
HYV4VL
이 모델은 2026-11-17에 Hugging Face Transformers에 기여되었습니다.
HYV4VL
개요
HYV4VL은 HYV4 mixture-of-experts 텍스트 백본에 비전 인코더를 결합하여 이미지-텍스트 및 비디오-텍스트 생성을 지원합니다. 동적 해상도의 시각 입력을 지원하며, 다중 모달 회전 위치 임베딩(mRoPE)을 사용하여 시간 및 공간 위치를 표현합니다.
사용
예제에는 출시 전 변경될 수 있는 임시 모델 ID tencent/Hy4가 사용됩니다.
완전한 모델에는 여러 GPU가 필요합니다. 예제에서는 dense layer를 tensor parallelism으로 분할하고, expert를 expert parallelism으로 분배합니다. 이 mixture-of-experts 모델의 경우, tensor parallelism만 사용하는 것보다 효율적입니다.
예제 중 하나를 generate.py로 저장하고, GPU당 하나의 프로세스로 실행하세요. 단일 노드 할당의 경우, 사용할 GPU 수를 NUM_GPUS에 설정하고 다음을 실행하세요:
torchrun --standalone --nproc-per-node="$NUM_GPUS" generate.py멀티 노드 할당의 경우, 분산 런처의 노드 수, 노드 랭크, rendezvous 주소를 구성합니다. 모델 로딩 시 분산 실행이 초기화되고 각 랭크의 디바이스가 선택됩니다.
이미지 입력
import os
import torch
from transformers import AutoModelForImageTextToText, AutoProcessor, DistributedConfig
model_id = "tencent/Hy4"
processor = AutoProcessor.from_pretrained(model_id)
distributed_config = DistributedConfig(
tp_size=int(os.environ["WORLD_SIZE"]), # Number of devices across which the dense layers are sharded
ep_size=int(os.environ["WORLD_SIZE"]), # Number of devices across which the experts are distributed
)
model = AutoModelForImageTextToText.from_pretrained(model_id, distributed_config=distributed_config)
messages = [{
"role": "user",
"content": [
{
"type": "image",
"url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg",
},
{"type": "text", "text": "Describe this image in one sentence."},
],
}]
inputs = processor.apply_chat_template(
messages,
tokenize=True,
add_generation_prompt=True,
reasoning_effort="no_think",
return_dict=True,
return_tensors="pt",
processor_kwargs={"images_kwargs": {"device": model.device}},
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=512, do_sample=False)
if torch.distributed.get_rank() == 0:
completion = outputs[0, inputs["input_ids"].shape[1]:]
print(processor.decode(completion, skip_special_tokens=True))텍스트 전용 생성의 경우, "text" 항목만 포함된 메시지를 사용하세요.
비디오 입력
Video-file decoding requires TorchCodec and its FFmpeg runtime dependencies. This example
samples four frames; set fps=None when providing num_frames to disable the default frame rate.
import os
import torch
from transformers import AutoModelForImageTextToText, AutoProcessor, DistributedConfig
model_id = "tencent/Hy4"
processor = AutoProcessor.from_pretrained(model_id)
distributed_config = DistributedConfig(
tp_size=int(os.environ["WORLD_SIZE"]), # Number of devices across which the dense layers are sharded
ep_size=int(os.environ["WORLD_SIZE"]), # Number of devices across which the experts are distributed
)
model = AutoModelForImageTextToText.from_pretrained(model_id, distributed_config=distributed_config)
messages = [{
"role": "user",
"content": [
{
"type": "video",
"url": "https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4",
},
{"type": "text", "text": "Summarize the action in this video."},
],
}]
inputs = processor.apply_chat_template(
messages,
tokenize=True,
add_generation_prompt=True,
reasoning_effort="no_think",
return_dict=True,
return_tensors="pt",
processor_kwargs={
"videos_kwargs": {
"do_sample_frames": True,
"num_frames": 4,
"fps": None,
"device": model.device,
},
},
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=512, do_sample=False)
if torch.distributed.get_rank() == 0:
completion = outputs[0, inputs["input_ids"].shape[1]:]
print(processor.decode(completion, skip_special_tokens=True))사용 팁
- 채팅 템플릿의 기본값은
reasoning_effort="high"입니다. 직접적인 답변을 원할 경우reasoning_effort="no_think"를 사용하세요. 추론을 수행할 때는 추론 과정과 최종 답변 모두에 충분한 생성 토큰을 허용해야 합니다. - 체크포인트에서 프로세서를 로드하여 이미지 및 비디오 설정을 사용합니다. 이미지는 HunYuanVLImageProcessor를, 비디오 전처리는 HYV4VLVideoProcessor를 사용합니다.
processor_kwargs["images_kwargs"]와processor_kwargs["videos_kwargs"]를 통해 이미지와 비디오 오버라이드를 각각 별도로 전달합니다. 이미지의size["longest_edge"]는 이미지별 픽셀 예산을 나타내며, 비디오의size["longest_edge"]는 클립 전체의 픽셀 예산을 나타냅니다. 따라서 더 많은 프레임을 샘플링하면 각 프레임의 해상도가 낮아질 수 있습니다. 비디오의max_image_size["longest_edge"]는 가장 긴 변의 길이가 아니라 각 프레임의 픽셀 면적을 추가로 제한합니다.- Video 샘플링은 기본적으로 비활성화되어 있습니다.
do_sample_frames를 활성화하고num_frames또는fps중 하나를 전달하세요. 프레임 레이트 샘플링에는 소스 프레임 레이트 메타데이터가 필요합니다. - 텍스트 길이가 다른 배치의 경우
processor_kwargs["text_kwargs"]에padding=True를 전달하세요.
HYV4VLConfig
클래스 transformers.HYV4VLConfig
< 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 = Noneimage_token_id: int = 120120video_token_id: int = 120124tie_word_embeddings: bool = False )
매개변수
- text_config (
Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 텍스트 백본의 config 객체 또는 사전입니다. - vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 비전 백본의 config 객체 또는 사전입니다. - image_token_id (
int, 선택 사항, 기본값120120) — 입력 이미지용으로 플레이스홀더로 사용되는 이미지 토큰 인덱스입니다. - video_token_id (
int, 선택 사항, 기본값120124) — 입력 비디오의 플레이스홀더로 사용되는 비디오 토큰 인덱스입니다. - tie_word_embeddings (
bool, 선택, 기본값False) — 모델의tied_weights_keys매핑에 따라 가중치 임베딩을 묶을지 여부.
이것은 HYV4VLModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Hy V4 Vl 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 tencent/Hy4와 유사한 구성이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
HYV4VLTextConfig
클래스 transformers.HYV4VLTextConfig
< 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 = Nonevocab_size: int = 120832hidden_size: int = 6144intermediate_size: int = 18432moe_intermediate_size: int = 2048num_hidden_layers: int = 78num_attention_heads: int = 64num_key_value_heads: int = 32head_dim: int = 256hidden_act: str = 'silu'max_position_embeddings: int = 262144initializer_range: float = 0.006rms_norm_eps: float = 1e-05use_cache: bool = Truepad_token_id: int | None = 120002bos_token_id: int | None = 120000eos_token_id: int | list[int] | None = 120025tie_word_embeddings: bool = Falseattention_bias: bool = Falseattention_dropout: float = 0.0n_routed_experts: int = 256output_router_logits: bool = Falsen_shared_experts: int = 1num_experts_per_tok: int = 8routed_scaling_factor: float = 2.827norm_topk_prob: bool = Truen_group: int = 1topk_group: int = 1q_lora_rank: int = 2048kv_lora_rank: int = 512qk_nope_head_dim: int = 192qk_rope_head_dim: int = 64v_head_dim: int = 256mlp_layer_types: list[str] | None = Nonelayer_types: list[str] | None = Noneindex_topk: int = 2048index_head_dim: int = 128index_n_heads: int = 32indexer_types: list[str] | None = Nonehc_mult: int = 4hc_magnitude: float = 2.0hc_eps: float = 1e-06learnable_sink_init: float = 0.0swiglu_limit: float = 10.0rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None )
매개변수
- vocab_size (
int, 선택 사항, 기본값120832) — 모델의 어휘 크기입니다.input_ids로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다. - hidden_size (
int, 선택 사항, 기본값6144) — 숨겨진 표현의 차원입니다. - intermediate_size (
int, 선택 사항, 기본값18432) — MLP 표현의 차원입니다. - moe_intermediate_size (
int, 선택 사항, 기본값2048) — 라우팅된 전문가 MLP의 중간 크기입니다. - num_hidden_layers (
int, 선택 사항, 기본값78) — Transformer decoder의 숨겨진 레이어 수. - num_attention_heads (
int, 선택 사항, 기본값64) — Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다. - num_key_value_heads (
int, 선택 사항, 기본값32) — Grouped Query Attention 구현에 사용할 key_value 헤드 수입니다.num_key_value_heads=num_attention_heads인 경우 모델은 Multi Head Attention(MHA)을 사용하고,num_key_value_heads=1인 경우 모델은 Multi Query Attention(MQA)을 사용하며, 그 외에는 GQA가 사용됩니다. 멀티 헤드 체크포인트를 GQA 체크포인트로 변환할 때, 각 그룹의 key 및 value 헤드는 해당 그룹 내 모든 원래 헤드를 meanpooling하여 구성해야 합니다. 자세한 내용은 이 논문을 참고하세요. 지정되지 않으면num_attention_heads가 기본값으로 사용됩니다. - head_dim (
int, 선택 사항, 기본값256) — Attention head의 차원입니다. None인 경우 hidden_size // num_attention_heads가 기본값으로 사용됩니다. - hidden_act (
str, 선택 사항, 기본값silu) — 디코더의 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어,"gelu","relu","silu"등이 있습니다. - max_position_embeddings (
int, 선택 사항, 기본값262144) — 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다. - initializer_range (
float, 선택 사항, 기본값0.006) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다. - rms_norm_eps (
float, 선택 사항, 기본값1e-05) — rms 정규화 레이어에서 사용되는 epsilon 값입니다. - use_cache (
bool, 선택 사항, 기본값True) — 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음).config.is_decoder=True인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다. - pad_token_id (
int, 선택 사항, 기본값120002) — 어휘에서 패딩에 사용되는 토큰 ID입니다. - bos_token_id (
int, 선택 사항, 기본값120000) — 어휘에서 스트림 시작에 사용되는 토큰 ID입니다. - eos_token_id (
Union[int, list[int]], 선택 사항, 기본값120025) — 어휘에서 스트림 종료에 사용되는 토큰 ID입니다. - tie_word_embeddings (
bool, 선택, 기본값False) — 모델의tied_weights_keys매핑에 따라 가중치 임베딩을 묶을지 여부. - attention_bias (
bool, 선택 사항, 기본값False) — 자기 주의(self-attention) 시 query, key, value 및 출력 투영 계층에 bias를 사용할지 여부입니다. - attention_dropout (
float, 선택 사항, 기본값0.0) — Attention 확률에 적용할 dropout 비율입니다. - n_routed_experts (
int, 선택 사항, 기본값256) — 라우팅된 전문가의 수입니다. - output_router_logits (
bool, 선택 사항, 기본값False) — 모델이 router logits를 반환할지 여부입니다. 이 옵션을 활성화하면 load balancing loss와 router z-loss를 포함한 auxiliary loss도 출력할 수 있습니다. - n_shared_experts (
int, 선택 사항, 기본값1) — 공유 전문가의 수입니다. - num_experts_per_tok (
int, 선택 사항, 기본값8) — 각 토큰을 라우팅할 전문가의 수입니다. 이는 토큰 선택 라우팅의 top-k 값입니다. - routed_scaling_factor (
float, 선택 사항, 기본값2.827) — 라우팅된 전문가에 대한 스케일링 팩터입니다. - norm_topk_prob (
bool, 선택 사항, 기본값True) — 라우팅된 전문가의 가중치를 정규화할지 여부입니다. - n_group (
int, 선택 사항, 기본값 1) — 라우팅을 위한 전문가 그룹의 수. - topk_group (
int, 선택 사항, 기본값 1) — 라우팅 과정에서 유지되는 전문가 그룹의 수입니다. - q_lora_rank (
int, 선택 사항, 기본값2048) — 쿼리 투영에 사용되는 LoRA 행렬의 랭크입니다. - kv_lora_rank (
int, 선택 사항, 기본값512) — 키 및 값 투영에 사용되는 LoRA 행렬의 랭크입니다. - qk_nope_head_dim (
int, 선택 사항, 기본값192) — Rotary position embeddings를 사용하지 않는 query/key head의 차원입니다. - qk_rope_head_dim (
int, 선택 사항, 기본값64) — 회전 위치 임베딩을 사용하는 쿼리/키 헤드의 차원입니다. - v_head_dim (
int, 선택 사항, 기본값256) — value head의 차원입니다. - mlp_layer_types (
list[str], 선택 사항) — 레이어별 MLP 유형으로,"dense"또는"sparse"중 하나입니다. 기본값은 dense 레이어 1개 뒤에 sparse 레이어가 오는 구성입니다. - layer_types (
list[str], 선택 사항) — 각 레이어 인덱스를 해당 레이어 유형에 명시적으로 매핑하는 목록입니다. 제공되지 않으면 config 값에 기반하여 자동으로 생성됩니다. - index_topk (
int, 선택 사항, 기본값 2048) — 각 DSA 쿼리가 선택하는 최대 키 위치 수입니다. - index_head_dim (
int, 선택 사항, 기본값 128) — 각 DSA indexer 헤드의 숨겨진 차원입니다. - index_n_heads (
int, 선택 사항, 기본값 32) — DSA 인덱서 헤드 수입니다. - indexer_types (
list[str], 선택 사항) — 레이어별 DSA 인덱서 유형으로,"full"또는"shared"(이전 full 레이어의 선택을 재사용) 중 하나입니다. - hc_mult (
int, 선택 사항, 기본값 4) — iHC가 유지하는 hidden-state 채널 수입니다. - hc_magnitude (
float, 선택 사항, 기본값 2.0) — iHC post-gating branch에 적용되는 스케일입니다. - hc_eps (
float, 선택 사항, 기본값 1e-6) — iHC 시그모이드 게이트에 추가되는 수치적 epsilon입니다. - learnable_sink_init (
float, 선택 사항, 기본값 0.0) — 학습된 attention-sink logit의 초기 값입니다. - swiglu_limit (
float, 선택 사항, 기본값 10.0) — 라우팅된 전문가 SwiGLU 클램프의 크기입니다. 0 이하의 값은 클램프를 비활성화합니다. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], 선택) — RoPE 임베딩의 구성 매개변수를 포함하는 사전입니다. 사전에는rope_theta값이 포함되어야 하며, 더 긴max_position_embeddings로 RoPE를 사용하려는 경우 스케일링에 사용되는 매개변수를 선택적으로 포함할 수 있습니다.
이것은 HYV4VLModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Hy V4 Vl 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 tencent/Hy4와 유사한 구성이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
HYV4VLVisionConfig
클래스 transformers.HYV4VLVisionConfig
< 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 = Nonehidden_act: str = 'gelu'hidden_size: int = 1536intermediate_size: int = 6144interpolate_mode: str = 'bilinear'rms_norm_eps: float = 1e-05attention_dropout: float = 0.0num_attention_heads: int = 16num_key_value_heads: int | None = Nonenum_channels: int = 3num_hidden_layers: int = 40out_hidden_size: int = 6144patch_size: int = 16spatial_merge_size: int = 2max_image_size: int = 2048 )
매개변수
- hidden_act (
str, 선택 사항, 기본값gelu) — 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어,"gelu","relu","silu"등이 있습니다. - hidden_size (
int, 선택 사항, 기본값1536) — 숨겨진 표현의 차원입니다. - intermediate_size (
int, 선택 사항, 기본값6144) — MLP 표현의 차원입니다. - interpolate_mode (
str, 선택 사항, 기본값"bilinear") — 학습된 패치 위치 임베딩에 사용할 보간 모드입니다. - rms_norm_eps (
float, 선택 사항, 기본값1e-05) — rms 정규화 레이어에서 사용되는 epsilon 값입니다. - attention_dropout (
float, 선택 사항, 기본값0.0) — Attention 확률에 적용할 dropout 비율입니다. - num_attention_heads (
int, 선택 사항, 기본값16) — Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다. - num_key_value_heads (
int, 선택 사항) — Grouped Query Attention 구현에 사용할 key_value 헤드 수입니다.num_key_value_heads=num_attention_heads인 경우 모델은 Multi Head Attention(MHA)을 사용하고,num_key_value_heads=1인 경우 모델은 Multi Query Attention(MQA)을 사용하며, 그 외에는 GQA가 사용됩니다. 멀티 헤드 체크포인트를 GQA 체크포인트로 변환할 때, 각 그룹의 key 및 value 헤드는 해당 그룹 내 모든 원래 헤드를 meanpooling하여 구성해야 합니다. 자세한 내용은 이 논문을 확인하세요. 지정되지 않으면num_attention_heads가 기본값으로 사용됩니다. - num_channels (
int, 선택 사항, 기본값3) — 입력 채널의 수입니다. - num_hidden_layers (
int, 선택 사항, 기본값40) — Transformer decoder의 hidden layer 수입니다. - out_hidden_size (
int, 선택 사항, 기본값 6144) — 텍스트 백본으로 전달되는 시각적 특징의 폭입니다. - patch_size (
int, 선택 사항, 기본값16) — 각 패치의 크기(해상도)입니다. - spatial_merge_size (
int, 선택 사항, 기본값2) — 인접한 패치를 병합하여 시각 토큰의 수를 줄이는 데 사용되는 공간 병합 윈도우의 크기입니다. - max_image_size (
int, 선택 사항, 기본값 2048) — 학습된 위치 임베딩 그리드를 정의하는 데 사용되는 이미지 크기입니다.
이것은 HYV4VLModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Hy V4 Vl 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 tencent/Hy4와 유사한 구성이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
HYV4VLProcessor
클래스 transformers.HYV4VLProcessor
< source >( image_processor = Nonetokenizer = Nonevideo_processor = Nonechat_template = None**kwargs )
이미지 프로세서, 토크나이저, 비디오 프로세서를 단일 프로세서로 래핑하는 HYV4VLProcessor를 생성합니다.
HYV4VLProcessor는 HYV4VLImageProcessor, tokenizer_class, HYV4VLVideoProcessor의 모든 기능을 제공합니다. 자세한 내용은 ~HYV4VLImageProcessor, ~tokenizer_class, ~HYV4VLVideoProcessor를 참고하세요.
__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: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )
매개변수
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], 선택) — 전처리할 이미지입니다. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 사이인 이미지를 전달하는 경우do_rescale=False로 설정하세요. - text (
Union[str, list[str], list[list[str]]], 선택 사항) — 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 사전 토큰화된 입력을 전달하는 경우, 배치 입력과의 혼동을 피하기 위해is_split_into_words=True를 설정하세요. - videos (
Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]], 선택) — 전처리할 비디오입니다. 픽셀 값이 0에서 255 범위를 가지는 단일 비디오 또는 비디오 배치(batch)를 기대합니다. 픽셀 값이 0에서 1 범위를 가지는 비디오를 전달하는 경우do_rescale=False로 설정하십시오. - audio (
Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], 선택 사항) — 준비할 오디오 또는 오디오 배치입니다. 각 오디오는 NumPy 배열 또는 PyTorch 텐서일 수 있습니다. NumPy 배열/PyTorch 텐서의 경우, 각 오디오의 shape은 (C, T)여야 하며, 여기서 C는 채널 수, T는 오디오의 샘플 길이입니다. - return_mm_token_type_ids (
bool, kwargs) — 멀티모달 플레이스홀더 토큰의 위치를 나타내는 멀티모달 토큰 타입 ID를 반환할지 여부입니다. - return_text_replacement_offsets (
bool, kwargs) — 각 멀티모달 플레이스홀더와 그 대체 문자열의 문자 오프셋을 반환할지 여부입니다. - return_tensors (
str또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:'pt': PyTorchtorch.Tensor객체를 반환합니다.'np': NumPynp.ndarray객체를 반환합니다.
- **kwargs (ProcessingKwargs, 선택) — 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.
HYV4VLImageProcessor
class transformers.HYV4VLImageProcessor
< source >( **kwargs: *<class 'transformers.models.hy_v4_vl.image_processing_hy_v4_vl.HYV4VLImageProcessorKwargs'> )
매개변수
- do_convert_rgb (
bool, kwargs, 선택 사항, 기본값True) — 이미지를 RGB로 변환할지 여부. - do_resize (
bool, kwargs, 선택 사항, 기본값True) — 이미지를 리사이즈할지 여부. - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, 기본값{'shortest_edge' -- 262144, 'longest_edge': 4194304}): 모델에 입력되는 최대 차원을 설명합니다. - default_to_square (
bool, kwargs, 선택 사항, 기본값False) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부. - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) —center_crop을 적용한 후 출력 이미지의 크기. - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, 기본값3) — 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다.PILImageResamplingenum 중 하나를 사용할 수 있습니다.do_resize가True로 설정된 경우에만 효과가 있습니다. - do_rescale (
bool, kwargs, 선택, 기본값True) — 이미지를 다시 스케일링할지 여부. - rescale_factor (
float, kwargs, 선택 사항, 기본값0.00392156862745098) —do_rescale이True로 설정된 경우 이미지를 재조정(rescale)하는 데 사용할 재조정 계수입니다. - do_normalize (
bool, kwargs, 선택, 기본값True) — 이미지를 정규화할지 여부. - image_mean (
Union[float, list[float], tuple[float, ...]], kwargs, 선택, 기본값[0.48145466, 0.4578275, 0.40821073]) — 정규화에 사용할 이미지 평균입니다.do_normalize가True로 설정된 경우에만 효과가 있습니다. - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, 선택, 기본값[0.26862954, 0.26130258, 0.27577711]) — 정규화에 사용할 이미지 표준 편차입니다.do_normalize가True로 설정된 경우에만 효과가 있습니다. - do_pad (
bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다. - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할{"height": int, "width" int}크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다.pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다.do_pad=True.일 때만 적용됩니다. - do_center_crop (
bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부. - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) —ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다. - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:"channels_first"또는ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지."channels_last"또는ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지."none"또는ChannelDimension.NONE: (height, width) 형식의 이미지.
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다. - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) —'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다. - disable_grouping (
bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다. - image_seq_length (
int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다. - min_pixels (
int, kwargs, 선택 사항, 기본값512 * 512) — 이미지를 리사이즈할 때 사용할 최소 픽셀 수입니다. - max_pixels (
int, kwargs, 선택 사항, 기본값2048 * 2048) — 이미지를 리사이즈할 때 사용할 최대 픽셀 수입니다. - patch_size (
int, kwargs, 선택 사항, 기본값 16) — 비전 인코더의 공간 패치 크기입니다. - temporal_patch_size (
int, kwargs, 선택 사항, 기본값 1) — 비전 인코더의 시간적 패치 크기입니다. - merge_size (
int, kwargs, 선택 사항, 기본값 2) — vision encoder에서 llm encoder로의 merge size입니다.
HYV4VLImageProcessor 이미지 프로세서를 생성합니다.
get_number_of_image_patches
< source >( height: intwidth: intimages_kwargs: dict | None = None ) → tuple[int, int]
주어진 이미지 크기에 대해 이미지 패치의 수를 반환하는 유틸리티입니다.
참고: 이 메서드를 제거하지 마세요! vLLM이 이미지 입력 없이 패치 및 플레이스홀더의 수를 추론하는 데 사용됩니다.
seq_len, patch_dim 형태의 평면 레이아웃으로 각 이미지를 패치화하여 동적 형태의 픽셀을 연결할 수 있도록 합니다.
preprocess
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]**kwargs: *<class 'transformers.models.hy_v4_vl.image_processing_hy_v4_vl.HYV4VLImageProcessorKwargs'> ) → ~image_processing_base.BatchFeature
매개변수
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — 전처리할 이미지. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 사이인 이미지를 전달하는 경우do_rescale=False로 설정하세요. - do_convert_rgb (
bool, kwargs, 선택 사항) — 이미지를 RGB로 변환할지 여부입니다. - do_resize (
bool, kwargs, 선택) — 이미지를 리사이즈할지 여부. - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 모델의 최대 입력 차원을 설명합니다. - default_to_square (
bool, kwargs, 선택 사항) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부. - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) —center_crop을 적용한 후 출력 이미지의 크기. - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 이미지를 리사이즈할 경우 사용할 리샘플링 필터입니다. 이는PILImageResamplingenum 중 하나일 수 있습니다.do_resize가True로 설정된 경우에만 효과가 있습니다. - do_rescale (
bool, kwargs, 선택 사항) — 이미지를 다시 스케일링할지 여부입니다. - rescale_factor (
float, kwargs, optional) —do_rescale이True로 설정된 경우 이미지를 리스케일하기 위한 리스케일 팩터입니다. - do_normalize (
bool, kwargs, optional) — 이미지를 정규화할지 여부. - image_mean (
Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 평균입니다.do_normalize가True로 설정된 경우에만 효과가 있습니다. - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 표준 편차.do_normalize가True로 설정된 경우에만 효과가 있습니다. - do_pad (
bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다. - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할{"height": int, "width" int}크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다.pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다.do_pad=True.일 때만 적용됩니다. - do_center_crop (
bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부. - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) —ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다. - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:"channels_first"또는ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지."channels_last"또는ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지."none"또는ChannelDimension.NONE: (height, width) 형식의 이미지.
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다. - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) —'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다. - disable_grouping (
bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다. - image_seq_length (
int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다. - min_pixels (
int, kwargs, 선택 사항, 기본값512 * 512) — 이미지를 리사이즈할 때 사용할 최소 픽셀 수입니다. - max_pixels (
int, kwargs, 선택 사항, 기본값2048 * 2048) — 이미지를 리사이즈할 때 사용할 최대 픽셀 수입니다. - patch_size (
int, kwargs, 선택 사항, 기본값 16) — 비전 인코더의 공간 패치 크기입니다. - temporal_patch_size (
int, kwargs, 선택 사항, 기본값 1) — 비전 인코더의 시간적 패치 크기입니다. - merge_size (
int, kwargs, 선택 사항, 기본값 2) — vision encoder에서 llm encoder로의 merge size입니다.
반환값
~image_processing_base.BatchFeature
- data (
dict) — call 메서드가 반환하는 리스트/배열/텐서 딕셔너리(‘pixel_values’ 등). - tensor_type (
Union[None, str, TensorType], 선택 사항) — 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type를 지정할 수 있습니다.
리사이즈
< source >( images: torch.Tensorsize: SizeDictresample: PILImageResampling | tvF.InterpolationMode | int | Nonefactor: int**kwargs )
입력 이미지의 종횡비에 따라 동적으로 크기를 조정합니다.
HYV4VLImageProcessorPil
class transformers.HYV4VLImageProcessorPil
< source >( **kwargs: *<class 'transformers.models.hy_v4_vl.image_processing_pil_hy_v4_vl.HYV4VLImageProcessorKwargs'> )
매개변수
- do_convert_rgb (
bool, kwargs, 선택 사항, 기본값True) — 이미지를 RGB로 변환할지 여부. - do_resize (
bool, kwargs, 선택 사항, 기본값True) — 이미지를 리사이즈할지 여부. - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, 기본값{'shortest_edge' -- 262144, 'longest_edge': 4194304}): 모델에 입력되는 최대 차원을 설명합니다. - default_to_square (
bool, kwargs, 선택 사항, 기본값False) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부. - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) —center_crop을 적용한 후 출력 이미지의 크기. - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, 기본값3) — 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다.PILImageResamplingenum 중 하나를 사용할 수 있습니다.do_resize가True로 설정된 경우에만 효과가 있습니다. - do_rescale (
bool, kwargs, 선택, 기본값True) — 이미지를 다시 스케일링할지 여부. - rescale_factor (
float, kwargs, 선택 사항, 기본값0.00392156862745098) —do_rescale이True로 설정된 경우 이미지를 재조정(rescale)하는 데 사용할 재조정 계수입니다. - do_normalize (
bool, kwargs, 선택, 기본값True) — 이미지를 정규화할지 여부. - image_mean (
Union[float, list[float], tuple[float, ...]], kwargs, 선택, 기본값[0.48145466, 0.4578275, 0.40821073]) — 정규화에 사용할 이미지 평균입니다.do_normalize가True로 설정된 경우에만 효과가 있습니다. - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, 선택, 기본값[0.26862954, 0.26130258, 0.27577711]) — 정규화에 사용할 이미지 표준 편차입니다.do_normalize가True로 설정된 경우에만 효과가 있습니다. - do_pad (
bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다. - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할{"height": int, "width" int}크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다.pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다.do_pad=True.일 때만 적용됩니다. - do_center_crop (
bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부. - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) —ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다. - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:"channels_first"또는ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지."channels_last"또는ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지."none"또는ChannelDimension.NONE: (height, width) 형식의 이미지.
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다. - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) —'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다. - disable_grouping (
bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다. - image_seq_length (
int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다. - min_pixels (
int, kwargs, 선택 사항, 기본값512 * 512) — 이미지를 리사이즈할 때 사용할 최소 픽셀 수입니다. - max_pixels (
int, kwargs, 선택 사항, 기본값2048 * 2048) — 이미지를 리사이즈할 때 사용할 최대 픽셀 수입니다. - patch_size (
int, kwargs, 선택 사항, 기본값 16) — 비전 인코더의 공간 패치 크기입니다. - temporal_patch_size (
int, kwargs, 선택 사항, 기본값 1) — 비전 인코더의 시간적 패치 크기입니다. - merge_size (
int, kwargs, 선택 사항, 기본값 2) — vision encoder에서 llm encoder로의 merge size입니다.
HYV4VLImageProcessor 이미지 프로세서를 생성합니다.
get_number_of_image_patches
< source >( height: intwidth: intimages_kwargs: dict | None = None ) → tuple[int, int]
주어진 이미지 크기에 대해 이미지 패치의 수를 반환하는 유틸리티입니다.
참고: 이 메서드를 제거하지 마세요! vLLM이 이미지 입력 없이 패치 및 플레이스홀더의 수를 추론하는 데 사용됩니다.
seq_len, patch_dim 형태의 평면 레이아웃으로 각 이미지를 패치화하여 동적 형태의 픽셀을 연결할 수 있도록 합니다.
preprocess
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]**kwargs: *<class 'transformers.models.hy_v4_vl.image_processing_pil_hy_v4_vl.HYV4VLImageProcessorKwargs'> ) → ~image_processing_base.BatchFeature
매개변수
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — 전처리할 이미지. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 사이인 이미지를 전달하는 경우do_rescale=False로 설정하세요. - do_convert_rgb (
bool, kwargs, 선택 사항) — 이미지를 RGB로 변환할지 여부입니다. - do_resize (
bool, kwargs, 선택) — 이미지를 리사이즈할지 여부. - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 모델의 최대 입력 차원을 설명합니다. - default_to_square (
bool, kwargs, 선택 사항) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부. - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) —center_crop을 적용한 후 출력 이미지의 크기. - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 이미지를 리사이즈할 경우 사용할 리샘플링 필터입니다. 이는PILImageResamplingenum 중 하나일 수 있습니다.do_resize가True로 설정된 경우에만 효과가 있습니다. - do_rescale (
bool, kwargs, 선택 사항) — 이미지를 다시 스케일링할지 여부입니다. - rescale_factor (
float, kwargs, optional) —do_rescale이True로 설정된 경우 이미지를 리스케일하기 위한 리스케일 팩터입니다. - do_normalize (
bool, kwargs, optional) — 이미지를 정규화할지 여부. - image_mean (
Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 평균입니다.do_normalize가True로 설정된 경우에만 효과가 있습니다. - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 표준 편차.do_normalize가True로 설정된 경우에만 효과가 있습니다. - do_pad (
bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다. - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할{"height": int, "width" int}크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다.pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다.do_pad=True.일 때만 적용됩니다. - do_center_crop (
bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부. - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) —ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다. - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:"channels_first"또는ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지."channels_last"또는ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지."none"또는ChannelDimension.NONE: (height, width) 형식의 이미지.
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다. - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) —'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다. - disable_grouping (
bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다. - image_seq_length (
int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다. - min_pixels (
int, kwargs, 선택 사항, 기본값512 * 512) — 이미지를 리사이즈할 때 사용할 최소 픽셀 수입니다. - max_pixels (
int, kwargs, 선택 사항, 기본값2048 * 2048) — 이미지를 리사이즈할 때 사용할 최대 픽셀 수입니다. - patch_size (
int, kwargs, 선택 사항, 기본값 16) — 비전 인코더의 공간 패치 크기입니다. - temporal_patch_size (
int, kwargs, 선택 사항, 기본값 1) — 비전 인코더의 시간적 패치 크기입니다. - merge_size (
int, kwargs, 선택 사항, 기본값 2) — vision encoder에서 llm encoder로의 merge size입니다.
반환값
~image_processing_base.BatchFeature
- data (
dict) — call 메서드가 반환하는 리스트/배열/텐서 딕셔너리(‘pixel_values’ 등). - tensor_type (
Union[None, str, TensorType], 선택 사항) — 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type를 지정할 수 있습니다.
리사이즈
< source >( image: ndarraysize: SizeDictresample: PILImageResampling | int | Nonefactor: int**kwargs )
입력 이미지의 종횡비에 따라 동적으로 크기를 조정합니다.
HYV4VLVideoProcessor
class transformers.HYV4VLVideoProcessor
< source >( **kwargs: *<class 'transformers.models.hy_v4_vl.video_processing_hy_v4_vl.HYV4VLVideoProcessorInitKwargs'> )
HYV4VLVideoProcessor 비디오 프로세서를 생성합니다.
preprocess
< source >( videos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]]]**kwargs: *<class 'transformers.processing_utils.VideosKwargs'> ) → ~image_processing_base.BatchFeature
매개변수
- videos (
Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]]) — 전처리할 비디오입니다. 픽셀 값이 0에서 255 범위로 이루어진 단일 비디오 또는 비디오 배치(batch)를 기대합니다. 픽셀 값이 0에서 1 범위로 이루어진 비디오를 전달하는 경우do_rescale=False로 설정하십시오. - do_convert_rgb (
bool, kwargs, 선택 사항) — 이미지를 RGB로 변환할지 여부입니다. - do_resize (
bool, kwargs, 선택) — 이미지를 리사이즈할지 여부. - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 모델의 최대 입력 차원을 설명합니다. - default_to_square (
bool, kwargs, 선택 사항) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부. - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 이미지를 리사이즈할 경우 사용할 리샘플링 필터입니다. 이는PILImageResamplingenum 중 하나일 수 있습니다.do_resize가True로 설정된 경우에만 효과가 있습니다. - do_rescale (
bool, kwargs, 선택 사항) — 이미지를 다시 스케일링할지 여부입니다. - rescale_factor (
float, kwargs, optional) —do_rescale이True로 설정된 경우 이미지를 리스케일하기 위한 리스케일 팩터입니다. - do_normalize (
bool, kwargs, optional) — 이미지를 정규화할지 여부. - image_mean (
Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 평균입니다.do_normalize가True로 설정된 경우에만 효과가 있습니다. - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 표준 편차.do_normalize가True로 설정된 경우에만 효과가 있습니다. - do_center_crop (
bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부. - do_pad (
bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다. - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) —center_crop을 적용한 후 출력 이미지의 크기. - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) —ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다. - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:"channels_first"또는ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지."channels_last"또는ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지."none"또는ChannelDimension.NONE: (height, width) 형식의 이미지.
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다. - do_sample_frames (
bool, kwargs, 선택) — 처리 전에 비디오에서 프레임을 샘플링할지, 아니면 비디오 전체를 처리할지 여부를 지정합니다. - video_metadata (
Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — 총 길이, fps, 총 프레임 수에 대한 정보를 포함하는 비디오의 메타데이터입니다. 비디오에서 프레임을 샘플링하거나 타임스탬프를 계산하는 데 사용됩니다. 비디오를 수동으로 디코딩하여 처리하려는 경우를 제외하고는 메타데이터를 전달하지 마세요. - fps (
Annotated[int | float | None, None], kwargs) —do_sample_frames=True인 경우 초당 샘플링할 대상 프레임 수. - num_frames (
Annotated[int | None, None], kwargs) —do_sample_frames=True일 때 샘플링할 최대 프레임 수. - return_metadata (
bool, kwargs, 선택) — 비디오 메타데이터를 반환할지 여부를 지정합니다. 비디오 메타데이터는 비디오 길이, fps, 디코딩 백엔드 등에 대한 정보를 포함하는 객체입니다. - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) —'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.
반환값
~image_processing_base.BatchFeature
- data (
dict) — call 메서드가 반환하는 리스트/배열/텐서 딕셔너리(‘pixel_values’ 등). - tensor_type (
Union[None, str, TensorType], 선택 사항) — 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type를 지정할 수 있습니다.
HYV4VLVisionModel
class transformers.HYV4VLVisionModel
< source >( config: HYV4VLVisionConfig )
매개변수
- config (HYV4VLVisionConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
특정 헤드가 위에 없는 순수한 Hy V4 Vl 모델은 원시 hidden-states를 출력합니다.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( pixel_values: Tensorgrid_thw: LongTensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
매개변수
- pixel_values (
torch.Tensor, shape(num_patches, num_channels * patch_size * patch_size)) — 이미지 프로세서가 생성한 패치별 평탄화 픽셀 특징입니다. - grid_thw (
torch.LongTensor, shape(num_images, 3)) — 각 이미지의 시간, 높이, 너비 차원입니다. 각 행에는[t, h, w]패치 수가 포함됩니다.
반환값
BaseModelOutputWithPooling 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(HYV4VLConfig)과 입력에 따라 다양한 요소를 포함합니다.
HYV4VLVisionModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.pooler_output (
torch.Tensor, shape(batch_size, hidden_size)) — 보조 사전 학습 작업을 위해 사용되는 레이어들을 통해 추가 처리된 시퀀스의 첫 번째 토큰(분류 토큰)의 마지막 레이어 hidden-state입니다. 예를 들어 BERT 계열 모델의 경우, 선형 레이어와 tanh 활성화 함수를 통해 처리된 후의 분류 토큰을 반환합니다. 선형 레이어의 가중치는 사전 학습 동안 다음 문장 예측(분류) 목적 함수를 통해 학습됩니다.hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.
HYV4VLTextModel
클래스 transformers.HYV4VLTextModel
< source >( config: HYV4VLTextConfig )
매개변수
- config (HYV4VLTextConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
특정 헤드가 위에 없는 순수한 Hy V4 Vl Text Model은 원시 hidden-states를 출력합니다.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonecache: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MoeModelOutputWithPast or tuple(torch.Tensor)
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- 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]. - cache (
~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key와 value)입니다. 이는 일반적으로cache디코딩의 이전 단계에서 모델이 반환한use_cache=True또는config.use_cache=True.입력으로 Cache 인스턴스만 허용되며, kv cache guide를 참고하세요.
cache가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.
cache가 사용되는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은input_ids만, 즉(batch_size, sequence_length)모양의 모든input_ids대신(batch_size, unprocessed_length)모양의 처리되지 않은input_ids를 입력해야 합니다. - inputs_embeds (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택) —input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다input_ids인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다. - use_cache (
bool, 선택 사항) —True로 설정하면cache키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(cache참조).
반환값
MoeModelOutputWithPast 또는 tuple(torch.Tensor)
MoeModelOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(None)과 입력에 따라 다양한 요소를 포함합니다.
HYV4VLTextModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.cache (
Cache, 선택 사항,use_cache=True가 전달되거나config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록의 key와 value, 그리고
config.is_encoder_decoder=True인 경우 크로스-어텐션 블록의 key와 value)를 포함합니다(사용 방법은cache입력을 참조).hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.
router_logits (
tuple(torch.Tensor), 선택 사항,output_router_probs=True와config.add_router_probs=True가 전달되었거나config.output_router_probs=True인 경우 반환됨) — 각 레이어마다 하나씩, 모양이(batch_size, sequence_length, num_experts)인torch.Tensor의 튜플.MoE 라우터가 계산하는 softmax 적용 후의 원시 라우터 로짓(raw router logits)입니다. 이 값들은 Mixture of Experts 모델의 보조 손실(auxiliary loss)을 계산하는 데 사용됩니다.
HYV4VLModel
클래스 transformers.HYV4VLModel
< source >( config: HYV4VLConfig )
매개변수
- config (HYV4VLConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
특정 헤드가 위에 없는 순수한 Hy V4 Vl 모델은 원시 hidden-states를 출력합니다.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonecache: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonepixel_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneimage_grid_thw: typing.Optional[torch.LongTensor] = Nonevideo_grid_thw: typing.Optional[torch.LongTensor] = Nonemm_token_type_ids: typing.Optional[torch.IntTensor] = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPast or tuple(torch.Tensor)
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- 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]. - cache (
~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key와 value)입니다. 이는 일반적으로cache디코딩의 이전 단계에서 모델이 반환한use_cache=True또는config.use_cache=True.입력으로 Cache 인스턴스만 허용되며, kv cache guide를 참고하세요.
cache가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.
cache가 사용되는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은input_ids만, 즉(batch_size, sequence_length)모양의 모든input_ids대신(batch_size, unprocessed_length)모양의 처리되지 않은input_ids를 입력해야 합니다. - inputs_embeds (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택) —input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다input_ids인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다. - use_cache (
bool, 선택 사항) —True로 설정하면cache키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(cache참조). - pixel_values (
torch.Tensor, shape(batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은image_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은image_processor_class.__call__를 참조하세요 (processor_class는 이미지 처리에image_processor_class를 사용합니다). - pixel_values_videos (
torch.Tensor, shape(batch_size, num_frames, num_channels, frame_size, frame_size), 선택 사항) — 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은video_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은video_processor_class.__call__를 참조하세요 (processor_class는 비디오 처리에video_processor_class를 사용합니다). - image_grid_thw (
torch.LongTensor, shape(num_images, 3), 선택 사항) — LLM에서 각 이미지의 feature shape에 대한 시간, 높이, 너비입니다. - video_grid_thw (
torch.LongTensor, shape(num_videos, 3), 선택 사항) — LLM에서 각 비디오의 feature shape에 해당하는 시간, 높이, 너비입니다. - mm_token_type_ids (
torch.IntTensor, shape(batch_size, sequence_length), 선택 사항) — 각 모달리티와 일치하는 입력 시퀀스 토큰의 인덱스입니다. 예를 들어 텍스트(0), 이미지(1), 비디오(2) 등이 있습니다. 멀티모달 토큰 타입 ID는 AutoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 ProcessorMixin.call()를 참조하세요. - mm_encoder_outputs (
dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 선택 사항) — 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 딕셔너리입니다. 각 인코딩된 출력은 (pooler_output, 선택 사항:last_hidden_states, 선택 사항:hidden_states, 선택 사항:attentions)pooler_output의 형태가(batch_size, sequence_length, hidden_size)인 선택 사항)으로 구성된 튜플이며, 인코더의 멀티모달 특징을 텍스트 임베딩에 병합한 시퀀스입니다.
반환값
BaseModelOutputWithPast 또는 tuple(torch.Tensor)
None 및 입력에 따라 구성이 달라지는 여러 요소로 구성된 BaseModelOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되거나 config.return_dict=False인 경우).
HYV4VLModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.cache가 사용되면(batch_size, 1, hidden_size)모양의 시퀀스의 마지막 hidden-state만 출력됩니다.cache (
Cache, 선택 사항,use_cache=True가 전달되거나config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록의 key와 value, 그리고
config.is_encoder_decoder=True인 경우 크로스-어텐션 블록의 key와 value)를 포함합니다(사용 방법은cache입력을 참조).hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.
get_image_features
< source >( pixel_values: Tensorimage_grid_thw: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
매개변수
- pixel_values (
torch.Tensor, shape(batch_size, num_channels, image_size, image_size)) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 HYV4VLImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 HYV4VLImageProcessor.call()를 참조하세요 (HYV4VLProcessor는 이미지 처리에 HYV4VLImageProcessor를 사용합니다). - image_grid_thw (
torch.LongTensor, shape(num_images, 3), 선택 사항) — LLM에서 각 이미지의 feature shape에 대한 시간, 높이, 너비입니다.
반환값
BaseModelOutputWithPooling 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(HYV4VLConfig)과 입력에 따라 다양한 요소를 포함합니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.pooler_output (
torch.Tensor, shape(batch_size, hidden_size)) — 보조 사전 학습 작업을 위해 사용되는 레이어들을 통해 추가 처리된 시퀀스의 첫 번째 토큰(분류 토큰)의 마지막 레이어 hidden-state입니다. 예를 들어 BERT 계열 모델의 경우, 선형 레이어와 tanh 활성화 함수를 통해 처리된 후의 분류 토큰을 반환합니다. 선형 레이어의 가중치는 사전 학습 동안 다음 문장 예측(분류) 목적 함수를 통해 학습됩니다.hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.
get_video_features
< source >( pixel_values_videos: Tensorvideo_grid_thw: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
매개변수
- pixel_values_videos (
torch.Tensor, shape(batch_size, num_frames, num_channels, frame_size, frame_size)) — 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은 HYV4VLVideoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 HYV4VLVideoProcessor.call()를 참조하세요 (HYV4VLProcessor는 비디오 처리에 HYV4VLVideoProcessor를 사용합니다). - video_grid_thw (
torch.LongTensor, shape(num_videos, 3), 선택 사항) — LLM에서 각 비디오의 feature shape에 해당하는 시간, 높이, 너비입니다.
반환값
BaseModelOutputWithPooling 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(HYV4VLConfig)과 입력에 따라 다양한 요소를 포함합니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.pooler_output (
torch.Tensor, shape(batch_size, hidden_size)) — 보조 사전 학습 작업을 위해 사용되는 레이어들을 통해 추가 처리된 시퀀스의 첫 번째 토큰(분류 토큰)의 마지막 레이어 hidden-state입니다. 예를 들어 BERT 계열 모델의 경우, 선형 레이어와 tanh 활성화 함수를 통해 처리된 후의 분류 토큰을 반환합니다. 선형 레이어의 가중치는 사전 학습 동안 다음 문장 예측(분류) 목적 함수를 통해 학습됩니다.hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.
HYV4VLForConditionalGeneration
클래스 transformers.HYV4VLForConditionalGeneration
< source >( config: HYV4VLConfig )
매개변수
- config (HYV4VLConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
다른 모달리티(예: 이미지-텍스트-텍스트 생성)에 조건부 설정된 토큰 생성을 위한 Hy V4 Vl 모델.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonecache: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonepixel_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneimage_grid_thw: typing.Optional[torch.LongTensor] = Nonevideo_grid_thw: typing.Optional[torch.LongTensor] = Nonemm_token_type_ids: typing.Optional[torch.IntTensor] = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MoeCausalLMOutputWithPast or tuple(torch.Tensor)
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- 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]. - cache (
~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key와 value)입니다. 이는 일반적으로cache디코딩의 이전 단계에서 모델이 반환한use_cache=True또는config.use_cache=True.입력으로 Cache 인스턴스만 허용되며, kv cache guide를 참고하세요.
cache가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.
cache가 사용되는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은input_ids만, 즉(batch_size, sequence_length)모양의 모든input_ids대신(batch_size, unprocessed_length)모양의 처리되지 않은input_ids를 입력해야 합니다. - inputs_embeds (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택) —input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다input_ids인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다. - labels (
torch.LongTensor, shape(batch_size, sequence_length), 선택 사항) — 마스크 언어 모델링 손실을 계산하는 데 사용되는 라벨입니다. 인덱스는[0, ..., config.vocab_size]범위 내의 값이거나 -100이어야 합니다(input_idsdocstring 참조). 인덱스가-100으로 설정된 토큰은 무시(마스크)되며, 손실은[0, ..., config.vocab_size]범위의 라벨을 가진 토큰에 대해서만 계산됩니다. - use_cache (
bool, 선택 사항) —True로 설정하면cache키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(cache참조). - pixel_values (
torch.Tensor, shape(batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은image_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은image_processor_class.__call__를 참조하세요 (processor_class는 이미지 처리에image_processor_class를 사용합니다). - pixel_values_videos (
torch.Tensor, shape(batch_size, num_frames, num_channels, frame_size, frame_size), 선택 사항) — 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은video_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은video_processor_class.__call__를 참조하세요 (processor_class는 비디오 처리에video_processor_class를 사용합니다). - image_grid_thw (
torch.LongTensor, shape(num_images, 3), 선택 사항) — LLM에서 각 이미지의 feature shape에 대한 시간, 높이, 너비입니다. - video_grid_thw (
torch.LongTensor, shape(num_videos, 3), 선택 사항) — LLM에서 각 비디오의 feature shape에 해당하는 시간, 높이, 너비입니다. - mm_token_type_ids (
torch.IntTensor, shape(batch_size, sequence_length), 선택 사항) — 각 모달리티와 일치하는 입력 시퀀스 토큰의 인덱스입니다. 예를 들어 텍스트(0), 이미지(1), 비디오(2) 등이 있습니다. 멀티모달 토큰 타입 ID는 AutoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 ProcessorMixin.call()를 참조하세요. - logits_to_keep (
Union[int, torch.Tensor], 선택 사항, 기본값0) —int인 경우, 마지막logits_to_keep토큰에 대한 logits를 계산합니다.0인 경우, 모든input_ids에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다.torch.Tensor인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 패킹된 텐서 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다. - mm_encoder_outputs (
dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 선택 사항) — 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 딕셔너리입니다. 각 인코딩된 출력은 (pooler_output, 선택 사항:last_hidden_states, 선택 사항:hidden_states, 선택 사항:attentions)pooler_output의 형태가(batch_size, sequence_length, hidden_size)인 선택 사항)으로 구성된 튜플이며, 인코더의 멀티모달 특징을 텍스트 임베딩에 병합한 시퀀스입니다.
반환값
MoeCausalLMOutputWithPast 또는 tuple(torch.Tensor)
MoeCausalLMOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(None)과 입력에 따라 다양한 요소를 포함합니다.
HYV4VLForConditionalGeneration의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
loss (
torch.Tensor, shape(1,), 선택 사항,labels이 제공될 때 반환됨) — 언어 모델링 손실(다음 토큰 예측용).logits (
torch.Tensor, shape(batch_size, sequence_length, config.vocab_size)) — 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).aux_loss (
torch.Tensor, 선택 사항,output_router_logits=True가 전달되거나config.output_router_logits=True인 경우, 그리고 모델이 로드 밸런싱 손실로 라우터를 학습하는 경우 반환됨) — 희소 모듈에 대한 로드 밸런싱 보조 손실입니다. 대신 라우터 바이어스로 전문가를 균형 맞추는 모델(DeepSeek-V3 및 이를 기반으로 파생된 아키텍처)은router_logits를 반환하되 여기서는None을 반환합니다.router_logits (
tuple(torch.Tensor), 선택 사항,output_router_logits=True가 전달되거나config.output_router_logits=True인 경우 반환됨) —torch.Tensor의 튜플(스파스 레이어마다 하나)로, 형태는(batch_size * sequence_length, num_experts)입니다.MoE 라우터가 계산한 원시 라우터 로짓입니다. 로드 밸런싱 손실을 계산하거나 토큰이 전문가로 어떻게 분배되는지 확인하는 데 사용할 수 있습니다.
cache (
Cache, 선택 사항,use_cache=True가 전달되거나config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력
cache참조).hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.
예:
>>> import os
>>> from transformers import AutoProcessor, DistributedConfig, HYV4VLForConditionalGeneration
>>> model_path = "tencent/Hy4" # Tentative release identifier.
>>> world_size = int(os.environ["WORLD_SIZE"])
>>> processor = AutoProcessor.from_pretrained(model_path)
>>> model = HYV4VLForConditionalGeneration.from_pretrained(
... model_path, distributed_config=DistributedConfig(tp_size=world_size, ep_size=world_size),
... )
>>> messages = [
... {
... "role": "user",
... "content": [
... {"type": "image", "image": "path/to/your/image.jpg"},
... {"type": "text", "text": "Describe this image."},
... ],
... }
... ]
>>> inputs = processor.apply_chat_template(
... messages, tokenize=True, add_generation_prompt=True, reasoning_effort="no_think",
... return_tensors="pt", return_dict=True,
... ).to(model.device)
>>> generated_ids = model.generate(**inputs, max_new_tokens=512, do_sample=False)
>>> generated_trimmed = generated_ids[0][inputs["input_ids"].shape[-1]:]
>>> print(processor.decode(generated_trimmed, skip_special_tokens=True))