Hugging Face Blog · 2026/10/19 08:00:00

TorchNeuron 发布 原生支持 AWS Trainium 运行 HF 模型

原标题:TorchNeuron: running HF models on AWS Trainium is easier than ever
68AI 研判分
核心综述

AWS 推出 TorchNeuron,为 PyTorch 提供原生 Trainium 后端支持。Hugging Face 的 Transformers、Diffusers 和 Kernels 库已集成该后端,大幅简化了模型在 Trainium 芯片上的训练与部署流程。

报道全文原始报道全文

本文目录10 个章节

返回文章列表

TorchNeuron:在 AWS Trainium 上运行 HF 模型比以往更简单

Régis Pierrard regisss Simon Pagezy pagezyhf Michael Benayoun michaelbenayoun Jingya Huang Jingya Alvaro Moran tengomucho David Corvoysier dacorvo Jeff Boudier jeffboudier

TorchNeuron 为 PyTorch 在 AWS Trainium 上提供了全新的原生后端。Transformers、Diffusers 和 Kernels 均原生支持该后端,使得在 Trainium 上运行模型以及在 Hugging Face Hub 上共享模型变得前所未有的轻松。

TorchNeuron

TorchNeuron 是一个 PyTorch 插件,它为 Trainium 引入了新的后端,支持 eager 模式、torch.compile 以及 FSDP 和 TP 等原生分布式 API。请阅读 PyTorch 博客以了解更多关于 TorchNeuron 的信息。

自 2026 年 10 月 20 日起,TorchNeuron 将以公开测试版(public beta)的形式发布。研究人员和开发者可以通过 pip install torch-neuronx 进行安装。

新后端,HF 库中的原生接口

迄今为止,Hugging Face 在 AWS Trainium 和 Inferentia——分别专为大规模低成本训练和推理设计的 AI 芯片——上的体验是通过 optimum-neuron 提供的。该库依赖于基于 PyTorch XLA 的 torch-neuronx 包。这在当时是自然的选择,但也意味着需要像编译器一样思考:使用惰性张量而非 eager 执行,仅支持静态形状,且每次图断裂(graph break)都需要重新编译。Optimum Neuron 的存在正是为了隐藏这种复杂性,并为此维护了自定义代码(如建模类、训练器等)。

TorchNeuron 改变了这一现状。它直接集成到 PyTorch 中,将 neuron 暴露为一个原生设备,支持 eager 执行、PyTorch 自身的分布式原语(DTensor, FSDP2)以及 torch.compile。

对于 Hugging Face 库而言,Trainium 现在就像其他设备一样:Transformers、Diffusers、Accelerate、PEFT 和 TRL 可以直接在其上运行,使用与其他加速器相同的类和脚本。从现在开始,我们建议 Neuron 用户直接使用这些库,而不是通过 Optimum Neuron。

Transformers

推理

Transformers 现已原生支持广泛模型的文本生成。借助 TorchNeuron,前 100 个最常用文本生成模型架构中有 89% 开箱即用,而 Optimum Neuron v0.4.5 仅支持 46%。你只需在代码中传入 device_map=neuron 参数,模型就会被移动到 Neuron 设备上。

以下是一个使用张量并行(tensor parallelism)进行文本生成的示例,这将使你能够充分利用 Neuron 实例的性能。请注意,该示例在生成过程中使用了静态缓存(static cache),因为在 Neuron 上强烈推荐使用静态缓存以防止频繁重新编译。

PY
import os

import torch
import torch.distributed as dist
import torch_neuronx  
from torch.distributed import DeviceMesh
from transformers import AutoModelForCausalLM, AutoTokenizer, GenerationConfig
from transformers.distributed import DistributedConfig
from transformers.generation.configuration_utils import CompileConfig

MODEL_ID = "Qwen/Qwen3.8-27B"
MAX_SEQ_LEN = 1024
PREFILL_CHUNK_SIZE = 512

dist.init_process_group(backend="neuron")
world_size = dist.get_world_size()

model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    dtype=torch.bfloat16,
    distributed_config=DistributedConfig(tp_size=world_size),
    device_mesh=DeviceMesh("neuron", list(range(world_size))),
).eval()

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = "left"

inputs = tokenizer.apply_chat_template(
    [{"role": "user", "content": "The future of AI is"}],
    add_generation_prompt=True,
    padding=True,
    tokenizer_kwargs={"pad_to_multiple_of": PREFILL_CHUNK_SIZE},
    return_tensors="pt",
)

