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++ demos——整合进一个精简的工作流中。

---

Key Features

Feature	What it does
One‑click compilation	llm_convert.py 将 HuggingFace 或 GGUF checkpoints 直接转换为 SOPHGO bmodel（TPU 可理解的二进制格式）。
Broad model catalog	提供预包装的数十种模型，从纯文本 LLMs（Qwen‑3, Llama‑3.2, Phi‑4, MiniCPM‑V）到支持图像、视频与音频的多模态 VLMs（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++ 参考脚本，以及预编译好的 bmodels 用于即时测试。
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 checkpoints 转换为快速、 TPU 原生的推理引擎，支持广泛的文本和多模态模型，并提供现成的 demos 和丰富的编译选项。