Transformers documentation

LLaVA-OneVision

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

نُشر هذا النموذج في أوراق HF في 2024-08-06 وسُهم به في Hugging Face Transformers في 2024-09-05.

LLaVA-OneVision

نظرة عامة

قُدِّم نموذج LLaVA-OneVision في LLaVA-OneVision: Easy Visual Task Transfer بواسطة Bo Li وYuanhan Zhang وDong Guo وRenrui Zhang وFeng Li وHao Zhang وKaichen Zhang وYanwei Li وZiwei Liu وChunyuan Li

LLaVA-OneVision هو نموذج لغة-رؤية قادر على توليد النص مشروطًا بصورة واحدة أو عدة صور/فيديوهات. يتكوّن النموذج من مشفّر رؤية SigLIP وهيكل لغوي أساسي Qwen2. تتم معالجة الصور باستخدام تقنية anyres-9 حيث تُقسَّم الصورة إلى 9 بقع لمعالجة الصور عالية الدقة بشكل أفضل ولالتقاط أكبر قدر ممكن من التفاصيل. ومع ذلك، يتم تجميع الفيديوهات إلى طول تسلسل إجمالي قدره 196 رمزًا لكل إطار لحساب أكثر كفاءة في استخدام الذاكرة. يتوفر LLaVA-OneVision بثلاثة أحجام: 0.5B و7B و72B، ويحقق أداءً ملحوظًا في تقييمات المعايير.

المستخلص من الورقة البحثية هو كالتالي:

نقدّم LLaVA-OneVision، وهو عائلة من النماذج الكبيرة متعددة الوسائط المفتوحة (LMMs) طُوِّرت من خلال توحيد رؤانا في البيانات والنماذج والتمثيلات البصرية في سلسلة مدونات LLaVA-NeXT. تُظهر نتائجنا التجريبية أن LLaVA-OneVision هو النموذج الفردي الأول الذي يمكنه في الوقت نفسه دفع حدود أداء النماذج المفتوحة متعددة الوسائط (LMMs) في ثلاثة سيناريوهات مهمة في مجال رؤية الحاسوب: سيناريو الصورة الواحدة، وسيناريو الصور المتعددة، وسيناريو الفيديو. والأهم من ذلك، أن تصميم LLaVAOneVision يتيح تعلماً انتقالياً قوياً عبر الوسائط/السيناريوهات المختلفة، مما يؤدي إلى ظهور قدرات جديدة. وبشكل خاص، يتم إظهار فهم قوي للفيديو وقدرات عبر السيناريوهات من خلال نقل المهام من الصور إلى مقاطع الفيديو.

LLaVA-OneVision architecture. Taken from the original paper.

نصائح:

ننصح المستخدمين باستخدام padding_side="left" عند حساب التوليد المجمّع، إذ يؤدي ذلك إلى نتائج أكثر دقة. ما عليك سوى التأكد من استدعاء processor.tokenizer.padding_side = "left" قبل التوليد.

تستخدم Llava-OneVision عدداً مختلفاً من البقع (patches) للصور، ولذلك يتعين عليها ملء المدخلات داخل كود النمذجة، إلى جانب عملية الملء التي تتم عند معالجة المدخلات. الإعداد الافتراضي هو "ملء من اليسار" إذا كان النموذج في وضع eval()، وإلا فهو "ملء من اليمين".

تنسيق الموجهات باستخدام قوالب المحادثة

يتم تدريب كل نقطة تحقق باستخدام تنسيق محدد للرسائل، وذلك بناءً على نموذج اللغة الكبير الأساسي. ولضمان التنسيق الصحيح، استخدم طريقة apply_chat_template الخاصة بالمعالج.

مهم:

يجب عليك بناء سجل محادثة — لن يعمل تمرير نص عادي.
يجب أن يكون كل رسالة قاموسًا يحتوي على المفاتيح "role" و"content".
يجب أن يكون "content" قائمة من القواميس الخاصة بأنماط مختلفة مثل "text" و"image".

فيما يلي مثال على كيفية هيكلة مدخلاتك. سنستخدم llava-onevision-qwen2-7b-si-hf وسجل محادثة يتضمن نصاً وصورة. يجب أن يكون كل حقل محتوى قائمة من القواميس (dicts)، على النحو التالي:

from transformers import AutoProcessor


processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-7b-si-hf")

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "text", "text": "What’s shown in this image?"},
        ],
    },
    {
        "role": "assistant",
        "content": [{"type": "text", "text": "This image shows a red stop sign."},]
    },
    {

        "role": "user",
        "content": [
            {"type": "text", "text": "Describe the image in more details."},
        ],
    },
]

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 images
print(text_prompt)
'<|im_start|>user\n<image>What is shown in this image?<|im_end|>\n<|im_start|>assistant\nPage showing the list of options.<|im_end|>'

🚀 مكافأة إضافية: إذا كنت تستخدم transformers>=4.49.0، يمكنك أيضًا الحصول على مخرجات متجهية من apply_chat_template. راجع أمثلة الاستخدام أدناه لمزيد من التفاصيل حول كيفية استخدامه.

تمت مساهمة هذا النموذج من قِبل RaushanTurganbay. يمكن العثور على الكود الأصلي هنا.

مثال على الاستخدام

استدلال صورة واحدة

إليك كيفية تحميل النموذج وتنفيذ الاستدلال بدقة نصفية (torch.float16):

import torch

from transformers import AutoProcessor, LlavaOnevisionForConditionalGeneration


processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf")
model = LlavaOnevisionForConditionalGeneration.from_pretrained(
    "llava-hf/llava-onevision-qwen2-7b-ov-hf",
    device_map="auto"
)

# prepare image and text prompt, using the appropriate prompt template
url = "https://github.com/haotian-liu/LLaVA/blob/1a91fc274d7c35a9b50b3cb29c4247ae5837ce39/images/llava_v1_5_radar.jpg?raw=true"
conversation = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": url},
            {"type": "text", "text": "What is shown in this image?"},
        ],
    },
]
inputs = processor.apply_chat_template(conversation, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt").to(model.device)
inputs = inputs.to(model.device, torch.float16)

# autoregressively complete prompt
output = model.generate(**inputs, max_new_tokens=100)
print(processor.decode(output[0], skip_special_tokens=True))
'user\n\nWhat is shown in this image?\nassistant\nThe image shows a radar chart, also known as a spider chart or a star chart, which is used to compare multiple quantitative variables. Each axis represents a different variable, and the chart is filled with'

الاستدلال على صور متعددة

يمكن لـ LLaVa-OneVision تنفيذ الاستدلال باستخدام عدة صور كمدخلات، حيث تنتمي الصور إما إلى نفس الموجه أو إلى موجهات مختلفة (في الاستدلال الدُفعي). لهذا الغرض، يجب عليك استخدام نقاط تفتيش تحمل لاحقة "ov". في حالات الصور المتعددة، نوصي باستخدام قائمة متداخلة للصور كمدخلات. وإلا، فسيتم تقسيم كل صورة إلى رقعات (patches) مما يستهلك الكثير من الذاكرة. إليك كيفية القيام بذلك:

import torch

from transformers import AutoProcessor, LlavaOnevisionForConditionalGeneration


# Load the model in half-precision
model = LlavaOnevisionForConditionalGeneration.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf", device_map="auto")
processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf")

# Prepare a batch of two prompts, where the first one is a multi-turn conversation and the second is not
conversation_1 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://www.ilankelman.org/stopsigns/australia.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ],
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "There is a red stop sign in the image."},
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"},
            {"type": "text", "text": "What about this image? How many cats do you see?"},
        ],
    },
]

conversation_2 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/microsoft/kosmos-2-patch14-224/resolve/main/snowman.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ],
    },
]

inputs = processor.apply_chat_template(
    [conversation_1, conversation_2],
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    padding=True,
    padding_side="left",
    return_tensors="pt",
).to(model.device, torch.float16)

# Generate
generate_ids = model.generate(**inputs, max_new_tokens=30)
processor.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)
['user\n\nWhat is shown in this image?\nassistant\nThere is a red stop sign in the image.\nuser\n\nWhat about this image? How many cats do you see?\nassistant\ntwo', 'user\n\nWhat is shown in this image?\nassistant\nThe image shows a whimsical scene of a snowman sitting by a campfire. The snowman is anthropomorphized, wearing a hat and']

استدلال الفيديو

