Transformers documentation
LLaVa-NeXT-Video
이 모델은 2024-05-31에 HF papers에 게시되었으며, 2024-06-26에 Hugging Face Transformers에 기여되었습니다.
LLaVa-NeXT-Video
개요
LLaVa-NeXT-Video 모델은 Yuanhan Zhang, Bo Li, Haotian Liu, Yong Jae Lee, Liangke Gui, Di Fu, Jiashi Feng, Ziwei Liu, Chunyuan Li가 제안한 LLaVA-NeXT: A Strong Zero-shot Video Understanding Model에 소개되었습니다. LLaVa-NeXT-Video는 LLaVa-NeXT를 기반으로 비디오와 이미지 데이터셋의 혼합으로 fine-tuning을 수행하여 비디오에 대한 모델 성능을 향상시켰습니다.
LLaVA-NeXT는 AnyRes 기법을 활용하여 제로샷 환경에서도 비디오 콘텐츠 이해에 놀라운 성능을 보입니다. AnyRes 기법은 고해상도 이미지를 여러 이미지로 자연스럽게 표현합니다. 비디오는 프레임의 집합으로 볼 수 있으므로(이는 LLaVa-NeXT의 이미지 집합과 유사합니다) 이 기법은 비디오 표현으로 자연스럽게 일반화됩니다. LLaVA-NeXT의 현재 버전은 AnyRes를 활용하고, LLaVA-Next를 기반으로 비디오 데이터에 대해 감독된 미세 조정(SFT)을 수행하여 더 나은 비디오 이해 능력을 달성합니다. 해당 모델은 VideoMME 벤치에서 오픈소스 모델 중 현재 SOTA입니다.
블로그의 도입부는 다음과 같습니다:
2024년 1월 30일, 텍스트-이미지 데이터만으로 학습된 오픈소스 대규모 멀티모달 모델(LMM)인 LLaVA-NeXT를 출시했습니다. 제안된 AnyRes 기법을 통해 추론, OCR, 세계 지식 역량을 강화하여 이미지 기반 멀티모달 이해 작업 전반에서 뛰어난 성능을 보여주며, MMMU와 MathVista와 같은 여러 이미지 벤치마크에서 Gemini-Pro를 능가하는 결과를 기록했습니다.
**오늘의 탐구에서는 비디오 이해 작업 영역에서 LLaVA-NeXT의 성능을 살펴봅니다. LLaVA-NeXT가 비디오 콘텐츠 이해에서 놀라울 정도로 강력한 성능을 보인다는 점을 확인했습니다. 비디오용 LLaVA-NeXT의 현재 버전에는 다음과 같은 여러 개선 사항이 있습니다:**
- AnyRes를 활용한 제로샷 비디오 표현 기능: AnyRes 기법은 고해상도 이미지를 사전 학습된 ViT가 처리할 수 있는 여러 이미지로 자연스럽게 표현하고, 이를 연결된 시퀀스로 구성합니다. 이 기법은 비디오(여러 프레임으로 구성됨) 표현으로 자연스럽게 일반화되어, 이미지만으로 학습된 LLaVA-Next 모델이 비디오 작업에서 놀라울 정도로 뛰어난 성능을 발휘할 수 있게 합니다. 주목할 점은, LMM이 강력한 제로샷 모달리티 전이 능력을 보여준 것이 이번이 처음이라는 것입니다.
- 길이 일반화를 통한 추론은 더 긴 영상에서 성능이 향상됩니다. 선형 확장 기법은 길이 일반화를 가능하게 하여, LLaVA-NeXT가 LLM의 max_token_length 한계를 넘어 긴 영상을 효과적으로 처리할 수 있게 합니다.
- 강력한 비디오 이해 능력. (1) 위의 두 기법을 결합한 LLaVA-Next-Image는 비디오로 튜닝된 오픈소스 LMM보다 우수한 제로샷 성능을 보입니다. (2) LLaVA-Next-Video는 비디오 데이터로 LLaVA-Next-Image에 대해 추가적으로 감독된 미세 조정(SFT)을 수행하여, LLaVA-Next-Image보다 더 나은 비디오 이해 능력을 달성합니다. (3) 직접 선호 최적화(DPO)를 사용하여 모델 응답을 AI 피드백과 정렬하는 LLaVA-Next-Video-DPO는 상당한 성능 향상을 보여줍니다.
- SGLang을 활용한 효율적인 배포 및 추론. 이를 통해 비디오 작업에서 5배 더 빠른 추론이 가능하며, 백만 단위 규모의 비디오 재캡셔닝과 같이 확장성이 높은 서빙이 가능합니다. 자세한 사용 방법은 저장소의 안내를 참고하세요.**
이 모델은 RaushanTurganbay님이 기여했습니다. 원본 코드는 여기에서 찾을 수 있습니다.
사용 팁
- 배치 생성을 계산할 때
padding_side="left"를 사용하도록 권장합니다. 더 정확한 결과를 얻을 수 있기 때문입니다. 생성 전에processor.tokenizer.padding_side = "left"를 호출하도록 하세요.
- Llava-Next는 이미지마다 패치의 수가 다르기 때문에, 입력 처리 시 수행되는 패딩과 별개로 모델링 코드 내에서 입력을 패딩해야 합니다. 모델이
eval()모드에 있는 경우 기본 설정은 “left-padding”이며, 그렇지 않은 경우 “right-padding”입니다.
v4.46 이후 릴리스된 LLaVA 모델에서는
processor.patch_size = {{patch_size}},processor.num_additional_image_tokens = {{num_additional_image_tokens}},processor.vision_feature_select_strategy = {{vision_feature_select_strategy}}를 추가하는 것에 대한 경고가 발생합니다. 모델 체크포인트를 소유하고 있다면 프로세서에 해당 속성을 추가하는 것이 강력히 권장되며, 소유자가 아니라면 PR을 열어 주세요. 이 속성들을 추가하면 LLaVA는 이미지당 필요한 이미지 토큰 수를 추론하고, 토큰 수만큼<image>플레이스홀더로 텍스트를 확장하려고 시도합니다. 일반적으로 이미지당 약 500개의 토큰이 사용되므로, 텍스트가 잘리지 않도록 확인해야 합니다. 그렇지 않으면 임베딩 병합 시 실패가 발생합니다. 해당 속성은 모델 설정에서model.config.vision_config.patch_size또는model.config.vision_feature_select_strategy로 가져올 수 있습니다. 비전 백본이 CLS 토큰을 추가하는 경우num_additional_image_tokens는1이어야 하고, 비전 패치에 추가적인 것이 없는 경우0이어야 합니다.
Chat Templates를 사용하여 프롬프트 형식 지정
각 checkpoint는 기반이 되는 large language model backbone에 따라 특정 prompt 형식으로 학습됩니다. 올바른 형식을 보장하려면 processor의 apply_chat_template 메서드를 사용하세요.
중요:
- 대화 히스토리를 구성해야 합니다. 일반 문자열만 전달하면 작동하지 않습니다.
- 각 메시지는
"role"와"content"키를 가진 딕셔너리여야 합니다. "content"은"text"와"image"와 같은 다양한 모달리티에 대한 사전 목록이어야 합니다.
입력 구조를 구성하는 예시를 보여 드리겠습니다. LLaVA-NeXT-Video-7B-hf와 비디오 및 이미지 대화 기록을 사용합니다.
from transformers import LlavaNextVideoProcessor
processor = LlavaNextVideoProcessor.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf")
conversation = [
{
"role": "system",
"content": [
{"type": "text", "text": "A chat between a curious human and an artificial intelligence assistant. The assistant gives helpful, detailed, and polite answers to the human's questions."},
],
},
{
"role": "user",
"content": [
{"type": "text", "text": "What’s shown in this image?"},
{"type": "image"},
],
},
{
"role": "assistant",
"content": [{"type": "text", "text": "This image shows a red stop sign."},]
},
{
"role": "user",
"content": [
{"type": "text", "text": "Why is this video funny?"},
{"type": "video"},
],
},
]
text_prompt = processor.apply_chat_template(conversation, add_generation_prompt=True)
# Note that the template simply formats your prompt, you still have to tokenize it and obtain pixel values for your visuals
print(text_prompt)🚀 보너스: transformers>=4.49.0를 사용 중이라면 apply_chat_template에서 벡터화된 출력도 얻을 수 있습니다. 사용 방법에 대한 자세한 내용은 아래 사용 예시를 참고하세요.
사용 예시
단일 미디어 모드
모델은 이미지와 비디오를 모두 입력으로 받을 수 있습니다. 반정밀도(torch.float16) 추론을 위한 예제 코드는 다음과 같습니다:
from huggingface_hub import hf_hub_download
from transformers import LlavaNextVideoForConditionalGeneration, LlavaNextVideoProcessor
# Load the model in half-precision
model = LlavaNextVideoForConditionalGeneration.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf", device_map="auto")
processor = LlavaNextVideoProcessor.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf")
# Load the video as an np.array, sampling uniformly 8 frames (can sample more for longer videos)
video_path = hf_hub_download(repo_id="raushan-testing-hf/videos-test", filename="sample_demo_1.mp4", repo_type="dataset")
conversation = [
{
"role": "user",
"content": [
{"type": "text", "text": "Why is this video funny?"},
{"type": "video", "path": video_path},
],
},
]
inputs = processor.apply_chat_template(conversation, num_frames=8, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt").to(model.device)
out = model.generate(**inputs, max_new_tokens=60)
processor.batch_decode(out, skip_special_tokens=True, clean_up_tokenization_spaces=True)혼합 미디어 모드
모델은 이미지와 영상이 교차된 입력에서도 생성을 수행할 수 있습니다. 다만, 교차된 이미지-영상 설정으로 학습되지 않았기 때문에 성능에 영향을 미칠 수 있습니다. 아래는 혼합 미디어 입력을 사용하는 예시입니다. 위의 코드 스니펫에 다음 줄을 추가하세요:
# Generate from image and video mixed inputs
conversation = [
{
"role": "user",
"content": [
{"type": "text", "text": "How many cats are there in the image?"},
{"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"},
],
},
{
"role": "assistant",
"content": [{"type": "text", "text": "There are two cats"}],
},
{
"role": "user",
"content": [
{"type": "text", "text": "Why is this video funny?"},
{"type": "video", "path": video_path},
],
},
]
inputs = processor.apply_chat_template(conversation, num_frames=8, add_generation_prompt=True, tokenize=True, return_dict=True, padding=True, return_tensors="pt").to(model.device)
# Generate
generate_ids = model.generate(**inputs, max_length=50)
processor.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=True)
모델 최적화
메모리 효율을 위한 Bitsandbytes를 활용한 양자화
모델은 더 낮은 비트로 로드할 수 있으며, 이는 원래 모델의 성능을 유지하면서 메모리 부담을 크게 줄여 줍니다. 이를 통해 리소스가 제한된 환경에서도 효율적으로 배포할 수 있습니다.
먼저 pip install bitsandbytes을 실행하여 bitsandbytes를 설치하고, 해당 라이브러리가 지원하는 GPU/accelerator에 접근할 수 있는지 확인하세요.
bitsandbytes는 CUDA를 넘어 여러 백엔드를 지원하도록 리팩터링되고 있습니다. 현재 ROCm(AMD GPU)과 Intel CPU 구현이 성숙했으며, Intel XPU는 진행 중이고 Apple Silicon 지원은 Q4/Q1에 예정되어 있습니다. 설치 방법 및 최신 백엔드 업데이트에 대해서는 이 링크를 방문하세요.
정식 출시 전 버그를 식별하는 데 도움이 되는 여러분의 피드백을 소중히 생각합니다! 자세한 내용과 피드백 링크는 이 문서를 확인하세요.
그런 다음 아래에 표시된 대로 BitsAndBytesConfig를 추가하여 양자화된 모델을 로드하면 됩니다.
from transformers import LlavaNextVideoForConditionalGeneration
# specify how to quantize the model
quantization_config = BitsAndBytesConfig(
load_in_4bit=True,
bnb_4bit_quant_type="nf4",
bnb_4bit_compute_dtype=torch.float16,
)
model = LlavaNextVideoForConditionalGeneration.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf", quantization_config=quantization_config, device_map="auto")생성 속도 향상을 위한 Flash-Attention 2
또한, 모델 내부에서 사용되는 어텐션 메커니즘의 더 빠른 구현체인 Flash Attention을 사용하면 모델 추론 속도를 크게 높일 수 있습니다.
먼저 Flash Attention 2의 최신 버전을 설치했는지 확인하세요:
pip install -U flash-attn --no-build-isolation
또한 Flash-Attention 2와 호환되는 하드웨어가 있어야 합니다. flash attention 저장소의 공식 문서에서 자세한 내용을 확인하세요. FlashAttention-2는 모델이 torch.float16 또는 torch.bfloat16로 로드된 경우에만 사용할 수 있습니다.
Flash Attention-2를 사용하여 모델을 로드하고 실행하려면, 다음과 같이 모델을 로드할 때 attn_implementation="flash_attention_2"를 추가하면 됩니다:
from transformers import LlavaNextVideoForConditionalGeneration
model = LlavaNextVideoForConditionalGeneration.from_pretrained(
"llava-hf/LLaVA-NeXT-Video-7B-hf", ,
attn_implementation="flash_attention_2",
).to(0, device_map="auto")LlavaNextVideoConfig
클래스 transformers.LlavaNextVideoConfig
< 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 = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneimage_token_index: int = 32001video_token_index: int = 32000projector_hidden_act: str = 'gelu'vision_feature_select_strategy: typing.Literal['default', 'full'] = 'default'vision_feature_layer: int | list[int] = -2multimodal_projector_bias: bool = Truetie_word_embeddings: bool = Falseimage_grid_pinpoints: list | None = Nonespatial_pool_mode: str = 'average'spatial_pool_stride: int = 2image_seq_length: int = 576video_seq_length: int = 288 )
매개변수
- vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 비전 백본의 config 객체 또는 사전입니다. - text_config (
Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 텍스트 백본의 config 객체 또는 사전입니다. - image_token_index (
int, 선택 사항, 기본값32001) — 입력 이미지를 위한 플레이스홀더로 사용되는 이미지 토큰 인덱스입니다. - video_token_index (
int, 선택 사항, 기본값32000) — 입력 비디오를 위한 플레이스홀더로 사용되는 비디오 토큰 인덱스입니다. - projector_hidden_act (
str, 선택 사항, 기본값gelu) — 멀티모달 projector에 사용되는 활성화 함수입니다. - vision_feature_select_strategy (
Literal[default, full], 선택 사항, 기본값default) — 비전 백본에서 비전 특징을 선택하는 데 사용되는 특징 선택 전략입니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항, 기본값-2) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - multimodal_projector_bias (
bool, 선택 사항, 기본값True) — 멀티모달 projector에 bias를 사용할지 여부입니다. - tie_word_embeddings (
bool, 선택, 기본값False) — 모델의tied_weights_keys매핑에 따라 가중치 임베딩을 묶을지 여부. - image_grid_pinpoints (
List, 선택 사항, 기본값[[336, 672], [672, 336], [672, 672], [1008, 336], [336, 1008]]) — 고해상도 이미지 처리에 사용할 수 있는 해상도 목록입니다. 목록의 각 항목은(height, width)형태의 튜플 또는 리스트여야 합니다. - spatial_pool_mode (
str, 선택 사항, 기본값"average") — 비디오에 사용할 풀링 모드입니다. “average”, “max”, “conv” 중 하나를 사용할 수 있습니다. - spatial_pool_stride (
int, 선택 사항, 기본값 2) — 동영상의 풀링 레이어에서 사용되는 스트라이드입니다. - image_seq_length (
int, 선택 사항, 기본값576) — 이미지 임베딩 하나의 시퀀스 길이입니다. - video_seq_length (
int, 선택 사항, 기본값288) — 하나의 video embedding 시퀀스 길이입니다.
이것은 LlavaNextVideoModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Llava Next Video 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 llava-hf/LLaVA-NeXT-Video-7B-hf와 유사한 구성이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
예:
>>> from transformers import LlavaNextVideoForConditionalGeneration, LlavaNextVideoConfig, CLIPVisionConfig, LlamaConfig
>>> # Initializing a CLIP-vision config
>>> vision_config = CLIPVisionConfig()
>>> # Initializing a Llama config
>>> text_config = LlamaConfig()
>>> configuration = LlavaNextVideoConfig(vision_config, text_config)
>>> model = LlavaNextVideoForConditionalGeneration(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configLlavaNextVideoProcessor
클래스 transformers.LlavaNextVideoProcessor
< source >( video_processor = Noneimage_processor = Nonetokenizer = Nonechat_template = Nonepatch_size = Nonevision_feature_select_strategy = Nonevideo_token = '<video>'image_token = '<image>'num_additional_image_tokens = 0**kwargs )
매개변수
- video_processor (
LlavaNextVideoVideoProcessor) — video processor는 필수 입력값입니다. - image_processor (
LlavaNextImageProcessor) — 이미지 프로세서가 필수 입력입니다. - tokenizer (
tokenizer_class) — 토크나이저는 필수 입력값입니다. - chat_template (
str) — 채팅의 메시지 목록을 토큰화 가능한 문자열로 변환하는 Jinja 템플릿입니다. - patch_size (
int, 선택 사항) — 비전 타워의 패치 크기입니다. - vision_feature_select_strategy (
str, 선택 사항) — vision backbone에서 vision feature를 선택하는 데 사용되는 feature 선택 전략입니다. 모델의 config와 동일해야 합니다. - video_token (
str, 선택 사항, 기본값"<video>") — 비디오 위치를 나타내는 데 사용되는 특수 토큰입니다. - image_token (
str, 선택 사항, 기본값"<image>") — 이미지 위치를 나타내는 데 사용되는 특수 토큰입니다. - num_additional_image_tokens (
int, 선택 사항, 기본값 0) — CLS(+1)와 같이 이미지 임베딩에 추가되는 토큰의 수입니다. 백본에 CLS나 기타 추가 토큰이 붙지 않는 경우 이 인수를 설정할 필요가 없습니다.
비디오 프로세서, 이미지 프로세서, 토크나이저를 단일 프로세서로 묶는 LlavaNextVideoProcessor를 생성합니다.
LlavaNextVideoProcessor는 LlavaNextVideoVideoProcessor, LlavaNextImageProcessor, tokenizer_class의 모든 기능을 제공합니다. 자세한 내용은 ~LlavaNextVideoVideoProcessor, ~LlavaNextImageProcessor, ~tokenizer_class를 참고하세요.
LlavaNextVideoVideoProcessor
class transformers.LlavaNextVideoVideoProcessor
< source >( **kwargs: *<class 'transformers.processing_utils.VideosKwargs'> )
매개변수
- 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' -- 224}): 모델에 입력되는 최대 차원을 설명합니다. - default_to_square (
bool, kwargs, 선택 사항, 기본값False) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부. - 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_center_crop (
bool, kwargs, 선택, 기본값True) — 이미지를 중앙으로 크롭할지 여부. - do_pad (
bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다. - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, 기본값{'height' -- 224, 'width': 224}):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, 선택 사항, 기본값False) — 처리 전에 비디오에서 프레임을 샘플링할지, 아니면 비디오 전체를 처리할지를 결정합니다. - 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, 선택, 기본값False) — 비디오 메타데이터를 반환할지 여부입니다. 비디오 메타데이터는 비디오 길이, fps, 디코딩 백엔드 등에 대한 정보를 포함하는 객체입니다. - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:'pt': PyTorchtorch.Tensor객체를 반환합니다.'np': NumPynp.ndarray객체를 반환합니다.
- **kwargs (VideosKwargs, optional) — 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인자의 전체 목록은 TypedDict 클래스를 참조하세요.
LlavaNextVideoVideoProcessor 비디오 프로세서를 생성합니다.
LlavaNextVideoModel
class transformers.LlavaNextVideoModel
< source >( config: LlavaNextVideoConfig )
매개변수
- config (LlavaNextVideoConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
언어 모델링 헤드가 없는 비전 백본과 언어 모델로 구성된 Llava-Next 모델입니다.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneimage_sizes: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonevision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = Noneuse_cache: bool | None = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.modeling_flash_attention_utils.FlashAttentionKwargs'> ) → LlavaNextVideoModelOutputWithPast or tuple(torch.Tensor)
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- pixel_values (
torch.Tensor, shape(batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 LlavaNextImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 LlavaNextImageProcessor.call()를 참조하세요 (LlavaNextVideoProcessor는 이미지 처리에 LlavaNextImageProcessor를 사용합니다). - pixel_values_videos (
torch.Tensor, shape(batch_size, num_frames, num_channels, frame_size, frame_size), 선택 사항) — 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은 LlavaNextVideoVideoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 LlavaNextVideoVideoProcessor.call()를 참조하세요 (LlavaNextVideoProcessor는 비디오 처리에 LlavaNextVideoVideoProcessor를 사용합니다). - image_sizes (
torch.LongTensor, shape(batch_size, 2), 선택 사항) — 배치 내 각 이미지의 크기입니다. 각 이미지에 대해 (height, width) 형식입니다. - 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를 입력하지 않습니다. - inputs_embeds (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택) —input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다input_ids인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - vision_feature_select_strategy (
str, 선택 사항, 기본값"default") — 비전 백본에서 비전 특징을 선택하는 데 사용되는 특징 선택 전략입니다."default"또는"full"중 하나를 사용할 수 있습니다."default"인 경우, 비전 특징에서 CLS 토큰이 제거됩니다."full"인 경우, 전체 비전 특징이 사용됩니다. - use_cache (
bool, 선택 사항) —True로 설정하면past_key_values키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(past_key_values참조). - mm_encoder_outputs (
dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 선택 사항) — 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 딕셔너리입니다. 각 인코딩된 출력은 (pooler_output, 선택 사항:last_hidden_states, 선택 사항:hidden_states, 선택 사항:attentions)pooler_output의 형태가(batch_size, sequence_length, hidden_size)인 선택 사항)으로 구성된 튜플이며, 인코더의 멀티모달 특징을 텍스트 임베딩에 병합한 시퀀스입니다.
반환값
LlavaNextVideoModelOutputWithPast 또는 tuple(torch.Tensor)
LlavaNextVideoModelOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(LlavaNextVideoConfig)과 입력에 따라 다양한 요소를 포함합니다.
LlavaNextVideoModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.past_key_values가 사용되면,(batch_size, 1, hidden_size)형태의 시퀀스의 마지막 hidden-state만 출력됩니다.past_key_values (
Cache, 선택 사항,use_cache=True가 전달되었거나config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력
past_key_values참조).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 가중치.
image_hidden_states (
torch.Tensor, 선택 사항) — 크기가(batch_size, num_images, sequence_length, hidden_size)인torch.Tensor입니다. 비전 인코더가 생성한 모델의 image_hidden_states이며, 마지막 hidden state를 투영한 후의 값입니다.video_hidden_states (
torch.Tensor, 선택 사항) — 크기가(batch_size * num_frames, num_videos, sequence_length, hidden_size)인torch.Tensor입니다. 비전 인코더가 생성한 모델의 video_hidden_states이며, 마지막 hidden state를 투사한 후의 값입니다.
get_image_features
< source >( pixel_values: Tensorimage_sizes: Tensorvision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
매개변수
- pixel_values (
torch.Tensor, shape(batch_size, num_patches, channels, height, width)) — 입력 이미지에 해당하는 텐서입니다. - image_sizes (
torch.Tensor, shape(num_images, 2)) — 각 이미지의 실제 크기(H, W). - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - image_sizes (
torch.Tensor, shape(batch_size, 2)) — 배치 내 각 이미지의 크기입니다. 각 이미지에 대해 (height, width) 형식입니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - vision_feature_select_strategy (
str, 선택 사항) — vision backbone에서 vision feature를 선택하는 데 사용되는 feature selection 전략입니다."default"또는"full"중 하나를 사용할 수 있습니다.
반환값
BaseModelOutputWithPooling 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(LlavaNextVideoConfig)과 입력에 따라 다양한 요소를 포함합니다.
비전 타워에서 이미지 마지막 hidden states를 가져와서 멀티모달 프로젝션을 적용합니다.
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_placeholder_mask
< source >( input_ids: LongTensorinputs_embeds: Tensorimage_features: typing.Optional[torch.Tensor] = Nonevideo_features: typing.Optional[torch.Tensor] = None )
input_ids 또는 inputs_embeds에서 멀티모달 플레이스홀더 마스크를 가져오고, 플레이스홀더 토큰의 개수가 멀티모달 특징의 길이와 같은지 확인합니다. 길이가 서로 다르면 오류가 발생합니다.
get_video_features
< source >( pixel_values_videos: Tensorvision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
매개변수
- pixel_values_videos (
torch.Tensor], shape(batch_size, num_frames, channels, height, width)) — 입력 비디오에 해당하는 텐서입니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - vision_feature_select_strategy (
str, 선택 사항) — vision backbone에서 vision feature를 선택하는 데 사용되는 feature selection 전략입니다."default"또는"full"중 하나를 사용할 수 있습니다.
반환값
BaseModelOutputWithPooling 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(LlavaNextVideoConfig)과 입력에 따라 다양한 요소를 포함합니다.
비전 타워에서 비디오의 마지막 hidden states를 가져와서 멀티모달 프로젝션을 적용합니다.
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 가중치.
pack_image_features
< source >( image_featuresimage_sizesvision_feature_select_strategyimage_newline = None )
매개변수
- image_features (
list[torch.Tensor], 길이 num_images, 각 요소의 shape은(num_patches, image_length, embed_dim)) — 각 패치의 모든 시각적 특징을 포함하는 이미지 특징 텐서의 목록입니다. - image_sizes (
torch.Tensor, shape(num_images, 2)) — 각 이미지의 실제 크기(H, W). - vision_feature_select_strategy (
str) — vision backbone에서 vision feature를 선택하는 데 사용되는 feature selection 전략입니다. - image_newline (
torch.Tensor, shape(embed_dim)) — 새로운 줄 임베딩 벡터.
각 image_feature를 reshape하고, unpad한 다음, 모든 시각 벡터를 포함하는 단일 image_features 텐서로 pack합니다.
LlavaNextVideoForConditionalGeneration
클래스 transformers.LlavaNextVideoForConditionalGeneration
< source >( config: LlavaNextVideoConfig )
매개변수
- config (LlavaNextVideoConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
비전 백본과 언어 모델로 구성된 LLAVA-NeXT 모델
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneimage_sizes: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonevision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = 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'> ) → LlavaNextVideoCausalLMOutputWithPast or tuple(torch.Tensor)
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- pixel_values (
torch.Tensor, shape(batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 LlavaNextImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 LlavaNextImageProcessor.call()를 참조하세요 (LlavaNextVideoProcessor는 이미지 처리에 LlavaNextImageProcessor를 사용합니다). - pixel_values_videos (
torch.Tensor, shape(batch_size, num_frames, num_channels, frame_size, frame_size), 선택 사항) — 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은 LlavaNextVideoVideoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 LlavaNextVideoVideoProcessor.call()를 참조하세요 (LlavaNextVideoProcessor는 비디오 처리에 LlavaNextVideoVideoProcessor를 사용합니다). - image_sizes (
torch.LongTensor, shape(batch_size, 2), 선택 사항) — 배치 내 각 이미지의 크기입니다. 각 이미지에 대해 (height, width) 형식입니다. - 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를 입력하지 않습니다. - inputs_embeds (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택) —input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다input_ids인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - vision_feature_select_strategy (
str, 선택 사항) — vision backbone에서 vision feature를 선택하는 데 사용되는 feature selection 전략입니다."default"또는"full"중 하나를 사용할 수 있습니다. - labels (
torch.LongTensor, shape(batch_size, sequence_length), 선택 사항) — 마스크 언어 모델링 손실을 계산하는 데 사용되는 라벨입니다. 인덱스는[0, ..., config.vocab_size]범위 내의 값이거나 -100이어야 합니다(input_idsdocstring 참조). 인덱스가-100으로 설정된 토큰은 무시(마스크)되며, 손실은[0, ..., config.vocab_size]범위의 라벨을 가진 토큰에 대해서만 계산됩니다. - use_cache (
bool, 선택 사항) —True로 설정하면past_key_values키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(past_key_values참조). - 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)인 선택 사항)으로 구성된 튜플이며, 인코더의 멀티모달 특징을 텍스트 임베딩에 병합한 시퀀스입니다.
반환값
LlavaNextVideoCausalLMOutputWithPast 또는 tuple(torch.Tensor)
LlavaNextVideoCausalLMOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(LlavaNextVideoConfig)과 입력에 따라 다양한 요소를 포함합니다.
LlavaNextVideoForConditionalGeneration의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
loss (
torch.Tensor, shape(1,), 선택 사항,labels이 제공될 때 반환됨) — 언어 모델링 손실(다음 토큰 예측용).logits (
torch.Tensor, shape(batch_size, sequence_length, config.vocab_size)) — 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).past_key_values (
Cache, 선택 사항,use_cache=True가 전달되었거나config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력
past_key_values참조).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 가중치.
image_hidden_states (
torch.Tensor, 선택 사항) — (batch_size * num_patches, num_images, sequence_length, hidden_size) 크기의torch.Tensor입니다. 비전 인코더가 생성한 모델의 image_hidden_states이며, 마지막 hidden state를 투영한 후의 값입니다.video_hidden_states (
torch.Tensor, 선택 사항) — 크기가(batch_size * num_frames, num_videos, sequence_length, hidden_size)인torch.Tensor입니다. 비전 인코더가 생성한 모델의 video_hidden_states이며, 마지막 hidden state를 투사한 후의 값입니다.
예:
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> import av
>>> from transformers import AutoProcessor, LlavaNextVideoForConditionalGeneration
>>> def read_video_pyav(container, indices):
... '''
... Decode the video with PyAV decoder.
... Args:
... container (`av.container.input.InputContainer`): PyAV container.
... indices (`list[int]`): List of frame indices to decode.
... Returns:
... result (np.ndarray): np array of decoded frames of shape (num_frames, height, width, 3).
... '''
... frames = []
... container.seek(0)
... start_index = indices[0]
... end_index = indices[-1]
... for i, frame in enumerate(container.decode(video=0)):
... if i > end_index:
... break
... if i >= start_index and i in indices:
... frames.append(frame)
... return np.stack([x.to_ndarray(format="rgb24") for x in frames])
>>> model = LlavaNextVideoForConditionalGeneration.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf", device_map="auto")
>>> processor = AutoProcessor.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf")
>>> prompt = "USER: <video>\nWhy is this video funny? ASSISTANT:"
>>> video_path = hf_hub_download(repo_id="raushan-testing-hf/videos-test", filename="sample_demo_1.mp4", repo_type="dataset")
>>> container = av.open(video_path)
>>> # sample uniformly 8 frames from the video (model was trained with 32 frames per video, but this video is short)
>>> total_frames = container.streams.video[0].frames
>>> indices = np.arange(0, total_frames, total_frames / 8).astype(int)
>>> clip = read_video_pyav(container, indices)
>>> inputs_video = processor(text=prompt, videos=clip, return_tensors="pt").to(model.device)
>>> # load an image to generate from an image
>>> prompt = "USER:<image>\nWhat is shown in this image? ASSISTANT:"
>>> url = "https://www.ilankelman.org/stopsigns/australia.jpg"
>>> with httpx.stream("GET", url) as response:
... image = Image.open(BytesIO(response.read()))
>>> inputs_image = processor(text=prompt, images=image, return_tensors="pt").to(model.device)
>>> # Generate from video
>>> generate_ids = model.generate(**inputs_video, max_length=50)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"USER:\nWhy is this video funny? ASSISTANT: The humor in this video comes from the unexpected and endearing sight of a baby wearing glasses and (...)"
>>> # Generate from image
>>> generate_ids = model.generate(**inputs_image, max_length=30)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"USER: \nWhat's the content of the image? ASSISTANT: The image shows a red stop sign on a pole, with a traditional Chinese archway (...)"get_image_features
< source >( pixel_values: Tensorimage_sizes: Tensorvision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
매개변수
- pixel_values (
torch.Tensor, shape(batch_size, num_patches, channels, height, width)) — 입력 이미지에 해당하는 텐서입니다. - image_sizes (
torch.Tensor, shape(num_images, 2)) — 각 이미지의 실제 크기(H, W). - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - image_sizes (
torch.Tensor, shape(batch_size, 2)) — 배치 내 각 이미지의 크기입니다. 각 이미지에 대해 (height, width) 형식입니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - vision_feature_select_strategy (
str, 선택 사항) — vision backbone에서 vision feature를 선택하는 데 사용되는 feature selection 전략입니다."default"또는"full"중 하나를 사용할 수 있습니다.
반환값
BaseModelOutputWithPooling 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(LlavaNextVideoConfig)과 입력에 따라 다양한 요소를 포함합니다.
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 가중치.
예:
>>> from PIL import Image
>>> from transformers import AutoProcessor, LlavaNextVideoForConditionalGeneration
>>> model = LlavaNextVideoForConditionalGeneration.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf")
>>> processor = AutoProcessor.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf")
>>> messages = [
... {
... "role": "user", "content": [
... {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
... {"type": "text", "text": "Where is the cat standing?"},
... ]
... },
... ]
>>> inputs = processor.apply_chat_template(
... messages,
... tokenize=True,
... return_dict=True,
... return_tensors="pt",
... add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]get_video_features
< source >( pixel_values_videos: Tensorvision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
매개변수
- pixel_values_videos (
torch.Tensor], shape(batch_size, num_frames, channels, height, width)) — 입력 비디오에 해당하는 텐서입니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - vision_feature_layer (
Union[int, list[int]], 선택 사항) — 시각 특성을 선택할 레이어의 인덱스입니다. 여러 인덱스가 제공되면 해당 인덱스에 해당하는 시각 특성이 연결(concatenate)되어 시각 특성을 형성합니다. - vision_feature_select_strategy (
str, 선택 사항) — vision backbone에서 vision feature를 선택하는 데 사용되는 feature selection 전략입니다."default"또는"full"중 하나를 사용할 수 있습니다.
반환값
BaseModelOutputWithPooling 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(LlavaNextVideoConfig)과 입력에 따라 다양한 요소를 포함합니다.
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 가중치.
예:
>>> from PIL import Image
>>> from transformers import AutoProcessor, LlavaNextVideoForConditionalGeneration
>>> model = LlavaNextVideoForConditionalGeneration.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf")
>>> processor = AutoProcessor.from_pretrained("llava-hf/LLaVA-NeXT-Video-7B-hf")
>>> messages = [
... {
... "role": "user", "content": [
... {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
... {"type": "text", "text": "Where is the cat standing?"},
... ]
... },
... ]
>>> inputs = processor.apply_chat_template(
... messages,
... tokenize=True,
... return_dict=True,
... return_tensors="pt",
... add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]