Docstring'lerin otomatik oluşturulması

@auto_docstring dekoratörü, model sınıfları ve yöntemleri için tutarlı dokümantasyon dizeleri (docstring) oluşturur. Standart argüman açıklamalarını otomatik olarak alır, böylece yalnızca yeni veya özel argümanlar için dokümantasyon yazarım. Yeni bir model eklerken, standart kalıpları (boilerplate) atlayıp yeni olanlara odaklanabilirsiniz.

@auto_docstring

Dekorasyonu modular_model.py dosyanıza (eski modeller için modeling_model.py) içe aktarın.

from ...utils import auto_docstring

Modeliniz modüler bir dosyada başka bir kütüphane modelinden türetiliyorsa, @auto_docstring zaten üst modelde uygulanmıştır. make fix-repo bunu sizin için oluşturulan modeling_model.py dosyasına kopyalar. Davranışını özelleştirmek (bağımsız modeller, özel intros veya geçersiz kılınmış argümanlar) için dekoratörü yalnızca açıkça uygulayın.

Modüler bir dosyada herhangi bir dekoratörü geçersiz kılarken, üst fonksiyondan veya sınıftan tüm dekoratörleri dahil edin. Sadece bazılarını geçersiz kılırsanız, kalanlar oluşturulan modelleme dosyasında görünmez.

Dekorator aşağıdaki isteğe bağlı argümanları kabul eder:

Kullanım

@auto_docstring'ın çalışma şekli, süslediğiniz şeye bağlıdır. Model sınıfları parametre belgelerini __init__'den alır, yapılandırma sınıfları sınıf düzeyindeki açıklamalardan alır, işlemci sınıfları bileşenlerinden otomatik olarak tanıtımlar üretir ve forward gibi yöntemler dönüş türleri ve kullanım örnekleri alır.

Model sınıfları

@auto_docstring etiketini sınıf tanımının hemen üzerine yerleştirin. Bu dekoratör, parametre açıklamalarını __init__ metodunun imzasından ve dokümantasyon dizgesinden türetir.

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

Daha fazla kontrol için custom_intro ve custom_args geçin. Özel argümanlar custom_args içinde veya __init__ docstring'inde bulunabilir. Aynı argümanların birden fazla yöntemde tekrarlandığı durumlarda custom_args kullanın.

@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'dan türeyen sınıflara da uygulayın.

@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

Config sınıfları

@auto_docstring etiketini, @strict dekoratörünün yanında, bir PreTrainedConfig alt sınıfının hemen üzerine yerleştirin. @strict, çalışma zamanı tür doğrulaması ekler ve sınıfı doğrulanmış bir dataclass'a dönüştürür. Yapılandırma parametreleri sınıf düzeyinde anotasyonlardır (__init__ argümanları değil) ve @auto_docstring, bunları sınıf gövdesinden okuyarak belgeleri oluşturur.

ConfigArgs, davranış farklı olmadıkça açıklama gerektirmeyen vocab_size, hidden_size ve num_hidden_layers gibi standart parametreleri sağlar. PreTrainedConfig taban parametreleri otomatik olarak hariç tutulur. checkpoint argümanı kullanım örneğini oluşturur.

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"

İşleyici sınıfları

Çok modlu işleyiciler (ProcessorMixin alt sınıfları, processing_*.py) her zaman çıplak @auto_docstring kullanır. Sınıf tanıtımı otomatik olarak oluşturulur. ProcessorArgs tarafından (image_processor, tokenizer, chat_template ve diğerleri) zaten kapsanmayan __init__ parametrelerini belgeleyin.

Tüm parametreler standartsa, docstring'i atlayın. __call__ metodunu da @auto_docstring ile süsleyin. Gövde docstring'i yalnızca bir Returns: bölümü ve varsa ek model-özel çağrı argümanlarını içerir. return_tensors otomatik olarak eklenir.

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.
        """
        # ...

Görsel ve video işleyicileri

Görsel ve video işleyicileri (BaseImageProcessor alt sınıfları, image_processing_*.py) iki kalıbından birini izler.

İşleyici model-özel parametrelere sahipse, bu parametreler için bir docstring içeren XxxImageProcessorKwargs(ImagesKwargs, total=False) TypedDict tanımlayın, sınıfta valid_kwargs değerini ayarlayın ve çıplak @auto_docstring kullanın. __init__ docstring içermez.

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)

Sınıf yalnızca özel kwargs olmadan standart sınıf düzeyinde öznitelikleri (size, resample, image_mean vb.) ayarlıyorsa, bunun yerine @auto_docstring(custom_intro="Constructs a MyModel image processor.") kullanın.

@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 işlevini geçersiz kıldığınızda, @auto_docstring ile süsleyin ve yalnızca ImageProcessorArgs içinde bulunmayan argümanları belgeleyin. Standart argümanlar ve return_tensors otomatik olarak dahil edilir.

Fonksiyonlar

@auto_docstring etiketini doğrudan fonksiyon tanımının üzerine yerleştirin. Bu dekoratör, parametre açıklamalarını fonksiyon imzasından türetir.

Dekoratör, ModelOutput sınıfının docstring'inden dönüş değeri metnini üretir.

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.
        """
        # ...

