Transformers documentation
Автоматическая генерация docstrings
Автоматическая генерация docstrings
Декоратор @auto_docstring генерирует единообразные строки документации для классов и методов моделей. Он автоматически подтягивает стандартные описания аргументов, поэтому вам нужно писать документацию только для новых или пользовательских аргументов. При добавлении новой модели пропустите шаблонные части и сосредоточьтесь на том, что является новым.
@auto_docstring
Импортируйте декоратор в ваш файл modular_model.py (или modeling_model.py для более старых моделей).
from ...utils import auto_docstringЕсли ваша модель наследуется от модели другой библиотеки в модульном файле, @auto_docstring уже применён в родительском классе. make fix-repo копирует его в сгенерированный файл modeling_model.py за вас. Применяйте декоратор явно только для настройки его поведения (автономные модели, кастомные интро или переопределённые аргументы).
При переопределении любого декоратора в модульном файле включайте все декораторы из родительской функции или класса. Если переопределить только часть, остальные не появятся в сгенерированном файле моделирования.
Декоратор принимает следующие необязательные аргументы:
| аргумент | Описание |
|---|---|
custom_intro | Описание класса или метода, вставляемое перед разделом Args. Обязательно для классов, имена которых не заканчиваются распознаваемым суффиксом, таким как ForCausalLM или ForTokenClassification. |
custom_args | Текст docstring для конкретных параметров. Полезно, когда одни и те же пользовательские аргументы встречаются в нескольких местах в файле моделирования. |
checkpoint | Идентификатор контрольной точки модели ("org/my-model"), используемый для генерации примеров использования. Переопределяет контрольную точку, автоматически определяемую из класса конфигурации. Как правило, устанавливается в классах конфигурации. |
Использование
То, как работает @auto_docstring, зависит от того, что вы декорируете. Классы моделей берут документацию параметров из __init__, классы конфигураций — из аннотаций на уровне класса, классы процессоров автоматически генерируют описания на основе своих компонентов, а методы вроде forward получают типы возвращаемых значений и примеры использования.
Классы моделей
Разместите @auto_docstring непосредственно над определением класса. Декоратор извлекает описания параметров из сигнатуры и 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 или в docstring метода __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 добавляет проверку типов во время выполнения и превращает класс в валидированный dataclass. Параметры конфигурации — это аннотации на уровне класса (не аргументы __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 и другие).
Если все параметры стандартные, опустите docstring. Также декорируйте __call__ с помощью @auto_docstring. В docstring его тела содержится только раздел Returns: и любые дополнительные аргументы вызова, специфичные для модели. return_tensors добавляется автоматически.
from ...processing_utils import ProcessorMixin, ProcessingKwargs, Unpack
from ...utils import auto_docstring
class MyModelProcessorKwargs(ProcessingKwargs, total=False):
"""
custom_call_kwarg (`bool`, *optional*, defaults to `False`):
A parameter with a default that can passed to __call__ which is not
covered by the standard processor arguments (including each modality).
"""
custom_call_kwarg: bool
@auto_docstring
class MyModelProcessor(ProcessorMixin):
valid_processor_kwargs = MyModelProcessorKwargs
custom_call_kwarg = False
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/v5.23.0/en/main_classes/feature_extractor#transformers.BatchFeature): A [BatchFeature](/docs/transformers/v5.23.0/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) следуют одному из двух шаблонов.
Если у процессора есть параметры, специфичные для модели, определите TypedDict XxxImageProcessorKwargs(ImagesKwargs, total=False) с docstring для этих параметров, установите valid_kwargs на классе и используйте «голый» @auto_docstring. У __init__ нет docstring.
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 и т. д.) без пользовательских kwargs, используйте @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 непосредственно над определением функции. Декоратор извлекает описания параметров из сигнатуры функции.
Декоратор генерирует текст возвращаемого значения из строки документации класса 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 в docstring для переопределения автоматически сгенерированных версий.
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""" """. Размещайте их после сигнатуры для функций, в docstring__init__для классов моделей или процессоров, в docstring тела класса для классов конфигурации или в теле TypedDictXxxImageProcessorKwargsдля процессоров изображений.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в обратные кавычки. - Добавьте optional, если аргумент не является обязательным или имеет значение по умолчанию.
- Добавляйте «по умолчанию X», если есть значение по умолчанию. Не нужно добавлять «по умолчанию
None», если значение по умолчанию равноNone. - Передавайте тот же блок в
custom_args, если одни и те же аргументы повторяются в нескольких методах (см. пример с функциями выше).
- Включите
Декоратор автоматически извлекает типы из сигнатур функций. Если у параметра есть аннотация типа, нет необходимости повторять тип в строке формата docstring. Если присутствуют оба, приоритет имеет тип из сигнатуры. Тип из docstring служит запасным вариантом для параметров без аннотаций.
Проверка docstrings
Утилита для проверки docstrings запускается при открытии pull request. CI выполняет скрипт и проверяет следующее.
Если в выводе вы видите
[ERROR], добавьте описание параметра в docstring или в соответствующий класс 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 к классам моделей, конфигураций и процессоров, а также к их основным методам (forward, __call__, preprocess). | Добавьте @auto_docstring к унаследованным моделям в модульных файлах, так как он переносится автоматически. |
| Документируйте только новые или специфичные для модели аргументы. | Переопределите стандартные аргументы (input_ids, attention_mask, vocab_size и т. д.), которые ведут себя так же, как описано в их значениях по умолчанию. |
| Разместите параметры конфигурации в docstring тела класса в виде аннотаций на уровне класса. | Разместите параметры конфигурации в __init__. |
Разместите параметры процессора изображений в TypedDict XxxImageProcessorKwargs. | Разместите параметры процессора изображений в __init__. |
Выполните python utils/check_docstrings.py --fix_and_overwrite перед коммитом. | Игнорируйте вывод [ERROR], так как он означает, что параметр не задокументирован. |
Как это работает
Декоратор @auto_docstring генерирует строки документации, выполняя следующие шаги.
Декоратор анализирует сигнатуру, чтобы извлечь аргументы, типы и значения по умолчанию из
__init__декорируемого класса или декорируемой функции. Для классов конфигурации он обходит аннотации на уровне класса вверх по цепочке наследования и останавливается перед PreTrainedConfig, исключая поля базового класса.Он автоматически отфильтровывает параметры, такие как
self,kwargs,args,deprecated_argumentsи имена с префиксом_. Несколько приватных параметров переименовываются в их публичные эквиваленты (_out_features→out_featuresдля моделей-бэкбонов).Описания общих аргументов берутся из
auto_docstring.py:ModelArgs(входные данные модели),ModelOutputArgs(поля вывода, такие какhidden_states),ImageProcessorArgs(предобработка изображений),ProcessorArgs(компоненты мультимодального процессора) иConfigArgs(гиперпараметры конфигурации).Описание каждого параметра следует этой цепочке приоритетов:
- Ручной docstring (блок
r""" """илиcustom_args) имеет приоритет. - Предопределённый словарь источников (
ModelArgs,ModelForArgs,ConfigArgs,ImageProcessorArgs,ProcessorArgs,ModelOutputArgs) используется как резервный вариант. - Если ни один из источников не содержит описания, параметр помечается как
[ERROR]в выводе сборки.
- Ручной docstring (блок
Для классов моделей со стандартными именами, такими как
ModelForCausalLM, или классов, которые сопоставляются с конвейером,@auto_docstringгенерирует вводную часть. Для мультимодальных процессоров во вводной части перечисляются компоненты (токенизатор, процессор изображений и так далее), которые класс инкапсулирует. Полный список см. в ClassDocstring.Если имя класса отсутствует в
ClassDocstring, задайтеcustom_intro.Предопределённые docstrings могут ссылаться на динамические значения из auto_modules Transformers, такие как
{processor_class},{image_processor_class}и{config_class}. Плейсхолдеры подставляются автоматически.Декоратор выбирает примеры использования на основе задачи модели или совместимости с конвейером. Он читает метаданные контрольной точки из класса конфигурации, чтобы в примерах использовались реальные идентификаторы моделей. Аргумент
checkpointпереопределяет контрольную точку, выведенную из строки документации класса конфигурации. Укажитеcheckpointв классах конфигурации или в том случае, если вывод контрольной точки не удался. Если вы видите ошибку вида"Config not found for <model_name>", добавьте запись вHARDCODED_CONFIG_FOR_MODELSв файлеauto_docstring.py.Для методов, таких как
forward, декоратор заполняет разделReturnsна основе типа возвращаемого значения метода. Если тип возвращаемого значения является подклассом ModelOutput,@auto_docstringизвлекает описания полей из docstring этого класса. Пользовательский блокReturnsв docstring функции имеет приоритет.Для методов из
UNROLL_KWARGS_METHODSи классов изUNROLL_KWARGS_CLASSESдекоратор разворачивает**kwargsс типомUnpack[KwargsTypedDict]. Каждый ключ изTypedDictстановится задокументированным параметром.Аналогичное расширение применяется к методам
__call__иpreprocessв подклассах BaseImageProcessor и ProcessorMixin. Общие базовые типы (TextKwargs,ImagesKwargs,VideosKwargs,AudioKwargs) пропускаются. Разворачиваются только подклассы, специфичные для модели.