模型结构规则
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 标志是开发期间最快的选项。它仅检查相对于主分支你所修改的文件。如果你直接调用 mlinter 而不是使用包装器,请传入 --rules-toml utils/rules.toml 以应用本地覆盖设置。
修复违规
当检测到规则违规时,错误信息如下所示:
src/transformers/models/acme/modeling_acme.py:18: TRF013: AcmeModel.__init__ does not call self.post_init().使用规则 ID 在 规则参考 中查找对应的修复方法。当 PreTrainedModel 的子类未调用 self.post_init() 时,会触发 TRF013。该方法会执行必要的最终化步骤,省略它会导致运行时错误。
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 是否为非空且不含空白字符的字符串字面量。无效的 prefix 可能会破坏权重加载的键映射以及基础模型的访问。
class AcmePreTrainedModel(PreTrainedModel):
- base_model_prefix = ""
+ base_model_prefix = "model"TRF003
标记 forward 中旧的 if not return_dict: return (x,) 模式。手动进行 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
检查 init 中在 self.post_init() 之后对 self 属性的赋值。在 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
检查 *.py 和 modular*.py 中直接继承自 PreTrainedConfig/PretrainedConfig 的子类是否带有 @strict(accept_kwargs=True)。如果缺少该装饰器,新的配置将不符合仓库的运行时类型验证约定,并偏离基于 dataclass 的配置标准。
+@strict(accept_kwargs=True)
class AcmeConfig(PreTrainedConfig):
...TRF011
在 PreTrainedModel 子类的 forward() 中,对循环变量(遍历 self.layers)以及 self.<submodule>.<attr>(其中 <attr> 不是标准的 nn.Module 属性)进行标志子模块属性访问时,torch.nn.Identity 不会具备这些属性。流水线并行可能会将任意子模块替换为 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
Flags in-place ops (.normal(), .zero(), …) on module weights inside _init_weights. Parameters carry internal flags tracking whether they still need re-initialization; in-place ops bypass them. Use the init primitives.
+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
检查每个定义了 init 的 PreTrainedModel 子类是否调用了 self.post_init()。在模块化文件中,super().init() 也算作有效调用,因为它会传播父类的 post_init。post_init 负责关键的最终初始化工作(权重初始化、梯度检查点设置等);跳过它会导致难以察觉的运行时错误。
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 或视频processing.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:因此它会修改父类的 init 的 doc,而不是子类的。
-@dataclass
@auto_docstring(
custom_intro="""
Output type of `AcmeForPreTraining`.
"""
)
+@dataclass
class AcmeForPreTrainingOutput(ModelOutput):
...TRF018
检查每个重写了 _init_weights(self, module, ...) 的 PreTrainedModel 子类是否通过 super()._init_weights(...) 进行链式调用。模块化文件还接受哨兵 PreTrainedModel._init_weights(self, module)、PreTrainedModel._init_weights(module) 以及 raise AttributeError(...)。如果是有意进行完全重写,请在方法上方使用 # trf-ignore: TRF018 来抑制该检查。基类的 _init_weights 涵盖了标准模块类型(Linear、Embedding、LayerNorm、RotaryEmbedding 等)。跳过它会导致重写中遗漏的所有子模块保持未初始化状态——这能通过测试,但稍后会以微妙的权重初始化 bug 的形式暴露出来(参见 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
标记 processing_*.py 中 *ProcessorKwargs TypedDict 上非空的 _defaults。在截止日期之前发布的模型可豁免此规则。硬编码的 _defaults 会将处理器配置分散在 Python 源代码中,难以从 config 中覆盖,且会使代码臃肿。而在 Hub 上的 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 和 modular.py 中,标记 torch.tensor(<value>, ..., device=<non-cpu>),其中 <value> 可证明解析为 Python 标量——来自数字字面量及其算术运算、torch.finfo/iinfo 字段、返回标量的内置函数和 math. 调用、恰好绑定一次的局部变量、在类体中赋值的 self.<attr>,以及伴随配置文件中(遵循 attribute_map)标注为 int/float/bool 的配置字段。任何可能也是序列(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
在 modeling*.py 和 modular.py 中,标记 torch.nn 构造函数(Linear、Embedding、LayerNorm、RMSNorm、GroupNorm、BatchNorm、InstanceNorm、Convd、ConvTranspose*d、Bilinear、MultiheadAttention)维度参数中大于 8 的整数字面量,无论是位置参数还是关键字参数(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 之前添加的模型不受此限制。硬编码的宽度会将模块固定到某一个 checkpoint 尺寸:同一架构在其他规模下加载时会出现形状不匹配,而 from_pretrained 无法指出哪个值有误,因为没有任何 config 字段指向它。这还会分裂真实来源,导致修改 config 后构建出的模型不再随之改变。
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 中,当某个未继承自 PreTrainedModel 的类(例如 layers、attention modules 和 encoders 等普通的 nn.Module 块)内部调用 mask 工厂(即 maskingutils 入口点 create_causal_mask、create_bidirectional_mask、create_sliding_window_causal_mask、create_chunked_causal_mask、create_masks_for_generate,以及任何 create_mask 辅助函数)时,会触发此警告。掩码构建是 O(序列长度平方) 级别的工作,且不随层数变化,因此在每一层中构建掩码意味着每层都要支付一次该成本,并且每层都会拥有自己的掩码,导致 attention 后端无法再接收一个统一准备好的掩码。应在模型中构建一次,然后向下传递。
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 中,标记那些仅定义了 init 和 forward 的非 PreTrainedModel 类,其中 init 恰好分配了一个 self.<attr>,且 forward 的主体恰好是 return self.<attr>(...)(开头的 docstring 会被忽略)。如果 forward 中存在任何其他方法、额外属性、return 之前的语句或 super() 调用,则意味着该类执行了自身的工作。该包装器会为每个权重名称、_no_split_modules、并行化方案以及每个转换映射增加一层,同时不执行任何计算——而读者必须打开另一个类才能发现这一点。PreTrainedModel 的子类除外:即使 forward 仅进行委托,它们也存在于 from_pretrained 和 auto 类中。
-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 可以指明出错的值并说明应如何处理。
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
检查 modeling*.py、modular.py、configuration_.py、processing*.py、image_processing.py 和 videoprocessing.py 的前 25 行,查找 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
在 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 这样的硬编码默认值则不在豁免之列——当调用方未传入任何值时,它会优先于 config 生效。kosmos2 被列入白名单:其文档页面无法从目录名推导得出,因此截止日期规则无法将其纳入豁免范围。现在同一个数值存在两个事实来源,由调用方决定哪个生效,因此修改 config 不再会改变最终构建的模型。此外,这还将架构知识外溢到了每一个调用点,而这些本不属于调用点的职责。
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
在 modeling*.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
在 modeling*.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 中,以绝对值大于等于 1e3 的取反数值字面量调用 maskedfill、masked_fill、full、full_like 和 new_full。硬编码的 -1e9 在 float16 中会溢出为 -inf,且远非 float32 中的最小值,因此同一掩码在不同 dtype 下表现不同,并在 softmax 之后可能产生 NaN。torch.finfo(dtype).min 是实际运行 dtype 所能表示的最小值。
-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_ 开头的方法被标记为 flags,但 PreTrainedModel 契约方法 set_input_embeddings、set_output_embeddings、set_decoder、set_encoder、set_attn_implementation 和 set_default_language 除外。setter 会使行为依赖于调用顺序:该值不在 config 中,因此不会被保存,不会被 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 中。在 modular 文件中,F401、F821 和 F822 是被接受的:该文件是生成源,有意不定义其使用的每个名称,因此 ruff 的未定义名称类规则会在正确的代码上触发——例如转换器填充的 __all__ 条目、位于父模型中的类,以及为了重新导出而保留的导入。仅指定这些代码的 # noqa 会被跳过;指定其他任何代码的注释则会在剩余的代码上被报告。裸的 # noqa 始终会被报告;在 modular 文件中,提示信息要求提供具体的代码,而不是重写。模型文件是受仓库 lint 规则约束的普通代码,因此抑制意味着底层问题仍然存在——而且裸的 # 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 以及每个并行化方案都会引用这些索引,而插入一个层会重命名其后所有层。此外,它还隐藏了 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,由配套的 testmodeling.py 中的 ConfigTester 覆盖;以及 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、错误的转换映射,或丢弃特殊 token 的 tokenizer 都可能被合并并长期保持损坏状态。一个带有随机权重的 dummy config,或一个小型手写词汇表,就足以测试其中任何一项。
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() 等组合),并在该名称在文件的其他位置(包括字符串类型提示和 all 内部)未被引用时,标记该导入。ruff 的未使用导入检查无法清理这些代码:由于该导入是可访问的,因此该代码块本身看起来没有问题。一旦重构后不再需要 PIL.Image、torch 等,受保护的导入就会作为无用的冗余代码残留下来,并对文件的实际依赖关系产生误导。
if is_vision_available():
- from PIL import ImageTRF040
在 modeling*.py 和 modular*.py 中,标记了同时使用 @capture_outputs 和 @can_return_tuple 装饰的方法。这与 TRF003 形成互补,后者涵盖 forward() 中手动进行 return_dict 分支处理的情况。由于两个装饰器都会弹出 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
在 tests/models//testtokenization.py 中,检查该文件是否定义了一个继承自 TokenizerTesterMixin 的被收集测试类。只有 runner 收集的类才计入——即 TestCase 基类,或者当基类是另一个模型的测试类时采用 *Test 命名约定——因此仅包含辅助函数的文件会被跳过,而混入该测试套件的辅助类也不满足真实测试类的规则。继承关系会沿着同一文件中的基类以及按名称导入的另一个模型的 tokenizer 测试进行追踪;无法解析的基类不计入。报告指向第一个未运行该套件的测试类。auto 在允许列表中:test_tokenization_auto.py 测试的是 AutoTokenizer 的解析,而非某个 tokenizer。TokenizerTesterMixin 是实际检查 encode/decode 往返、填充与截断、特殊 token 处理、添加 token 的持久化以及保存/加载等价性的地方。一个仅断言几个手写 token id 列表的测试,即使 tokenizer 在其中每一项上都是损坏的,也会通过,并且在代码审查中看起来像是已经测试过。
-class AcmeTokenizationTest(unittest.TestCase):
+class AcmeTokenizationTest(TokenizerTesterMixin, unittest.TestCase):
+ tokenizer_class = AcmeTokenizer
+ test_slow_tokenizer = TrueTRF043
标记了名称以 Attention 结尾的类中,其 forward 签名里声明的 position_ids 参数。position_ids 会在下游被 flash-attention 的无填充(padding-free)训练所消费,因此必须通过 kwargs 传递。如果在签名中显式命名该参数,它会在注意力接口读取之前就被吞掉;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
标记 modeling.py 和 modular_.py 中任何函数里名为 cache_position 的参数。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
Flags the legacy outputattentions, output_hidden_states and return_dict parameters in forward signatures in modeling.py and modular_.py. Models contributed before the cutoff date are exempt. The decorator stack owns output control: @captureoutputs resolves the output* flags against the config and records tensors via _can_record_outputs, and @can_return_tuple handles return_dict. Declaring them in the signature reintroduces manual flag threading that drifts from the decorators.
+@capture_outputs
def forward(
self,
input_ids,
- output_attentions=None,
- output_hidden_states=None,
- return_dict=None,
**kwargs: Unpack[TransformersKwargs],
):TRF046
在 modeling*.py 和 modular*.py 的 forward 方法中,禁止对 self 属性进行赋值。在 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
在 preprocess, call and post_process* methods in image_processing.py and videoprocessing.py 中,禁止将标志位赋值给 self 属性。在多次调用之间携带状态的处理器会破坏“先批量预处理、后批量后处理”的批处理流程:第二次 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
Flags list/tuple/set literals in class-level _tied_weights_keys declarations. v5 changed _tied_weights_keys to a dict mapping each tied target parameter to its source. The list form no longer says which parameter is the source, so tying, device_map computation and saving misbehave silently.
class AcmeForCausalLM(AcmePreTrainedModel):
- _tied_weights_keys = ["lm_head.weight"]
+ _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}TRF049
Flags init calls in init methods in modeling*.py and modular.py: nn.init. / init.* primitives and in-place initializers on own parameters (self.weight.data.normal_()). Models instantiate on the meta device, so tensor values written in init are discarded before loading: a parameter initialized only there holds random content when fine-tuning from scratch or after a meta-device reload. Allocate with torch.empty in init, initialize in _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
在名称以 Attention 结尾的类的 init 中,对 *RotaryEmbedding 类的调用进行标记。Model 持有单个 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,而依赖后端的张量处理(填充、重塑)应放在 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 中的 hub 注意力内核永远无法到达它们。通过接口进行分发的单一注意力类将取代该字典;请勿从旧版父类中传播它。
-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 中,通过切片(例如 labels[…, 1:])来构建 shiftlogits/shift_labels(以及 shifted 变体)的赋值操作会被标记。接收已经移位过的标签(shift_labels = kwargs.pop(“shift_labels”, labels))是正确的惯用写法,不会被标记。由于 self.loss_function 会自行对标签进行移位,因此在 modeling 代码中预先移位会导致在双重移位的目标上进行训练,或者强制使用自定义的损失路径。仅解码器模型应传入原始标签,让损失函数自行移位。编码器-解码器模型是相反的情况:它们的标签已经通过前置的解码器起始 token 进行了移位,因此应传入 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 赋值、未带 config 注解的 <Model>PreTrainedModel,以及 config 参数未加注解或指向其他配置的 __init__。由子配置构建的类(AcmeTextModel(config.text_config))必须声明该子配置。modular_*.py 文件通过其生成的文件进行检查。PreTrainedModel 从 config 注解推导 config_class。赋值或手写的 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 中,任何 forward 内部的 .item() 和 .tolist() 调用都会触发标志。作为 split(...) 的 split-size 参数传入的 .tolist() 调用除外:torch.split 需要 Python int。这两种调用都会将张量读回主机,而 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 子类、图像处理器、视频处理器以及 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 中,标记那些 buffer 名称为字符串字面量的 register_buffer("<name>", ...) 调用,无论接收者是谁(self,或其他模块,例如 layer.mamba)。对于计算得出的名称——即变量或 f-string,例如在循环中为每一层创建一个 buffer——没有等价的属性赋值形式,因此予以豁免。由于 torch>=2.5 中 nn.Buffer 通过普通的属性赋值来注册 buffer,类似于 nn.Parameter。通过方法调用创建的 buffer 仅作为运行 __init__ 的副作用而存在,因此希望调整某个 buffer 的 modular 文件必须重新定义整个 __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
对于张量并行计划中分配了 moe_tp_experts 的模型目录,会检查路由的 *Experts 类是否将隐藏状态、top-k 索引和 top-k 路由权重作为 forward 的前三个位置参数。接受诸如 selected_experts 和 routing_weights 之类的别名。MoeExpertsParallel 会对第 3 个位置参数应用梯度变换。如果签名不同,则会静默地对错误的张量应用该变换,或者跳过该变换。
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
在 modular_*.py 中,标记那些基类在同一文件较早位置定义的类。从其他模型导入的基类、<Model>PreTrainedModel 的子类以及向后兼容的别名不会被标记。转换器会内联从其他模型导入的基类,但会保留同一文件中的基类,因此生成的 modeling 文件会保留继承关系,其类无法再逐个读取。
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
_init_weights 内部调用的就地 torch.nn.init 初始化器(无论以何种方式导入的 nn.init.normal_(...))都会被标记。仅用于计算值的辅助函数(例如 calculate_gain)不会被标记。Transformers 的 init 函数会跳过已从检查点加载的张量。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
跟踪模型文件在导入时执行的每个相对导入,并在被导入的文件需要导入文件未声明的后端时发出标记:通过其基础依赖项、其 __all__ 对象中最弱的 @requires,或 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 和 modular*.py 中,标记了分配或重新注释 _defaults、text_kwargs、images_kwargs、videos_kwargs 或 audio_kwargs 的 ProcessingKwargs 子类。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 的类。在同样包含子处理器的 modular.py 中,当子类命名为 <Model>ImageProcessorKwargs、<Model>VideoProcessorKwargs、<Model>VideoProcessorInitKwargs 或 <Model>AudioProcessorKwargs 时,是允许存在子类的。模态 kwargs 应位于子处理器文件中(`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 装饰器,也会标记它;同样,位于 @classmethod 或 @staticmethod 上方的 @requires 也会被标记。该截止规则将旧模型豁免于除装饰器位置错误之外的所有检查。重复后端要求会掩盖方法实际新增的依赖关系。函数开头的无条件检查应放在 @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
在 modeling*.py 和 modular*.py 中,当函数随后仅通过索引读取 .hidden_states[...] 时,会标记出那些开启所有隐藏状态的调用(即 output_hidden_states=True,或在 **kwargs 中设置该值)。使用整个元组的代码(例如进行迭代、切片、堆叠或返回该元组)以及带有 @filter_output_hidden_states 的骨干网络不受此限制。由于每一层的隐藏状态在调用返回之前都会保持存活,因此峰值内存会随深度增加而增长。output_hidden_states 还接受一个索引或索引列表,并仅捕获这些索引对应的状态:可以使用 @select_hidden_states 装饰一个转发 **kwargs 的方法,或者直接传入索引。
+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 文件通过其在磁盘上生成的文件进行检查,因此在运行 lint 之前请重新生成。accelerate 会将这些名称与子模块的类名进行匹配。如果某个名称不是类,则永远不会匹配,因此该层可以被拆分到不同的设备上。这种情况通常源于继承 _no_split_modules 的 modular 文件:转换器会重命名前缀,而不是类名。
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
对于无法立即修复的包含遗留代码的模型,请将该模型的目录名称添加到 mlinter rules.toml 中相应规则的 allowlist_models 列表中。
[rules.TRF004]
allowlist_models = ["existing_model", "your_model_name"]