vLLM TT 插件将 Tenstorrent 加速器引入 LLM 服务

TL;DR

vLLM TT 插件为 vLLM 服务堆栈增加了对 Tenstorrent 加速器的支持，保留了相同的 OpenAI 兼容 API，同时引入了原生网格调度器、设备端采样以及单进程车道数据并行设计。

TT 插件概览

该插件以树外平台模块的形式分发，当可导入 TT-Metal 的 ttnn 包时会自动激活。无需更改客户端代码或请求格式；OpenAI 兼容 API 可直接使用，无需修改。

支持的模型家族

该插件使用 TT 前缀注册基于 Tenstorrent 的架构。模型选择基于架构而非模型名称，允许单个注册覆盖多个版本。当前支持的列表包括：

模型家族 TT 架构类
Llama 3.1 / 3.2 / 3.3 TTLlamaForCausalLM
Llama 3.2 Vision TTMllamaForConditionalGeneration
Qwen 2.5 / Qwen 3 TTQwen2ForCausalLM, TTQwen3ForCausalLM
Qwen 3.5 / 3.6 TTQwen3_5ForConditionalGeneration
Qwen 2.5‑VL / 3‑VL TTQwen2_5_VLForConditionalGeneration, TTQwen3VLForConditionalGeneration
Mistral / Mistral 3 TTMistralForCausalLM, TTMistral3ForConditionalGeneration
Gemma 3 TTGemma3ForConditionalGeneration
Gemma 4 TTGemma4ForCausalLM, TTGemma4ForConditionalGeneration, TTGemma4UnifiedForConditionalGeneration
DeepSeek V3 TTDeepseekV3ForCausalLM
GPT‑OSS 20B / 120B TTGptOssForCausalLM

Llama 3.2 Vision、Qwen‑VL、Qwen 3.6、Mistral 3 和 Gemma 3 等多模态模型已通过该插件提供服务。

架构为中心的注册

该插件不包含模型代码；它仅注册架构名称。实际实现位于 TT-Metal 中，每个类封装了一个手工编写的 TTNN 模型。由于注册基于架构，单个类可支持多个模型版本（例如 TTQwen3_5ForConditionalGeneration 可服务 Qwen/Qwen3.6-27B）。

可通过将 EXTRA_MODELS_DIR 指向包含 vllm_metadata.json 和适配器类的目录，无需修改插件源码即可添加自定义模型。设置 TT_VLLM_BUILTIN_MODELS=0 可将注册表限制为仅用户提供的模型。

Tenstorrent 网格与 GPU 形状推理堆栈

Tenstorrent 硬件是一个由核心和芯片组成的网格，通过片上网络连接（例如 n150、n300、QuietBox、Galaxy）。程序针对固定网格形状编译，芯片间的数据移动被固化在编译后的追踪中，而非作为主机端的集体操作发出。

这种编译模型的关键后果包括：

  • 无张量并行或流水线并行等级 – 网格程序直接编码并行性。MESH_DEVICE=TG 标志取代了通常的 --tensor‑parallel-size 参数，插件会拒绝 -tp/-pp。
  • 步骤粒度为整个追踪程序 – 每个步骤重放一个固定批处理形状的捕获追踪，使得同质批处理比异质批处理便宜得多。
  • 采样可在设备上执行 – 网格程序可直接返回所选标记，消除主机端 logits 传输。

这些差异要求对 vLLM 的插件接口进行重大调整。

插件集成点

vLLM 硬件插件机制（2025 年 5 月引入）提供两个入口点：

入口点组 名称 目标
vllm.platform_plugins tt vllm_tt_plugin.entrypoints:platform_plugin
vllm.general_plugins tt_model_registry vllm_tt_plugin.entrypoints:register

platform_plugin() 仅在 ttnn 可导入时返回 TTPlatform 实例，防止在纯 CUDA 环境中意外激活。

该插件通过 vLLM 的扩展点替换为 Tenstorrent 特定的运行时类：

vLLM 配置字段 TT 实现
parallel_config.worker_cls vllm_tt_plugin.worker.TTWorker
scheduler_config.scheduler_cls vllm_tt_plugin.scheduler.TTScheduler 或 vllm_tt_plugin.lane_scheduler.TTLaneCoordinator

设备特定选项通过 vLLM 的通用 --additional-config 命名空间传递，例如：

--additional-config.tt.sample_on_device_mode all
--additional-config.tt.fabric_config FABRIC_1D_RING

vLLM 核心中不包含任何 Tenstorrent 特定代码，确保与上游版本的向前兼容性。

基于阶段的调度

与 vLLM 的 token 预算调度器不同，Tenstorrent 路径将每个调度步骤限制为三种同质结果之一：

  1. 仅预填充
  2. 仅解码
  3. 空

不允许混合预填充和解码的批处理。长提示被拆分为多个仅预填充步骤，解码步骤穿插其中以保持其他请求的推进。该设计保持了追踪稳定性，这对编译后的网格程序至关重要。