Daha fazla kontrol için custom_intro ve custom_args geçin. Aynı parametreler birden fazla yöntemde görünüyorsa, ortak argüman belgelerini bir kez tanımlamak için custom_args kullanın.

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"""
        # ...

Otomatik oluşturulan sürümleri geçersiz kılmak için docstring içinde Returns ve Examples bölümlerini elle yazın.

    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)
        ```
        """
        # ...

Argümanları belgeleme

Farklı argüman türlerini belgelediğinizde bu kurallara uyun.

• auto_docstring.py standart argümanları (input_ids, attention_mask, pixel_values vb.) tanımlar ve bunları otomatik olarak dahil eder. Argüman modelinizde farklı davranmıyorsa bunları yerel olarak yeniden tanımlamayın.

  Standart bir argüman modelinizde farklı davranıyorsa, onu yerel olarak bir r""" """ bloğunda geçersiz kılın. Yerel tanım önceliklidir. Örneğin, labels argümanı genellikle modele göre özelleştirilir ve çoğu zaman geçersiz kılınması gerekir.

• Standart yapılandırma argümanları (vocab_size, hidden_size, num_hidden_layers vb.) aynı ilkeyi izler ancak ConfigArgs sınıfından gelir. Standart işlemci argümanları (image_processor, tokenizer, do_resize, return_tensors vb.) ProcessorArgs ve ImageProcessorArgs sınıflarından gelir. Bir parametreyi yalnızca modele özgü olması veya standart açıklamadan farklı davranması durumunda belgeleyin.

• Yeni veya özel argümanları r""" """ bloğunda belgeleyin. Bunları fonksiyonlar için imzanın ardından, model veya işlemci sınıfları için __init__ docstring'inde, yapılandırma sınıfları için sınıf gövdesi docstring'inde veya görüntü işlemcileri için XxxImageProcessorKwargs TypedDict gövdesinde yerleştirin.

  Kopyalandı

  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 öğesini geri tırnak içine alın.
  • Argüman zorunlu değilse veya bir varsayılan değere sahipse isteğe bağlı ekleyin.
  • Varsayılan bir değeri varsa “varsayılan olarak X” ifadesini ekleyin. Varsayılan değer None ise “varsayılan olarak None” ifadesini eklemenize gerek yoktur.
  • Aynı argümanlar birden fazla yöntemde tekrarlandığında, aynı bloğu custom_args içine geçirin (bkz. yukarıdaki Fonksiyonlar örneği).

• Dekorator, tipleri fonksiyon imzalarından otomatik olarak çıkarır. Bir parametrenin tip etiketi varsa, tipin dokümantasyon dizgisindeki biçim dizgesinde tekrarlanmasına gerek yoktur. Her ikisi de mevcut olduğunda, imza tipi önceliklidir. Dokümantasyon dizgisi tipi, etiketlenmemiş parametreler için yedek olarak işlev görür.

Belge dizelerini kontrol etme

Bir yardımcı betik, bir çekme isteği (pull request) açtığınızda dokümantasyon dizelerini (docstring) doğrular. CI betiği çalıştırır ve aşağıdakileri kontrol eder.

Çıktıda [ERROR] görürseniz, parametrenin açıklamasını auto_docstring.py içindeki docstring'e veya uygun Args sınıfına ekleyin.

• @auto_docstring'in ilgili model sınıflarına ve genel yöntemlere uygulandığını kontrol eder.
• Argüman bütünlüğünü ve tutarlılığını doğrular: belgelenmiş argümanlar imzada var olmalı ve türler ile varsayılan değerler eşleşmelidir. Yerel bir açıklamaya sahip olmayan bilinmeyen argümanlar işaretlenir.
• <fill_type> ve <fill_docstring> gibi eksik yer tutucuları işaretler.
• Belge dizelerinin (docstring) beklenen biçimlendirme stilini izlediğini doğrular.

