توليد توثيق الدوال تلقائيًا

يولّد المُزيِّن @auto_docstring سلاسل توثيق متسقة لفئات النماذج وطرقها. فهو يستورد أوصاف المعايير القياسية تلقائيًا، لذا عليك كتابة التوثيق للمعايير الجديدة أو المخصصة فقط. عند إضافة نموذج جديد، تجاوز الكتابة الروتينية وركّز على ما هو جديد.

@auto_docstring

استورد المُزيّن (decorator) في ملف modular_model.py (أو modeling_model.py للنماذج الأقدم).

from ...utils import auto_docstring

إذا كان نموذجك يرث من نموذج مكتبة أخرى في ملفٍ مُعَدّ، فإن @auto_docstring مُطبَّق بالفعل في النموذج الأب. ينسخ make fix-repo ذلك إلى الملف المُولَّد modeling_model.py نيابةً عنك. طبّق المُزيِّن صراحةً فقط لتخصيص سلوكه (النماذج المستقلة، أو التمهيدات المخصصة، أو الحُجج المُعاد تعريفها).

عند تجاوز أي مُزيِّن في ملفٍ مُقسَّم، شمل جميع المُزيِّنات من الدالة أو الفئة الأصلية. إذا تجاوزت بعضها فقط، فلن تظهر البقية في ملف النمذجة المُولَّد.

يقبل المُزيِّن (decorator) الحُجُج الاختيارية التالية:

الاستخدام

يعتمد عمل @auto_docstring على ما تقوم بتزيينه. ففئات النماذج تستخرج توثيق المعاملات من __init__، بينما تستخرج فئات الإعدادات من التعليقات على مستوى الفئة، وتولّد فئات المعالجين تلقائيًا تعريفات من مكوّناتها، وتحصل الدوال مثل forward على أنواع الإرجاع وأمثلة الاستخدام.

فئات النماذج

ضع @auto_docstring مباشرةً فوق تعريف الفئة. يستخرج المُزيِّن أوصاف المعاملات من توقيع وطريقة التوثيق الخاصة بالطريقة __init__.

from transformers.modeling_utils import PreTrainedModel
from ...utils import auto_docstring

@auto_docstring
class MyAwesomeModel(PreTrainedModel):
    def __init__(self, config, custom_parameter: int = 10, another_custom_arg: str = "default"):
        r"""
        custom_parameter (`int`, *optional*, defaults to 10):
            Description of the custom_parameter for MyAwesomeModel.
        another_custom_arg (`str`, *optional*, defaults to "default"):
            Documentation for another unique argument.
        """
        super().__init__(config)
        self.custom_parameter = custom_parameter
        self.another_custom_arg = another_custom_arg
        # ... rest of your init

    # ... other methods

مرّر custom_intro وcustom_args للحصول على مزيد من التحكم. يمكن وضع الحُجج المخصّصة في custom_args أو في سطر التوثيق الخاص بـ__init__. استخدم custom_args عندما تتكرر الحُجج نفسها عبر عدة طرق.

@auto_docstring(
    custom_intro="""This model performs specific synergistic operations.
    It builds upon the standard Transformer architecture with unique modifications.""",
    custom_args="""
    custom_parameter (`type`, *optional*, defaults to `default_value`):
        A concise description for custom_parameter if not defined or overriding the description in `auto_docstring.py`.
    internal_helper_arg (`type`, *optional*, defaults to `default_value`):
        A concise description for internal_helper_arg if not defined or overriding the description in `auto_docstring.py`.
    """
)
class MySpecialModel(PreTrainedModel):
    def __init__(self, config: ConfigType, custom_parameter: "type" = "default_value", internal_helper_arg=None):
        # ...

كما يُطبَّق @auto_docstring على الفئات التي ترث من ModelOutput.

@auto_docstring(
    custom_intro="""
    Custom model outputs with additional fields.
    """
)
@dataclass
class MyModelOutput(ImageClassifierOutput):
    r"""
    loss (`torch.Tensor`, *optional*):
        The loss of the model.
    custom_field (`torch.Tensor` of shape `(batch_size, hidden_size)`, *optional*):
        A custom output field specific to this model.
    """

    # Standard fields (hidden_states, logits, attentions, etc.) are documented automatically when
    # the description matches the standard text. Loss typically varies per model, so document it above.
    loss: Optional[torch.Tensor] = None
    logits: Optional[torch.Tensor] = None
    hidden_states: Optional[tuple[torch.Tensor, ...]] = None
    attentions: Optional[tuple[torch.Tensor, ...]] = None
    # Custom fields need to be documented in the docstring above
    custom_field: Optional[torch.Tensor] = None