阶段拆分带来的优势

  • 每个步骤形状可复用单一编译追踪。
  • 模仿大型 GPU 集群中使用的“解耦服务”模式，但应用于单个引擎内。

所需代价

  • 解码请求需等待每个预填充块，产生步骤级延迟惩罚。
  • 调度器必须在步骤间切换模式，带来少量策略开销。

该设计仍具可扩展性；未来版本如需可捕获混合形状追踪。

Galaxy 上的单进程车道数据并行

Galaxy（一个 32 芯片网格）将某些模型作为单执行程序运行于整个网格。由于仅支持一次网格提交，传统多进程数据并行无法应用。

解决方案是进程内车道 DP：

  • TTLaneCoordinator 为每个车道（默认四个车道）创建一个 TTScheduler。
  • 每个车道维护自己的等待/运行队列、KV 缓存和块 ID 空间。
  • 请求被分配给负载最低的车道并绑定在其上。
  • 每个步骤中协调器为所有车道选择共享模式（预填充或解码）。无工作的车道贡献空切片。
  • 合并后的批处理仅发送一次设备；结果在内部拆分回车道。

这消除了早期多进程尝试中困扰的昂贵进程间散射/聚集操作。

边界情况

如果预填充步骤因 KV 压力而未接纳任何标记，而另一车道有解码工作，则该步骤将重试为解码模式，以避免死锁。

用户可见标志

使用常规 vLLM 标志：

MESH_DEVICE=TG \
TT_LLAMA_TEXT_VER=llama3_70b_galaxy \
VLLM_RPC_TIMEOUT=900000 \
python examples/server_example_tt.py \
  --model "meta-llama/Llama-3.3-70B-Instruct" \
  --data_parallel_size 4 \
  --max_num_seqs 8 \
  --async-scheduling \
  --additional-config.tt.dispatch_core_axis col \
  --additional-config.tt.sample_on_device_mode all \
  --additional-config.tt.fabric_config FABRIC_1D_RING \
  --additional-config.tt.worker_l1_size 1344544 \
  --additional-config.tt.trace_region_size 220000000

--data_parallel_size 4 现在创建四个进程内车道，每个车道可处理 --max_num_seqs 个请求。

设备端采样与自动回退

当设置 sample_on_device_mode 时，网格程序执行标记选择并直接返回标记。如果某批处理需要设备无法表达的功能（logprobs、惩罚、自定义 logits 处理器等），该插件仅对该批处理回退到 vLLM 的主机端采样器。always_compat_sampling 标志强制主机端采样以供调试。

异步解码重叠

该插件提供解码/主机重叠，但仅作为异步主机读取，而非独立设备执行线程：

  1. 提交解码工作而不阻塞（read_from_device=False）。
  2. 启动非阻塞主机读取（async_read=True）。
  3. 存储结果事件。
  4. 在最终化时，使用 ttnn.event_synchronize() 同步后再转换为主机张量。

深度为 2 的在途队列允许主机在步骤 N 的读取仍在进行时调度步骤 N+1。重叠仅在稳定生成阶段（稳定形状、设备端采样、无结构化输出记账）维持。预填充仍为同步操作。

当前限制

该插件会提前验证配置并拒绝不支持的组合：

  • 张量并行和流水线并行通过网格形状表达，而非 vLLM 等级。
  • 未支持推测解码、LoRA 和提示 logprobs。
  • 前缀缓存仅对声明支持的模型可用。
  • 异步解码重叠需要模型声明支持能力。
  • 标准多进程 DP 不支持 MoE 模型；改用车道 DP。
  • 多主机服务尚未实现。

这些是当前 TT-Metal 运行时和模型实现的限制，而非硬性硬件约束。

快速入门

  1. 按照官方指南安装 TT-Metal。

  2. 克隆并安装插件：

    git clone https://github.com/tenstorrent/vllm-tt-plugin.git
cd vllm-tt-plugin
source docs/install-vllm-tt.sh

    该脚本在 TT-Metal 环境内使用版本 0.26.0 构建 vLLM。

  3. 服务一个模型：

    MESH_DEVICE=T3K VLLM_RPC_TIMEOUT=100000 python examples/server_example_tt.py

  4. 使用任何 OpenAI 兼容客户端查询，例如：

    curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "meta-llama/Llama-3.1-70B-Instruct", "prompt": "San Francisco is a", "max_tokens": 32}'

发展路线图

  • 扩展异步解码支持至更多模型家族。
  • 为更多模型启用前缀缓存及车道 DP RoPE 处理。
  • 一旦网格端草稿/验证流水线稳定，实现推测解码。
  • 添加多主机服务以突破单机规模。

致谢

该插件基于 Ascend 团队贡献的 vLLM 平台插件机制和 Spyre 团队的可插拔调度器设计。感谢 vLLM 维护者保持扩展点足够通用，以支持网格架构。

贡献者包括 Viktor Puš、Tomasz Cheda、Sanjar Adylov 和 Salar Hosseini。欢迎通过 GitHub 问题或 vLLM Slack 提供关于车道 DP 用户界面和优先模型家族的反馈。

Sources