sophgo/LLM-TPU

LLM‑TPU – 在 SOPHGO TPUs 上部署大型語言與視覺模型

什麼是它 – SOPHGO 的開源工具包，讓您能透過單一指令，將熱門的生成式 AI 模型（如 Qwen、Llama、Phi、MiniCPM 等 LLM，以及多模態視覺語言模型）在 SOPHGO 的 BM1684X、BM1688 或 CV186X TPU 晶片上運行。

為什麼重要 – 在專用 TPU 上運行大模型可以比 CPU/GPU 提供數個數量級的速度提升與更低的功耗，但編譯與部署步驟通常很複雜。LLM‑TPU 將整個流程——權重轉換、量化、bmodel 生成以及現成的 Python/C++ demo——整合進一個精簡的工作流中。

---

Key Features

Feature	What it does
One‑click compilation	llm_convert.py 將 HuggingFace 或 GGUF checkpoint 轉換為 SOPHGO bmodel（TPU 可理解的二進位格式）。
Broad model catalog	提供預包裝的數十種模型，從純文本 LLM（Qwen‑3, Llama‑3.2, Phi‑4, MiniCPM‑V）到支援影像、影片與音訊的多模態 VLM（Mage‑VL, InternVL‑3, Qwen‑3.5‑VL, Gemma‑4）。
Quantisation support	原生支援 AWQ/GPTQ/AutoRound int4 模型；也提供可選的 --quantize 參數來進行自定義精度（w4bf16, bf16 等）。
Dynamic & KV‑cache compilation	--dynamic 可降低短輸入的延遲；--use_history_kv 支援多輪對話與長上下文的 KV‑cache。
Multi‑chip parallelism	--num_device N 可將模型擴展至多個 TPU，實現更大的模型與更高的吞吐量。
Dual‑language demos	每個模型都附帶 Python 與 C++ 參考腳本，以及預編譯好的 bmodel 以供即時測試。
Advanced utilities	包含共享 prefill 複用、多任務權重共享、可選的模型加密以及 LoRA‑aware 編譯。

---

Quick Start (two commands)

git clone https://github.com/sophgo/LLM-TPU.git
cd LLM-TPU
./run.sh --model qwen3.5   # pulls a pre‑compiled bmodel and launches the demo

該腳本會自動下載適當的 bmodel（如果您已設置 TPU‑MLIR，則會進行編譯）並啟動一個可以透過 @<path> 接受影像/影片檔案的互動式聊天介面。

---

Supported Hardware

• BM1684X – 入門級 TPU，適合 4‑8 B 模型。
• BM1688 – 高階晶片，透過多晶片擴展可處理 10‑30 B 模型。
• CV186X – 以視覺為核心的 TPU，用於 VLM 推論。

---

Model Coverage (excerpt)

Category	Example Models	One‑click compile?
Text‑only LLMs	Qwen‑3, Qwen‑2.5, Llama‑3.2, Phi‑4, MiniCPM‑4, DeepSeek‑R1 series	✅
Vision‑Language	Mage‑VL, InternVL‑3, Qwen‑3.5‑VL, Qwen‑2.5‑VL, Gemma‑4	✅
Audio / Video	Qwen‑3.5 (audio), MiniCPM‑V‑4.6 (video), Gemma‑4 (audio)	✅
Legacy demos	Baichuan‑2, ChatGLM‑3, RWKV, etc. (still in models/legacy/)	—

---

Compilation Flow (example with Qwen3.5‑2B)

1. Download weights – 建議使用 int4 AWQ/GPTQ checkpoint。
2. Set up TPU‑MLIR – 遵循連結的 repo 或使用提供的 Docker 映像檔。
3. Run the converter:

   llm_convert.py -m /path/Qwen3.5-2B-int4-AutoRound \
       -s 2048 --max_input_length 1024 \
       -c bm1684x -o qwen3.5_2b
   

   • -s = 總 KV‑cache 長度。
   • 加入 --use_history_kv 與 --chunk_length 以進行長上下文、多輪對話使用。
4. 輸出資料夾包含一個 *.bmodel 檔案與一個已準備好用於 demo 腳本的 config 目錄。

---

Getting the Most Accuracy

• 偏好使用預量化的 AWQ/GPTQ/AutoRound checkpoints – 這些在轉換後能保留原模型的品質。
• 如果僅有 FP16/FP32 權重，請在執行 llm_convert.py 之前，先使用 AutoAWQ 或 AutoGPTQ 進行量化。

---

Where to Learn More

• FAQ – docs/FAQ.md
• Paper – An MLIR‑Based Compilation Method for Large Language Models (arXiv:2607.15865)
• TPU‑MLIR repo & docs – 實際產生 bmodel 的編譯器。
• Video walkthroughs – README 中的 Bilibili 連結。

---

Contributing

歡迎透過 GitHub 頁面或 SOPHGO 網站進行 Issues, pull‑requests 與商業洽詢。

---

License

Apache‑2.0 (see LICENSE).

---

TL;DR – LLM‑TPU 是一個實用的、官方支援的橋樑，能將 HuggingFace checkpoint 轉換為快速、TPU 原生的推論引擎，支援廣泛的文本與多模態模型，並提供現成的 demo 與豐富的編譯 compilation options。