Transformers documentation
Правила структуры модели
Правила структуры модели
Transformers применяет набор статических правил к каждому файлу modeling_*.py, modular_*.py и configuration_*.py. Пакет mlinter предоставляет движок проверки, а активный набор правил репозитория хранится в utils/rules.toml. Этот локальный TOML позволяет быстро включать, отключать или настраивать правила, не дожидаясь выхода новой версии transformers-mlinter.
См. документацию mlinter для полного справочника по проверкам и подробностей использования.
Эти соглашения описывают ожидаемый формат кода моделирования при добавлении или изменении кода. Они обеспечивают единообразие кодовой базы и совместимость с такими функциями, как параллелизм по пайплайну, карты устройств и связывание весов.
Запуск средства проверки
make typing запускает mlinter вместе с проверщиком типов ty через обёртку репозитория, поэтому подхватывает utils/rules.toml. Запустите ту же обёртку напрямую с помощью следующих команд.
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 — самый быстрый вариант на этапе разработки. Он проверяет только те файлы, которые вы изменили относительно ветки main. Если вы вызываете mlinter напрямую, а не через обёртку, передайте --rules-toml utils/rules.toml, чтобы были применены локальные переопределения.
Исправление нарушения
При обнаружении нарушения правила ошибка выглядит следующим образом:
src/transformers/models/acme/modeling_acme.py:18: TRF013: AcmeModel.__init__ does not call self.post_init().Используйте идентификатор правила, чтобы найти исправление в справочнике по правилам. Правило TRF013 срабатывает, если подкласс PreTrainedModel не вызывает self.post_init(). Этот метод выполняет необходимые завершающие шаги, и его пропуск приводит к ошибкам во время выполнения.
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 является непустой строковой константой без пробельных символов. Некорректные префиксы могут нарушить сопоставление ключей при загрузке весов и доступ к базовой модели.
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.
-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.
-def tie_weights(self):
- self.lm_head.weight = self.emb.weight
+class AcmeForCausalLM(AcmePreTrainedModel):
+ _tied_weights_keys = ["lm_head.weight"]TRF005
Проверяет форму _no_split_modules, если она присутствует. Некорректные значения могут нарушить разделение по устройствам и шардирование.
-_no_split_modules = [SomeLayerClass, ""]
+_no_split_modules = ["AcmeDecoderLayer", "AcmeAttention"]TRF006
Проверяет, что аргументы кэша в сигнатуре метода forward используются в его теле. Неиспользуемый аргумент кэша указывает на неполную поддержку кэширования и непоследовательное поведение API.
def forward(self, x, past_key_values=None, use_cache=False):
+ if use_cache:
+ ...
return xTRF007
Проверяет присваивания атрибутам self после вызова self.post_init() в init. Изменение структуры модели после post_init обходит её инициализацию и завершающую обработку.
def __init__(self, config):
...
- self.post_init()
- self.proj = nn.Linear(...)
+ self.proj = nn.Linear(...)
+ self.post_init()TRF008
Проверяет, что add_start_docstrings для класса модели получает непустой аргумент. Пустой аргумент приводит к неясной документации API низкого качества.
-@add_start_docstrings("")
+@add_start_docstrings("The Acme model.")
class AcmeModel(AcmePreTrainedModel):
...TRF009
Flags imports into another model’s package from a model’s shipped implementation files: modeling*, configuration, processing_, imageprocessing, videoprocessing, featureextraction, tokenization_ and generation*.py. Three forms count: package path (from transformers.models.other.modeling_other import X), relative path (from ..other.configuration_other import X) and public API (from transformers import OtherModel) — for the last the owning directory is inferred from the class name and confirmed against the classes it defines, so an unresolvable name is left alone. Out of scope: `modular.py(building on another model is its purpose, and the converter flattens those imports away),convert_.py,init.pyand files underauto. Allowed targets: the model's own directory,autoandtimm_wrapper`. One model, one definition: model A’s behavior lives in its own files, and a change to model B must not silently change model A — for every file kind, not just modeling. Reach sub-configs through AutoConfig and CONFIG_MAPPING, and use a modular file to build on another model’s code.
-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.
+@strict(accept_kwargs=True)
class AcmeConfig(PreTrainedConfig):
...TRF011
В методе forward() подклассов PreTrainedModel флаги доступа к атрибутам подмодулей, которых не было бы у torch.nn.Identity: по переменным цикла, итерующим по self.layers, и по self.<submodule>.<attr>, где <attr> не является стандартным атрибутом nn.Module. Пайплайн-параллелизм может заменить любой подмодуль на torch.nn.Identity, поэтому чтение пользовательского атрибута (например, decoder_layer.attention_type) из него вызывает AttributeError во время выполнения. Читайте метаданные для каждого слоя из self.config.
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.
+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 выполняет критически важные завершающие действия (инициализация весов, настройка gradient checkpointing и т. д.); его пропуск приводит к тонким ошибкам во время выполнения.
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.
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 в сопутствующем файле конфигурации. Без этого поля пользователи не могут управлять связыванием весов: модель связывает веса безоговорочно, что нарушает циклы сериализации и дообучение с несвязанными головками.
# configuration_foo.py
@strict(accept_kwargs=True)
class FooConfig(PreTrainedConfig):
hidden_size: int = 768
+ tie_word_embeddings: bool = TrueTRF016
Если класс processing.py или videoprocessing.py объявляет булевы атрибуты do_* (do_resize, do_rescale, do_normalize, do_convert_rgb, …) и переопределяет preprocess() или _preprocess(), проверьте, что каждый флаг по-прежнему используется в них: ссылаются на него напрямую, делегируют через super().preprocess/_preprocess(…, **kwargs) или — только для процессоров изображений — передают через _preprocess_image_like_inputs/_prepare_image_like_inputs. do_sample_frames исключение: базовый preprocess() потребляет его до запуска _preprocess(). Флаг do_X, на который переопределение никогда не ссылается, является мёртвым: установка do_X=False не даёт эффекта, операция выполняется в любом случае, а переопределения на уровне вызова молча ломаются.
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, проверка @auto_docstring выполняется первой. Декораторы применяются снизу вверх, поэтому @dataclass, расположенный сверху, сначала запускает @auto_docstring для класса, у которого ещё нет синтезированного init: в результате он изменяет doc родительского init, а не дочернего.
-@dataclass
@auto_docstring(
custom_intro="""
Output type of `AcmeForPreTraining`.
"""
)
+@dataclass
class AcmeForPreTrainingOutput(ModelOutput):
...TRF018
Проверяет, что каждый подкласс _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).
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 на хабе они хранятся вместе с чекпоинтом и могут обновляться без изменения кода.
class Gemma4ProcessorKwargs(ProcessingKwargs, total=False):
- _defaults = {
- "text_kwargs": {"padding": False},
- "images_kwargs": {"return_tensors": "pt"},
- }
images_kwargs: Gemma4ImageProcessorKwargsTRF020
В каталогах моделей, в конфигурации которых объявлено 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.
+ 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
В файлах моделирования *.py и модульных .py флаги torch.tensor(<value>, ..., device=<non-cpu>), где <value> однозначно разрешается в скаляр Python — из числовых литералов и арифметических операций над ними, полей torch.finfo/iinfo, встроенных функций и вызовов math., возвращающих скаляр, локальных переменных, присвоенных ровно один раз, self.<attr>, присвоенных в теле класса, и полей конфигурации, аннотированных как int/float/bool в сопутствующем файле конфигурации (с учётом attribute_map). Всё, что может быть также последовательностью (eos_token_id: int | list[int] | None), или то, что не может быть разрешено, остаётся без изменений. init, _init_weights, post_init и post_init исключены: они никогда не выполняются внутри области захвата. torch.tensor(<python scalar>, device=<accelerator>) материализует значение на хосте, а затем копирует его на устройство; захват графа CUDA запрещает такую копию, поэтому модель не может быть захвачена. torch.full((), <value>, dtype=…, device=…) заполняет тот же тензор размерности 0 на устройстве с помощью захватываемого ядра и без синхронизации.
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 из дочерних подмоделей.
class VideoLlavaPreTrainedModel(PreTrainedModel):
- _no_split_modules = ["VideoLlavaVisionAttention"]TRF023
In configuration*.py and modular.py, flags `Configfields named after an upstream paper's abbreviation instead of the canonical name: 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. Fields are read from the class body and from __init__/__post_init__ assignments and defaults. Ambiguous but idiomatic names (num_heads, num_layers, embed_dim, mlp_ratio) are not flagged, and models added before cutoff_date keep theirs. Everything that reads a model's shape -- device_map planning, tensor/pipeline parallel plans, quantization, PEFT, attention-backend selection,attribute_mapconsumers -- looks up the canonical names, so a config spelling the same quantityd_model` silently opts out of all of them. Map the checkpoint’s own spelling in the conversion script.
@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 = 24TRF024
В файлах *.py и modular.py флаг отмечает целочисленный литерал, превышающий 8, в аргументе размерности конструктора torch.nn (Linear, Embedding, LayerNorm, RMSNorm, GroupNorm, BatchNorm, InstanceNorm, Convd, 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, не подпадают под проверку. Жёстко заданная ширина привязывает модуль к размеру одного конкретного чекпоинта: та же архитектура в другом масштабе будет загружена с несовпадением форм, а from_pretrained не сможет указать, какое именно значение неверно, поскольку ни одно поле конфигурации на него не ссылается. Кроме того, это разделяет источник истины, поэтому изменение конфигурации больше не влияет на создаваемую модель.
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
В файлах *.py и modular.py флаги вызывают обращение к фабрике масок (входные точки маскирования 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(квадрат длины последовательности), которые не зависят от конкретного слоя, поэтому создание маски внутри слоя приводит к тому, что эта цена оплачивается один раз для каждого слоя, и каждый слой владеет собственной маской, из-за чего бэкендам внимания больше невозможно передать единую подготовленную маску. Постройте её один раз в модели и передайте вниз.
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.<attr> в init и чьё тело forward состоит ровно из return self.<attr>(...) для него (начальный docstring игнорируется). Наличие любого другого метода, дополнительного атрибута, оператора перед return или вызова super() в forward означает, что класс выполняет собственную работу. Обёртка добавляет уровень к каждому имени веса, к _no_split_modules, планам параллелизма и каждому отображению преобразований, при этом не вычисляя ничего, — а читателю приходится открывать ещё один класс, чтобы это обнаружить. Подклассы PreTrainedModel исключены: они существуют для from_pretrained и auto-классов, даже если forward лишь делегирует.
-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 удаляет утверждения, поэтому проверка формы или конфигурации, написанная в виде assert, молча исчезает в оптимизированных запусках. Кроме того, assert возвращает голый AssertionError, тогда как ValueError может указать проблемное значение и подсказать, что с ним делать.
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 и videoprocessing.py на наличие строки Licensed under the <name> License, за которой следуют все пункты стандартного абзаца об отказе от гарантий, от You may obtain a copy of the License at до limitations under the License.. Перед проверкой строки объединяются и приводятся к нижнему регистру, поэтому переносы строк и стиль комментариев не имеют значения. Название лицензии и строка с копирайтом не проверяются: они различаются для разных моделей. Если файл поставляется без заголовка, его происхождение остаётся неопределённым, а добавление заголовка позже потребует изменения уже выпущенного файла. Проверка только на Apache License не позволила бы выявить реальные дефекты: абзац, обрванный на середине, заголовок, обрывающийся после URL, или заголовок, искажённый неудачной заменой.
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# ...
"""PyTorch Acme model."""TRF029
В файлах *.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 включён в белый список: его страница документации не может быть выведена из имени каталога, поэтому пороговое значение не может предоставить ему право на сохранение. Теперь у одного и того же числа есть два источника истины, и вызывающий код выбирает победителя, поэтому изменение конфигурации больше не влияет на создаваемую модель. Кроме того, это выносит знания об архитектуре во все места вызова, где им не место.
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_sizeTRF030
В файлах *.py и modular*.py атрибутные цепочки, корневые узлы которых — config или self.config, — не должны иметь глубину три и более уровней. config.hidden_size (один переход) и config.text_config.hidden_size (два перехода, обычный доступ к подконфигурации) допустимы. Одно нарушение на строку. Модуль, обращающийся к config.diffusion_config.atom_encoder_config.hidden_size, связан со всей иерархией конфигурации, а не со своим собственным срезом, поэтому его невозможно переиспользовать, протестировать или заменить на другую подконфигурацию. Передавайте соответствующую подконфигурацию вниз, и цепочка сократится до одного перехода.
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
В файлах *.py и modular*.py флаг поднимается на верхний уровень @dataclass, если среди его базовых классов нет ни одного, заканчивающегося на Output, при условии, что у него два или более обязательных поля — это внутренние наборы аргументов, которые ModelOutput отклоняет во время выполнения. Обычный dataclass для вывода не поддерживает индексацию как кортеж, не переживает return_dict=False и невидим для @auto_docstring, поэтому его поля никогда не попадают в сгенерированную документацию API. ModelOutput получает все три преимущества бесплатно.
@auto_docstring
@dataclass
-class AcmeStructureOutput:
+class AcmeStructureOutput(ModelOutput):
positions: torch.Tensor
confidence: Optional[torch.Tensor] = NoneTRF032
В файлах modeling*.py и modular*.py флаги maskedfill, masked_fill, full, full_like и new_full вызываются с отрицательным числовым литералом, модуль которого составляет 1e3 или более. Заданное жёстко значение -1e9 приводит к переполнению до -inf в float16 и далеко не является минимальным значением в float32, поэтому одна и та же маска ведёт себя по-разному в зависимости от типа данных и может порождать NaN после softmax. torch.finfo(dtype).min — это минимальное представимое значение для того типа данных, который фактически используется.
-attention_scores = attention_scores.masked_fill(~mask, -1e9)
+attention_scores = attention_scores.masked_fill(~mask, torch.finfo(attention_scores.dtype).min)TRF033
В модулях *.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 или параллелизма. Пользователи должны знать о необходимости их вызова, а пропуск вызова происходит без предупреждений.
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_sizeTRF034
In modeling*.py and modular.py, flags a locally-defined `Layer/Blockclass instantiated in annn.ModuleList(…)that does not reachGradientCheckpointingLayerthrough its base chain; modular files follow relative imports into sibling models, and unresolved chains are inconclusive. Out of scope: a model that never setssupports_gradient_checkpointing = True, which raises fromgradient_checkpointing_enable()instead of skipping a layer; a layer holdingnn.BatchNorm/nn.InstanceNorm*, whose statistics would be recomputed twice; and a stack that is not the model's token mixer, shown by an attention, modulation, mixer or SSM module assigned asself.x = Y(…).gradient_checkpointing_enable()` wraps a layer only if it is a GradientCheckpointingLayer. A plain nn.Module on the trunk is skipped silently, so training looks checkpointed while still allocating full activations, and the OOM surfaces far from the cause. Elsewhere — a conv backbone, a decode head — the trade is the author’s call, so the rule stays out.
-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 дополнительно скрывает все будущие нарушения на этой строке. Лучше исправить код.
-from ...modeling_utils import PreTrainedModel # noqa: F401
+from ...modeling_utils import PreTrainedModelTRF036
В файлах modeling*.py и modular*.py помечается любая конструкция nn.Sequential(...). Sequential именует дочерние слои по их позиции, поэтому веса оказываются в mlp.0.weight и mlp.2.weight: в результате отображение для конвертации, _tied_weights_keys и каждый план параллелизма ссылаются на индексы, а вставка слоя переименовывает всё, что идёт после него. Кроме того, Sequential скрывает forward, из-за чего приведение dtype и остаточные соединения между шагами остаются невидимыми в том месте, где они выполняются.
- 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.
- 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, imageprocessing.py, videoprocessing.py, featureextraction.py и tokenization*.py существует соответствующий файл tests/models/<model>/test.py (modelingacme.py -> tests/models/acme/test_modeling_acme.py). Исключения: configuration.py, который покрывается ConfigTester в сопутствующем файле testmodeling.py, и tokenization_utils.py — вспомогательный модуль, покрываемый через его tokenizer; tokenization<name>_fast.py соответствует файлу тестов своей «медленной» версии. Модульный*.py может определять несколько семейств сразу, поэтому его классы распределяются по суффиксу имени — XxxModel/XxxPreTrainedModel/XxxFor<Task> для modeling, XxxImageProcessor(Fast) для image processing, XxxProcessor для processing, XxxVideoProcessor для video processing, XxxFeatureExtractor для feature extraction, XxxTokenizer(Fast) для tokenization, XxxConfig пропускается — и одно нарушение сообщается для каждого отсутствующего файла тестов. # trf-ignore: TRF038 не поддерживается; используйте allowlist_models, чтобы исключение было видно при ревью. Исходный файл без файла тестов не имеет регрессионного покрытия: сломанный forward pass, неверное отображение при конвертации или tokenizer, теряющий специальный токен, могут попасть в код и оставаться сломанными неопределённо долго. Демонстрационного конфигурационного файла со случайными весами или небольшого рукописного словаря достаточно, чтобы проверить любой из этих сценариев.
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.pyTRF039
Находит блоки вида if is_*_available(): import ... (включая комбинации, например is_vision_available() and is_torch_available()) и помечает импорт, если имя не используется нигде else в файле, в том числе внутри строковых аннотаций типов и all. Проверка неиспользуемых импортов в ruff не убирает такие блоки: импорт достижим, поэтому сам по себе блок выглядит корректно. Когда после рефакторинга больше не нужны PIL.Image, torch и т. д., защищённый импорт остаётся как мёртвый код и вводит в заблуждение относительно реальных зависимостей файла.
if is_vision_available():
- from PIL import ImageTRF040
В модулях modeling*.py и modular*.py методы, декорированные одновременно @capture_outputs и @can_return_tuple. Дополняет правило TRF003, которое охватывает ручное ветвление по return_dict в forward(). Оба декоратора удаляют return_dict, поэтому истинное значение видит только самый внешний из них. @capture_outputs уже выполняет преобразование to_tuple, что делает @can_return_tuple избыточным.
-@can_return_tuple
@merge_with_config_defaults
@capture_outputs
@auto_docstring
def forward(self, x):
return AcmeModelOutput(last_hidden_state=x)TRF041
In modeling*.py and modular.py, flags every if/elif and conditional expression whose condition reads a `config.orself.config.attribute without a# CODEPATH:comment, accepted on the branch line or in the contiguous comment block directly above it. Any config attribute counts, not just boolean flags. Exempt by structure:X if X is not None else fallback, where the tested field is itself one of the results --getattr(config, x, default)spelled long, which cannot fork the graph; and a guard, anifwith noelsewhose body only raises or only warns/logs, since one side aborts and nothing diverges past it. Merely mentioning None does not qualify:config.visionconfig is not Nonestill owes a note. Exempt by field: framework plumbing that gates no checkpoint divergence --problem_typeselecting a loss,hidden_actlooking up an activation,num_labels,use_cache,is_decoder, the special token ids, thesummaryhead settings; the full list isDEFAULT_EXEMPT_ATTRIBUTESinmlinter/trf041.py, extended per project byignored_attributes = […]on the rule table. A model exempts one of its own fields file-wide with a module-level# trf-ignore: TRF041 config.scale_embedding, config.auxiliary_lossat column 0 (self.config.x,config.xandxare the same field). It must name at least one field -- a bare# trf-ignore: TRF041keeps its per-line meaning -- and a condition is skipped only when every field it reads is exempt. A config-gated branch is a second architecture in the same file, and the code cannot say whether both halves are still reachable -- which is how dead experimental branches survive for releases. The rule does not forbid the branch: like Rust's// SAFETY:`, it asks for the checkpoints taking each side to be written down next to it. A branch nobody can name one for is a branch to delete.
+ # 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 removedTRF042
In tests/models//testtokenization.py, checks the file defines a collected test class inheriting TokenizerTesterMixin. Only classes the runner collects count — a TestCase base, or the *Test naming convention when the base is another model’s test class — so helper-only files are skipped, and a helper mixing in the suite does not satisfy the rule for a real test class. Inheritance is followed through bases in the same file and into another model’s tokenizer test imported by name; an unresolvable base never counts. Reported on the first test class that does not run the suite. auto is allowlisted: test_tokenization_auto.py tests AutoTokenizer resolution, not a tokenizer. TokenizerTesterMixin is where encode/decode round-tripping, padding and truncation, special-token handling, added-token persistence and save/load equivalence are actually checked. A test that only asserts a few hand-written token id lists passes while the tokenizer is broken in every one of them, and still looks tested in review.
-class AcmeTokenizationTest(unittest.TestCase):
+class AcmeTokenizationTest(TokenizerTesterMixin, unittest.TestCase):
+ tokenizer_class = AcmeTokenizer
+ test_slow_tokenizer = TrueTRF043
Флаг, указывающий на объявленный параметр position_ids в сигнатуре метода forward классов, чьё имя заканчивается на Attention. Параметр position_ids используется ниже по цепочке при обучении с использованием flash-attention без padding и должен передаваться через kwargs. Если он указан в сигнатуре, он перехватывается до того, как интерфейс attention сможет его прочитать; стандартный подход для Llama — передавать position_embeddings вместе сkwargs.
class AcmeAttention(nn.Module):
def forward(
self,
hidden_states,
position_embeddings,
attention_mask=None,
- position_ids=None,
**kwargs: Unpack[TransformersKwargs],
):TRF044
Флаггирует параметр с именем position в любой функции в modeling.py и modular_.py. cache_position был удалён из всех моделей в v5. Его повторное введение (обычно скопированное из исходников до v5) приводит к тому, что мёртвый аргумент проходит через каждый слой; обновление кэша выполняется как past_key_values.update(key_states, value_states, self.layer_idx), без передачи position.
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
Флаггирует устаревшие параметры attentions, output_hidden_states и return_dict в сигнатурах forward в modeling.py и modular_.py. Модели, добавленные до даты отсечения, не подпадают под это правило. Управление выходом обеспечивает стек декораторов: @captureoutputs сопоставляет флаги output* с конфигурацией и записывает тензоры через _can_record_outputs, а @can_return_tuple обрабатывает return_dict. Их объявление в сигнатуре приводит к повторному введению ручной передачи флагов, которая расходится с логикой декораторов.
+@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.
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 и videoprocessing.py. Процессор, сохраняющий состояние между вызовами, нарушает батчинг по схеме «несколько preprocess, затем postprocess»: второй вызов preprocess перезаписывает состояние, необходимое первому postprocess. Возвращайте значение или передавайте его через цепочку методов.
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 и сохранение молча работают некорректно.
class AcmeForCausalLM(AcmePreTrainedModel):
- _tied_weights_keys = ["lm_head.weight"]
+ _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}TRF049
Флаги вызовов init в методах init в modeling*.py и modular.py: примитивы nn.init. / init.* и инициализаторы in-place для собственных параметров (self.weight.data.normal_()). Модели создаются на meta-устройстве, поэтому значения тензоров, записанные в init, отбрасываются до загрузки: параметр, инициализированный только там, содержит случайные данные при дообучении с нуля или после повторной загрузки с meta-устройства. Выделяйте память с помощью torch.empty в init, а инициализацию выполняйте в _init_weights.
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.
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/. Встроенные ветвления делают тело модели зависимым от конкретного ядра и ломаются при регистрации новых бэкендов.
-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, до них не доходят. Один класс внимания, диспетчеризующий вызовы через интерфейс, заменяет словарь; не наследуйте его от устаревшего родительского класса.
-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 флаги присваиваний, которые формируют shiftlogits/shift_labels (и сдвинутые варианты) с помощью среза, например labels[…, 1:]. Получение уже сдвинутых меток (shift_labels = kwargs.pop(“shift_labels”, labels)) — это правильный идиоматический подход, и он не помечается. self.loss_function сдвигает метки самостоятельно, поэтому предварительный сдвиг в коде моделирования приводит к обучению на дважды сдвинутых целевых значениях или принуждает использовать собственный путь вычисления функции потерь. Модели только с декодером передают исходные метки и позволяют функции потерь сдвинуть их. Модели с энкодером-декодером представляют собой зеркальный случай: их метки уже сдвинуты благодаря добавленному в начало токену начала декодера, поэтому они передают shift_labels=labels, чтобы предотвратить повторный сдвиг в функции потерь.
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__ собирает модель из одного конфига, тогда как декларируется другой.
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 не может проследить, из-за чего граф разрывается.
- 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 проверяется по сравнению с файлами, сгенерированными из него. Без него класс и его методы поставляются без документации параметров, возвращаемых значений и примеров, которую затем приходится писать вручную для каждой модели.
+@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__. Если буфер присвоен как атрибут, его можно наследовать и переопределять независимо.
- 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 применяет преобразование градиента к третьему позиционному аргументу. Если сигнатура отличается, преобразование будет применено к неверному тензору или пропущено без предупреждения.
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.
-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 initTRF061
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.
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, однако функция, импортированная по имени, обходит этот патч, из-за чего загруженный вес может быть молча переинициализирован.
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.
if is_vision_available():
- from .image_processing_acme import AcmeImageProcessorKwargs
+ from .image_processing_pil_acme import AcmeImageProcessorKwargs
@requires(backends=("vision",))
class AcmeProcessor(ProcessorMixin):TRF064
При обработке *.py и модульных *.py обнаруживается подкласс ProcessingKwargs, который назначает или переопределяет аннотации для _defaults, text_kwargs, images_kwargs, videos_kwargs или audio_kwargs. ProcessingKwargs._defaults устарел: значения по умолчанию являются атрибутами класса процессора и наследуются или переопределяются так же, как и любые другие. Поля модальностей сохраняют свои типы по умолчанию, поскольку доступные аргументы становятся известны только после загрузки подпроцессоров во время выполнения.
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 = 4TRF065
При обработке*.py любой класс, расширяющий ImagesKwargs, TextKwargs, AudioKwargs или VideosKwargs, напрямую или через подкласс другой модели, будет отмечен. В модульном.py, который также содержит подпроцессоры, подкласс допустим, если он называется <Model>ImageProcessorKwargs, <Model>VideoProcessorKwargs, <Model>VideoProcessorInitKwargs или <Model>AudioProcessorKwargs. Параметры модальности должны находиться в файлах подпроцессоров (`imageprocessing.py,videoprocessing.py`, …). В processing_.py они остаются без типизации, поскольку подпроцессоры загружаются динамически.
-class AcmeImagesKwargs(ImagesKwargs, total=False):
- num_crops: int
-
-
class AcmeProcessorKwargs(ProcessingKwargs, total=False):
- images_kwargs: AcmeImagesKwargs
+ num_crops: intTRF066
Флаг @requires с backends, которые повторяют неявные требования файла или, для метода, явные требования его внешнего класса. Также помечает requires_backends(...), если его можно было записать в виде декоратора @requires, а также @requires, размещённый выше @classmethod или @staticmethod. Порог освобождает старые модели от всего, кроме неправильно размещённого декоратора. Повторение требований к backends затрудняет понимание, какие зависимости метод действительно добавляет. Безусловная проверка в начале функции должна находиться в @requires(backends=...), который раскрывает метаданные зависимостей и выполняет проверку при вызове функции. Оставляйте requires_backends для условных требований. @requires оборачивает обычную функцию, поэтому выше @classmethod или @staticmethod он оборачивает дескриптор, и каждый вызов вызывает TypeError: он должен находиться ниже них.
# 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 outputsTRF067
В модулях *.py и modular*.py флаг помечает вызов, при котором включается вывод всех скрытых состояний (output_hidden_states=True или его установка в **kwargs), если далее функция обращается только к .hidden_states[...] по индексу. Код, использующий весь кортеж (итерация, нарезка, стек или возврат), и бэкбоны с @filter_output_hidden_states не подпадают под это правило. Скрытое состояние каждого слоя остаётся в памяти до завершения вызова, поэтому пиковое потребление памяти растёт с глубиной. Параметр output_hidden_states также принимает индекс или список индексов и захватывает только их: декорируйте метод, передающий **kwargs, декоратором @select_hidden_states, либо передайте индекс напрямую.
+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: конвертер переименовывает префикс, а не класс.
class Qwen4ExpModel(Qwen3_5MoeModel):
- # inherits ["Qwen3_5MoeDecoderLayer"] -> converted to "Qwen4ExpDecoderLayer", which does not exist
+ _no_split_modules = ["Qwen4ExpTextDecoderLayer"]Подавление нарушений
Если вам нужно подавить нарушение правила, используйте один из двух вариантов ниже.
Подавление в строке
Добавьте комментарий # trf-ignore: RULE_ID на строке с нарушением. Включите объяснение, чтобы ревьюеры понимали, почему подавление обосновано.
# 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.
[rules.TRF004]
allowlist_models = ["existing_model", "your_model_name"]