يمكن لـ LLaVa-OneVision أيضاً تنفيذ الاستدلال باستخدام مقاطع الفيديو كمدخلات، حيث تُعامل إطارات الفيديو كصور متعددة. وإليك كيفية القيام بذلك:

from huggingface_hub import hf_hub_download
import torch
from transformers import AutoProcessor, LlavaOnevisionForConditionalGeneration

# Load the model in half-precision
model = LlavaOnevisionForConditionalGeneration.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf", device_map="auto")
processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-7b-ov-hf")

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": "video", "path": video_path},
            {"type": "text", "text": "Why is this video funny?"},
            ],
    },
]

inputs = processor.apply_chat_template(
    conversation,
    num_frames=8
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt"
).to(model.device, torch.float16)

out = model.generate(**inputs, max_new_tokens=60)
processor.batch_decode(out, skip_special_tokens=True, clean_up_tokenization_spaces=True)
["user\n\nWhy is this video funny?\nassistant\nThe video appears to be humorous because it shows a young child, who is wearing glasses and holding a book, seemingly reading with a serious and focused expression. The child's glasses are a bit oversized for their face, which adds a comical touch, as it's a common trope to see children wearing"]

تحسين النموذج

التكميم باستخدام bitsandbytes

يمكن تحميل النموذج بدقة 8 أو 4 بت، مما يقلل بشكل كبير من متطلبات الذاكرة مع الحفاظ على أداء النموذج الأصلي. أولاً، تأكد من تثبيت bitsandbytes عبر الأمر pip install bitsandbytes، وتأكد من أن لديك وصولاً إلى وحدة معالجة رسومية/مسرّع مدعوم من قبل المكتبة.

يخضع bitsandbytes لإعادة هيكلة لدعم واجهات خلفية متعددة تتجاوز CUDA. حالياً، نضجت تطبيقات ROCm (لوحات AMD GPU) وIntel CPU، بينما جارٍ العمل على Intel XPU، ومن المتوقع دعم Apple Silicon بحلول الربع الرابع/الربع الأول. للحصول على تعليمات التثبيت وآخر تحديثات الواجهات الخلفية، زر هذا الرابط.

نقدّر ملاحظاتكم للمساعدة في تحديد الأخطاء قبل الإطلاق الكامل! راجعوا هذه الوثائق لمزيد من التفاصيل وروابط تقديم الملاحظات.

ما عليك سوى تغيير المقطع أعلاه إلى:

from transformers import BitsAndBytesConfig, LlavaOnevisionForConditionalGeneration


# 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 = LlavaOnevisionForConditionalGeneration.from_pretrained(model_id, quantization_config=quantization_config, device_map="auto")

استخدم Flash-Attention 2 لتسريع عملية التوليد بشكل أكبر

أولاً، تأكد من تثبيت flash-attn. راجع المستودع الأصلي لـ Flash Attention لمعرفة كيفية تثبيت هذا الحزمة. ما عليك سوى تغيير المقطع أعلاه إلى:

from transformers import LlavaOnevisionForConditionalGeneration


model = LlavaOnevisionForConditionalGeneration.from_pretrained(
    model_id,
    use_flash_attention_2=True
).to(0, device_map="auto")

Transformers

LLaVA-OneVision

نظرة عامة

تنسيق الموجهات باستخدام قوالب المحادثة

مثال على الاستخدام

استدلال صورة واحدة

الاستدلال على صور متعددة

استدلال الفيديو

تحسين النموذج

التكميم باستخدام bitsandbytes

استخدم Flash-Attention 2 لتسريع عملية التوليد بشكل أكبر

LlavaOnevisionConfig

فئة transformers.LlavaOnevisionConfig

LlavaOnevisionProcessor

فئة transformers.LlavaOnevisionProcessor

__call__

LlavaOnevisionImageProcessor

فئة transformers.LlavaOnevisionImageProcessor

preprocess

LlavaOnevisionImageProcessorPil

فئة transformers.LlavaOnevisionImageProcessorPil

preprocess

LlavaOnevisionVideoProcessor

فئة transformers.LlavaOnevisionVideoProcessor

LlavaOnevisionModel

فئة transformers.LlavaOnevisionModel

forward

get_image_features

get_placeholder_mask

get_video_features

pack_image_features

LlavaOnevisionForConditionalGeneration

فئة transformers.LlavaOnevisionForConditionalGeneration

forward

get_image_features

get_video_features

call