Hugging Face's logo

Transformers documentation

محوّل الكامنات البايتية (BLT)

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

نُشر هذا النموذج في أوراق HF في 13 ديسمبر 2024، وأُضيف إلى مكتبة Hugging Face Transformers في 19 سبتمبر 2025.

FlashAttention SDPA

محوّل الكامنات البايتية (BLT)

نظرة عامة

قُدِّم نموذج BLT في Byte Latent Transformer: Patches Scale Better Than Tokens من قِبل Artidoro Pagnoni وRam Pasunuru وPedro Rodriguez وJohn Nguyen وBenjamin Muller وMargaret Li1 وChunting Zhou وLili Yu وJason Weston وLuke Zettlemoyer وGargi Ghosh وMike Lewis وAri Holtzman† وSrinivasan Iyer. BLT هو نموذج لغوي كبير على مستوى البايتات يحقق أداءً على مستوى الترميز (tokenization) من خلال الترقيع الديناميكي القائم على الإنتروبيا.

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

نقدّم هنا محوّل البايتات الكامنة (BLT)، وهو معمارية جديدة لنماذج اللغة على مستوى البايتات، تتطابق لأوّل مرة مع أداء نماذج اللغة المعتمدة على الترميز (tokenization) عند توسيع النطاق، مع تحسينات كبيرة في كفاءة الاستدلال (inference) والمتانة. يقوم BLT بتشفير البايتات إلى رقعات (patches) ذات أحجام ديناميكية، تعمل هذه الرقعات كوحدة الحساب الأساسية. يتم تقسيم الرقعات بناءً على إنتروبيا البايت التالي، مما يخصص المزيد من الحسابات وسعة النموذج حيث تتطلب تعقيدات البيانات المتزايدة ذلك. نعرض أول دراسة تحكّم في عدد العمليات العائمة (flop) لتوسيع النماذج على مستوى البايتات حتى 8 مليارات من المعاملات و4 تريليونات من بايتات التدريب. تُظهر نتائجنا جدوى توسيع النماذج المدربة على بايتات خام دون معجم ثابت. تتحسّن كفاءة التدريب والاستدلال معاً بسبب الاختيار الديناميكي للرقعات الطويلة عندما تكون البيانات قابلة للتنبؤ، إلى جانب تحسينات نوعية في الاستدلال المنطقي (reasoning) والتعميم على الذيل الطويل (long tail). بشكل عام، وبالنسبة لتكاليف استدلال ثابتة، يُظهر BLT توسيعاً (scaling) أفضل بكثير من النماذج المعتمدة على الترميز، من خلال زيادة حجم الرقعة وحجم النموذج في آنٍ واحد.

نصائح للاستخدام

  • بنية النموذج المزدوج: يتكون BLT من نموذجين منفصلين تم تدريبهما:

    • مُرقّع (نموذج الإنتروبيا): نموذج تحويل أصغر يتنبأ بإنتروبيا مستوى البايت لتحديد حدود الرقع وقطع المدخلات.
    • نموذج Transformer الرئيسي: النموذج الأساسي الذي يعالج البقع (patches) عبر مشفّر محلي (Local Encoder) وTransformer شامل (Global Transformer) ومفكك محلي (Local Decoder).

  • التبديل الديناميكي: يستخدم النموذج التبديل الديناميكي القائم على الإنتروبيا حيث:

    • تحصل المناطق عالية الإنتروبيا (البيانات المعقدة) على رقع أقصر مع اهتمام حسابي أكبر
    • تحصل المناطق منخفضة الإنتروبيا (البيانات القابلة للتنبؤ) على رقعات أطول من أجل الكفاءة
    • هذا يتيح للنموذج تخصيص موارد الحوسبة حيث تكون الحاجة إليها في أشدّها

  • المُشفِّر المحلي: يعالج تسلسلات البايتات باستخدام الانتباه المتقاطع مع تمثيلات البُقع

  • المحوّل العام: يعالج التمثيلات على مستوى البقع مع انتباه كامل عبر البقع

  • المفكك المحلي: يولّد المخرجات مع انتباه متقاطع يعود إلى تسلسل البايتات الأصلي

  • مجزئ على مستوى البايت: على عكس المجزئات التقليدية التي تستخدم مفردات متعلمة، يقوم مجزئ BLT ببساطة بتحويل النص إلى بايتات UTF-8 ويربط كل بايت بمعرّف رمز. لا حاجة إلى مفردات.

يمكن تحميل النموذج عبر:

<hfoption id="AutoModel"> 
from transformers import AutoModelForCausalLM, AutoTokenizer


