Transformers 中的 ApertusSwiss AI 8B 级大语言模型的架构解析与使用指南【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersApertus 是瑞士人工智能计划Swiss AI Initiative发布的开源大语言模型家族于 2025-08-28 贡献并入 Transformers。本文以官方模型文档 docs/source/en/model_doc/apertus.md 为主体结合仓库中的配置、建模与测试源码逐层拆解 Apertus 的架构设计、配置参数、并行方案与实战用法帮助读者快速完成加载、推理、微调与二次开发。Apertus 是什么来自 Swiss AI Initiative 的开源 LLM 家族官方模型文档给出的定位非常简洁Apertus 是瑞士人工智能计划Swiss AI Initiative详见其官网 swiss-ai.org 的公开介绍推出的一族大语言模型LLM。它是一个纯 Decoder-only 的因果语言模型家族在代码仓库中体现为model_type apertus的完整实现源码位于 src/transformers/models/apertus/共包含 4 个文件文件职责configuration_apertus.pyApertusConfig模型超参定义与默认值modeling_apertus.py前向计算实现由 modular 生成modular_apertus.py模块化源文件真正体现继承与定制关系__init__.py导出ApertusConfig、ApertusModel、ApertusForCausalLM、ApertusForTokenClassification、ApertusPreTrainedModel建模代码头部注释明确说明 modeling_apertus.py 是由 modular_apertus.py自动生成的扁平化文件CI 强制二者一致因此任何架构改动都应作用于 modular 源文件而非生成文件——这是理解该目录组织方式的关键。官方文档首页还标注了 Apertus 支持的能力徽章FlashAttention、SDPAPyTorch scaled dot-product attention、Tensor parallelism张量并行。这些能力在源码中都有对应证据见下文ApertusPreTrainedModel的支持标志与并行计划配置。架构深度解析基于 Llama 的少而精定制从 modular 源文件可以最清晰地看到 Apertus 的血统modular_apertus.py 顶层直接复用了两个既有实现——LlamaAttention / LlamaDecoderLayer / LlamaModel / LlamaForCausalLM / LlamaRMSNorm / LlamaRotaryEmbedding来自..llama.modeling_llama以及NemotronMLP来自..nemotron.modeling_nemotron。这意味着 Apertus 本质上是一个LLaMA 系架构再叠加三处关键定制其中前两处在 modular 中通过继承覆写完成定制点 1Q/K 头部 RMSNormper-head normalization标准 LLaMA 在 Q/K 投影之后直接施加 RoPE而 ApertusAttention 在q_proj/k_proj之后、RoPE 之前对每个注意力头额外做了一次 RMSNormself.q_norm ApertusRMSNorm(self.head_dim, config.rms_norm_eps) self.k_norm ApertusRMSNorm(self.head_dim, config.rms_norm_eps) # forward 中 query_states self.q_norm(query_states) key_states self.k_norm(key_states)该逻辑见 modeling_apertus.py。注意 Q/K 归一化作用于每个头的head_dim由config.hidden_size // config.num_attention_heads推导8B 配置下为 128而非整个hidden_size。定制点 2双前置 RMSNorm 的残差结构pre-norm 残差与 LLaMA 的input_layernorm post_attention_layernorm布线不同ApertusDecoderLayer只保留两个前置pre-normRMSNormattention_layernorm归一化后进注意力、feedforward_layernorm归一化后进 MLP随后各自做残差相加residual hidden_states hidden_states self.attention_layernorm(hidden_states) hidden_states, _ self.self_attn(hidden_states, ...) hidden_states residual hidden_states # 注意力残差 residual hidden_states hidden_states self.feedforward_layernorm(hidden_states) hidden_states self.mlp(hidden_states) hidden_states residual hidden_states # MLP 残差该结构在 modular 中通过del self.input_layernorm; del self.post_attention_layernorm显式删除 LLaMA 父类组件后重建见 modular_apertus.py 与生成文件 modeling_apertus.py。定制点 3xIELU 激活 非门控 MLPApertus 的 MLP 选择了一个非常规激活函数xIELU。仓库在 activations.py 中实现了XIELUActivation类文档标注其方法出自 arXiv:2411.13010 对应的工作。ApertusMLP的默认配置为hidden_actxielu实例化时携带可学习参数self.act_fn ACT2CLSxielu # 使用可学习 alpha_p/alpha_n 的 xIELU def forward(self, x): return self.down_proj(self.act_fn(self.up_proj(x))) # 单分支、无 gate 投影从XIELUActivation.__init__可以看到其参数化细节可学习的alpha_p、alpha_n初始值均为 0.8经 log-expm1 参数化保证正数域以及beta0.5、eps-1e-6等常量 Buffer。实现上有锦上添花的加速路径——若用户环境安装了nickjbrowning/XIELU的 CUDA wheel则优先调用 CUDA kernel否则回退到 Python 实现并给出一次性警告源码注释原话见 activations.py。整个 MLP 是down_proj(act(up_proj(x)))的单分支形式不包含 LLaMA 的 gate_proj 门控结构。RoPE复用 LLaMA-3 长上下文缩放ApertusConfig.__post_init__在未显式指定时会填入一组默认 RoPE 参数见 configuration_apertus.pyself.rope_parameters { rope_type: llama3, rope_theta: 12000000.0, factor: 8.0, original_max_position_embeddings: 8192, low_freq_factor: 1.0, high_freq_factor: 4.0, }结合max_position_embeddings 6553664K可以推断Apertus 以约 8K 的原始训练长度为基础通过LLaMA-3 风格的低/高频分段插值 RoPEθ1200 万、factor8将上下文能力扩展至 64K。旋转位置编码实现在ApertusRotaryEmbedding中完成其rope_theta12000000同时也被定义为default_theta类常量。forward中强制在 fp32 下计算 cos/sin 并施加attention_scaling体现了数值稳定性考虑。注意力后端eager / SDPA / FlashAttention / FlexAttention 可插拔ApertusAttention通过ALL_ATTENTION_FUNCTIONS.get_interface(...)统一分发注意力实现modeling_apertus.py与仓库新一代 attention-backend 机制对齐。基类声明了完整的能力矩阵_supports_flash_attn True _supports_sdpa True _supports_flex_attn True _supports_attention_backend True _can_compile_fullgraph True对应的 eager 参考实现eager_attention_forward在 softmax 前显式repeat_kv扩展 KV 头并在fp32 下计算 softmax后转回原 dtype以提升数值稳定性modeling_apertus.py。ApertusConfig 配置详解8B 默认值与关键参数ApertusConfig继承自PreTrainedConfig以类型注解字段 strict校验的方式声明默认值。从配置类默认值configuration_apertus.py可以得到 Apertus-8B 的完整超参画像参数默认值说明vocab_size131072词表大小约 128K对应较大规模的 tokenizerhidden_size4096隐藏层维度intermediate_size14336FFN 中间维度约 3.5×hiddennum_hidden_layers32Decoder 层数num_attention_heads32注意力头数num_key_value_headsNone若为 None 则在__post_init__中取num_attention_heads即默认 MHA可配置为 GQAhidden_actxieluxIELU 激活max_position_embeddings65536最大位置数64Kinitializer_range0.02参数初始化标准差rms_norm_eps1e-5RMSNorm 的 epsuse_cacheTrue推理缓存KV cache开关pad_token_id/bos_token_id/eos_token_id3 / 1 / 2特殊 token idtie_word_embeddingsFalse默认不捆绑输入/输出词嵌入attention_biasFalse各投影层不带 biasattention_dropout0.0注意力 dropout此外还声明了keys_to_ignore_at_inference [past_key_values]推理时忽略键与default_theta 12000000.0。配置类 docstring 里的标准用法如下from transformers import ApertusModel, ApertusConfig # 初始化一个 Apertus-8B 风格的配置 configuration ApertusConfig() # 用配置构建模型 model ApertusModel(configuration) # 读取模型配置 configuration model.configrope_parameters是RopeParameters类型也可传 dict__post_init__中的两条推导规则值得注意其一是num_key_value_headsNone时自动对齐num_attention_heads其二是rope_parametersNone时自动填入上文那组 LLaMA-3 长上下文插值参数。这意味着新建ApertusConfig()即得到开箱可用的完整配置。并行计划TP / PP / FSDP 的默认布局Apertus 是少数在配置层内置完整张量并行TP与流水线并行PP切分计划的模型之一configuration_apertus.pybase_model_tp_plan { layers.*.self_attn.q_proj: colwise, # Q/K/V 按列切分 layers.*.self_attn.k_proj: colwise, layers.*.self_attn.v_proj: colwise, layers.*.self_attn.q_norm: replicated_with_grad_allreduce, # 头级 Norm 复制 梯度全归约 layers.*.self_attn.k_norm: replicated_with_grad_allreduce, layers.*.self_attn.o_proj: rowwise, # 输出投影按行切分 layers.*.mlp.up_proj: colwise, layers.*.mlp.down_proj: rowwise, } base_model_pp_plan { embed_tokens: ([input_ids], [inputs_embeds]), layers: ([hidden_states, attention_mask], [hidden_states]), norm: ([hidden_states], [hidden_states]), }读法很直观colwise/rowwise表明列/行并行切分策略q_norm/k_norm这类细粒度模块被标为replicated_with_grad_allreduce各 rank 复制一份并在反向时做全归约这与Q/K 头级归一化的定制架构是配套的——TP 后每个 rank 持有部分头复制归一化参数更利于稳定性。在ApertusForCausalLM上还有与语言模型头相关的补充计划lm_head的_tp_plan为colwise_gather_output、_pp_plan接收hidden_states输出logits同时_fsdp_plan为keep_full_weight不切分 lm_head 权重见 modeling_apertus.py。这些字段说明 Apertus 对Tensor parallelism / Pipeline parallelism / FSDP 三种分布式范式都做了开箱配置与官方徽章中的 Tensor parallelism 遥相呼应。快速开始官方推荐的三种加载方式模型文档apertus.md以swiss-ai/Apertus-8B为例展示了生成式用法。文档同时声明了 Pipeline、AutoModel 与命令行三种入口——其中命令行示例在原文档中标注为 Coming soon尚未落地因此下文完整展开前两种可直接运行的 Python 方式。方式一pipeline一行调用最简路径使用text-generation管线适合快速冒烟测试from transformers import pipeline pipe pipeline( tasktext-generation, modelswiss-ai/Apertus-8B, device0, # 指定 GPU ) pipe(Plants create energy through a process known as)方式二AutoModel AutoTokenizer可控性最高from transformers import AutoModelForCausalLM, AutoTokenizer tokenizer AutoTokenizer.from_pretrained(swiss-ai/Apertus-8B) model AutoModelForCausalLM.from_pretrained( swiss-ai/Apertus-8B, device_mapauto, # 自动设备映射 attn_implementationsdpa, # 显式选择 SDPA 注意力后端 ) input_ids tokenizer(Plants create energy through a process known as, return_tensorspt).to(model.device) output model.generate(**input_ids) print(tokenizer.decode(output[0], skip_special_tokensTrue))AutoModelForCausalLM.from_pretrained之所以能自动解析为ApertusForCausalLM依赖仓库的自动注册表auto_mappings.py与modeling_auto.py中登记了(apertus, ApertusConfig / ApertusModel / ApertusForCausalLM / ApertusForTokenClassification)四组映射见 src/transformers/models/auto/auto_mappings.py。若不依赖 Auto 类也可直接导入具名类from transformers import ApertusForCausalLM, AutoTokenizer model ApertusForCausalLM.from_pretrained(swiss-ai/Apertus-8B-Instruct-2509) tokenizer AutoTokenizer.from_pretrained(swiss-ai/Apertus-8B-Instruct-2509) prompt Hey, are you conscious? Can you talk to me? inputs tokenizer(prompt, return_tensorspt) generate_ids model.generate(inputs.input_ids, max_length30)这段具名用法直接取自 modeling_apertus.py 中ApertusForCausalLM.forward的 docstring 示例。仓库标注的默认检查点名为swiss-ai/Apertus-8B-Instruct-2509出现在配置类与 docstring 的auto_docstring(checkpoint...)装饰器中与文档示例中的swiss-ai/Apertus-8B同属该模型家族。任务入口三个公开模型的职责划分除ApertusConfig外文档以 autodoc 形式公开了三个模型类它们的源码分工如下ApertusModel裸 Transformer 主干无任务头。内部由embed_tokens词嵌入、ApertusDecoderLayer堆叠nn.ModuleList共 32 层、末端norm与rotary_emb组成forward中通过create_causal_mask构造因果掩码、以DynamicCache承载 KV cache输出BaseModelOutputWithPast。主干代码见 modeling_apertus.py。ApertusForCausalLM叠加lm_head无 bias 的hidden_size → vocab_size线性层的因果语言建模头混入GenerationMixin获得generate()能力forward支持labels计算 CE 损失并以logits_to_keep参数只对必要的尾部 token 计算 logits降低生成阶段开销默认不捆绑词嵌入tie_word_embeddingsFalse。见 modeling_apertus.py。ApertusForTokenClassification继承GenericForTokenClassificationApertusPreTrainedModel的组合实现modeling_apertus.py用于词级分类任务如 NER。它与因果 LM 头共用同一个 Apertus 主干。训练与推理工程化特性除前述注意力后端外基类还开启了多项工程特性modeling_apertus.py梯度检查点supports_gradient_checkpointing True且ApertusDecoderLayer继承GradientCheckpointingLayer基础设施可用model.gradient_checkpointing_enable()以显存换算力全图编译_can_compile_fullgraph True可配合torch.compile进行训练/推理优化测试套件中对应test_torch_compile_for_training用例KV cacheuse_cache与DynamicCache机制配合keys_to_ignore_at_inference优化推理路径输出捕获_can_record_outputs声明可按ApertusDecoderLayer/ApertusAttention粒度捕获hidden_states与attentions。测试体系仓库如何验证 Apertus模型级测试位于 tests/models/apertus/test_modeling_apertus.py直接复用tests/causal_lm_tester.py提供的通用因果 LM 测试基座CausalLMModelTester/CausalLMModelTest这说明 Apertus 已完全纳入 Transformers 的公共测试契约。两个值得关注的细节ApertusModelTester强制将attention_probs_dropout_prob设为0.0代码注释解释TP 反向测试中非零 dropout 会导致非 TP 与 TP 两次前向的 RNG 状态不一致进而使 dropout mask 不同、loss 对不上——这是分布式训练测试的典型约束model_split_percents [0.5, 0.7, 0.8]注释说明为避开 causal_mask buffer 的边界用例而在 CPU offload 测试中使用 0.8 而非默认 0.9。测试文件的文件头注释也再次印证了架构出处本实现基于 HuggingFace 的 LLaMA 实现Swiss AI 在训练时做了细微的架构调整即上文所述三处定制。小结Apertus 代表了 Transformers 中一类典型的继承优先、覆盖精修的模型集成范式以 LLaMA 的成熟骨架为基础通过 modular 机制做定向架构创新——Q/K 头级 RMSNorm、双前置归一化的残差布线、xIELU 可学习激活与 LLaMA-3 式 64K 长上下文 RoPE同时原生集成 SDPA/FlashAttention/FlexAttention 与 TP/PP/FSDP 并行方案。对开发者而言无论是通过pipeline、AutoModelForCausalLM快速上手还是参考其 TP/PP 计划与 modular 源文件来定制新模型Apertus 都是不可多得的完整范本。进一步阅读与验证材料模型官方文档docs/source/en/model_doc/apertus.md配置与默认值src/transformers/models/apertus/configuration_apertus.py前向实现生成文件src/transformers/models/apertus/modeling_apertus.py架构继承关系modular 源src/transformers/models/apertus/modular_apertus.pyxIELU 激活实现src/transformers/activations.py自动类注册src/transformers/models/auto/modeling_auto.py模型测试tests/models/apertus/test_modeling_apertus.py【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考