generation_config = GenerationConfig(
    max_new_tokens=128,
    do_sample=False,
    use_cache=True,
    pad_token_id=tokenizer.pad_token_id,
    eos_token_id=tokenizer.eos_token_id,
    cache_implementation="static",
    max_cache_len=MAX_SEQ_LEN,
    prefill_chunk_size=PREFILL_CHUNK_SIZE,
    compile_config=CompileConfig(backend="neuron", fullgraph=False, dynamic=False),
)

```py
with torch.no_grad():
    output_ids = model.generate(
        inputs["input_ids"],
        attention_mask=inputs["attention_mask"],
        generation_config=generation_config,
    )

if dist.get_rank() == 0:
    prompt_len = inputs["input_ids"].shape[1]
    print(tokenizer.decode(output_ids[0, prompt_len:], skip_special_tokens=True))

训练

既然 Neuron 已成为 PyTorch 的原生设备,在 Trainium 上进行训练时可以使用与其他加速器相同的 Hugging Face 库:Transformers、Accelerate、PEFT 和 TRL。你不再需要专用的训练器或模型代码的 Neuron 特定分支。标准的 TRL 微调脚本只需少量 Neuron 特定设置即可在 Trainium 实例上运行。

以下是一个基于 TRL 的 SFTTrainer 构建的监督微调脚本。如果你之前曾在 GPU 上使用 TRL 对模型进行微调,这个脚本应该看起来很熟悉。

PY
import os

import torch
from datasets import load_dataset
from transformers.distributed import DistributedConfig

from trl import ModelConfig, ScriptArguments, SFTConfig, SFTTrainer, TrlParser

def main(script_args, training_args, model_args):

torch._dynamo.config.automatic_dynamic_shapes = False

training_args.model_init_kwargs = {
        "revision": model_args.model_revision,
        "trust_remote_code": training_args.trust_remote_code,
        "attn_implementation": model_args.attn_implementation,
        "dtype": model_args.dtype,
        "device_map": None,
    }
    if int(os.environ.get("WORLD_SIZE", "1")) > 1:

training_args.model_init_kwargs["distributed_config"] = DistributedConfig(
            tp_size=int(os.environ.get("TP_SIZE", "1")),
            fsdp_size=int(os.environ.get("FSDP_SIZE", "1")),
        )

train_dataset = load_dataset(
        script_args.dataset_name,
        name=script_args.dataset_config,
        split=script_args.dataset_train_split,
    )

train_dataset = train_dataset.select_columns(["messages"])

trainer = SFTTrainer(
        model=model_args.model_name_or_path,
        args=training_args,
        train_dataset=train_dataset,
    )

trainer.train()
    trainer.save_model(training_args.output_dir)
    trainer.end()

if __name__ == "__main__":
    parser = TrlParser((ScriptArguments, SFTConfig, ModelConfig))
    script_args, training_args, model_args = parser.parse_args_and_config()
    main(script_args, training_args, model_args)

Transformers 原生支持并行处理。你只需在 model_init_kwargs 中传入包含张量并行(TP)和 FSDP 大小的 DistributedConfig,SFTTrainer 会将其传递给 from_pretrained,模型在加载权重时即完成分片。Trainer 检测到模型已处于分布式状态,因此不会再次进行包装。你无需使用 --fsdp 标志或配置 Accelerate FSDP。

脚本中的任何内容都不与 Trainium 绑定:相同的代码可在任意硬件上运行。但在 Trainium 上运行时,有几点值得注意:

  • 静态形状。 该脚本禁用了 torch.compile 中的自动动态形状功能,并使用带包装的打包方式生成长度不超过 2048 个 token 的序列。对于 TRL ≥ 1.16,Neuron 上的批次会被填充至 128 个 token 的倍数,从而限制输入形状的数量。编译后的计算图会在后续具有相同形状的步骤中被复用。
  • 启用 torch.compile。 只需传递 --torch_compile true 即可:在 Trainium 实例上,torch.compile 会自动检测设备并选择 Neuron 后端,无需其他配置。
  • 关闭异步权重加载。 Transformers 内置的异步权重加载功能目前不支持 Neuron,因此我们暂时通过设置 HF_DEACTIVATE_ASYNC_LOAD=1 来禁用它。

以下命令使用 torchrun 启动训练,每个 NeuronCore 启动一个进程。TP_SIZE 和 FSDP_SIZE 定义并行布局,其乘积即为进程总数:此处为 4 x 8 = 32,与 --nproc_per_node 匹配。这 32 个进程构成一个 4 x 8 的网格。张量并行将每一层拆分到 TP 组的 4 个核心上,而 FSDP 则将参数、梯度和优化器状态分片到 8 个 TP 组之间。

SH
TP_SIZE=4 FSDP_SIZE=8 HF_DEACTIVATE_ASYNC_LOAD=1 uv run torchrun --nproc_per_node=32 sft_neuron_example.py \
    --model_name_or_path Qwen/Qwen3-8B \
    --dataset_name HuggingFaceH4/ultrachat_200k \
    --dataset_train_split train_sft \
    --output_dir Qwen3-8B-sft-tp4-fsdp8 \
    --dtype bfloat16 \
    --max_length 2048 \
    --packing true \
    --packing_strategy wrapped \
    --learning_rate 2e-5 \
    --warmup_steps 0.03 \
    --num_train_epochs 1 \
    --logging_steps 2 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 4 \
    --save_only_model true \
    --torch_compile true

我们在 8 颗 Trainium2 芯片(共 32 个 NeuronCores)上运行了该任务,这相当于半个 trn2.48xlarge 实例。

训练顺利运行至完成,trainer.save_model 会写入一个标准的 Transformers 检查点。其中没有任何内容与 Neuron 绑定:你可以直接将其推送到 Hugging Face Hub,并在任何其他硬件上加载使用。

Diffusers

推理

Diffusers 库中的许多 pipeline 都兼容 TorchNeuron 的 eager(即时)模式和 compiled(编译)模式。FLUX.1-dev、FLUX.2、Qwen-Image、Qwen-Image-2.1 和 H3 还支持张量并行(Tensor Parallelism),以充分利用你的 Neuron 设备性能。以下示例展示了如何使用 TP:

PY
import torch, torch.distributed as dist, torch_neuronx 
from torch.distributed.device_mesh import DeviceMesh 
from diffusers import QwenImage21Pipeline, QwenImage21Transformer2DModel, TensorParallelConfig

dist.init_process_group(backend="neuron") 
dev = torch.neuron.current_device()
mesh = DeviceMesh("neuron", list(range(8)))

model = "Qwen/Qwen-Image-2.1"
transformer = QwenImage21Transformer2DModel.from_pretrained(
    model,
    subfolder="transformer",
    torch_dtype=torch.bfloat16,
    parallel_config=TensorParallelConfig(mesh=mesh), 
)
pipe = QwenImage21Pipeline.from_pretrained(
    model,
    transformer=transformer,
    torch_dtype=torch.bfloat16,
)
pipe.vae.to(dev)
pipe.transformer.compile_repeated_blocks(backend="neuron", fullgraph=True, dynamic=False)

emb, mask, _ = pipe.encode_prompt(prompt="A capybara wearing a wizard hat, oil painting", device="cpu")  
image = pipe(
    prompt_embeds=emb.to(dev),
    prompt_embeds_mask=mask.to(dev) if mask is not None else None,
    height=1024,
    width=1024,
    num_inference_steps=40,
    generator=torch.Generator("cpu").manual_seed(0), 
).images[0]
if dist.get_rank() == 0:
    image.save("out.png")

你可以通过以下命令运行这段代码:NEURON_LOGICAL_NC_CONFIG=2 torchrun --nproc_per_node=8 run.py。

越来越多的 pipeline 将支持 TP。如果你喜欢的某个 pipeline 尚未支持,你也可以按照 此指南 为其添加支持。

Kernels

请务必查看 Neuron 团队的 kernels,因为 Hub 上会有越来越多的 Neuron kernels 可用,以加速你的模型。Neuron kernels 可以使用 Neuron Kernel Interface (NKI) 编写,它提供了更底层的控制能力来优化操作。这样,用户就可以运行自己的自定义操作,并将它们分享到 Hub 上。

例如,你可以使用 这个 kernel 来加速你的 Vision Transformer,在 Trainium 上最高可获得 2.4 倍的加速!

致谢

特别感谢 AWS 团队在 TorchNeuron 方面所做的工作,以及他们对我们反馈的快速响应,使 HF 集成尽可能完善。

TorchNeuron 发布 原生支持 AWS Trainium 运行 HF 模型 | Today for AI