tokenizer = AutoTokenizer.from_pretrained("itazap/blt-1b-hf")
model = AutoModelForCausalLM.from_pretrained(
    "itazap/blt-1b-hf",
    device_map="auto",
)

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

prompt = "my name is"
generated_ids = model.generate(
    **inputs, max_new_tokens=NUM_TOKENS_TO_GENERATE, do_sample=False, use_cache=False
)

print(tokenizer.decode(generated_ids[0]))
</hfoption>

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

BltConfig

فئة transformers.BltConfig

< >

( 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 = 260max_position_embeddings: int = 4096patch_in_forward: bool | None = Truepatch_size: int | None = 4patching_mode: str | None = 'entropy'patching_threshold: float | None = 1.335442066192627patching_batch_size: int | None = 1max_patch_length: int | None = Nonelocal_attention_window_len: int | None = 512cross_attn_k: int | None = 2encoder_hash_byte_group_size: list[int] | None = Noneencoder_hash_byte_group_vocab: int | None = 500002encoder_hash_byte_group_nb_functions: int | None = 1patcher_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneencoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonedecoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneglobal_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetie_word_embeddings: bool = Falseuse_cache: bool = Truepad_token_id: int | None = Nonebos_token_id: int | None = Noneeos_token_id: int | list[int] | None = Noneinitializer_range: float = 0.02rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None )

المعاملات

  • vocab_size (int، اختياري، القيمة الافتراضية 260) — حجم مفردات النموذج. يحدد عدد الرموز المختلفة التي يمكن تمثيلها بواسطة input_ids.
  • max_position_embeddings (int، اختياري، القيمة الافتراضية 4096) — أقصى طول تسلسل قد يُستخدم معه هذا النموذج.
  • patch_in_forward (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم تنفيذ التصحيح (patching) أثناء المرور الأمامي (forward pass).
  • patch_size (int، اختياري، القيمة الافتراضية 4) — حجم البقع المستخدمة في آلية التقطيع.
  • patching_mode (str، اختياري، القيمة الافتراضية "entropy") — الوضع المستخدم للتبديل (patching)، مثل التبديل القائم على الإنتروبيا.
  • patching_threshold (float، اختياري، القيمة الافتراضية 1.34) — القيمة العتبة المستخدمة لتحديد متى يجب تطبيق التصحيحات.
  • patching_batch_size (int، اختياري، القيمة الافتراضية 1) — حجم الدفعة المستخدمة أثناء عملية التصحيح.
  • max_patch_length (int، اختياري) — الحد الأقصى لطول المقاطع التي يمكن توليدها.
  • local_attention_window_len (int, اختياري، القيمة الافتراضية 512) — حجم نافذة الانتباه المحلية المستخدمة من قِبل المُشفِّر المحلي والمُفكِّك المحلي، بما يتوافق مع local_attention_window_len في نقاط التفتيش المُصدَّرة. اضبطه على None للانتباه عبر السياق السببي الكامل بدلاً من ذلك.
  • cross_attn_k (int، اختياري، القيمة الافتراضية 2) — عدد رؤوس الانتباه المتقاطع المستخدمة في النموذج.
  • encoder_hash_byte_group_size (list, اختياري) — قائمة بأحجام مجموعات البايتات المستخدمة في دالة التجزئة (hash) في المُشفِّر.
  • encoder_hash_byte_group_vocab (int، اختياري، القيمة الافتراضية 500002) — حجم المفردات لمجموعات بايتات الترميز التجزئي (hash) في المُرمِّز.
  • encoder_hash_byte_group_nb_functions (int، اختياري، القيمة الافتراضية 1) — عدد دوال التجزئة المستخدمة في تجميع بايتات المُشفِّر.
  • patcher_config (BltPatcherConfig، اختياري) — إعدادات مكوّن المُرقِّع (patcher) في النموذج.
  • encoder_config (Union[dict, ~configuration_utils.PreTrainedConfig]، اختياري) — كائن الإعداد أو قاموس العمود الفقري للترميز.
  • decoder_config (Union[dict, ~configuration_utils.PreTrainedConfig], اختياري) — كائن الإعداد أو قاموس هيكل فك الترميز.
  • global_config (BltGlobalTransformerConfig، اختياري) — إعدادات مكوّن التحوّل العام في النموذج.
  • tie_word_embeddings (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم ربط ترميزات الأوزان وفقاً لخريطة tied_weights_keys الخاصة بالنموذج.
  • use_cache (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب على النموذج إرجاع قيم المفاتيح/القيم الأخيرة للانتباه (لا تستخدمها جميع النماذج). لا ينطبق إلا إذا كان config.is_decoder=True أو إذا كان النموذج نموذجًا توليديًا يعتمد على المُفكِّك فقط.
  • pad_token_id (int, اختياري) — معرّف الرمز المستخدم للتعبئة في المفردات.
  • bos_token_id (int, اختياري) — معرّف الرمز المستخدم لبدء البث في المفردات.
  • eos_token_id (Union[int, list[int]], اختياري) — معرّف الرمز المستخدم لنهاية التدفق في المفردات.
  • initializer_range (float، اختياري، القيمة الافتراضية 0.02) — الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], اختياري) — قائمة تحتوي على معاملات التهيئة الخاصة بتضمينات RoPE. يجب أن تحتوي القائمة على قيمة لـ rope_theta، ومعاملات اختيارية تُستخدم للتوسيع في حال رغبتَ في استخدام RoPE مع max_position_embeddings أطول.

هذه فئة الإعدادات المخزنة لإعدادات نموذج BltModel. تُستخدم لاستحداث نموذج Blt وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ itazap/blt-1b-hf

ترث كائنات التهيئة من PreTrainedConfig ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ PreTrainedConfig لمزيد من المعلومات.

مثال:

>>> from transformers import BltModel, BltConfig

>>> # Initializing a Blt configuration
>>> configuration = BltConfig()

>>> # Initializing a model from the configuration
>>> model = BltModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

فئة transformers.BltModel

< >

( config: BltConfig )

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Nonepatch_lengths: typing.Optional[torch.Tensor] = 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] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )

BltForCausalLM

فئة transformers.BltForCausalLM

< >

( config: BltConfig )

المعاملات

  • config (BltConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.

نموذج Blt Text مع رأس نمذجة اللغة في الأعلى.

يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonecross_attention_states: typing.Optional[torch.LongTensor] = Nonecross_attention_mask: typing.Optional[torch.LongTensor] = Nonefull_text_row_masked_out_mask: tuple[torch.Tensor, torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → CausalLMOutputWithPast or tuple(torch.Tensor)

المعاملات

  • input_ids (torch.LongTensor بشكل (batch_size, sequence_length), اختياري) — مؤشرات رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا.

    يمكن الحصول على الفهارس باستخدام AutoTokenizer. راجع PreTrainedTokenizer.encode() و PreTrainedTokenizer.call() للتفاصيل.

    ما هي معرّفات الإدخال؟

  • attention_mask (torch.Tensor بشكل (batch_size, sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. القيم المختارة للقناع هي [0, 1]:
    • 1 للرموز التي لم تُقنَّع،
    • 0 للرموز التي تم إخفاؤها.

    ما هي أقنعة الانتباه؟

  • position_ids (torch.LongTensor بشكل (batch_size, sequence_length), اختياري) — مؤشرات مواضع رموز كل تسلسل إدخال في تضمينات المواضع. يتم اختيارها ضمن النطاق [0, config.n_positions - 1].

    ما هي معرّفات المواقع؟

  • cross_attention_states (torch.Tensor, اختياري) — مخرجات نموذج الرؤية، تُستخدم للانتباه المتقاطع. يحتوي هذا الموتر على ميزات الصورة المعالجة التي سيقوم نموذج اللغة بالانتباه إليها.
  • cross_attention_mask (torch.Tensor بشكل (batch_size, seq_length, max_num_images, max_num_tiles), اختياري) — قناع الانتباه المتقاطع (Cross-attention mask) للتحكم في التفاعل بين رموز النص وبلاطات الصور. يعرّف هذا الموتر رباعي الأبعاد أيّ بلاطات الصور يجب أن ينتبه إليها كل رمز نصي.

    لكل رمز نصي (في seq_length):

    • 1 يشير إلى أن الرمز يجب أن ينتبه إلى بلاطة الصورة المقابلة
    • يشير 0 إلى أن الرمز لا ينبغي أن ينتبه إلى بلاطة الصورة المقابلة
  • full_text_row_masked_out_mask (tuple[torch.Tensor, torch.Tensor], اختياري) — مجموعة (tuple) تحتوي على مصفوفتين (tensors) تُستخدمان لإخفاء الصفوف في آلية الانتباه المتقاطع (cross-attention):
    • للمصفوفة الأولى الشكل (batch_size, 1, seq_length, 1) وتحتوي على قيم 0 أو 1. تدل القيمة 0 على أنه يجب إخفاء الصف بأكمله للرمز النصي المقابل في مصفوفة الانتباه المتقاطع (تجاهل جميع رموز الصورة).
    • يتمتع الموتر الثاني بالشكل نفسه ويُستخدم داخليًا لتطبيق الإخفاء (masking) أثناء المرور الأمامي (forward pass) لطبقات الانتباه المتقاطع (cross-attention). يشتق هذا القناع من cross_attention_mask ويُستخدم للتعامل مع الحالات التي يجب فيها ألا ينتبه رمز نصي إلى أي رمز صورة.
  • past_key_values (~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً من past_key_values الذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندما use_cache=True أو config.use_cache=True.

    يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير past_key_values، فسيتم تهيئة DynamicCache افتراضياً.

    سيُخرج النموذج نفس صيغة الكاش التي تُمرَّر كمدخل.

    عند استخدام past_key_values، يُتوقَّع من المستخدم إدخال input_ids غير المعالجة فقط (تلك التي لم تُقدَّم حالات مفاتيحها وقيمها السابقة إلى هذا النموذج) بأبعاد (batch_size, unprocessed_length) بدلاً من جميع input_ids بأبعاد (batch_size, sequence_length).

  • inputs_embeds (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)، اختياري) — اختياريًا، بدلاً من تمرير input_ids، يمكنك اختيار تمرير تمثيل مضمّن مباشرة. وهذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارس input_ids إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.
  • labels (torch.LongTensor من الشكل (batch_size, sequence_length)، اختياري) — التسميات لحساب خسارة نمذجة اللغة المقنّعة. يجب أن تكون الفهارس ضمن [0, ..., config.vocab_size] أو -100 (انظر input_ids docstring). يتم تجاهل الرموز التي فهارسها مضبوطة على -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 لآخر logits_to_keep رموز. إذا كانت القيمة 0، يتم حساب logits لجميع input_ids (حالة خاصة). لا يُحتاج إلى logits إلا للرمز الأخير في عملية التوليد، ويمكن أن يوفر حسابها لذلك الرمز وحده ذاكرة كبيرة، وهو أمر مهم بشكل ملحوظ للتسلسلات الطويلة أو حجم المفردات الكبير. إذا كان torch.Tensor، يجب أن يكون بعدًا واحدًا (1D) ويتوافق مع الفهارس التي يجب الاحتفاظ بها في بُعد طول التسلسل. يكون هذا مفيدًا عند استخدام تنسيق المصفوفات المعبأة (packed tensor format) (بعد واحد لكل من الدفعة وطول التسلسل).

يعيد

CausalLMOutputWithPast أو tuple(torch.Tensor)

CausalLMOutputWithPast أو مجموعة (tuple) من torch.Tensor (في حال تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة تعتمد على الإعداد (BltConfig) والمدخلات.

تتجاوز طريقة BltForCausalLM الخاصة بالتقديم (forward) الطريقة الخاصة __call__.

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

  • loss (torch.Tensor of shape (1,), اختياري, يُعاد عند توفير labels) — خسارة نمذجة اللغة (لتوقع الرمز التالي).

  • logits (torch.Tensor من الشكل (batch_size, sequence_length, config.vocab_size)) — درجات التنبؤ لرأس نمذجة اللغة (درجات لكل رمز في المفردات قبل SoftMax).

  • past_key_values (Cache، اختياري، يُعاد عند تمرير use_cache=True أو عند تعيين config.use_cache=True) — إنه كائن من نوع Cache. لمزيد من التفاصيل، راجع دليل ذاكرة kv.

    تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي) يمكن استخدامها (انظر مدخل past_key_values) لتسريع فك الترميز التسلسلي.

  • hidden_states (tuple(torch.Tensor)، اختياري، يُعاد عند تمرير output_hidden_states=True أو عند تعيين config.output_hidden_states=True) — مجموعة من torch.Tensor (واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) من الشكل (batch_size, sequence_length, hidden_size).

    حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.

  • attentions (tuple(torch.Tensor)، اختياري، يُعاد عند تمرير output_attentions=True أو عند تعيين config.output_attentions=True) — مجموعة من torch.Tensor (واحدة لكل طبقة) بأبعاد (batch_size, num_heads, sequence_length, sequence_length).

    أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

مثال:

>>> from transformers import AutoTokenizer, BltForCausalLM

>>> model = BltForCausalLM.from_pretrained("itazap/blt-1b-hf")
>>> tokenizer = AutoTokenizer.from_pretrained("itazap/blt-1b-hf")

>>> prompt = "If I had to write a haiku, it would be:"
>>> inputs = tokenizer(prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, max_length=40, do_sample=True, temperature=0.6)
>>> result = tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
>>> print(result)
If I had to write a haiku, it would be: "Snowflakes gently fall" - simple, yet peaceful.
I love the idea of snowflakes gently falling, each one
Update on GitHub

←BLOOM ByT5→