فئات الإعداد

ضع @auto_docstring مباشرةً فوق فئة فرعية من PreTrainedConfig، إلى جانب مُزيّن @strict. يضيف @strict التحقق من الأنواع وقت التشغيل ويحوّل الفئة إلى فئة بيانات مُتحقق منها. معلمات الإعداد هي تعليقات على مستوى الفئة (وليس حُجج __init__)، ويقرأ @auto_docstring هذه التعليقات من جسم الفئة لتوليد التوثيق.

ConfigArgs يوفر معايير قياسية مثل vocab_size وhidden_size وnum_hidden_layers، لذا لا تحتاج إلى وصف ما لم يختلف السلوك. تُستبعد معايير PreTrainedConfig الأساسية تلقائيًا. يولّد الحجة checkpoint مثال الاستخدام.

from huggingface_hub.dataclasses import strict
from ...configuration_utils import PreTrainedConfig
from ...utils import auto_docstring

@strict
@auto_docstring(checkpoint="org/my-model-checkpoint")
class MyModelConfig(PreTrainedConfig):
    r"""
    custom_param (`int`, *optional*, defaults to 64):
        Description of a parameter specific to this model.
    another_param (`str`, *optional*, defaults to `"gelu"`):
        Description of another model-specific parameter.

    ```python
    from transformers import MyModelConfig, MyModel

    configuration = MyModelConfig()
    model = MyModel(configuration)
    configuration = model.config
    ```
    """

    model_type = "my_model"

    # Standard params (vocab_size, hidden_size, etc.) are auto-documented from ConfigArgs.
    vocab_size: int = 32000
    hidden_size: int = 768
    num_hidden_layers: int = 12
    # Model-specific params must be documented in the class docstring above.
    custom_param: int = 64
    another_param: str = "gelu"

فئات المعالج

تستخدم معالجات الوسائط المتعددة (فئات فرعية من ProcessorMixin، processing_*.py) دائمًا @auto_docstring الصريح. يتم توليد مقدمة الفئة تلقائيًا. وثّق فقط معاملات __init__ التي لا تغطيها ProcessorArgs مسبقًا (image_processor، tokenizer، chat_template، وغيرها).

إذا كانت جميع المعايير قياسية، فتجاهل سلسلة التوثيق. زُيِّن __call__ بـ @auto_docstring أيضاً. تحتوي سلسلة توثيق جسمه على قسم Returns: فقط بالإضافة إلى أي حُجج استدعاء إضافية خاصة بالنموذج. يُضاف return_tensors تلقائياً.

from ...processing_utils import ProcessorMixin, ProcessingKwargs, Unpack
from ...utils import auto_docstring

class MyModelProcessorKwargs(ProcessingKwargs, total=False):
    _defaults = {"text_kwargs": {"padding": False}}

@auto_docstring
class MyModelProcessor(ProcessorMixin):
    def __init__(self, image_processor=None, tokenizer=None, custom_param: int = 4, **kwargs):
        r"""
        custom_param (`int`, *optional*, defaults to 4):
            A parameter specific to this processor not covered by the standard ProcessorArgs.
        """
        super().__init__(image_processor, tokenizer)
        self.custom_param = custom_param

    @auto_docstring
    def __call__(self, images=None, text=None, **kwargs: Unpack[MyModelProcessorKwargs]):
        r"""
        Returns:
            [BatchFeature](/docs/transformers/main/en/main_classes/feature_extractor#transformers.BatchFeature): A [BatchFeature](/docs/transformers/main/en/main_classes/feature_extractor#transformers.BatchFeature) with the following fields:

            - **input_ids** -- Token ids to be fed to the model.
            - **pixel_values** -- Pixel values to be fed to the model.
        """
        # ...

معالجات الصور والفيديو

