Triton-CPU 部署实录（Ubuntu + Conda + 自编译 LLVM）

这份文档是一次真实可复现的成功部署流程，重点解决了 triton-cpu 在较旧系统库环境下常见的 ABI 问题（GLIBC/libstdc++ 不匹配）。

结论先说： triton-cpu 安装比 triton 更复杂，核心难点通常不在 Python 包，而在 LLVM 工具链版本与本机系统库兼容性。

---

1. 环境准备

先创建并进入一个独立的 Conda 环境（示例名称：triton-cpu）：

conda create -n triton-cpu python=3.10 -y
conda activate triton-cpu

建议升级 pip：

python -m pip install --upgrade pip

---

2. 获取 triton-cpu 仓库

cd ~
git clone https://github.com/triton-lang/triton-cpu.git
cd triton-cpu

如果你已有仓库，这步可跳过。

---

3. 安装 Python 依赖（requirements）

按仓库中的依赖文件安装：

cd ~/triton-cpu
python -m pip install -r python/requirements.txt

不同版本仓库中 requirements 路径可能略有差异，若文件不存在，请以当前仓库实际路径为准。

---

4. 为什么不能直接 pip install -e .

一开始直接安装时，出现过类似错误：

• GLIBC_2.33 not found
• 大量 undefined reference to std::...

根因是：triton-cpu 默认下载或使用的某些预编译 LLVM 组件，和本机系统 glibc/libstdc++ ABI 不兼容。 在这类环境里，最稳定方案是：按 triton-cpu/README.md 自己编译 LLVM，再让 Triton 指向这套 LLVM。

---

5. 按 README 构建兼容 LLVM（关键步骤）

5.1 拉取 LLVM 源码

cd ~
git clone https://github.com/llvm/llvm-project.git
cd llvm-project

5.2 切换到 triton-cpu 指定 LLVM 提交

triton-cpu 会在 cmake/llvm-hash.txt 指定对应 LLVM commit。先读取该哈希，再 checkout。

cd ~/triton-cpu
cat cmake/llvm-hash.txt

然后在 LLVM 仓库切过去（以下 <LLVM_HASH> 替换成上一步看到的值）：

cd ~/llvm-project
git fetch --all --tags
git checkout <LLVM_HASH>

处于 detached HEAD 是正常的，这里我们就是按固定提交构建。

5.3 配置并编译 LLVM

cd ~/llvm-project
mkdir -p build
cd build
​
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DLLVM_ENABLE_PROJECTS="mlir;llvm;lld" \
  -DLLVM_TARGETS_TO_BUILD="host;NVPTX;AMDGPU" \
  ../llvm
​
ninja -j"$(nproc)"

编译时间较长（常见 30~120 分钟，取决于机器）。

---

6. 用本地 LLVM 安装 triton-cpu

回到 triton-cpu 仓库，清理旧 build，然后显式指定 LLVM 路径：

cd ~/triton-cpu
rm -rf build
​
export LLVM_BUILD_DIR=~/llvm-project/build
​
MAX_JOBS=16 \
LLVM_INCLUDE_DIRS=$LLVM_BUILD_DIR/include \
LLVM_LIBRARY_DIR=$LLVM_BUILD_DIR/lib \
LLVM_SYSPATH=$LLVM_BUILD_DIR \
pip install --no-build-isolation -e .

成功标志示例：

• Successfully built triton
• Successfully installed triton-...

---

7. 基础验证

先验证 Python 能导入：

python -c "import triton; print(triton.__version__)"

如果输出版本号（如 3.6.0），说明安装层面成功。

---

8. 运行 CPU 教程示例与两个常见问题

8.1 正确的示例路径

示例在 python/tutorials/ 下，不是根目录 tutorials/：

cd ~/triton-cpu
TRITON_CPU_BACKEND=1 python3 python/tutorials/01-vector-add.py

8.2 可能遇到的问题 A：No module named 'torch'

教程依赖 PyTorch，安装 CPU 版：

python3 -m pip install torch --index-url https://download.pytorch.org/whl/cpu

8.3 可能遇到的问题 B：汇编报错（junk at end of line, first unrecognized character is '"'）

在较旧 binutils（例如 as 2.34）环境下，可能因行信息相关汇编指令解析失败。 可通过禁用 line info 绕过：

TRITON_CPU_BACKEND=1 TRITON_DISABLE_LINE_INFO=1 python3 python/tutorials/01-vector-add.py

我们这次就是通过这条命令跑通的。

---

9. 如何判断"真的跑通了"

示例输出中出现以下信息即可认为 CPU backend 已正常工作：

• 打印出两个 tensor
• The maximum difference ... is 0.0

如果最后只报：

• ModuleNotFoundError: No module named 'matplotlib'

那只是 benchmark 画图依赖缺失，不影响核心 Triton-CPU 计算正确性。 可选安装：

python3 -m pip install matplotlib pandas

---

10. 推荐的最终可复用命令顺序（精简版）

conda create -n triton-cpu python=3.10 -y
conda activate triton-cpu
​
cd ~
git clone https://github.com/triton-lang/triton-cpu.git
git clone https://github.com/llvm/llvm-project.git
​
cd ~/triton-cpu
python -m pip install --upgrade pip
python -m pip install -r python/requirements.txt
​
# 读取 LLVM 对应版本
LLVM_HASH=$(cat cmake/llvm-hash.txt)
​
cd ~/llvm-project
git fetch --all --tags
git checkout "$LLVM_HASH"
mkdir -p build && cd build
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DLLVM_ENABLE_PROJECTS="mlir;llvm;lld" \
  -DLLVM_TARGETS_TO_BUILD="host;NVPTX;AMDGPU" \
  ../llvm
ninja -j"$(nproc)"
​
cd ~/triton-cpu
rm -rf build
export LLVM_BUILD_DIR=~/llvm-project/build
MAX_JOBS=16 \
LLVM_INCLUDE_DIRS=$LLVM_BUILD_DIR/include \
LLVM_LIBRARY_DIR=$LLVM_BUILD_DIR/lib \
LLVM_SYSPATH=$LLVM_BUILD_DIR \
pip install --no-build-isolation -e .
​
python -c "import triton; print(triton.__version__)"
python3 -m pip install torch --index-url https://download.pytorch.org/whl/cpu
TRITON_CPU_BACKEND=1 TRITON_DISABLE_LINE_INFO=1 python3 python/tutorials/01-vector-add.py

---

11. 给分享对象的经验建议

0. triton-cpu 失败时，先怀疑 LLVM/ABI，不要只盯 Python 包。
1. 用仓库指定 commit 的 LLVM 自编译，是最稳方案。
2. 旧系统常见 line-info + assembler 兼容性问题，可先用 TRITON_DISABLE_LINE_INFO=1 保证功能验证通过。
3. 示例脚本依赖 torch 和可能的 matplotlib，分别处理"计算"和"画图"依赖，不要混淆。