vLLM TT 插件將 Tenstorrent 加速器帶入 LLM 服務

TL;DR

vLLM TT 插件為 vLLM 服務堆疊新增 Tenstorrent 加速器支援，保留相同的 OpenAI 兼容 API，同時引入原生網格排程、設備端取樣，以及單一程序 lane 資料平行設計。

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 網格 vs. GPU 形狀推理堆疊

Tenstorrent 硬體是由核心與晶片組成的網格，透過片上網路（如 n150、n300、QuietBox、Galaxy）連接。程式碼會針對固定網格形狀編譯，晶片間的資料移動會內嵌於編譯後的追蹤中，而非由主機端發出集合操作。

此編譯模型的關鍵後果：

  • 無張量平行或流水線平行的 rank – 網格程式直接編碼平行性。MESH_DEVICE=TG 標記取代常見的 --tensor‑parallel-size 參數，插件會拒絕 -tp/-pp。
  • 步驟粒度為整個追蹤程式 – 每個步驟重播針對固定批次形狀的捕捉追蹤，使同質批次的代價遠低於異質批次。
  • 取樣可在設備端執行 – 網格程式可直接回傳選取的 token，消除主機端 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 上的單一程序 lane 資料平行

Galaxy（32 晶片網格）將部分模型以單一執行程式跨整個網格執行。由於僅有一個網格提交，傳統的多程序資料平行無法應用。

解決方案是程序內 lane DP：

  • TTLaneCoordinator 為每個 lane（預設四 lane）建立一個 TTScheduler。
  • 每個 lane 維護自己的等候/執行佇列、KV 快取與 block-ID 空間。
  • 請求會指派給負載最低的 lane，並在該 lane 上保持綁定。
  • 每個步驟中，協調器為所有 lane 選擇共享模式（預填或解碼）。無工作的 lane 則貢獻空切片。
  • 合併後的批次僅傳送至設備一次；結果由內部拆分回 lane。

此設計消除了早期多程序嘗試中導致高成本的跨程序分散/聚合。

特殊情況

若預填步驟因 KV 壓力導致無 token 接納，而另一 lane 有解碼工作，則該步驟會以解碼模式重試，以避免死結。

使用者可見的旗標

使用常見的 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 現在會建立四個程序內 lane，每個 lane 均可處理 --max_num_seqs 個請求。

設備端取樣與自動回退

當設定 sample_on_device_mode 時，網格程式會執行 token 選取並直接回傳 token。若某批次需要設備無法表達的功能（如 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 的 rank。
  • 推測解碼、LoRA 和提示 logprobs 目前尚未支援。
  • 前綴快取僅對宣告支援的模型可用。
  • 非同步解碼重疊需要模型宣告的能力。
  • 標準多程序 DP 不支援 MoE 模型；改用 lane-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}'

路線圖

  • 擴展非同步解碼支援至更多模型家族。
  • 為更多模型啟用前綴快取，並支援 lane-DP RoPE 處理。
  • 一旦網格端草稿/驗證流程穩定，即實作推測解碼。
  • 加入多主機服務，以突破單一機器的規模限制。

致謝

該插件建立在 Ascend 團隊貢獻的 vLLM 平台插件機制，以及 Spyre 團隊的可插拔排程設計之上。感謝 vLLM 維護者，讓擴展點保持足夠通用，以支援網格架構。

貢獻者包括 Viktor Puš、Tomasz Cheda、Sanjar Adylov 和 Salar Hosseini。歡迎透過 GitHub 問題或 vLLM Slack 提出關於 lane-DP 使用介面與優先模型家族的反饋。

Sources