تتبع معالجات الصور والفيديو (فئات فرعية من BaseImageProcessor، image_processing_*.py) أحد نمطين.

إذا كانت المعالج يحتوي على معاملات خاصة بالنموذج، فعرّف XxxImageProcessorKwargs(ImagesKwargs, total=False) TypedDict مع سلسلة توثيق لتلك المعاملات، واضبط valid_kwargs على الفئة، واستخدم @auto_docstring العاري. لا تحتوي __init__ على سلسلة توثيق.

class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    r"""
    custom_threshold (`float`, *optional*, defaults to `self.custom_threshold`):
        A parameter specific to this image processor.
    """
    custom_threshold: float | None

@auto_docstring
class MyModelImageProcessor(TorchvisionBackend):
    valid_kwargs = MyModelImageProcessorKwargs
    custom_threshold: float = 0.5

    def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
        super().__init__(**kwargs)

إذا كانت الفئة تضبط فقط سمات مستوى الفئة القياسية (size، resample، image_mean، إلخ) دون أي معاملات إضافية مخصصة، فاستخدم @auto_docstring(custom_intro="Constructs a MyModel image processor.") بدلاً من ذلك.

@auto_docstring(custom_intro="Constructs a MyModel image processor.")
class MyModelImageProcessor(TorchvisionBackend):
    resample = PILImageResampling.BICUBIC
    image_mean = IMAGENET_STANDARD_MEAN
    image_std = IMAGENET_STANDARD_STD
    size = {"height": 224, "width": 224}

عند تجاوز preprocess، زُيِّنه بـ @auto_docstring ووثِّق فقط الحُجج غير الموجودة في ImageProcessorArgs. تُضمَّن الحُجج القياسية وreturn_tensors تلقائيًا.

الدوال

ضع @auto_docstring مباشرةً فوق تعريف الدالة. يستنتج المُزيِّن (decorator) أوصاف المعاملات من توقيع الدالة.

يولّد المُزيِّن نصَّ قيمة الإرجاع من سلسلة التوثيق الخاصة بفئة ModelOutput.

class MyModel(PreTrainedModel):
    # ...
    @auto_docstring
    def forward(
        self,
        input_ids: Optional[torch.Tensor] = None,
        attention_mask: Optional[torch.Tensor] = None,
        new_custom_argument: Optional[torch.Tensor] = None,
        # ... other arguments
    ) -> Union[Tuple, ModelOutput]:
        r"""
        new_custom_argument (`torch.Tensor`, *optional*):
            Description of this new custom argument and its expected shape or type.
        """
        # ...

مرّر custom_intro وcustom_args للحصول على مزيد من التحكم. استخدم custom_args لتعريف توثيق مشترك للحجج مرة واحدة عندما تظهر نفس المعلمات في عدة طرق.

MODEL_COMMON_CUSTOM_ARGS = r"""
    common_arg_1 (`torch.Tensor`, *optional*, defaults to `default_value`):
        Description of common_arg_1
    common_arg_2 (`torch.Tensor`, *optional*, defaults to `default_value`):
        Description of common_arg_2
"""

class MyModel(PreTrainedModel):
    # ...
    @auto_docstring(
        custom_intro="""This is a custom introduction for the function.""",
        custom_args=MODEL_COMMON_CUSTOM_ARGS
    )
    def forward(self, input_ids=None, common_arg_1=None, common_arg_2=None) -> ModelOutput:
        r"""method-specific args go here"""
        # ...

اكتب قسمي Returns وExamples يدويًا في سلسلة التوثيق لتجاوز النسخ المولّدة تلقائيًا.

    def forward(self, input_ids=None) -> torch.Tensor:
        r"""
        Returns:
            `torch.Tensor`: A custom Returns section for non-ModelOutput return types.

        Example:

        ```python
        model = MyModel.from_pretrained("org/my-model")
        output = model(input_ids)
        ```
        """
        # ...

توثيق الحُجج

اتبع هذه القواعد عند توثيق أنواع الحُجج المختلفة.

