vllm-torchtpu README

README проекта с github.com/vllm-project/vllm-torchtpu. Одним файлом markdown: README.md.

vLLM TorchTPU vLLM TorchTPU

| Documentation | Blog | User Forum | Developer Slack (#sig-tpu) |


About

vLLM TorchTPU is the PyTorch-native TPU backend for vLLM. It is an out-of-tree vLLM platform plugin, packaged as vllm-torchtpu, that runs vLLM's standard PyTorch model definitions on Google Cloud TPUs through TorchTPU (torch_tpu, via torch.compile(backend="tpu")) and a library of custom JAX/Pallas kernels for attention, Mixture-of-Experts, and quantized matmul.

The goal is simple: the same vLLM you already use — same CLI, same OpenAI-compatible server, same model definitions — running at TPU speed with no model code changes.

[!NOTE] Looking for the JAX backend? The original TPU backend for vLLM, tpu-inference, has been rebranded as vLLM JAX. It remains available for serving pure JAX model implementations on TPU. vllm-torchtpu is the recommended path for serving PyTorch model definitions on TPU.


Supported hardware

TPU generation Status
TPU v7x (Ironwood) Recommended — validated in CI on every pull request and nightly
TPU v6e (Trillium) Supported — not covered by CI
TPU v5e / v5p Experimental — not covered by CI

See Cloud TPU Setup for project setup, quota, and provisioning commands.


Get started

Install

vllm-torchtpu requires Python 3.12 on a Cloud TPU VM. Install vllm-torchtpu from PyPI and a matching vLLM with a single command:

pip install \
  --extra-index-url https://download.pytorch.org/whl/cpu \
  vllm-torchtpu

Or pull the pre-built container from Docker Hub (vllm/vllm-torchtpu):

docker pull vllm/vllm-torchtpu:latest

For uv, editable source installs, cross-repo development against a local vllm checkout, and Docker images, see the full Installation guide and Docker guide.

Serve a model

Start an OpenAI-compatible server exactly as you would on any other vLLM platform:

vllm serve meta-llama/Llama-3.2-1B-Instruct \
  --tensor-parallel-size 1 \
  --max-model-len 4096

Then send a request:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.2-1B-Instruct",
    "messages": [{"role": "user", "content": "Explain how TPUs accelerate matrix multiplication."}],
    "max_tokens": 128
  }'

[!TIP] The first startup compiles TPU graphs for the configured shapes and can take several minutes. Set VLLM_XLA_CACHE_PATH to persist compiled artifacts across restarts — see Compilation & Warmup Cache.

The Quickstart covers offline batch inference with vllm.LLM, multi-device serving with TP/EP, and multimodal examples.


Supported models and features

vllm-torchtpu can serve most PyTorch models supported by vLLM, with first-class TPU kernel, quantization, and parallelism support for Qwen3 / Qwen3.5, DeepSeek-V3 / R1 / V4, Kimi-K2.5 / K3, GLM-5, Llama 3 / 4, GPT-OSS, Gemma 3 / 4, Mixtral, Qwen-VL and Gemma VL families, and diffusion models via vllm-omni.


Recipes and deployment


🤝 Contribute

We welcome contributions of all kinds — bug reports, model and feature requests, documentation fixes, and code.

Developer references: Testing & CI · Profiling · Benchmarking · Coding guidance · Optimization best practices


💬 Contact us

vllm-torchtpu (vllm-project/vllm-torchtpu)

Ищем в базе…

Что это такое?vllm-torchtpu — это плагин-бэкенд для vLLM на основе PyTorch, который позволяет запускать те же команды vLLM CLI, сервер с совместимым с OpenAI API и определения моделей на TPU Google Cloud через torch.compile и собственные ядра JAX/Pallas, без изменений в коде модели.
Это отдельное приложение или плагин для vLLM?Это внешний платформенный плагин для vLLM, который распространяется пакетом vllm-torchtpu. Его устанавливают вместе с vLLM, а не как самостоятельное приложение.
Как установить и запустить?Установите vllm-torchtpu из PyPI вместе с подходящей версией vLLM одной командой pip или скачайте готовый образ vllm/vllm-torchtpu с Docker Hub, а затем запустите обычный сервер vLLM с совместимым с OpenAI API.
Что нужно перед использованием?Нужен Python 3.12, запущенный на виртуальной машине TPU Google Cloud. GPU не требуется, но сначала нужно настроить доступ к проекту TPU, квоты и выделение ресурсов.
Есть ли подводные камни при запуске?При первом запуске сервера компилируются графы TPU для заданных форм данных, и это может занять несколько минут (скомпилированный кеш можно сохранить через VLLMXLACACHEPATH). В CI проверена только TPU v7x: для v6e покрытия в CI нет, а v5e и v5p остаются экспериментальными.
Чем это отличается от JAX-бэкенда проекта (vLLM JAX)?Исходный бэкенд для TPU, который раньше назывался tpu-inference, а теперь переименован в vLLM JAX, работает с моделями, реализованными на чистом JAX. vllm-torchtpu же рекомендуется для запуска нативных моделей vLLM на PyTorch на TPU.
Какие модели и функции поддерживаются?Можно запускать большинство моделей PyTorch, которые vLLM уже поддерживает. Для Qwen3/3.5, DeepSeek-V3/R1/V4, Kimi-K2.5/K3, GLM-5, Llama 3/4, GPT-OSS, Gemma 3/4, Mixtral, Qwen-VL/Gemma-VL есть полноценные ядра для TPU и квантизация. Также поддерживаются диффузионные модели через vllm-omni.
Какие собственные ядра он добавляет для производительности на TPU?В комплекте есть ядра Pallas, настроенные под TPU: Ragged Paged Attention, dense и sparse MLA, Gated DeltaNet, fused MoE с разгрузкой на SparseCore, а также квантованные матричные умножения в FP8, INT8 и MXFP4.
Поддерживается ли масштабирование на несколько хостов TPU?Да. Тензорный, данных, конвейерный и экспертный параллелизм, а также параллелизм контекста для prefill и decode работают вместе на одиночных и многохостовых срезах TPU, включая разнесённый (disaggregated) режим prefill/decode.
Автор
vllm-project
Размер
220.3 MB
Звёзды
142
Возраст
5 мес
Коммиты · 90 дней