聊到深度学习模型部署，很多人都会经历同一个尴尬：训练时用的 PyTorch、TensorFlow 跑实验风生水起，一上生产环境换 CPU、换 GPU、换嵌入式设备，性能直接崩给你看。要么算子不支持，要么延迟高得离谱。TVM 就是在这个痛点里长出来的编译器框架，它不是一个推理引擎，而是一套把模型“重新编译优化”成目标硬件代码的编译器基础设施，适合做推理加速、算子调优、以及各种新兴芯片上的模型移植。这篇是 TVM 从入门到精通系列的第一篇，我不打算铺垫太多，直接说安装。但标题虽然叫“安装 TVM”，真正决定你后面几天体验的，是安装方式的选择、版本的选择，以及 LLVM、CUDA 这些依赖怎么配。这些坑我会一个个讲清楚，你照着操作就好。
1. 安装之前的必修课：TVM 的组成和安装决策
1.1 为什么模型部署需要 TVM
传统推理引擎的问题在于“每个硬件都要一套独立优化”。NVIDIA 有 TensorRT，Intel 有 OpenVINO，它们都很快，但各自只解决自家硬件，且大多只接受已经定义好的算子集合。换了新算子、新模型结构，或者碰到一款不在名单里的新芯片，优化就得从头再来。
TVM 的思路更像“把模型重新编译一次”。它把 PyTorch、ONNX、TensorFlow 这些前端模型统一转成自己的 IR，做图级优化，再把算子拆到低层 IR 上做优化和代码生成，最后编译成目标硬件的可执行代码。这意味着你用同一套代码，可以同时生成 CPU、GPU、OpenCL、Vulkan 甚至 FPGA 的后端实现。你不需要为每个硬件写一套算子库，而是让编译器帮你完成大部分底层适配。
我入行时是先从“手工算子优化”干起的，那时候为了在一个新 NPU 上跑通模型，常常要手动拆图手写算子，一写就是几周。TVM 这类编译器把很多工作自动化了，虽然学习曲线不低，但值得投入。
1.2 三个核心组件决定了你要开哪些编译开关
安装 TVM 时经常遇到 config.cmake 里的各种选项，看起来是在配构建参数，实际上是在选择“你将要使用哪些功能”。所以先认识几个关键组件，配开关时才不会一头雾水。
Relay 是 TVM 的图级 IR，负责接收前端模型、做算子融合、常量折叠这些图优化。只要你想导入 PyTorch 或 ONNX 模型，你就离不开 Relay。TE（张量表达式）是写自定义算子的高层接口，你把算子的计算逻辑写出来，如何调度再交给 TVM 去搜索。TIR 是更底层的 IR，贴近具体设备，TVM 的很多调试信息就是 TIR 形式的代码。Target 是目标硬件描述，比如 llvm、cuda、opencl、vulkan，它直接对应你编译时要不要开对应后端。
明白这些之后，config.cmake 里的 USE_LLVM、USE_CUDA、USE_OPENCL 是什么意思就清楚了：它们决定 TVM 的编译器栈能生成哪些目标平台的代码。安装时你开的开关，就是你之后能用的 Target。
1.3 源码编译前，先想清楚版本策略
安装 TVM 不是“越新越好”，而是“和你学习的资料、要复现的论文、要跑的项目越匹配越好”。我写这篇时最新的稳定版是 v0.18.0，它是官方维护的 release 分支，API 相对稳定，网上能搜到的教程大多能对上号。如果你只是想稳定学习，直接选这个。
如果你更想跟进新特性，比如最新的 pass 优化、RPC 协议变化，可以切到 main 分支。但要知道，main 分支每天都在变，昨天能编译的代码今天可能就编译不过了。我的习惯是：先按稳定 tag 装好一套能用的环境，再另开一个目录拉 main 研究，两边互不干扰。
无论选哪个版本，记得把 commit hash 记下来。以后你在社区提问、复现别人的方案时，这个 hash 就是你和对方对齐世界的关键。
2. 安装路线怎么选：pip、源码编译还是 Docker
2.1 pip 包：五分钟跑通 demo
最简单的一条路是pip install apache-tvm。注意包名不是 tvm，而是 apache-tvm。装完直接import tvm就能用 CPU 后端跑大部分 Relay 教程。
但我要说清楚它的边界：预编译包针对的是通用 CPU 环境，GPU 后端受限于官方构建时的 CUDA 版本，和你宿主机上装的驱动不一定匹配。它适合快速验证、跑通官方文档里的示例、或者用纯 CPU 跑模型对比精度。如果你想开 CUDA、TensorRT、Vulkan 这些后端，或者想改 C++ 端的调度代码，pip 包就不够用了。
2.2 源码编译：最完整也最值得走的路
官方文档主推的方式是源码编译。它的好处是配置完全可控：想支持几个 Target 就开几个开关，想调试 Relay pass 就打开 USE_RELAY_DEBUG，想开发 C++ 端扩展库也有完整源码。缺点很明显：依赖多、耗时长、对系统环境有一定要求。
我强烈建议所有打算长期使用 TVM 的人都走一遍源码编译。这不是自虐，而是因为你在后面一定会遇到需要看源码、改编译选项、检查生成代码的场景。如果连编译都跑过，遇到问题会更有底气。第一次编译成功后，整个环境是什么结构、哪些文件在哪儿、怎么重启配置，你心里会非常清楚。
2.3 Docker 和 CI 镜像：环境洁癖患者的救星
TVM 官方在仓库的 docker 目录下维护了不少 CI 镜像，里面预装了编译 TVM 所需的大部分依赖。如果你不想把宿主机环境搞得一团糟，或者需要在不同机器上复现同一套环境，用 Docker 是最省心的。写完 Dockerfile，把源码挂载进容器，构建一次以后随时复用。
它的缺点是开发体验不如本地流畅，比如你想用 IDE 直接调试 C++ 代码，在容器里配置麻烦一些。但作为备选方案，它尤其适合“不想污染服务器环境”的场景。
2.4 选型小结：三个对比维度
| 路线 | 安装耗时 | GPU 后端支持 | 可调试性 | 适合场景 | 踩坑概率 |
|---|---|---|---|---|---|
| pip 包 | 数分钟 | 有限，受限于官方构建参数 | 差，难以改底层 | 快速跑 Demo、学习 Relay | 低 |
| 源码编译 | 10-40 分钟 | 完全可控，想开就开 | 强，可读源码可加日志 | 长期使用、开发、调优 | 中，但值得 |
| Docker 镜像 | 取决于镜像下载速度 | 可控，需自己配容器内环境 | 一般，可通过 vscode 远程调试 | 环境隔离、团队复现 | 低，但需学 Docker |
我个人强烈建议至少完成一次源码编译。就算你后面决定用 pip 包当日常工具，源码编译的经验也会帮你理解 TVM 到底是怎么工作的。
3. 源码编译完整实录：从零到 import tvm 成功
3.1 系统依赖：先装齐再动手
以 Ubuntu 22.04 为例，先把基础工具链装好：
sudo apt update sudo apt install -y git build-essential cmake python3 python3-dev python3-pip这里每个包都有自己的用途：git 用来拉取源码；build-essential 提供宿主编译器 gcc/g++，TVM 本体是要被编译成 C++ 库的；cmake 是构建系统；python3-dev 提供 Python 头文件，TVM 的 C++ 模块需要它来生成 Python 绑定。
如果你用的是 CentOS 或较老的系统，包名可能不同，但逻辑是一样的：要么有编译器，要么没有。装完后先用gcc --version和cmake --version确认版本足够新，TVM 0.18 需要 CMake 3.20 以上、gcc 能支持 C++17。
3.2 拉取源码：别漏了子模块
git clone --recursive https://github.com/apache/tvm.git cd tvm git checkout v0.18.0 git submodule update --init --recursive第一行的--recursive很多人会漏掉，这个参数会把 3rdparty 目录下的子模块一并拉下来，包括 dmlc-core、dlpack、rang 等。这些子模块是 TVM 编译时的底层依赖。如果你漏了它们，编译到一半会报类似fatal error: dmlc/base.h: No such file or directory的错误。
切换到 tag 之后再执行一次git submodule update --init --recursive是为了确保子模块版本和 tag 对应。拉源码这件事看起来简单，但子模块版本不匹配导致的编译失败很常见，值得养成固定习惯。
3.3 LLVM：决定 target="llvm" 能不能用的关键
TVM 生成 CPU 代码依赖 LLVM。你可能会想，为什么不用 gcc 当代码生成后端？因为 TVM 需要的是“在运行时或编译期快速生成针对特定 CPU 特性的机器码”，LLVM 提供了一套完整的基础设施，包括代码优化、寄存器分配、指令选择，还能跨架构支持 x86、ARM、RISC-V。没有 LLVM，TVM 基本就废了一半。
在 Ubuntu 上安装官方 LLVM 15：
sudo apt install -y llvm-15-dev llvm-15-tools注意是llvm-15-dev，它才带 llvm-config 和开发头文件。只装llvm-15的话，运行时库有，但编译期找不到头文件和 llvm-config，后面 cmake 大概率要报错。
校验一下：
/usr/lib/llvm-15/bin/llvm-config --versionTVM 找 LLVM 有两种方式：一是在 config.cmake 里写USE_LLVM=ON，让构建系统自动搜 PATH；二是直接写绝对路径，比如USE_LLVM=/usr/lib/llvm-15/bin/llvm-config。我推荐第二种，明确、稳定，不会因为系统 PATH 环境不同而找错版本。
3.4 配置 config.cmake：每一个开关都要看懂
进入源码目录，创建 build 目录并初始化配置：
cd tvm mkdir -p build cd build cp ../cmake/config.cmake .然后用你熟悉的编辑器打开 config.cmake。最关键的是下面几个开关：
| 配置项 | 建议值 | 作用与说明 |
|---|---|---|
| USE_LLVM | ON 或绝对路径 | 必开，决定是否支持 target="llvm" |
| USE_CUDA | OFF 或 ON | 开启 CUDA 后端，需要本机有 CUDA Toolkit |
| USE_CUDNN | OFF 或 ON | 配合 CUDA 使用 cuDNN 库加速卷积 |
| USE_TENSORRT | OFF 或 ON | 集成 TensorRT 优化，依赖 NVIDIA 闭源库 |
| USE_OPENCL | OFF 或 ON | 跨平台并行计算，适合移动端、嵌入式 |
| USE_VULKAN | OFF 或 ON | GPU 通用计算，Linux 桌面和移动端首选 |
| USE_METAL | OFF 或 ON | macOS 上的 GPU 后端 |
| USE_STACKVM_RUNTIME | ON | 安全执行模型代码，默认开即可 |
| USE_GRAPH_EXECUTOR | ON | 支持图执行器，跑推理必需 |
| USE_PROFILER | OFF 或 ON | 性能分析，开发阶段建议开 |
| USE_RELAY_DEBUG | OFF 或 ON | 输出 Relay pass 调试信息，会明显增加编译时间 |
我第一次编译时贪心，把所有 GPU 后端全开了，结果光 CUDA 和 TensorRT 的依赖就折腾了一下午。后来我养成了一个原则：第一遍只开 USE_LLVM，把最小链路跑通，后面缺什么后端再加什么。这样定位问题快得多。
3.5 编译：时间和内存都要有预期
配置完成后执行：
cmake .. make -j$(nproc)$(nproc)会调用你机器的全部核心数，听起来很美，但 TVM 编译期比较吃内存，如果内存只有 8GB，几个核一起编译容易直接 OOM。一个更稳妥的做法是先看内存大小，内存小就老老实实make -j2或make -j4。编译时长通常在 10 到 40 分钟之间，具体看 CPU 和核数。
在编译过程中，终端会滚动大量日志，不要看到几行警告就慌。真正的成功标志是 build 目录下出现libtvm.so和libtvm_runtime.so。如果编译中途失败，常见是依赖缺失，先看日志里第一个 error，再对症下药。
3.6 让 Python 找到 TVM：两条路任选
编译完成后，还需要让 Python 能 import 到 tvm。官方推荐在 tvm/python 目录下执行 editable 安装：
cd tvm/python pip install -e .这样做的好处是以后你修改 Python 端代码不需要重新安装，开发时很舒服。如果不想影响当前 Python 环境，也可以直接用环境变量指定路径：
export TVM_HOME=/path/to/tvm export PYTHONPATH=$TVM_HOME/python:${PYTHONPATH}两条路选一条就行。但要注意顺序：必须先编译完 C++ 库，再安装 Python 包。因为 Python 包在 import 时是会动态加载 build 目录下的 libtvm.so 的，库不存在后面什么都跑不了。
3.7 验证安装：跑第一个编译任务
先确认版本：
python -c "import tvm; print(tvm.__version__)"能打印出 0.18.0 这种版本号就说明安装成功。接下来可以跑一个最小的 Relay 例子，验证编译链路真的通：
import numpy as np import tvm from tvm import relay x = relay.var("x", shape=(1, 16), dtype="float32") w = relay.const(np.random.rand(16, 8).astype("float32")) y = relay.nn.dense(x, w) mod = tvm.IRModule.from_expr(y) lib = relay.build(mod, target="llvm") print("build ok")如果输出 build ok，说明你已经成功编译并打通了第一条 TVM 编译链路。从这一刻开始，你已经算摸到 TVM 的门了。
4. 想上 GPU？CUDA 后端一次性配明白
4.1 先确认宿主机的 CUDA 版本
很多人误以为 PyTorch 能用 GPU，TVM 就一定能用。其实 PyTorch 自带了一套 CUDA runtime，TVM 编译需要系统里有独立的 CUDA Toolkit。在装 CUDA 后端之前，先看两个命令：
nvidia-smi nvcc -Vnvidia-smi 显示的是当前驱动支持的 CUDA 最高版本，nvcc 显示的是实际安装的 Toolkit 版本。两者不一定要严格相等，但 Toolkit 版本不能高于驱动支持的最高版本，否则运行时会报版本不匹配。
如果你发现没装 Toolkit，可以到 NVIDIA 官网下载对应版本的 runfile，或用 conda 装一个 cudatoolkit。我的建议是：如果用 conda 管理环境，就优先用 conda 装，省事且不容易污染系统。
4.2 config.cmake 里开启 CUDA 相关配置
编辑 config.cmake，找到以下几行并修改：
USE_CUDA = ON USE_CUDNN = ON USE_TENSORRT = OFF如果 cmake 没自动找到 CUDA，可以在文件里指定路径，比如USE_CUDA=/usr/local/cuda。之后重新执行：
cmake .. make -j$(nproc)注意，新增后端后一定要重新编译。TVM 的 Python 包安装一次就行，C++ 端动态库更新后会自动被加载，但保险起见，编译完重启一下 Python 进程，避免旧进程加载老版本。
编译完可以验证：
python -c "import tvm; print(tvm.target.Target('cuda'))"不报错就说明 CUDA 后端已经启用。
4.3 GPU 后端常见报错与排查
| 报错现象 | 可能原因 | 处理办法 |
|---|---|---|
CUDA is not enabled | 编译时没开 USE_CUDA | 重新编译，别只改 config.cmake 忘了 make |
libcuda.so not found | 驱动库路径不在 ld 搜索范围内 | 确认 nvidia-smi 正常，必要时设置 LD_LIBRARY_PATH |
cannot find -lcudart | 缺 CUDA Toolkit 或路径不对 | 正确安装 Toolkit，并在 config 里指定 CUDA 路径 |
CUDA driver version is insufficient | 驱动版本旧、Toolkit 版本新 | 降 Toolkit 版本或升级驱动 |
| PyTorch 能跑 GPU，TVM 不行 | TVM 依赖独立 TK，不依赖 PyTorch 自带 runtime | 装好系统级 CUDA Toolkit 后再重编译 TVM |
我见过最典型的案例就是机器上明明装了驱动，nvidia-smi 也正常，但 TVM 编译 CUDA 后端时就是找不到 cudart。最后发现是只装了驱动没有装 Toolkit。这个问题只要跑一下 nvcc 就能发现，却因为大家对 PyTorch 的惯性过于信任而被忽视了。
4.4 其他后端：OpenCL、Vulkan、Metal、TensorRT
CUDA 不是唯一的加速方案。OpenCL 的覆盖面广，各类嵌入式设备和部分 AMD/Intel 平台都支持；Vulkan 在移动端和桌面 GPU 上越来越主流，内存管理也更现代；Metal 是 macOS 专属；TensorRT 则是 NVIDIA 自家闭源优化，和 TVM 叠加使用可以吃一波额外的优化红利。
如果你做的不是 NVIDIA 专属工作，我建议学习阶段把 LLVM + OpenCL 这两个后端先跑通，它们能覆盖绝大多数开发板的验证场景。等需要深入某一芯片时，再针对性开启对应后端。
5. 常见问题速查与避坑手册
5.1 编译期问题速查
| 问题 | 原因 | 解决方案 |
|---|---|---|
dmlc/base.h: No such file | 子模块没拉全 | git submodule update --init --recursive |
Cannot find llvm-config | 缺 LLVM 开发套件或路径未指定 | 装 llvm-15-dev，config.cmake 写绝对路径 |
| cmake 提示找不到 Python | 缺 python3-dev | 补齐开发头文件，重新 cmake |
make -j16直接卡死或 OOM | 内存不足 | 减小并发数，加 swap 或增加内存 |
| gcc 版本过老不支持 C++17 | 系统工具链太旧 | 升级 gcc，或换成 Docker 方式构建 |
编译报错时最重要的一件事是看第一个 error，而不是看最后几行。TVM 的构建系统层层嵌套，很多 error 是连锁反应，真正的根因通常在日志最前面。我排查问题的套路是：先搜 error 关键字，再往上翻十行，看看哪个包或哪个文件缺失，然后针对性安装。
5.2 运行期问题速查
| 问题 | 原因 | 解决方案 |
|---|---|---|
No module named 'tvm' | Python 包没安装 | pip install -e .或检查 PYTHONPATH |
libtvm.so: cannot open shared object file | 没找到 C++ 动态库 | export LD_LIBRARY_PATH 加上 build 目录 |
import tvm报 tvm._ffi 错误 | 动态库版本和 Python 包不一致 | 重新编译并重装 Python 包，重启解释器 |
| Relay build 时 target 不合法 | target 名称拼错或后端未开启 | 输tvm.target.list_targets()看可用的后端 |
| 报错里出现无效指令或 segfault | 目标平台指令集和 CPU 不匹配 | 给 target 指定正确的 CPU 特性，如-mcpu |
运行期问题里，libtvm.so: cannot open shared object file是最常见的。源码编译的 TVM，动态库在 build 目录，Python 包通常会自己找，但如果你的环境比较特殊，就得手动设置环境变量。这类问题通常在重开一个新终端后出现，因为旧终端里环境变量还挂着。
5.3 版本切换和缓存导致的“神秘问题”
TVM 迭代很快，如果你拉完 main 分支再接回之前的目录跑旧代码，经常出现一些莫名其妙的行为，比如某个算子不见了、某个函数签名变了。这些大多不是代码写错，而是版本漂移。
解决办法是“隔离”：一个目录装稳定版，另一个目录跑 main 分支，Python 环境也建议分开。在同一个环境里反复覆盖安装不同版本，迟早会遇到解释器里缓存了旧模块的问题。遇到这类问题，最彻底的做法是把 build 目录删掉重编译，再pip uninstall apache-tvm或pip install -e .重新装 Python 包。
5.4 我总结的几条独家避坑技巧
第一，最小化起步。只开 LLVM 后端，能跑通再逐渐加 GPU、OpenCL。千万别第一次就把所有开关打开。第二，编译长任务用 tmux 或 screen 挂着，断开会话重写一遍很崩溃。第三，换编译器、换 CUDA 版本后，务必删掉 build 缓存重新 cmake。不用怀疑，这一步能解决很多“看起来没道理”的报错。第四，如果是台老机器，别碰 main 分支，老老实实用稳定 tag，能省一半烦恼。
6. 装完之后，下一步该怎么走
6.1 先跑通一次完整的模型导入
安装只是起点。我建议你的第一个实战练习，是从 PyTorch 或 ONNX 导入一个真实模型，用 Relay 走一遍编译、部署的完整流程。比如导出一份 ResNet18 的 ONNX 模型，在 TVM 里 relay.build 之后跑一遍推理，比较一下和 PyTorch 的精度差在可接受范围。这个过程不复杂，但能让你把安装时开的编译开关和 Relay 的编译流程串起来。
6.2 再试试自动调优
TVM 最吸引人的能力之一是用 AutoTVM 或 Ansor 自动搜索算子的最优调度。安装时只要开了对应 target，你就能跑tvm.autotvm和tvm.auto_scheduler。第一次调优可能需要较长时间，这是正常的。把某个算子的调优结果保存下来，以后编译同类模型可以直接复用。
6.3 建议的学习路线
如果你想深入，可以从写自定义算子开始。用 TE 写一个矩阵乘法的超简单实现，观察 TIR 输出，然后尝试切换不同 schedule，看看性能怎么变化。这个过程能帮你真正理解 TVM “算法和调度分离”的设计理念，也是从“会用”到“懂用”的分水岭。
最后再分享一个小经验：我每次在新机器上配 TVM 时，都会在配置完成后先跑一遍最小 Relay 编译示例，然后立刻跑一次带优化选项的模型推理，最后才碰调优。这套流程能帮我快速确认当前安装的 TVM 是否健康。安装阶段踩过的坑越多，后面进入 Relay、TE、TIR 的世界越轻松，因为你对这个框架的运行方式已经有了太直观的体感了。