• auto_docstring.py يحدد الحجة القياسية (input_ids، attention_mask، pixel_values، إلخ) ويشملها تلقائيًا. لا تعيد تعريفها محليًا إلا إذا كانت الحجة تتصرف بشكل مختلف في نموذجك.

  إذا كان معامل قياسي يتصرف بشكل مختلف في نموذجك، فقم بتجاوز محليًا داخل كتلة r""" """. التعريف المحلي له الأولوية. على سبيل المثال، معامل labels يُخصص عادةً لكل نموذج على حدة وغالبًا ما يحتاج إلى تجاوز.

• تتبع حُجج الإعداد القياسية (vocab_size، hidden_size، num_hidden_layers، إلخ) المبدأ نفسه لكنها تأتي من ConfigArgs. أما حُجج المعالج القياسية (image_processor، tokenizer، do_resize، return_tensors، إلخ) فتأتي من ProcessorArgs وImageProcessorArgs. وثّق المعامل فقط إذا كان خاصاً بالنموذج أو إذا كان سلوكه مختلفاً عن الوصف القياسي.

• وثّق الحُجج الجديدة أو المخصصة في كتلة r""" """. ضعها بعد التوقيع للدوال، وفي سلسلة التوثيق __init__ لفئات النماذج أو المعالِجات، وفي سلسلة توثيق جسم الفئة لفئات الإعدادات، أو في جسم XxxImageProcessorKwargs TypedDict لمعالجات الصور.

  تم النسخ

  argument_name (`type`, *optional*, defaults to `X`):
      Description of the argument.
      Explain its purpose, expected shape/type if complex, and default behavior.
      This can span multiple lines.

  • شمل type بين علامتي تنصيص خلفيتين.
  • أضف اختياري إذا لم يكن الحُجج مطلوباً أو كان له قيمة افتراضية.
  • أضِف “الافتراضي هو X” إذا كان له قيمة افتراضية. لا تحتاج إلى إضافة “الافتراضي هو None” إذا كانت القيمة الافتراضية هي None.
  • مرّر نفس الكتلة إلى custom_args عندما تتكرر نفس الحجج عبر عدة طرق (انظر مثال الدوال أعلاه).

• يستخرج المُزيِّن الأنواع تلقائيًا من توقيعات الدوال. إذا كان للمعامل نوع مُعلَّم، فلا حاجة إلى تكرار النوع في سلسلة تنسيق الوصف التوثيقي. عند وجود كلاهما، يُعطى الأولوية لنوع التوقيع. أما نوع الوصف التوثيقي فيعمل كبديل للمعاملات غير المُعلَّمة.

التحقق من نصوص التوثيق

يُتحقق من سلاسل التوثيق (docstrings) عبر سكربت أدوات عند فتح طلب سحب. يقوم CI بتشغيل السكربت والتحقق مما يلي.

إذا ظهر [ERROR] في المخرجات، أضف وصف المعامل إلى سلسلة التوثيق أو إلى فئة Args المناسبة في auto_docstring.py.

• يتحقق من أن @auto_docstring مطبّق على فئات النماذج ذات الصلة والوظائف العامة.
• يتحقق من اكتمال الحُجج واتساقها: يجب أن تكون الحُجج الموثقة موجودة في التوقيع، وأن تتطابق الأنواع والقيم الافتراضية. كما يتم تحديد الحُجج غير المعروفة التي لا تحتوي على وصف محلي.
• يُصدر تحذيرًا عند وجود أماكن مخصصة غير مكتملة مثل <fill_type> و<fill_docstring>.
• يتحقق من أن التعليقات التوضيحية تتبع نمط التنسيق المتوقع.

نفّذ الفحص محليًا قبل الإرسال.

make fix-repo

make fix-repo ينفّذ عدة فحوصات أخرى أيضًا. لتشغيل فحوصات docstring وauto-docstring فقط، استخدم الأمر أدناه.

# to only check files included in the diff without fixing them
python utils/check_docstrings.py
# to fix and overwrite the files in the diff
# python utils/check_docstrings.py --fix_and_overwrite
# to fix and overwrite all files
# python utils/check_docstrings.py --fix_and_overwrite --check_all

قائمة مرجعية سريعة

كيف يعمل

يولّد المُزيِّن @auto_docstring سلاسل التوثيق عبر الخطوات التالية.

