# Правила структуры модели

Transformers применяет набор статических правил к каждому файлу `modeling_*.py`, `modular_*.py` и `configuration_*.py`. Пакет [mlinter](https://github.com/huggingface/transformers-mlinter) предоставляет движок проверки, а активный набор правил репозитория хранится в `utils/rules.toml`. Этот локальный TOML позволяет быстро включать, отключать или настраивать правила, не дожидаясь выхода новой версии `transformers-mlinter`.

> [!TIP]
> См. [документацию mlinter](https://huggingface.github.io/transformers-mlinter/) для полного справочника по проверкам и подробностей использования.

Эти соглашения описывают ожидаемый формат кода моделирования при добавлении или изменении кода. Они обеспечивают единообразие кодовой базы и совместимость с такими функциями, как параллелизм по пайплайну, карты устройств и связывание весов.

## Запуск средства проверки

`make typing` запускает `mlinter` вместе с проверщиком типов `ty` через обёртку репозитория, поэтому подхватывает `utils/rules.toml`. Запустите ту же обёртку напрямую с помощью следующих команд.

```bash
python utils/check_modeling_structure.py                 # check all modeling files
python utils/check_modeling_structure.py --changed-only  # check only files changed vs origin/main
python utils/check_modeling_structure.py --list-rules    # list all rules and their enabled status
python utils/check_modeling_structure.py --rule TRF001   # show built-in docs for a specific rule
```

Флаг `--changed-only` — самый быстрый вариант на этапе разработки. Он проверяет только те файлы, которые вы изменили относительно основной ветки. Если вы вызываете `mlinter` напрямую, а не через обёртку, передайте `--rules-toml utils/rules.toml`, чтобы были применены локальные переопределения.

## Исправление нарушения

При обнаружении нарушения правила ошибка выглядит следующим образом:

```
src/transformers/models/acme/modeling_acme.py:18: TRF013: AcmeModel.__init__ does not call self.post_init().
```

Используйте идентификатор правила, чтобы найти исправление в [справочнике по правилам](#rules-reference). Правило TRF013 срабатывает, если подкласс [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel) не вызывает `self.post_init()`. Этот метод выполняет необходимые завершающие шаги, и его пропуск приводит к ошибкам во время выполнения.

```diff
 class AcmeModel(AcmePreTrainedModel):
     def __init__(self, config):
         super().__init__(config)
         self.layers = nn.ModuleList(
             [AcmeDecoderLayer(config) for _ in range(config.num_hidden_layers)]
         )
+        self.post_init()
```

## Справочник по правилам

Каждое правило ниже описывает, что оно контролирует, и показывает diff с исправлением. Запустите `python utils/check_modeling_structure.py --rule TRF001`, чтобы увидеть встроенную документацию для любого правила с текущим набором правил репозитория.

### TRF002

Проверяет, что base_model_prefix является непустой строковой константой без пробельных символов. Некорректные префиксы могут нарушить сопоставление ключей при загрузке весов и доступ к базовой модели.

```diff
class AcmePreTrainedModel(PreTrainedModel):
-    base_model_prefix = ""
+    base_model_prefix = "model"
```

### TRF003

Флаггирует старый паттерн `if not return_dict: return (x,)` в forward. Ручная ветвление по return_dict громоздка и легко приводит к ошибкам. Пусть этим занимаются @capture_output или @can_return_tuple.

```diff
-def forward(self, x, return_dict=None):
-    if not return_dict:
-        return (x,)
-    return AcmeModelOutput(last_hidden_state=x)
+@can_return_tuple
+def forward(self, x):
+    return AcmeModelOutput(last_hidden_state=x)
```

### TRF004

Проверяет, что ни один класс модели не переопределяет метод tie_weights. Переопределение tie_weights нарушает загрузку, вычисление device_map и сохранение. Связанные веса следует объявлять в атрибуте класса _tied_weights_keys.

```diff
-def tie_weights(self):
-    self.lm_head.weight = self.emb.weight
+class AcmeForCausalLM(AcmePreTrainedModel):
+    _tied_weights_keys = ["lm_head.weight"]
```

### TRF005

Проверяет форму _no_split_modules, если она присутствует. Некорректные значения могут нарушить разделение по устройствам и шардирование.

```diff
-_no_split_modules = [SomeLayerClass, ""]
+_no_split_modules = ["AcmeDecoderLayer", "AcmeAttention"]
```

### TRF006

Проверяет, что аргументы кэша в сигнатуре метода forward используются в его теле. Неиспользуемый аргумент кэша указывает на неполную поддержку кэширования и непоследовательное поведение API.

```diff
def forward(self, x, past_key_values=None, use_cache=False):
+    if use_cache:
+        ...
     return x
```

### TRF007

Проверяет присваивания атрибутам self после вызова self.post_init() в __init__. Изменение структуры модели после post_init обходит её инициализацию и завершающую обработку.

```diff
def __init__(self, config):
     ...
-    self.post_init()
-    self.proj = nn.Linear(...)
+    self.proj = nn.Linear(...)
+    self.post_init()
```

### TRF008

Проверяет, что add_start_docstrings для класса модели получает непустой аргумент. Пустой аргумент приводит к неясной документации API низкого качества.

```diff
-@add_start_docstrings("")
+@add_start_docstrings("The Acme model.")
 class AcmeModel(AcmePreTrainedModel):
     ...
```

### TRF009

Флаг фиксирует импорты из пакета другой модели в поставляемых файлах реализации модели: modeling_*, configuration_*, processing_*, image_processing_*, video_processing_*, feature_extraction_*, tokenization_* и generation_*.py. Учитываются три формы: путь к пакету (`from transformers.models.other.modeling_other import X`), относительный путь (`from ..other.configuration_other import X`) и публичный API (`from transformers import OtherModel`) — в последнем случае каталог-владелец выводится из имени класса и сверяется с определяемыми им классами, поэтому неразрешимое имя остаётся без изменений. Вне области применения: `modular_*.py` (построение на основе другой модели — их прямое назначение, а конвертер убирает такие импорты), `convert_*.py`, `__init__.py` и файлы в каталоге `auto`. Допустимые цели: собственный каталог модели, `auto` и `timm_wrapper`. Одна модель — одно определение: поведение модели A описывается в её собственных файлах, и изменение модели B не должно незаметно менять модель A — для каждого типа файлов, а не только для modeling. Обращайтесь к подконфигурациям через AutoConfig и CONFIG_MAPPING, а для построения на основе кода другой модели используйте модулярный файл.

```diff
-from transformers.models.llama.modeling_llama import LlamaAttention
-from transformers import CLIPTextModelWithProjection
+# Keep implementation local to this model's own files.
+# To build on another model, write modular_acme.py; to reuse a snippet,
+# copy it with a # Copied from comment.
```

### TRF010

Проверяет, что прямые подклассы PreTrainedConfig/PretrainedConfig в configuration_*.py и modular_*.py имеют декоратор @strict(accept_kwargs=True). Без него новый конфиг не соответствует контракту проверки типов во время выполнения в репозитории и отклоняется от стандарта конфигов на основе dataclass.

```diff
+@strict(accept_kwargs=True)
 class AcmeConfig(PreTrainedConfig):
     ...
```

### TRF011

В методах forward() подклассов PreTrainedModel флаги доступа к атрибутам подмодулей, которых не было бы у torch.nn.Identity: по переменным цикла, итерующим по self.layers, и self., где  не является стандартным атрибутом nn.Module. Пайплайн-параллелизм может заменить любой подмодуль на torch.nn.Identity, поэтому чтение пользовательского атрибута (например, decoder_layer.attention_type) с него вызывает AttributeError во время выполнения. Читайте метаданные для каждого слоя из self.config.

```diff
def forward(self, ...):
-    for decoder_layer in self.layers:
+    for i, decoder_layer in enumerate(self.layers):
         hidden_states = decoder_layer(
             hidden_states,
-            attention_mask=causal_mask_mapping[decoder_layer.attention_type],
+            attention_mask=causal_mask_mapping[self.config.layer_types[i]],
         )
```

### TRF012

Флаги in-place операций (.normal_(), .zero_(), ...) на весах модулей внутри _init_weights. Параметры имеют внутренние флаги, отслеживающие, требуется ли им повторная инициализация; in-place операции обходят эти флаги. Используйте примитивы `init`.

```diff
+from transformers import initialization as init
+
 def _init_weights(self, module):
-    module.weight.normal_(mean=0.0, std=0.02)
+    init.normal_(module.weight, mean=0.0, std=0.02)
```

### TRF013

Проверяет, что каждый подкласс PreTrainedModel, определяющий __init__, вызывает self.post_init(). В модульных файлах достаточно вызова super().__init__(), так как он транслирует post_init родительского класса. post_init выполняет критически важную финализацию (инициализация весов, настройка градиентного чекпоинтинга и т. д.); его пропуск приводит к тонким ошибкам во время выполнения.

```diff
class AcmeModel(AcmePreTrainedModel):
     def __init__(self, config):
         super().__init__(config)
         self.layers = nn.ModuleList(...)
+        self.post_init()
```

### TRF014

Флаги `trust_remote_code`, используемые или передаваемые (например, в качестве именованного аргумента) в файлах нативной интеграции моделей. `trust_remote_code` загружает произвольный код, включая бинарные файлы, — это мощная функция для пользователей, но не то, на что может полагаться нативная интеграция, поскольку удаленный код не может быть проверен или поддерживаться в transformers.

```diff
class AcmeModel(AcmePreTrainedModel):
     def __init__(self, config):
         super().__init__(config)
-        self.model = AutoModel.from_pretrained(..., trust_remote_code=True)
+        self.model = AutoModel.from_pretrained(...)
```

### TRF015

Если подкласс PreTrainedModel устанавливает непустое значение _tied_weights_keys, проверяется наличие поля tie_word_embeddings в сопутствующем файле конфигурации. Без этого поля пользователи не могут управлять связыванием весов: модель связывает веса безоговорочно, что нарушает циклы сериализации и дообучение с несвязанными головками.

```diff
# configuration_foo.py
 @strict(accept_kwargs=True)
 class FooConfig(PreTrainedConfig):
     hidden_size: int = 768
+    tie_word_embeddings: bool = True
```

### TRF016

Если класс image_processing_*.py или video_processing_*.py объявляет булевы атрибуты do_* (do_resize, do_rescale, do_normalize, do_convert_rgb, ...) и переопределяет preprocess() или _preprocess(), проверьте, что каждый флаг по-прежнему используется в них: ссылаются на него напрямую, делегируют через super().preprocess/_preprocess(..., **kwargs) или — только для image processors — передают через _preprocess_image_like_inputs/_prepare_image_like_inputs. do_sample_frames исключение: базовый preprocess() потребляет его до запуска _preprocess(). do_X, на который переопределение никогда не ссылается, является мёртвым: установка do_X=False не имеет эффекта, операция выполняется в любом случае, а переопределения для каждого вызова молча ломаются.

```diff
class AcmeVideoProcessor(BaseVideoProcessor):
     do_resize = True
     do_normalize = True

     def _preprocess(
         self,
         videos,
+        do_resize: bool,
+        do_normalize: bool,
         size,
         image_mean,
         image_std,
         **kwargs,
     ):
         for video in videos:
-            video = self.resize(video, size=size)
-            video = self.normalize(video, image_mean, image_std)
+            if do_resize:
+                video = self.resize(video, size=size)
+            if do_normalize:
+                video = self.normalize(video, image_mean, image_std)
```

### TRF017

Для классов, несущих как @auto_docstring, так и @dataclass, проверка выполняется в том порядке, в котором декораторы применяются снизу вверх: @dataclass, расположенный сверху, запускает @auto_docstring первым, на классе, у которого ещё нет синтезированного __init__. В результате он изменяет __init____doc__ родительского класса, а не дочернего.

```diff
-@dataclass
 @auto_docstring(
     custom_intro="""
     Output type of `AcmeForPreTraining`.
     """
 )
+@dataclass
 class AcmeForPreTrainingOutput(ModelOutput):
     ...
```

### TRF018

Проверяет, что каждый подкласс PreTrainedModel, переопределяющий `_init_weights(self, module, ...)`, вызывает родительский метод через `super()._init_weights(...)`. Модульные файлы также принимают маркеры `PreTrainedModel._init_weights(self, module)`, `PreTrainedModel._init_weights(module)` и `raise AttributeError(...)`. Для намеренного полного переопределения подавите предупреждение, добавив `# trf-ignore: TRF018` над методом. Базовый метод `_init_weights` покрывает стандартные типы модулей (Linear, Embedding, LayerNorm, RotaryEmbedding, ...). Пропуск этого вызова оставляет все подмодули, не затронутые переопределением, неинициализированными, что проходит тесты, но проявляется значительно позже как тонкий баг инициализации весов (см. https://github.com/huggingface/transformers/pull/45597).

```diff
from ... import initialization as init

 def _init_weights(self, module):
+    super()._init_weights(module)
     if isinstance(module, AcmeCustomLayer):
-        module.gate.data.zero_()
+        init.zeros_(module.gate)
```

### TRF019

Флаггирует непустое `_defaults` в TypedDict `*ProcessorKwargs` в файлах `processing_*.py`. Модели, выпущенные до даты отсечения, сохраняют прежний статус. Жёстко заданные `_defaults` разбрасывают конфигурацию процессора по исходному коду Python, их неудобно переопределять из конфигурации, и они раздувают код. В `processor_config.json` на хабе они хранятся вместе с чекпоинтом и могут обновляться без изменения кода.

```diff
class Gemma4ProcessorKwargs(ProcessingKwargs, total=False):
-    _defaults = {
-        "text_kwargs": {"padding": False},
-        "images_kwargs": {"return_tensors": "pt"},
-    }
     images_kwargs: Gemma4ImageProcessorKwargs
```

### TRF020

В каталогах моделей, в конфигурации которых объявлено `kv_lora_rank` (Multi-head Latent Attention), проверяется класс внимания, владеющий проекцией расширения KV LoRA (`kv_b_proj` или любой `nn.Linear(config.kv_lora_rank, ...)`): расширение должно находиться в отдельном методе (например, `expand_kv`), который вызывает `forward()`, а не быть встроено непосредственно в код. В модульных файлах учитывается метод, унаследованный от импортированного базового класса. Внешние бэкенды (vLLM/SGLang) переопределяют расширение, чтобы напрямую использовать сжатый KV-кэш. Если расширение встроено в `forward()`, переопределять нечего, и бэкенду приходится материализовать полный кэш, что сводит на нет экономию памяти, ради которой и существует MLA.

```diff
+    def expand_kv(self, k_nope, k_pe):
+        key_shape = (*k_nope.shape[:-1], -1, self.qk_nope_head_dim + self.v_head_dim)
+        k_nope = self.kv_b_proj(k_nope).view(key_shape).transpose(1, 2)
+        k_nope, value_states = torch.split(k_nope, [self.qk_nope_head_dim, self.v_head_dim], dim=-1)
+        k_pe = k_pe.expand(*k_nope.shape[:-1], -1)
+        key_states = torch.cat((k_nope, k_pe), dim=-1)
+        return key_states, value_states
+
     def forward(self, hidden_states, ...):
         ...
-        k_nope = self.kv_b_proj(k_pass).view(key_shape).transpose(1, 2)
-        k_nope, value_states = torch.split(k_nope, [self.qk_nope_head_dim, self.v_head_dim], dim=-1)
-        k_pe = k_rot.expand(*k_nope.shape[:-1], -1)
-        key_states = torch.cat((k_nope, k_pe), dim=-1)
+        key_states, value_states = self.expand_kv(k_pass, k_rot)
```

### TRF021

В файлах modeling_*.py и modular_*.py флаги `torch.tensor(<value>, ..., device=<non-cpu>)`, где `<value>` однозначно разрешается в скаляр Python — из числовых литералов и арифметических операций над ними, полей torch.finfo/iinfo, встроенных функций, возвращающих скаляр, вызовов math.*, локальных переменных, привязанных ровно один раз, self., присвоенных в теле класса, и полей конфигурации, аннотированных как int/float/bool в сопутствующем файле конфигурации (с учётом attribute_map). Всё, что может быть также последовательностью (`eos_token_id: int | list[int] | None`), или то, что не может быть разрешено, остаётся без изменений. __init__, _init_weights, __post_init__ и post_init исключены: они никогда не выполняются внутри области захвата. torch.tensor(, device=) материализует значение на хосте, а затем копирует его на устройство; захват графа CUDA запрещает такую копию, поэтому модель не может быть захвачена. torch.full((), , dtype=..., device=...) заполняет тот же тензор размерности 0 на устройстве с помощью захватываемого ядра и без синхронизации.

```diff
def get_placeholder_mask(self, input_ids, inputs_embeds):
     special_image_mask = (
         inputs_embeds
         == self.get_input_embeddings()(
-            torch.tensor(self.config.image_token_id, dtype=torch.long, device=inputs_embeds.device)
+            torch.full((), self.config.image_token_id, dtype=torch.long, device=inputs_embeds.device)
         )
     ).all(-1)
```

### TRF022

Проверяет, что каждая строка в списке `_no_split_modules` в modeling_*.py или modular_*.py указывает на класс, определённый в этом файле, импортированный в него или определённый в модуле-соседе той же директории модели. Дополняет TRF005, который проверяет только структуру значения. `device_map` сопоставляет эти строки с `module.__class__.__name__` во время выполнения, поэтому устаревшее или неправильно написанное имя не совпадает ни с чем и молча игнорируется — модуль, который должен оставаться вместе, всё равно может быть распределён по разным устройствам. Удаляйте записи, указывающие на классы другой модели, вместо того чтобы исправлять их: `post_init` уже собирает `_no_split_modules` из дочерних подмоделей.

```diff
class VideoLlavaPreTrainedModel(PreTrainedModel):
-    _no_split_modules = ["VideoLlavaVisionAttention"]
```

### TRF023

В файлах configuration_*.py и modular_*.py флаги `*Config` помечают поля, названные по аббревиатуре из исходной статьи, вместо канонического имени: d_model/n_embd -> hidden_size, d_ff/d_inner/ffn_dim/ffn_hidden_size/expansion_ratio -> intermediate_size, d_head -> head_dim, n_head/n_heads -> num_attention_heads, n_layer/n_layers/num_blocks -> num_hidden_layers. Поля считываются из тела класса, а также из присваиваний и значений по умолчанию в __init__/__post_init__. Неоднозначные, но идиоматичные имена (num_heads, num_layers, embed_dim, mlp_ratio) не помечаются, а модели, добавленные до cutoff_date, сохраняют свои имена. Всё, что обращается к форме модели, — планирование device_map, планы тензорного/пайплайн-параллелизма, квантование, PEFT, выбор бэкенда внимания, потребители `attribute_map` — использует канонические имена, поэтому конфигурация, использующая для одной и той же величины имя `d_model`, молча исключается из всех этих механизмов. В скрипте конвертации отображайте собственное написание имени в чекпоинте.

```diff
@strict(accept_kwargs=True)
 class AcmeConfig(PreTrainedConfig):
-    d_model: int = 1024
-    d_ff: int = 4096
-    n_heads: int = 16
-    n_layers: int = 24
+    hidden_size: int = 1024
+    intermediate_size: int = 4096
+    num_attention_heads: int = 16
+    num_hidden_layers: int = 24
```

### TRF024

В файлах modeling_*.py и modular_*.py флаг указывает на целочисленный литерал, превышающий 8, в аргументе размера (dimension) конструктора torch.nn (Linear, Embedding, LayerNorm, RMSNorm, GroupNorm, BatchNorm*, InstanceNorm*, Conv*d, ConvTranspose*d, Bilinear, MultiheadAttention), переданном по позиции или по имени (in_features, out_features, in_channels, out_channels, num_embeddings, embedding_dim, embed_dim, normalized_shape, num_channels, hidden_size). Аргументы, определяющие форму оператора (kernel_size, stride, padding, num_groups), игнорируются; литералы до 8 включительно сохраняют корректность скалярных выходов, бинарных классификаторов и количества каналов RGB. Модели, добавленные до cutoff_date, не подпадают под это правило. Жестко заданная ширина (hardcoded width) привязывает модуль к размеру одного конкретного чекпоинта: та же архитектура в другом масштабе будет загружена с несовпадением форм, а `from_pretrained` не сможет указать, какое именно значение неверно, так как ни одно поле конфигурации на него не ссылается. Кроме того, это разделяет источник истины (source of truth), из-за чего изменение конфигурации больше не влияет на собираемую модель.

```diff
class AcmeAtomEmbedding(nn.Module):
     def __init__(self, config):
         super().__init__()
-        self.proj = nn.Linear(768, 3072, bias=False)
-        self.norm = nn.LayerNorm(3072)
+        self.proj = nn.Linear(config.hidden_size, config.intermediate_size, bias=False)
+        self.norm = nn.LayerNorm(config.intermediate_size)
```

### TRF025

В файлах modeling_*.py и modular_*.py вызовы фабрики масок (точки входа masking_utils: create_causal_mask, create_bidirectional_mask, create_sliding_window_causal_mask, create_chunked_causal_mask, create_masks_for_generate, а также любые вспомогательные функции create_*_mask) находятся внутри класса, который не наследует от PreTrainedModel, — в обычных блоках nn.Module, таких как слои, модули внимания и энкодеры. Построение маски требует вычислительных затрат порядка O(квадрат длины последовательности), которые не зависят от конкретного слоя, поэтому создание маски внутри слоя приводит к тому, что эта цена оплачивается для каждого слоя отдельно, и каждый слой хранит собственную копию маски. В результате бэкендам внимания больше невозможно передать единую подготовленную маску. Постройте маску один раз в модели и передавайте её вниз по иерархии.

```diff
class AcmeLayer(nn.Module):
     def forward(self, hidden_states, attention_mask=None, **kwargs):
-        attention_mask = create_causal_mask(
-            config=self.config, input_embeds=hidden_states, attention_mask=attention_mask, ...
-        )
         return self.self_attn(hidden_states, attention_mask, **kwargs)

 class AcmeModel(AcmePreTrainedModel):
     def forward(self, input_ids=None, attention_mask=None, **kwargs):
+        causal_mask = create_causal_mask(
+            config=self.config, input_embeds=inputs_embeds, attention_mask=attention_mask, ...
+        )
         for layer in self.layers:
-            hidden_states = layer(hidden_states, attention_mask, **kwargs)
+            hidden_states = layer(hidden_states, causal_mask, **kwargs)
```

### TRF026

В файлах modeling_*.py и modular_*.py флаг присваивается классу, не являющемуся подклассом PreTrainedModel, который определяет только __init__ и forward, назначает ровно один self. в __init__, а тело forward состоит ровно из `return self.<attr>(...)` для него (начальный docstring игнорируется). Наличие любого другого метода, дополнительного атрибута, оператора перед return или вызова `super()` в forward означает, что класс выполняет собственную работу. Обёртка добавляет уровень к каждому имени веса, к _no_split_modules, планам параллелизма и каждому отображению преобразований, при этом не вычисляя ничего, — и читателю приходится открывать ещё один класс, чтобы это обнаружить. Подклассы PreTrainedModel освобождены от этого правила: они существуют для from_pretrained и автоматических классов, даже если forward лишь делегирует.

```diff
-class AcmeAtomTransformer(nn.Module):
-    def __init__(self, config):
-        super().__init__()
-        self.encoder = AcmeEncoder(config)
-
-    def forward(self, hidden_states, **kwargs):
-        return self.encoder(hidden_states, **kwargs)
-
 class AcmeModel(AcmePreTrainedModel):
     def __init__(self, config):
         super().__init__(config)
-        self.atom_transformer = AcmeAtomTransformer(config)
+        self.encoder = AcmeEncoder(config)
```

### TRF027

Флаггирует любое утверждение `assert` в modeling_*.py, modular_*.py и configuration_*.py. `python -O` удаляет утверждения, поэтому проверка формы или конфигурации, написанная в виде утверждения, молча исчезает в оптимизированных запусках. Кроме того, утверждение возвращает голый AssertionError, тогда как ValueError может указать проблемное значение и подсказать, что с ним делать.

```diff
def forward(self, hidden_states):
-    assert hidden_states.dim() == 3
+    if hidden_states.dim() != 3:
+        raise ValueError(f"Expected a 3D tensor, got shape {tuple(hidden_states.shape)}.")
```

### TRF028

Проверяет первые 25 строк файлов modeling_*.py, modular_*.py, configuration_*.py, processing_*.py, image_processing_*.py и video_processing_*.py на наличие строки `Licensed under the <name> License`, за которой следуют все пункты стандартного абзаца об отказе от гарантий, от `You may obtain a copy of the License at` до `limitations under the License.`. Сначала строки объединяются и приводятся к нижнему регистру, поэтому переносы строк и стиль комментариев не имеют значения. Название лицензии и строка с копирайтом не проверяются: они различаются для разных моделей. Файл, поставляемый без заголовка, оставляет его происхождение неоднозначным, а добавление заголовка позже потребует изменения уже выпущенного файла. Проверка только на `Apache License` позволила бы пропустить дефекты, которые действительно встречаются: абзац, обрванный на середине, заголовок, обрывающийся после URL, или заголовок, искажённый неудачной заменой.

```diff
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# ...
 """PyTorch Acme model."""
```

### TRF029

В файлах modeling_*.py и modular_*.py флаг поднимается, если `__init__` принимает `config` вместе с аргументом, имя которого однозначно указывает на поле конфигурации (hidden_size, num_attention_heads, intermediate_size, head_dim, num_hidden_layers, embed_dim, dropout, eps, patch_size, rope_theta, ...). Необязательный параметр со значением по умолчанию `None` не подпадает под это правило: это переопределение, а не второй источник истины, и именно так один класс MLP обслуживает и плотную, и экспертную ширину модели MoE. Жёстко заданное значение по умолчанию, например `hidden_size: int = 1024`, не является исключением — оно имеет приоритет над конфигурацией, если вызывающая сторона ничего не передаёт. kosmos2 внесён в белый список: его страница документации не может быть выведена из имени каталога, поэтому пороговое значение не может предоставить ему право на сохранение. Теперь у одного и того же числа есть два источника истины, и вызывающая сторона выбирает победителя, поэтому изменение конфигурации больше не влияет на создаваемую модель. Кроме того, это выносит знания об архитектуре во все места вызова, где им не место.

```diff
class AcmeAttention(nn.Module):
-    def __init__(self, config, embed_dim, num_heads, dropout):
+    def __init__(self, config, layer_idx=None):
         super().__init__()
-        self.embed_dim = embed_dim
-        self.num_heads = num_heads
+        self.embed_dim = config.hidden_size
+        self.num_heads = config.num_attention_heads

 class AcmeMLP(nn.Module):
     # an optional override is fine: omitting it reads the config
     def __init__(self, config, intermediate_size=None):
         super().__init__()
         self.intermediate_size = intermediate_size or config.intermediate_size
```

### TRF030

В файлах modeling_*.py и modular_*.py атрибутные цепочки, корневые узлы которых — `config` или `self.config`, имеют глубину три и более уровней. `config.hidden_size` (один переход) и `config.text_config.hidden_size` (два перехода, стандартный доступ к подконфигурации) допустимы. Одно нарушение на строку. Модуль, который обращается к `config.diffusion_config.atom_encoder_config.hidden_size`, связан со всей иерархией конфигурации, а не со своим собственным срезом, поэтому его невозможно переиспользовать, протестировать или заменить на другую подконфигурацию. Передайте вниз соответствующую подконфигурацию, и цепочка сократится до одного перехода.

```diff
class AcmeAtomEncoder(nn.Module):
     def __init__(self, config):
         super().__init__()
-        self.norm = AcmeLayerNorm(config.diffusion_config.atom_encoder_config.hidden_size)
+        self.norm = AcmeLayerNorm(config.hidden_size)
```

### TRF031

В файлах modeling_*.py и modular_*.py флаг поднимается на верхний уровень `@dataclass`, если среди его базовых классов нет ни одного, заканчивающегося на `Output`, при условии, что у него два или более обязательных поля — это внутренние наборы аргументов, которые `ModelOutput` отклоняет во время выполнения. Обычный dataclass для вывода не поддерживает индексацию как кортеж, не переживает `return_dict=False` и невидим для @auto_docstring, поэтому его поля никогда не попадают в сгенерированную документацию API. ModelOutput получает все три преимущества бесплатно.

```diff
@auto_docstring
 @dataclass
-class AcmeStructureOutput:
+class AcmeStructureOutput(ModelOutput):
     positions: torch.Tensor
     confidence: Optional[torch.Tensor] = None
```

### TRF032

В файлах modeling_*.py и modular_*.py флаги masked_fill, masked_fill_, full, full_like и new_full вызываются с отрицательным числовым литералом, модуль которого составляет 1e3 или более. Жёстко заданное значение -1e9 переполняется до -inf в float16 и далеко не является минимальным значением в float32, поэтому одна и та же маска ведёт себя по-разному в зависимости от типа данных и может приводить к появлению NaN после softmax. `torch.finfo(dtype).min` — это минимальное представимое значение для того типа данных, который фактически используется.

```diff
-attention_scores = attention_scores.masked_fill(~mask, -1e9)
+attention_scores = attention_scores.masked_fill(~mask, torch.finfo(attention_scores.dtype).min)
```

### TRF033

В файлах modeling_*.py и modular_*.py помечаются методы, имена которых начинаются с `set_`, за исключением методов контракта PreTrainedModel: set_input_embeddings, set_output_embeddings, set_decoder, set_encoder, set_attn_implementation и set_default_language. Сеттер делает поведение зависимым от порядка вызовов: значение не хранится в конфигурации, поэтому не сохраняется, не восстанавливается через from_pretrained и не учитывается при планировании device-map или параллелизма. Пользователи должны знать о необходимости его вызова, а его пропуск происходит без предупреждений.

```diff
class AcmeTriangleAttention(nn.Module):
-    def set_chunk_size(self, chunk_size):
-        self.chunk_size = chunk_size
+    def __init__(self, config):
+        super().__init__()
+        self.chunk_size = config.chunk_size
```

### TRF034

В файлах modeling_*.py и modular_*.py флаги локально определённые классы `*Layer`/`*Block`, инстанцируемые в `nn.ModuleList(...)`, которые не достигают `GradientCheckpointingLayer` через цепочку базовых классов; модульные файлы следуют относительным импортам в соседние модели, а неразрешённые цепочки являются неопределёнными. Вне области применения: модель, которая никогда не устанавливает `supports_gradient_checkpointing = True`, что приводит к исключению из `gradient_checkpointing_enable()` вместо пропуска слоя; слой, содержащий `nn.BatchNorm*`/`nn.InstanceNorm*`, статистика которого будет пересчитана дважды; и стек, который не является токеновым миксером модели, что показано наличием модуля внимания, модуляции, миксера или SSM, назначенного как `self.x = Y(...)`. `gradient_checkpointing_enable()` оборачивает слой только в том случае, если он является GradientCheckpointingLayer. Обычный nn.Module на стержне пропускается молча, поэтому обучение выглядит как с чекпоинтингом, но при этом выделяются полные активации, и OOM проявляется далеко от причины. В других местах — conv-бэкбон, декодирующая головка — компромисс остаётся на усмотрение автора, поэтому правило не распространяется на них.

```diff
-class AcmeDecoderLayer(nn.Module):
+class AcmeDecoderLayer(GradientCheckpointingLayer):
     def __init__(self, config, layer_idx):
         super().__init__()
```

### TRF035

Флаги `# noqa` (с кодами или без них) в modeling_*.py, modular_*.py и configuration_*.py. В модульных файлах допустимы `F401`, `F821` и `F822`: это источник генерации, который намеренно не определяет все используемые имена, поэтому семейство правил ruff об неопределённых именах срабатывает на корректном коде — записи в `__all__`, которые заполняет конвертер, классы, находящиеся в родительской модели, импорты, оставленные для повторного экспорта. `# noqa`, указывающий только эти коды, пропускается; если указаны другие коды, они сообщаются. Голый `# noqa` всегда сообщается; в модульных файлах сообщение требует указать код, а не переписать строку. Файлы моделей — это обычный код, подчиняющийся правилам линтера репозитория, поэтому подавление означает, что исходная проблема осталась в коде — а голый `# noqa` скрывает и все будущие нарушения на этой строке. Лучше исправить код.

```diff
-from ...modeling_utils import PreTrainedModel  # noqa: F401
+from ...modeling_utils import PreTrainedModel
```

### TRF036

В файлах modeling_*.py и modular_*.py флаги any `nn.Sequential(...)` конструирования. Sequential называет своих детей по позиции, поэтому веса попадают в `mlp.0.weight` и `mlp.2.weight`: отображение преобразования, _tied_weights_keys и каждый план параллелизма затем ссылаются на индексы, а вставка слоя переименовывает всё, что идёт после него. Кроме того, он скрывает forward, поэтому приведения dtype и остаточные связи между шагами невидимы там, где они происходят.

```diff
-        self.mlp = nn.Sequential(
-            nn.Linear(config.hidden_size, config.intermediate_size),
-            nn.GELU(),
-            nn.Linear(config.intermediate_size, config.hidden_size),
-        )
+        self.fc1 = nn.Linear(config.hidden_size, config.intermediate_size)
+        self.act = ACT2FN[config.hidden_act]
+        self.fc2 = nn.Linear(config.intermediate_size, config.hidden_size)
```

### TRF037

В файлах modeling_*.py и modular_*.py отслеживаются вызовы einsum, при этом уравнение выводится, если оно задано литералом. По умолчанию отключено: einsum иногда является наиболее ясным способом записи сокращения, поэтому это опциональная настройка, а не строгое правило. Уравнение einsum кодирует формы в нотации, которую читателю приходится расшифровывать, а динамически построенное уравнение скрывает, какое именно сокращение выполняется. Замените его на явные операции matmul/transpose.

```diff
-        pair_bias = torch.einsum("bqhc,bkhc->bhqk", query_states, key_states)
+        pair_bias = query_states.permute(0, 2, 1, 3) @ key_states.permute(0, 2, 3, 1)
```

### TRF038

Проверяет, что для каждого файла modeling_*.py, processing_*.py, image_processing_*.py, video_processing_*.py, feature_extraction_*.py и tokenization_*.py существует соответствующий файл tests/models//test_*.py (modeling_acme.py -> tests/models/acme/test_modeling_acme.py). Исключения: configuration_*.py, которые покрываются ConfigTester в сопутствующем файле test_modeling_*.py, и tokenization_utils*.py, вспомогательный модуль, покрываемый через его токенизатор; tokenization__fast.py соответствует файлу тестов своего «медленного» аналога. Файл modular_*.py может определять несколько семейств сразу, поэтому его классы маршрутизируются по суффиксу имени: XxxModel/XxxPreTrainedModel/XxxFor — modeling, XxxImageProcessor(Fast) — image processing, XxxProcessor — processing, XxxVideoProcessor — video processing, XxxFeatureExtractor — feature extraction, XxxTokenizer(Fast) — tokenization, XxxConfig — пропускается; при этом за каждый отсутствующий файл тестов выводится одно нарушение. `# trf-ignore: TRF038` не поддерживается; используйте `allowlist_models`, чтобы исключение было видно при ревью. Исходный файл без файла тестов не имеет регрессионного покрытия: сломанный прямой проход, неверное отображение при конвертации или токенизатор, теряющий специальный токен, могут попасть в код и оставаться сломанными неопределённо долго. Для проверки любого из них достаточно конфигурации с случайными весами или небольшого рукописного словаря.

```diff
src/transformers/models/acme/modeling_acme.py
+tests/models/acme/test_modeling_acme.py
 src/transformers/models/acme/tokenization_acme.py
+tests/models/acme/test_tokenization_acme.py
```

### TRF039

Находит блоки `if is_*_available(): import ...` (включая комбинации, такие как `is_vision_available() and is_torch_available()`) и помечает импорт, если имя не используется нигде else в файле, в том числе внутри строковых аннотаций типов и __all__. Проверка неиспользуемых импортов в ruff не убирает их: импорт достижим, поэтому блок сам по себе выглядит корректно. Когда после рефакторинга больше не нужны PIL.Image, torch и т. д., защищённый импорт остаётся как мёртвый код и вводит в заблуждение относительно реальных зависимостей файла.

```diff
if is_vision_available():
-    from PIL import Image
```

### TRF040

В modeling_*.py и modular_*.py флаги методы, декорированные как @capture_outputs, так и @can_return_tuple. Дополняет TRF003, который охватывает ручное ветвление return_dict в forward(). Оба декоратора удаляют return_dict, поэтому истинное значение видит только самый внешний из них. @capture_outputs уже обрабатывает преобразование to_tuple, что делает @can_return_tuple избыточным.

```diff
-@can_return_tuple
 @merge_with_config_defaults
 @capture_outputs
 @auto_docstring
 def forward(self, x):
     return AcmeModelOutput(last_hidden_state=x)
```

### TRF041

В файлах modeling_*.py и modular_*.py флаги ставятся на каждый `if`/`elif` и условное выражение, условие которого обращается к атрибуту `config.*` или `self.config.*` без комментария `# CODEPATH:`, который должен находиться на строке ветвления или в непрерывном блоке комментариев непосредственно над ней. Учитывается любой атрибут конфигурации, а не только булевы флаги. Исключения по структуре: `X if X is not None else fallback`, где проверяемое поле само является одним из результатов — `getattr(config, x, default)`, записанное в развёрнутом виде, что не может разветвить граф; а также защитный блок, `if` без `else`, тело которого только вызывает исключение или только выводит предупреждение/лог, поскольку одна сторона прерывает выполнение и ничего не расходится после неё. Просто упоминание None не является основанием для исключения: `config.vision_config is not None` всё равно требует пометки. Исключения по полю: инфраструктурные настройки фреймворка, которые не управляют расхождением контрольных точек — `problem_type`, выбирающий функцию потерь, `hidden_act`, ищущий функцию активации, `num_labels`, `use_cache`, `is_decoder`, идентификаторы специальных токенов, настройки головок `summary_*`; полный список — `DEFAULT_EXEMPT_ATTRIBUTES` в `mlinter/trf041.py`, расширяемый для каждого проекта через `ignored_attributes = [...]` в таблице правил. Модель может исключить одно из своих полей на весь файл с помощью модульного комментария `# trf-ignore: TRF041 config.scale_embedding, config.auxiliary_loss` в нулевой колонке (`self.config.x`, `config.x` и `x` — это одно и то же поле). В нём должно быть указано как минимум одно поле — голый `# trf-ignore: TRF041` сохраняет своё построчное значение — и условие пропускается только тогда, когда все поля, к которым оно обращается, исключены. Ветвление, управляемое конфигурацией, — это вторая архитектура в том же файле, и код не может сказать, достижимы ли обе половины — именно так экспериментальные ветви переживают релизы. Правило не запрещает ветвление: как `// SAFETY:` в Rust, оно требует, чтобы контрольные точки, проходящие по каждой стороне, были записаны рядом с ним. Ветвь, для которой никто не может назвать ни одной такой контрольной точки, — это ветвь, которую нужно удалить.

```diff
+        # CODEPATH: ESMC-6B ships pre-normalised embeddings, the 300M/600M checkpoints do not.
         if config.use_embedding_norm:
             hidden_states = self.embedding_norm(hidden_states)

-        if config.msa_encoder_enabled:
-            hidden_states = self.msa_encoder(hidden_states)
+        # no released checkpoint sets msa_encoder_enabled -> branch removed
```

### TRF042

В файле tests/models/*/test_tokenization_*.py проверяется, что файл определяет собранный тестовый класс, наследующийся от TokenizerTesterMixin. Учитываются только те классы, которые собирает раннер: базовый класс `TestCase` или именование `*Test`, если базовым классом является тестовый класс другой модели. Поэтому файлы, содержащие только вспомогательные функции, пропускаются, а вспомогательный класс, включающий в себя набор тестов, не соответствует правилу для реального тестового класса. Наследование отслеживается через базовые классы в том же файле и в тесты токенизатора другой модели, импортированные по имени; неразрешимый базовый класс никогда не учитывается. Ошибка сообщается для первого тестового класса, который не выполняет набор тестов. `auto` включен в белый список: test_tokenization_auto.py проверяет разрешение AutoTokenizer, а не токенизатор. Именно в TokenizerTesterMixin фактически проверяются циклическое кодирование/декодирование, отступы и усечение, обработка специальных токенов, сохранение добавленных токенов и эквивалентность при сохранении/загрузке. Тест, который лишь утверждает несколько вручную написанных списков идентификаторов токенов, проходит, даже если токенизатор сломан во всех этих случаях, и при этом выглядит протестированным при ревью.

```diff
-class AcmeTokenizationTest(unittest.TestCase):
+class AcmeTokenizationTest(TokenizerTesterMixin, unittest.TestCase):
+    tokenizer_class = AcmeTokenizer
+    test_slow_tokenizer = True
```

### TRF043

Флаг, указывающий на объявленный параметр position_ids в сигнатуре метода forward классов, имена которых заканчиваются на Attention. Параметр position_ids используется далее по цепочке в обучении без паддинга с flash-attention и должен передаваться через **kwargs. Если указать его в сигнатуре, он будет перехвачен до того, как интерфейс внимания сможет его прочитать; стандартный подход для Llama — передавать position_embeddings вместе с **kwargs.

```diff
class AcmeAttention(nn.Module):
     def forward(
         self,
         hidden_states,
         position_embeddings,
         attention_mask=None,
-        position_ids=None,
         **kwargs: Unpack[TransformersKwargs],
     ):
```

### TRF044

Флаггирует параметр с именем cache_position в любой функции в modeling_*.py и modular_*.py. cache_position был удалён из всех моделей в v5. Его повторное введение (обычно скопированное из исходников до v5) приводит к тому, что мёртвый аргумент проходит через каждый слой; обновление кэша выполняется как past_key_values.update(key_states, value_states, self.layer_idx), без передачи позиции.

```diff
def forward(
     self,
     hidden_states,
     past_key_values=None,
-    cache_position=None,
     **kwargs,
 ):
-    key_states, value_states = past_key_values.update(key_states, value_states, self.layer_idx, cache_position)
+    key_states, value_states = past_key_values.update(key_states, value_states, self.layer_idx)
```

### TRF045

Флаггирует устаревшие параметры output_attentions, output_hidden_states и return_dict в сигнатурах forward в modeling_*.py и modular_*.py. Модели, добавленные до даты отсечения, не подпадают под это правило. Управление выходными данными обеспечивает стек декораторов: @capture_outputs разрешает флаги output_* на основе конфигурации и записывает тензоры через _can_record_outputs, а @can_return_tuple обрабатывает return_dict. Их объявление в сигнатуре вновь вводит ручную передачу флагов, которая расходится с логикой декораторов.

```diff
+@capture_outputs
 def forward(
     self,
     input_ids,
-    output_attentions=None,
-    output_hidden_states=None,
-    return_dict=None,
     **kwargs: Unpack[TransformersKwargs],
 ):
```

### TRF046

Флаги присваиваний атрибутам self в методах forward в modeling_*.py и modular_*.py. Состояние, записываемое во время forward, нарушает батчинг, torch.compile и рассуждения о модуле. Передаваемое состояние передается явно (объекты cache, цикл generate); значения, зависящие только от config или статических форм, должны находиться в __init__.

```diff
def forward(self, hidden_states):
-    self.sequence_length = hidden_states.shape[1]
-    embeddings = self.compute_embeddings(self.sequence_length)
+    embeddings = self.compute_embeddings(hidden_states.shape[1])
```

### TRF047

Флаги присваиваний атрибутам self в методах preprocess, _preprocess, __call__ и post_process* в файлах image_processing_*.py и video_processing_*.py. Процессор, сохраняющий состояние между вызовами, нарушает пакетную обработку в сценарии «несколько preprocess, затем postprocess»: второй вызов preprocess перезаписывает состояние, необходимое для первого postprocess. Возвращайте значение или передавайте его через цепочку методов.

```diff
def _preprocess(self, images, **kwargs):
-    self.original_sizes = [image.shape[-2:] for image in images]
+    original_sizes = [image.shape[-2:] for image in images]
     ...
+    return BatchFeature(data={"pixel_values": pixel_values, "original_sizes": original_sizes})
```

### TRF048

Флаг для литералов list/tuple/set в объявлениях _tied_weights_keys на уровне класса. В v5 _tied_weights_keys было изменено на dict, который сопоставляет каждый связанный целевой параметр с его источником. Формат списка больше не указывает, какой параметр является источником, из-за чего связывание, вычисление device_map и сохранение молча работают некорректно.

```diff
class AcmeForCausalLM(AcmePreTrainedModel):
-    _tied_weights_keys = ["lm_head.weight"]
+    _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}
```

### TRF049

Флаги вызовов инициализации в методах __init__ в modeling_*.py и modular_*.py: примитивы nn.init.* / init.* и инициализаторы in-place для собственных параметров (self.weight.data.normal_()). Модели создаются на meta-устройстве, поэтому значения тензоров, записанные в __init__, отбрасываются до загрузки: параметр, инициализированный только там, содержит случайные данные при дообучении с нуля или после повторной загрузки с meta-устройства. Выделяйте память с помощью torch.empty в __init__, а инициализацию выполняйте в _init_weights.

```diff
class AcmeEmbeddings(nn.Module):
     def __init__(self, config):
         super().__init__()
         self.position_embedding = nn.Parameter(torch.empty(config.num_positions, config.hidden_size))
-        nn.init.trunc_normal_(self.position_embedding, std=config.initializer_range)

 class AcmePreTrainedModel(PreTrainedModel):
     def _init_weights(self, module):
         super()._init_weights(module)
+        if isinstance(module, AcmeEmbeddings):
+            init.trunc_normal_(module.position_embedding, std=self.config.initializer_range)
```

### TRF050

Флаги вызовы класса *RotaryEmbedding в __init__ классов, чьи имена заканчиваются на Attention. Модель владеет единственным rotary_emb, строит inv_freq один раз и передаёт cos/sin вниз как position_embeddings. Наличие отдельного модуля rotary в каждом слое внимания приводит к дублированию буферов, повторному вычислению частот для каждого слоя и отклонению от контракта, согласно которому внимание получает position_embeddings.

```diff
class AcmeAttention(nn.Module):
     def __init__(self, config, layer_idx):
         super().__init__()
-        self.rotary_emb = AcmeRotaryEmbedding(config)

 class AcmeModel(AcmePreTrainedModel):
     def __init__(self, config):
         super().__init__(config)
+        self.rotary_emb = AcmeRotaryEmbedding(config)
```

### TRF051

Сравнение флагов с атрибутом _attn_implementation в файлах modeling_*.py и modular_*.py. Диспетчеризация бэкендов должна выполняться в ALL_ATTENTION_FUNCTIONS.get_interface, а условная обработка тензоров, зависящая от бэкенда (padding, reshaping), — в общих обёртках под integrations/. Инлайновые ветвления делают тело модели зависимым от конкретного ядра и ломаются при регистрации новых бэкендов.

```diff
-if self.config._attn_implementation == "flash_attention_2":
-    attn_output = flash_path(query_states, key_states, value_states)
-else:
-    attn_output = eager_path(query_states, key_states, value_states)
+attention_interface = ALL_ATTENTION_FUNCTIONS.get_interface(self.config._attn_implementation, eager_attention_forward)
+attn_output, attn_weights = attention_interface(self, query_states, key_states, value_states, ...)
```

### TRF052

Флаг для модульных присваиваний имен, заканчивающихся на _ATTENTION_CLASSES, в файлах modeling_*.py и modular_*.py. Классы внимания для каждого бэкенда, выбираемые из словаря, — это идиома до введения интерфейса: практически идентичные классы расходятся, а ядра внимания с хаба, зарегистрированные в ALL_ATTENTION_FUNCTIONS, до них не доходят. Один класс внимания, диспетчеризующий вызовы через интерфейс, заменяет словарь; не распространяйте его из устаревшего родительского класса.

```diff
-ACME_ATTENTION_CLASSES = {
-    "eager": AcmeAttention,
-    "flash_attention_2": AcmeFlashAttention2,
-    "sdpa": AcmeSdpaAttention,
-}
+class AcmeAttention(nn.Module):
+    def forward(self, ...):
+        attention_interface = ALL_ATTENTION_FUNCTIONS.get_interface(self.config._attn_implementation, eager_attention_forward)
```

### TRF053

В файлах modeling_*.py и modular_*.py флаги присваиваний, которые формируют shift_logits/shift_labels (и варианты shifted_) с помощью среза, как в labels[..., 1:]. Получение уже сдвинутых меток (shift_labels = kwargs.pop("shift_labels", labels)) — это правильный идиоматический подход, и он не помечается. self.loss_function сдвигает метки самостоятельно, поэтому предварительный сдвиг в коде модели приводит к обучению на дважды сдвинутых целевых значениях или принуждает использовать собственный путь вычисления функции потерь. Модели только с декодером передают исходные метки и позволяют функции потерь выполнить сдвиг. Модели с энкодером-декодером представляют собой зеркальный случай: их метки уже сдвинуты благодаря добавленному в начало токену начала декодера, поэтому они передают shift_labels=labels, чтобы предотвратить повторный сдвиг в функции потерь.

```diff
if labels is not None:
-    shift_logits = logits[..., :-1, :].contiguous()
-    shift_labels = labels[..., 1:].contiguous()
-    loss = nn.functional.cross_entropy(shift_logits.view(-1, self.config.vocab_size), shift_labels.view(-1))
+    # decoder-only: labels are unshifted, the loss shifts them
+    loss = self.loss_function(logits=logits, labels=labels, vocab_size=self.config.vocab_size)
+    # encoder-decoder: labels are already shifted, hand them over as shift_labels
+    loss = self.loss_function(logits=logits, labels=labels, shift_labels=labels, vocab_size=self.config.vocab_size)
```

### TRF055

Флаги `config_class`, присваивание `config = SomeConfig`, класс `<Model>PreTrainedModel` без аннотации `config` и метод `__init__`, у которого аргумент `config` не имеет аннотации или ссылается на другой конфиг. Класс, создаваемый из подконфига (`AcmeTextModel(config.text_config)`), должен объявлять этот подконфиг. Файл `modular_*.py` проверяется через файлы, которые он генерирует. `PreTrainedModel` выводит `config_class` из аннотации `config`. Присваивание или вручную заданный `config_class` сохраняет значение родительского класса или отклоняется от него, а несоответствующий `__init__` собирает модель из одного конфига, тогда как декларируется другой.

```diff
class Gemma4VisionModel(Gemma4PreTrainedModel):
     """The Gemma 4 Vision Encoder."""
-    config = Gemma4VisionConfig
+    config: Gemma4VisionConfig

-    def __init__(self, config):
+    def __init__(self, config: Gemma4VisionConfig):
```

### TRF056

В файлах modeling_*.py и modular_*.py флаги `.item()` и `.tolist()` вызываются внутри любого `forward`. Вызов `.tolist()`, передающий аргумент размера разделения в `split(...)`, не учитывается: torch.split требует целые числа Python. Оба вызова считывают тензор на хост, что dynamo не может проследить, из-за чего граф прерывается.

```diff
-        for grid, item in zip(grid_thw.tolist(), split_items):
-            _, height, width = grid
-            merged.append(self.patch_merger(item, size=(height, width)))
+        for grid, item in zip(grid_thw, split_items):
+            merged.append(self.patch_merger(item, size=(grid[1], grid[2])))
```

### TRF057

Проверяет `@auto_docstring` для публичных подклассов `PreTrainedModel` (`<Model>PreTrainedModel`, `<Model>Model`, `<Model>For<Task>`, backbones), подклассов `PreTrainedConfig`, подклассов `ModelOutput`, image processors, video processors и подклассов `ProcessorMixin`, а также для их публичных методов `forward`, `get_image_features`, `get_video_features`, `get_audio_features`, `get_text_features`, `preprocess` и `__call__`. Файл `modular_*.py` проверяется по сравнению с файлами, сгенерированными из него. Без него класс и его методы поставляются без документации параметров, возвращаемых значений и примеров, которую затем приходится писать вручную для каждой модели.

```diff
+@auto_docstring
 @dataclass
 class AcmeModelOutputWithPast(ModelOutput):
     logits: torch.Tensor | None = None

+@auto_docstring
 class AcmeForConditionalGeneration(AcmePreTrainedModel):
+    @auto_docstring
     def forward(self, input_ids, pixel_values=None, **kwargs):
         ...
```

### TRF058

В файлах modeling_*.py и modular_*.py флаги `register_buffer("<name>", ...)` вызываются, когда имя буфера является строковым литералом, на любом получателе (`self` или другой модуль, например `layer.mamba`). Вычисленное имя — переменная или f-строка, например, один буфер на слой внутри цикла — не имеет эквивалента в виде присваивания атрибута и не подпадает под это правило. Так как в torch>=2.5 `nn.Buffer` регистрирует буфер через обычное присваивание атрибута, как и `nn.Parameter`. Буфер, созданный вызовом метода, существует только как побочный эффект выполнения `__init__`, поэтому модульный файл, который хочет изменить один из них, должен переопределить весь `__init__`. Присвоенный как атрибут, он может наследоваться и переопределяться независимо.

```diff
-        self.register_buffer("inv_freq", inv_freq, persistent=False)
-        self.register_buffer(
-            "position_ids", torch.arange(config.max_position_embeddings).expand((1, -1)), persistent=False
-        )
+        self.inv_freq = nn.Buffer(inv_freq, persistent=False)
+        self.position_ids = nn.Buffer(torch.arange(config.max_position_embeddings).expand((1, -1)), persistent=False)
```

### TRF059

Для каталогов моделей, в которых план tensor-parallel назначает `moe_tp_experts`, проверяется, что классы `*Experts` принимают скрытые состояния, индексы top-k и веса маршрутизации top-k в качестве первых трёх позиционных аргументов `forward`. Принимаются и алиасы, такие как `selected_experts` и `routing_weights`. `MoeExpertsParallel` применяет преобразование градиента к третьему позиционному аргументу. Если сигнатура отличается, преобразование будет применено к неверному тензору или пропущено без предупреждения.

```diff
class AcmeExperts(nn.Module):
-    def forward(self, hidden_states):
+    def forward(self, hidden_states, top_k_index, top_k_weights):
         ...
```

### TRF060

Флаги `from transformers... import X` и `import transformers...` под `src/transformers/models/` и предлагает относительную форму (`from ...modeling_utils import X`). Скрипты `convert_*.py` пропускаются. Абсолютный импорт внутри пакета проходит через ленивый верхнеуровневый `transformers/__init__.py`, что может привести к циклическим импортам и разрешиться в другую установленную копию transformers.

```diff
-from transformers.modeling_utils import PreTrainedModel
-from transformers.models.acme.configuration_acme import AcmeConfig
-from transformers import initialization as init
+from ...modeling_utils import PreTrainedModel
+from .configuration_acme import AcmeConfig
+from ... import initialization as init
```

### TRF061

In modular_*.py, flags a class whose base is defined earlier in the same file. Bases imported from another model, `<Model>PreTrainedModel` subclasses and backward-compatibility aliases are not flagged. The converter inlines bases imported from other models but keeps a same-file base, so the generated modeling file keeps the inheritance and its classes can no longer be read one at a time.

```diff
from ..llama.modeling_llama import LlamaDecoderLayer

 class AcmeDecoderLayer(LlamaDecoderLayer):
     pass

-class AcmeSparseDecoderLayer(AcmeDecoderLayer):
+class AcmeSparseDecoderLayer(LlamaDecoderLayer):
     def __init__(self, config, layer_idx):
         super().__init__(config, layer_idx)
         self.mlp = AcmeSparseMoeBlock(config)
```

### TRF062

Функции-инициализаторы `torch.nn.init` (например, `nn.init.normal_(...)`, независимо от способа импорта), вызванные внутри `_init_weights`, помечаются как изменяющие данные на месте. Вспомогательные функции, которые только вычисляют значение, такие как `calculate_gain`, не помечаются. Функции инициализации `init` в transformers пропускают тензоры, уже загруженные из чекпоинта. `torch.nn.init` полагается на патч, применяемый во время `from_pretrained`, однако функция, импортированная по имени, обходит этот патч, из-за чего загруженный вес может быть молча переинициализирован.

```diff
from torch import nn
+
+from ... import initialization as init

 def _init_weights(self, module):
     super()._init_weights(module)
     if isinstance(module, AcmeLayerScale):
-        nn.init.constant_(module.lambda1, self.config.layer_scale_init_value)
+        init.constant_(module.lambda1, self.config.layer_scale_init_value)
```

### TRF063

Каждый относительный импорт, выполняемый файлом модели при импорте, отслеживается, и система помечает случаи, когда импортируемые файлы требуют бэкенд, который не объявлен в импортирующем файле: через его базовые требования, самое слабое `@requires` среди его объектов `__all__` или через защиту `is_<backend>_available()`. Файл `modular_*.py` проверяется через файлы, которые он генерирует. Ленивый модуль импортирует файл, как только его объявленные бэкенды установлены. Если этот файл импортирует соседний файл, которому требуется больше, `from transformers import *` завершится с ошибкой в такой среде: процессор, работающий только с изображениями, который импортирует процессор изображений torchvision, ломает установки с Pillow, но без torch.

```diff
if is_vision_available():
-    from .image_processing_acme import AcmeImageProcessorKwargs
+    from .image_processing_pil_acme import AcmeImageProcessorKwargs
 
 @requires(backends=("vision",))
 class AcmeProcessor(ProcessorMixin):
```

### TRF064

В файлах processing_*.py и modular_*.py помечается подкласс `ProcessingKwargs`, который присваивает или переопределяет аннотации для `_defaults`, `text_kwargs`, `images_kwargs`, `videos_kwargs` или `audio_kwargs`. `ProcessingKwargs._defaults` устарел: значения по умолчанию являются атрибутами класса процессора и наследуются или переопределяются так же, как и любые другие. Поля модальностей сохраняют свои типы по умолчанию, поскольку доступные аргументы становятся известны только после загрузки подпроцессоров во время выполнения.

```diff
class AcmeProcessorKwargs(ProcessingKwargs, total=False):
-    images_kwargs: AcmeImagesKwargs
-    _defaults = {
-        "text_kwargs": {"padding": False},
-        "images_kwargs": {"num_crops": 4},
-    }
+    num_crops: int

 class AcmeProcessor(ProcessorMixin):
     valid_processor_kwargs = AcmeProcessorKwargs
+    text_kwargs = {"padding": False}
+    num_crops: int = 4
```

### TRF065

В файлах processing_*.py помечается любой класс, расширяющий `ImagesKwargs`, `TextKwargs`, `AudioKwargs` или `VideosKwargs`, напрямую или через подкласс другой модели. В файлах modular_*.py, которые также содержат подпроцессоры, подкласс допускается, если он называется `<Model>ImageProcessorKwargs`, `<Model>VideoProcessorKwargs`, `<Model>VideoProcessorInitKwargs` или `<Model>AudioProcessorKwargs`. Кwargs модальностей должны находиться в файлах подпроцессоров (`image_processing_*.py`, `video_processing_*.py`, ...). В файлах processing_*.py они остаются без типизации, поскольку подпроцессоры загружаются динамически.

```diff
-class AcmeImagesKwargs(ImagesKwargs, total=False):
-    num_crops: int
-
-
 class AcmeProcessorKwargs(ProcessingKwargs, total=False):
-    images_kwargs: AcmeImagesKwargs
+    num_crops: int
```

### TRF066

Флаг `@requires` с backends, которые повторяют неявные требования файла или, для метода, явные требования его внешнего класса. Также помечает `requires_backends(...)`, если его можно было записать в виде декоратора `@requires`, а также `@requires`, размещённый выше `@classmethod` или `@staticmethod`. Порог освобождает старые модели от всех проверок, кроме неправильно размещённого декоратора. Повторение требований к backends затрудняет понимание, какие зависимости метод действительно добавляет. Безусловная проверка в начале функции должна находиться в `@requires(backends=...)`, который раскрывает метаданные зависимостей и выполняет проверку при вызове функции. Оставляйте `requires_backends` для условных требований. `@requires` оборачивает обычную функцию, поэтому выше `@classmethod` или `@staticmethod` он оборачивает дескриптор, и каждый вызов вызывает `TypeError`: он должен находиться ниже них.

```diff
# image_processing_pil_acme.py already requires vision.
-@requires(backends=("vision", "torch"))
+@requires(backends=("torch",))
 class AcmeImageProcessorPil(PilBackend):
-    @requires(backends=("torch",))
     def post_process(self, outputs):
         return outputs

+    @requires(backends=("scipy",))
     def refine(self, outputs):
-        requires_backends(self, ["scipy"])
         return outputs
```

### TRF067

В файлах modeling_*.py и modular_*.py флаг включает получение всех скрытых состояний (`output_hidden_states=True` или его указание в `**kwargs`), если далее функция обращается только к `.hidden_states[...]` по индексу. Код, использующий весь кортеж (итерация, нарезка, стек или возврат), и бэкбоны с `@filter_output_hidden_states` не подпадают под это правило. Скрытое состояние каждого слоя остаётся в памяти до завершения вызова, поэтому пиковое потребление памяти растёт с глубиной. `output_hidden_states` также принимает индекс или список индексов и захватывает только их: декорируйте метод, передающий `**kwargs`, декоратором `@select_hidden_states`, либо передайте индекс напрямую.

```diff
+from ...utils.output_capturing import select_hidden_states
 ...
+    @select_hidden_states("vision_feature_layer")
     def get_image_features(self, pixel_values, vision_feature_layer=None, **kwargs):
-        kwargs["output_hidden_states"] = True
         image_outputs = self.vision_tower(pixel_values, return_dict=True, **kwargs)
         selected_image_feature = image_outputs.hidden_states[vision_feature_layer]
 ...
-        outputs = self.img_processor(img_embeds, output_hidden_states=True)
+        outputs = self.img_processor(img_embeds, output_hidden_states=self.layer_idx)
         return outputs.hidden_states[self.layer_idx]
```

### TRF068

Проверяет каждую запись `_no_split_modules` на соответствие классам, которые определяются или импортируются в файле моделирования. Файл `modular_*.py` проверяется через файлы, которые он генерирует на диске, поэтому перед линтингом необходимо выполнить перегенерацию. accelerate сопоставляет эти имена с именами классов подмодулей. Имя, которое не является классом, никогда не совпадает, поэтому слой может быть разделён между устройствами. Обычно это происходит из-за модульного файла, наследующего `_no_split_modules`: конвертер переименовывает префикс, а не класс.

```diff
class Qwen4ExpModel(Qwen3_5MoeModel):
-    # inherits ["Qwen3_5MoeDecoderLayer"] -> converted to "Qwen4ExpDecoderLayer", which does not exist
+    _no_split_modules = ["Qwen4ExpTextDecoderLayer"]
```

## Подавление нарушений

Если вам нужно подавить нарушение правила, используйте один из двух вариантов ниже.

### Подавление в строке

Добавьте комментарий `# trf-ignore: RULE_ID` на строке с нарушением. Включите объяснение, чтобы ревьюеры понимали, почему подавление обосновано.

```py
# trf-ignore: TRF011 — mask is derived from self.config, not the layer
hidden_states = layer(hidden_states, attention_mask=mask_from_config)
```

Не используйте `trf-ignore` для подавления нарушений, которые следует исправить в коде.

### `allowlist_models`

Для моделей с устаревшим кодом, который нельзя исправить сразу, добавьте имя каталога модели в список `allowlist_models` соответствующего правила в файле [mlinter rules.toml](https://github.com/huggingface/transformers-mlinter/blob/main/mlinter/rules.toml).

```toml
[rules.TRF004]
allowlist_models = ["existing_model", "your_model_name"]
```

