Transformers documentation
Google TPU
Google TPU
Google Cloud TPUs ejecutan PyTorch de forma nativa a través del paquete torch_tpu, que registra el dispositivo tpu. torch_tpu compila las operaciones que ejecuta para cada forma de entrada que detecta, por lo que mantener las formas de entrada estáticas evita recompilaciones.
Instalación
Instale torch_tpu siguiendo las instrucciones del repositorio de torch_tpu. torch_tpu se carga automáticamente al importar torch. Compruebe que PyTorch detecta las chips TPU.
import torch
print(torch.accelerator.is_available(), torch.accelerator.device_count())Imprime True y el número de chips TPU, por ejemplo True 4.
Ejecutar inferencia
device_map="auto" no detecta TPU. La colocación automática depende de Accelerate para listar los dispositivos disponibles, y Accelerate no lista los dispositivos TPU, por lo que el modelo se carga silenciosamente en la CPU. Pasa device_map="tpu" a from_pretrained() de forma explícita, o device="tpu" a Pipeline.
Pase las entradas de generación en la CPU en lugar de llamar a .to(model.device). generate() solo mueve a la TPU los tensores que forward consume. Los tensores que crecen en cada paso (secuencia de salida, attention_mask) permanecen en la CPU, por lo que el gráfico compilado se mantiene estable. generate devuelve la salida en el mismo dispositivo que las entradas. Consulte Mantener los tensores de generación en la CPU para más detalles. Los modelos usan SDPA de forma predeterminada en la 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
Con una caché estática, generate() compila la pasada hacia adelante con torch.compile y el backend tpu de forma automática. Pasa disable_compile=True a generate para desactivar esta opción.
Paralelismo de tensores
torch_tpu ejecuta un proceso por chip TPU, y cada proceso ve su chip como tpu:0. Crea un DistributedConfig con el tamaño de paralelismo de tensor y pásalo a from_pretrained(). Transformers fragmenta el modelo en el momento de la carga.
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 requiere que se establezcan algunas variables de entorno antes de que comiencen los procesos, algo que torchrun no hace por sí solo. Llama a torch.tpu.distributed.set_tpu_launch_env() e inicia torchrun desde Python.
# launch.py
import sys
import torch
from torch.distributed.run import main
torch.tpu.distributed.set_tpu_launch_env()
main(sys.argv[1:])Pase los argumentos habituales de torchrun al lanzador.
python launch.py --nproc_per_node=4 generate.py
Algunos modelos necesitan adaptarse antes de poder fragmentarse entre chips TPU.
Los modelos cuyo número de cabezas de clave-valor no es divisible por tp_size no pueden fragmentar sus capas de atención y fallan en la pasada hacia adelante con un error de forma. En su lugar, replica las proyecciones de atención en cada chip, sobrescribiendo sus reglas en tp_plan. Las reglas que no sobrescribas conservarán el plan predeterminado del modelo. Por ejemplo, GLM-4-9B-0414 tiene 2 cabezas de clave-valor, que no se pueden dividir entre 4 chips.
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",
},
),
)Los modelos con pesos vinculados, como Qwen3-0.6B, no se pueden cargar con un tp_size mayor que 1.
Usar kernels de Hub
La biblioteca kernels admite TPU desde la v0.17. Los kernels de TPU envuelven código de JAX y Pallas, por lo que instale jax junto con kernels.
pip install "transformers[kernels]" jaxConsulte Carga de kernels para saber cómo cargar un kernel desde el Hub.
Limitaciones
device_map="auto"carga el modelo en la CPU en lugar de la TPU. Pasa explícitamentedevice_map="tpu".- Las formas dinámicas provocan recompilación. La generación se ralentiza cuando las formas de entrada cambian de un paso a otro. Utilice una caché estática para una generación más rápida.
- Cada proceso solo puede acceder a un chip TPU. Utilice un proceso por chip para ejecutar en varios chips.
- Las integraciones de Transformers para el entrenamiento y la cuantización en TPU aún están en desarrollo, por lo que es posible que algunas funciones no funcionen todavía. Si te encuentras con un problema, por favor abre un issue.