1. يفحص المُزيِّن التوقيع لقراءة الحُجج والأنواع والقيم الافتراضية من __init__ للفئة المُزيَّنة أو من الدالة المُزيَّنة. أما لفئات الإعداد، فيتتبع التعليقات على مستوى الفئة عبر سلسلة الوراثة ويتوقف قبل PreTrainedConfig، مستثنياً حقول الفئة الأساسية.

   يقوم تلقائيًا بتصفية المعاملات مثل self وkwargs وargs وdeprecated_arguments والأسماء التي تبدأ بـ_. كما يتم إعادة تسمية بعض المعاملات الخاصة إلى ما يعادلها من المعاملات العامة (_out_features إلى out_features في نماذج الهيكل العظمي).

2. تأتي أوصاف الحجج الشائعة من auto_docstring.py: ModelArgs (مدخلات النموذج)، ModelOutputArgs (حقول المخرجات مثل hidden_states)، ImageProcessorArgs (المعالجة المسبقة للصور)، ProcessorArgs (مكونات المعالج متعدد الوسائط)، وConfigArgs (معلمات الإعدادات الفائقة).

3. تتبع وصف كل معامل هذا التسلسل الأولويات:

   • تتمتع سلسلة التوثيق اليدوية (كتلة r""" """ أو custom_args) بالأولوية.
   • يُعدّ قاموس المصدر المُعرَّف مسبقًا (ModelArgs، ModelForArgs، ConfigArgs، ImageProcessorArgs، ProcessorArgs، ModelOutputArgs) هو الخيار الاحتياطي.
   • إذا لم يكن لأيٍّ من المصدرين وصف، يُعلَّم المعامل بـ [ERROR] في مخرجات البناء.

4. بالنسبة لفئات النماذج التي تحمل أسماء قياسية مثل ModelForCausalLM، أو الفئات التي تُخاط إلى خط أنابيب، يولّد @auto_docstring المقدمة. أما بالنسبة لمعالجات الوسائط المتعددة، فتُدرج المقدمة المكونات (مجزّئ النص، ومعالج الصور، وما إلى ذلك) التي تغلفها الفئة. راجع ClassDocstring للحصول على القائمة الكاملة.

   إذا لم يكن اسم الفئة موجودًا في ClassDocstring، فعيّن custom_intro.

5. يمكن أن تشير سلاسل التوثيق (docstrings) المُعرَّفة مسبقًا إلى قيم ديناميكية من auto_modules في Transformers، مثل {processor_class} و{image_processor_class} و{config_class}. يتم حلّ العناوين الوهمية تلقائيًا.

6. يختار المُزيِّن أمثلة الاستخدام بناءً على مهمة النموذج أو توافق خط المعالجة. إنه يقرأ بيانات الوصفية (metadata) للنقطة المحفوظة من فئة الإعدادات بحيث تستخدم الأمثلة معرّفات نماذج حقيقية. يتجاوز الحُجج checkpoint النقطة المحفوظة المستنتجة من نص التوثيق (docstring) لفئة الإعدادات. اضبط checkpoint على فئات الإعدادات، أو عندما يفشل استنتاج النقطة المحفوظة. إذا رأيت خطأً مثل "Config not found for <model_name>"، أضف إدخالا إلى HARDCODED_CONFIG_FOR_MODELS في auto_docstring.py.

7. بالنسبة لطرق مثل forward، يكتب المُزيّن قسم Returns من نوع الإرجاع الخاص بالطريقة. عندما يكون نوع الإرجاع فئة فرعية من ModelOutput، يستخرج @auto_docstring أوصاف الحقول من توثيق تلك الفئة. أما كتلة Returns مخصصة في توثيق الدالة فتتمتع بالأولوية.

8. بالنسبة للطرق في UNROLL_KWARGS_METHODS والفئات في UNROLL_KWARGS_CLASSES، يقوم المُزيّن بتوسيع **kwargs المُصنّف بـ Unpack[KwargsTypedDict]. يصبح كل مفتاح من TypedDict معاملًا موثقًا.

   تنطبق التوسعة نفسها على طريقتي __call__ وpreprocess في فئات BaseImageProcessor وProcessorMixin الفرعية. يتم تجاوز الأنواع الأساسية العامة (TextKwargs، ImagesKwargs، VideosKwargs، AudioKwargs). يتم فك لفّ الفئات الفرعية الخاصة بالنموذج فقط.