Yüklemeden önce kontrolü yerel olarak çalıştırın.

make fix-repo

make fix-repo ayrıca birkaç başka denetimi de çalıştırır. Yalnızca docstring ve auto-docstring denetimlerini çalıştırmak için aşağıdaki komutu kullanın.

# 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

Hızlı başvuru kontrol listesi

Nasıl çalışır

@auto_docstring dekoratörü, aşağıdaki adımlar aracılığıyla dokümantasyon dizeleri (docstring) oluşturur.

1. Dekorator, imzayı inceleyerek dekore edilen sınıfın __init__ veya dekore edilen fonksiyondan argümanları, tipleri ve varsayılan değerleri okur. Yapılandırma sınıfları için, sınıf düzeyindeki açıklamaları miras alma zinciri boyunca yukarı doğru izler ve PreTrainedConfig'den önce durur; böylece temel sınıf alanları hariç tutulur.

   self, kwargs, args, deprecated_arguments ve _ önekli adlar gibi parametreleri otomatik olarak filtreler. Birkaç özel parametre, herkese açık karşılıklarıyla yeniden adlandırılır (backbone modeller için _out_features → out_features).

2. Ortak argüman açıklamaları auto_docstring.py dosyasından gelir: ModelArgs (model girdileri), ModelOutputArgs (hidden_states gibi çıktı alanları), ImageProcessorArgs (görsel ön işleme), ProcessorArgs (çok modlu işlemci bileşenleri) ve ConfigArgs (yapılandırma hiperparametreleri).

3. Her parametrenin açıklaması şu öncelik zincirine göre belirlenir:

   • Manuel docstring (r""" """ bloğu veya custom_args) önceliklidir.
   • Önceden tanımlı kaynak sözlüğü (ModelArgs, ModelForArgs, ConfigArgs, ImageProcessorArgs, ProcessorArgs, ModelOutputArgs) yedektir.
   • Hiçbir kaynakta açıklama yoksa, parametre derleme çıktısında [ERROR] ile işaretlenir.

4. ModelForCausalLM gibi standart adlara sahip model sınıfları için veya bir pipeline'a eşlenen sınıflar için @auto_docstring giriş metnini oluşturur. Çok modlu işleyicilerde giriş metni, sınıfın hangi bileşenleri (tokenizör, görüntü işleyici vb.) sardığını listeler. Tam liste için ClassDocstring bölümüne bakın.

   Sınıf adı ClassDocstring içinde değilse, custom_intro değerini ayarlayın.

5. Önceden tanımlanmış docstring'ler, {processor_class}, {image_processor_class} ve {config_class} gibi Transformers'ın auto_modules içindeki dinamik değerlere atıfta bulunabilir. Yer tutucular otomatik olarak çözümlenir.

6. Dekorator, modelin görevine veya pipeline uyumluluğuna göre kullanım örneklerini seçer. Örneklerin gerçek model kimliklerini kullanması için yapılandırma sınıfından checkpoint meta verilerini okur. checkpoint argümanı, yapılandırma sınıfının dokümantasyon dizgesinden çıkarılan checkpoint'i geçersiz kılar. Yapılandırma sınıflarında checkpoint değerini ayarlayın veya checkpoint çıkarımı başarısız olduğunda ayarlayın. "Config not found for <model_name>" gibi bir hata görürseniz, auto_docstring.py dosyasındaki HARDCODED_CONFIG_FOR_MODELS yapısına bir giriş ekleyin.

7. forward gibi yöntemler için dekoratör, yöntemin dönüş türünden Returns bölümünü yazar. Dönüş türü bir ModelOutput alt sınıfı olduğunda, @auto_docstring alan açıklamalarını o sınıfın dokümantasyon dizgisinden alır. İşlevin dokümantasyon dizgisindeki özel bir Returns bloğu önceliklidir.

8. UNROLL_KWARGS_METHODS içindeki yöntemler ve UNROLL_KWARGS_CLASSES içindeki sınıflar için, dekoratör Unpack[KwargsTypedDict] ile tiplemiş **kwargs parametresini açar. TypedDict'ten gelen her anahtar, belgelenmiş bir parametreye dönüşür.

   Aynı genişletme, BaseImageProcessor ve ProcessorMixin alt sınıflarındaki __call__ ve preprocess yöntemlerine de uygulanır. Genel taban türleri (TextKwargs, ImagesKwargs, VideosKwargs, AudioKwargs) atlanır. Yalnızca modele özgü alt sınıflar açılır.