Transformers documentation
Google TPU
Google TPU
Google Cloud TPUs exécutent PyTorch nativement via le package torch_tpu, qui enregistre le périphérique tpu. torch_tpu compile les opérations qu’il exécute pour chaque forme d’entrée qu’il rencontre, il est donc recommandé de conserver des formes d’entrée statiques afin d’éviter les recompilations.
Installation
Installez torch_tpu en suivant les instructions du dépôt torch_tpu. torch_tpu est chargé automatiquement lors de l’importation de torch. Vérifiez que PyTorch détecte les puces TPU.
import torch
print(torch.accelerator.is_available(), torch.accelerator.device_count())Il affiche True et le nombre de puces TPU, par exemple True 4.
Exécuter l'inférence
device_map="auto" ne détecte pas les TPU. Le placement automatique s’appuie sur Accelerate pour lister les appareils disponibles, et Accelerate ne liste pas les appareils TPU, de sorte que le modèle se charge silencieusement sur le CPU. Passez explicitement device_map="tpu" à from_pretrained(), ou device="tpu" à Pipeline.
Transmettez les entrées de génération sur le CPU au lieu d’appeler .to(model.device). generate() ne déplace vers le TPU que les tenseurs consommés par forward. Les tenseurs qui augmentent à chaque étape (séquence de sortie, attention_mask) restent sur le CPU, ce qui maintient le graphe compilé stable. generate renvoie la sortie sur le même appareil que les entrées. Consultez Conserver les tenseurs de génération sur le CPU pour plus de détails. Les modèles utilisent SDPA par défaut sur TPU.
from transformers import AutoModelForCausalLM, AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
model = AutoModelForCausalLM.from_pretrained(
"Qwen/Qwen3-0.6B", dtype="bfloat16", device_map="tpu"
)
# leave the inputs on CPU
inputs = tokenizer("The French Bread Law states", return_tensors="pt")
output = model.generate(
**inputs, do_sample=True, max_new_tokens=50, cache_implementation="static"
)
print(tokenizer.decode(output[0], skip_special_tokens=True))The French Bread Law states that a farmer can sell their harvest of bread at a certain price. The price is determined by the market price and the price of the bread, and the price is set by the farmers' decision-making committee. What are the implications of this law on
Avec un cache statique, generate() compile le passage avant avec torch.compile et le backend tpu automatiquement. Passez disable_compile=True à generate pour désactiver cette option.
Parallélisme de tenseurs
torch_tpu exécute un processus par puce TPU, et chaque processus voit sa puce comme tpu:0. Créez un DistributedConfig avec la taille de parallélisme de tenseurs et passez-le à from_pretrained(). Transformers découpe le modèle au moment du chargement.
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, DistributedConfig
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")
model = AutoModelForCausalLM.from_pretrained(
"Qwen/Qwen3-8B",
dtype=torch.bfloat16,
distributed_config=DistributedConfig(tp_size=4),
)
# leave the inputs on CPU
inputs = tokenizer("The French Bread Law states", return_tensors="pt")
output = model.generate(
**inputs, do_sample=False, max_new_tokens=50, cache_implementation="static"
)
if torch.distributed.get_rank() == 0:
print(tokenizer.decode(output[0], skip_special_tokens=True))torch_tpu nécessite la configuration de certaines variables d’environnement avant le démarrage des processus, ce que torchrun ne fait pas de lui-même. Appelez torch.tpu.distributed.set_tpu_launch_env() et lancez torchrun depuis Python.
# launch.py
import sys
import torch
from torch.distributed.run import main
torch.tpu.distributed.set_tpu_launch_env()
main(sys.argv[1:])Passez les arguments habituels de torchrun au lanceur.
python launch.py --nproc_per_node=4 generate.py
Certains modèles nécessitent une adaptation avant de pouvoir être répartis sur plusieurs puces TPU.
Les modèles dont le nombre de têtes clé-valeur n’est pas divisible par tp_size ne peuvent pas fractionner leurs couches d’attention et échouent lors du passage avant avec une erreur de forme. Il faut plutôt répliquer les projections d’attention sur chaque puce, en surchargeant leurs règles dans tp_plan. Les règles que vous ne surchargez pas conservent le plan par défaut du modèle. Par exemple, GLM-4-9B-0414 possède 2 têtes clé-valeur, qui ne peuvent pas être réparties sur 4 puces.
model = AutoModelForCausalLM.from_pretrained(
"zai-org/GLM-4-9B-0414",
dtype=torch.bfloat16,
distributed_config=DistributedConfig(
tp_size=4,
tp_plan={
"layers.*.self_attn.q_proj": "replicated_with_grad_allreduce",
"layers.*.self_attn.k_proj": "replicated_with_grad_allreduce",
"layers.*.self_attn.v_proj": "replicated_with_grad_allreduce",
"layers.*.self_attn.o_proj": "replicated_with_grad_allreduce",
},
),
)Les modèles avec des poids liés, tels que Qwen3-0.6B, échouent au chargement lorsque tp_size est supérieur à 1.
Utiliser les noyaux du Hub
La bibliothèque kernels prend en charge les TPU depuis la v0.17. Les noyaux TPU encapsulent le code JAX et Pallas, il est donc nécessaire d’installer jax en parallèle de kernels.
pip install "transformers[kernels]" jaxVoir Chargement des noyaux pour savoir comment charger un noyau depuis le Hub.
Limites
device_map="auto"charge le modèle sur le CPU au lieu du TPU. Passez explicitementdevice_map="tpu".- Les formes dynamiques déclenchent une recompilation. La génération ralentit lorsque les formes des entrées changent d'une étape à l'autre. Utilisez un cache statique pour une génération plus rapide.
- Chaque processus ne peut accéder qu'à une seule puce TPU. Utilisez un processus par puce pour exécuter sur plusieurs puces.
- Les intégrations de Transformers pour l’entraînement et la quantification sur TPU sont encore en cours de développement, certaines fonctionnalités peuvent donc ne pas fonctionner encore. Veuillez ouvrir un ticket si vous rencontrez un problème.