[DOC] Update readme, build and decoupling documents (#273)

Author: zhzhcookie

README.md

@@ -4,6 +4,7 @@
 
 FlagTree is an open source, unified compiler for multiple AI chips project dedicated to developing a diverse ecosystem of AI chip compilers and related tooling platforms, thereby fostering and strengthening the upstream and downstream Triton ecosystem. Currently in its initial phase, the project aims to maintain compatibility with existing adaptation solutions while unifying the codebase to rapidly implement single-repository multi-backend support. For upstream model users, it provides unified compilation capabilities across multiple backends; for downstream chip manufacturers, it offers examples of Triton ecosystem integration. <br>
 Each backend is based on different versions of triton, and therefore resides in different protected branches. All these protected branches have equal status.
+
 |Branch|Vendor|Backend|Triton version|
 |------|------|-------|--------------|
 |[main](https://github.com/flagos-ai/flagtree/tree/main)|NVIDIA<br>AMD<br>x86_64 cpu<br>ILUVATAR（天数智芯）<br>Moore Threads（摩尔线程）<br>KLX<br>MetaX（沐曦股份）<br>HYGON（海光信息）|[nvidia](/third_party/nvidia/)<br>[amd](/third_party/amd/)<br>[triton-shared](https://github.com/microsoft/triton-shared)<br>[iluvatar](/third_party/iluvatar/)<br>[mthreads](/third_party/mthreads/)<br>[xpu](/third_party/xpu/)<br>[metax](/third_party/metax/)<br>[hcu](third_party/hcu/)|3.1<br>3.1<br>3.1<br>3.1<br>3.1<br>3.0<br>3.1<br>3.0|
@@ -13,6 +14,7 @@ Each backend is based on different versions of triton, and therefore resides in
 |[triton_v3.5.x](https://github.com/flagos-ai/flagtree/tree/triton_v3.5.x)|NVIDIA<br>AMD|[nvidia](https://github.com/FlagTree/flagtree/tree/triton_v3.5.x/third_party/nvidia/)<br>[amd](https://github.com/FlagTree/flagtree/tree/triton_v3.5.x/third_party/amd/)|3.5|
 
 ## Latest News
+
 * 2025/12/24 Support pull and install [Wheel](/README.md#non-source-installation).
 * 2025/12/08 Added [enflame](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/enflame/) backend integration (based on Triton 3.3), and added CI/CD.
 * 2025/11/26 Add FlagTree_Backend_Specialization Unified Design Document [FlagTree_Backend_Specialization](/documents/decoupling/).
@@ -38,40 +40,44 @@ Each backend is based on different versions of triton, and therefore resides in
 * 2025/06/03 Added [metax](https://github.com/FlagTree/flagtree/tree/main/third_party/metax/) backend integration (based on Triton 3.1), and added CI/CD.
 * 2025/05/22 FlagGems LibEntry adapted to triton_v3.3.x version.
 * 2025/05/21 [FLIR](https://github.com/flagos-ai/flir) began supporting conversion functionality to middle layer.
-* 2025/04/09 Added arm [aipu](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/aipu/) backend integration (based on Triton 3.3), provided a torch standard extension [example](https://github.com/flagos-ai/flagtree/blob/triton_v3.3.x/third_party/aipu/backend/aipu_torch_dev.cpp), and added CI/CD.
+* 2025/04/09 Added [aipu](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/aipu/) backend integration (based on Triton 3.3), provided a torch standard extension [example](https://github.com/flagos-ai/flagtree/blob/triton_v3.3.x/third_party/aipu/backend/aipu_torch_dev.cpp), and added CI/CD.
 * 2025/03/26 Integrated security compliance scanning.
-* 2025/03/19 Added klx [xpu](https://github.com/FlagTree/flagtree/tree/main/third_party/xpu/) backend integration (based on Triton 3.0), and added CI/CD.
+* 2025/03/19 Added [xpu](https://github.com/FlagTree/flagtree/tree/main/third_party/xpu/) backend integration (based on Triton 3.0), and added CI/CD.
 * 2025/03/19 Added [mthreads](https://github.com/FlagTree/flagtree/tree/main/third_party/mthreads/) backend integration (based on Triton 3.1), and added CI/CD.
 * 2025/03/12 Added [iluvatar](https://github.com/FlagTree/flagtree/tree/main/third_party/iluvatar/) backend integration (based on Triton 3.1), and added CI/CD.
 
 ## Install from source
+
 Installation dependencies (ensure you use the correct python3.x version):
+
 ```shell
 apt install zlib1g zlib1g-dev libxml2 libxml2-dev  # ubuntu
 cd python; python3 -m pip install -r requirements.txt
 ```
 
 Building and Installation (Recommended for environments with good network connectivity):
 ```shell
-cd python
 # Set FLAGTREE_BACKEND using the backend name from the table above
 export FLAGTREE_BACKEND=${backend_name}  # nvidia/amd/triton-shared do not set it
+cd python  # For Triton 3.1, 3.2, 3.3, you need to enter the python directory to build
 python3 -m pip install . --no-build-isolation -v  # Automatically uninstall triton
 python3 -m pip show flagtree
-cd; python3 -c 'import triton; print(triton.__path__)'
+cd ${ANY_OTHER_PATH}; python3 -c 'import triton; print(triton.__path__)'
 ```
 
 - [Tips for building](/documents/build.md#tips-for-building)
 - [Offline build support: pre-downloading dependency packages](/documents/build.md#offline-build-support)
 
 ## Non-Source Installation
+
 If you do not wish to build from source, you can directly pull and install whl (supports some backends).
 
 ```shell
 # Note: First install PyTorch, then execute the following commands
-python3 -m pip uninstall -y triton    # TODO: automatically uninstall triton
+python3 -m pip uninstall -y triton  # TODO: automatically uninstall triton
 RES="--index-url=https://resource.flagos.net/repository/flagos-pypi-hosted/simple --trusted-host=https://resource.flagos.net"
 ```
+
 |Backend |Install cmd (versions have corresponding git tags)|Triton version|Python version|
 |--------|--------------------------------------------------|--------------|--------------|
 |nvidia  |python3 -m pip install flagtree==0.3.0rc1 $RES            |3.1|3.10, 3.11, 3.12|

README_cn.md

@@ -4,6 +4,7 @@
 
 FlagTree 是面向多种 AI 芯片的开源、统一编译器。FlagTree 致力于打造多元 AI 芯片编译器及相关工具平台，发展和壮大 Triton 上下游生态。项目当前处于初期，目标是兼容现有适配方案，统一代码仓库，快速实现单仓库多后端支持。对于上游模型用户，提供多后端的统一编译能力；对于下游芯片厂商，提供 Triton 生态接入范例。<br>
 各后端基于不同版本的 triton 适配，因此位于不同的主干分支，各主干分支均为保护分支且地位相等：<br>
+
 |主干分支|厂商|后端|Triton 版本|
 |-------|---|---|-----------|
 |[main](https://github.com/flagos-ai/flagtree/tree/main)|NVIDIA<br>AMD<br>x86_64 cpu<br>ILUVATAR（天数智芯）<br>Moore Threads（摩尔线程）<br>KLX<br>MetaX（沐曦股份）<br>HYGON（海光信息）|[nvidia](/third_party/nvidia/)<br>[amd](/third_party/amd/)<br>[triton-shared](https://github.com/microsoft/triton-shared)<br>[iluvatar](/third_party/iluvatar/)<br>[mthreads](/third_party/mthreads/)<br>[xpu](/third_party/xpu/)<br>[metax](/third_party/metax/)<br>[hcu](third_party/hcu/)|3.1<br>3.1<br>3.1<br>3.1<br>3.1<br>3.0<br>3.1<br>3.0|
@@ -13,6 +14,7 @@ FlagTree 是面向多种 AI 芯片的开源、统一编译器。FlagTree 致力
 |[triton_v3.5.x](https://github.com/flagos-ai/flagtree/tree/triton_v3.5.x)|NVIDIA<br>AMD|[nvidia](https://github.com/FlagTree/flagtree/tree/triton_v3.5.x/third_party/nvidia/)<br>[amd](https://github.com/FlagTree/flagtree/tree/triton_v3.5.x/third_party/amd/)|3.5|
 
 ## 新特性
+
 * 2025/12/24 支持拉取和安装 [Wheel](/README_cn.md#非源码安装)。
 * 2025/12/08 新增接入 [enflame](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/enflame/) 后端（对应 Triton 3.3），加入 CI/CD。
 * 2025/11/26 添加 FlagTree 后端特化统一设计文档 [FlagTree_Backend_Specialization](/documents/decoupling/)。
@@ -38,39 +40,44 @@ FlagTree 是面向多种 AI 芯片的开源、统一编译器。FlagTree 致力
 * 2025/06/03 新增接入 [metax](https://github.com/FlagTree/flagtree/tree/main/third_party/metax/) 后端（对应 Triton 3.1），加入 CI/CD。
 * 2025/05/22 [FlagGems](https://github.com/flagos-ai/FlagGems) LibEntry 适配 triton_v3.3.x 版本。
 * 2025/05/21 [FLIR](https://github.com/flagos-ai/flir) 开始承接到中间层的转换功能。
-* 2025/04/09 新增接入 arm [aipu](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/aipu/) 后端（对应 Triton 3.3），提供 torch 标准扩展[范例](https://github.com/flagos-ai/flagtree/blob/triton_v3.3.x/third_party/aipu/backend/aipu_torch_dev.cpp)，加入 CI/CD。
+* 2025/04/09 新增接入 [aipu](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/aipu/) 后端（对应 Triton 3.3），提供 torch 标准扩展[范例](https://github.com/flagos-ai/flagtree/blob/triton_v3.3.x/third_party/aipu/backend/aipu_torch_dev.cpp)，加入 CI/CD。
 * 2025/03/26 接入安全合规扫描。
-* 2025/03/19 新增接入 klx [xpu](https://github.com/FlagTree/flagtree/tree/main/third_party/xpu/) 后端（对应 Triton 3.0），加入 CI/CD。
+* 2025/03/19 新增接入 [xpu](https://github.com/FlagTree/flagtree/tree/main/third_party/xpu/) 后端（对应 Triton 3.0），加入 CI/CD。
 * 2025/03/19 新增接入 [mthreads](https://github.com/FlagTree/flagtree/tree/main/third_party/mthreads/) 后端（对应 Triton 3.1），加入 CI/CD。
 * 2025/03/12 新增接入 [iluvatar](https://github.com/FlagTree/flagtree/tree/main/third_party/iluvatar/) 后端（对应 Triton 3.1），加入 CI/CD。
 
 ## 从源代码安装
+
 安装依赖（注意使用正确的 python3.x 执行）：
 ```shell
 apt install zlib1g zlib1g-dev libxml2 libxml2-dev  # ubuntu
-cd python; python3 -m pip install -r requirements.txt
+cd python
+python3 -m pip install -r requirements.txt
 ```
 
 构建安装（网络畅通环境下推荐使用）：
 ```shell
-cd python
-# 使用上文表格中的后端名称设置 FLAGTREE_BACKEND
-export FLAGTREE_BACKEND=${backend_name}  # 但对于 nvidia/amd/triton-shared 不要设置
+# Set FLAGTREE_BACKEND using the backend name from the table above
+export FLAGTREE_BACKEND=${backend_name}  # nvidia/amd/triton-shared do not set it
+cd python  # For Triton 3.1, 3.2, 3.3, you need to enter the python directory to build
 python3 -m pip install . --no-build-isolation -v  # 自动卸载 triton
 python3 -m pip show flagtree
-cd; python3 -c 'import triton; print(triton.__path__)'
+cd ${ANY_OTHER_PATH}; python3 -c 'import triton; print(triton.__path__)'
 ```
 
 - [从源码构建技巧](/documents/build_cn.md#从源码构建技巧)
 - [离线构建支持：预下载依赖包](/documents/build_cn.md#离线构建支持)
 
 ## 非源码安装
+
 如果不希望从源码安装，可以直接拉取安装 whl（支持部分后端）。
+
 ```shell
-# 注意：先安装 PyTorch，然后执行下列命令
-python3 -m pip uninstall -y triton    # TODO: 支持自动卸载 triton
+# Note: First install PyTorch, then execute the following commands
+python3 -m pip uninstall -y triton  # TODO: automatically uninstall triton
 RES="--index-url=https://resource.flagos.net/repository/flagos-pypi-hosted/simple --trusted-host=https://resource.flagos.net"
 ```
+
 |后端     |安装命令（版本号对应 git tag）|Triton 版本|支持的 Python 版本|
 |--------|---------------------------|----------|----------------|
 |nvidia  |python3 -m pip install flagtree==0.3.0rc1 $RES            |3.1|3.10, 3.11, 3.12|

documents/build.md

@@ -4,13 +4,15 @@
 
 ### Tips for building
 
-Automatic dependency library downloads may be limited by network conditions. You can manually download to the cache directory ~/.flagtree (modifiable via the FLAGTREE_CACHE_DIR environment variable). No need to manually set LLVM environment variables such as LLVM_BUILD_DIR.
-Complete build commands for each backend:
+Automatic dependency library downloads may be limited by network conditions. You can manually download to the cache directory ~/.flagtree (modifiable via the FLAGTREE_CACHE_DIR environment variable). No need to manually set LLVM environment variables such as LLVM_BUILD_DIR. <br>
+Complete build commands for each backend: <br>
+
+#### ILUVATAR（天数智芯）[iluvatar](https://github.com/FlagTree/flagtree/tree/main/third_party/iluvatar/)
+
+- Based on Triton 3.1, x64
+- Recommended: Use Ubuntu 20.04
 
-* [iluvatar](https://github.com/FlagTree/flagtree/tree/main/third_party/iluvatar/) <br>
-Based on Triton 3.1, x64
 ```shell
-# Recommended: Use Ubuntu 20.04
 mkdir -p ~/.flagtree/iluvatar; cd ~/.flagtree/iluvatar
 wget https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/iluvatar-llvm18-x86_64_v0.4.0.tar.gz
 tar zxvf iluvatar-llvm18-x86_64_v0.4.0.tar.gz
@@ -20,11 +22,14 @@ cd ${YOUR_CODE_DIR}/flagtree/python
 export FLAGTREE_BACKEND=iluvatar
 python3 -m pip install . --no-build-isolation -v
 ```
-* klx [xpu](https://github.com/FlagTree/flagtree/tree/main/third_party/xpu/) <br>
-Based on Triton 3.0, x64
+
+#### KLX [xpu](https://github.com/FlagTree/flagtree/tree/main/third_party/xpu/)
+
+- Based on Triton 3.0, x64
+- Recommended: Use the Docker image (22GB) [ubuntu_2004_x86_64_v30.tar](https://su.bcebos.com/klx-sdk-release-public/xpytorch/docker/ubuntu2004_v030/ubuntu_2004_x86_64_v30.tar)
+- Contact kunlunxin-support@baidu.com for support
+
 ```shell
-# Recommended: Use the Docker image (22GB) https://su.bcebos.com/klx-sdk-release-public/xpytorch/docker/ubuntu2004_v030/ubuntu_2004_x86_64_v30.tar
-# Contact kunlunxin-support@baidu.com for support
 mkdir -p ~/.flagtree/xpu; cd ~/.flagtree/xpu
 wget https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/XTDK-llvm19-ubuntu2004_x86_64_v0.3.0.tar.gz
 tar zxvf XTDK-llvm19-ubuntu2004_x86_64_v0.3.0.tar.gz
@@ -36,10 +41,13 @@ cd ${YOUR_CODE_DIR}/flagtree/python
 export FLAGTREE_BACKEND=xpu
 python3 -m pip install . --no-build-isolation -v
 ```
-* [mthreads](https://github.com/FlagTree/flagtree/tree/main/third_party/mthreads/) <br>
-Based on Triton 3.1, x64/aarch64
+
+#### Moore Threads（摩尔线程）[mthreads](https://github.com/FlagTree/flagtree/tree/main/third_party/mthreads/)
+
+- Based on Triton 3.1, x64/aarch64
+- Recommended: Use [Dockerfile-ubuntu22.04-python3.10-mthreads](/dockerfiles/Dockerfile-ubuntu22.04-python3.10-mthreads)
+
 ```shell
-# Recommended: Use the Dockerfile flagtree/dockerfiles/Dockerfile-ubuntu22.04-python3.10-mthreads
 mkdir -p ~/.flagtree/mthreads; cd ~/.flagtree/mthreads
 # x64
 wget https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/mthreads-llvm19-glibc2.35-glibcxx3.4.30-x64_v0.4.0.tar.gz
@@ -56,23 +64,29 @@ cd ${YOUR_CODE_DIR}/flagtree/python
 export FLAGTREE_BACKEND=mthreads
 python3 -m pip install . --no-build-isolation -v
 ```
-* arm [aipu](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/aipu/) <br>
-Based on Triton 3.3, x64/arm64
+
+#### ARM China [aipu](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/aipu/)
+
+- Based on Triton 3.3, x64/arm64
+- Recommended: Use Ubuntu 22.04
+- llvm x64 in the simulated environment, llvm arm64 on the ARM development board
+
 ```shell
-# Recommended: Use Ubuntu 22.04
 mkdir -p ~/.flagtree/aipu; cd ~/.flagtree/aipu
-# x64 in the simulated environment, arm64 on the ARM development board
 wget https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/llvm-a66376b0-ubuntu-x64-clang16-lld16_v0.4.0.tar.gz
 tar zxvf llvm-a66376b0-ubuntu-x64-clang16-lld16_v0.4.0.tar.gz
 cd ${YOUR_CODE_DIR}/flagtree/python
 git checkout -b triton_v3.3.x origin/triton_v3.3.x
 export FLAGTREE_BACKEND=aipu
 python3 -m pip install . --no-build-isolation -v
 ```
-* [tsingmicro](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/tsingmicro/) <br>
-Based on Triton 3.3, x64
+
+#### [tsingmicro](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/tsingmicro/)
+
+- Based on Triton 3.3, x64
+- Recommended: Use Ubuntu 20.04
+
 ```shell
-# Recommended: Use Ubuntu 20.04
 mkdir -p ~/.flagtree/tsingmicro; cd ~/.flagtree/tsingmicro
 wget https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/tsingmicro-llvm21-glibc2.30-glibcxx3.4.28-python3.11-x64_v0.2.0.tar.gz
 tar zxvf tsingmicro-llvm21-glibc2.30-glibcxx3.4.28-python3.11-x64_v0.2.0.tar.gz
@@ -84,12 +98,14 @@ git checkout -b triton_v3.3.x origin/triton_v3.3.x
 export FLAGTREE_BACKEND=tsingmicro
 python3 -m pip install . --no-build-isolation -v
 ```
-* [ascend](https://github.com/FlagTree/flagtree/blob/triton_v3.2.x/third_party/ascend/) <br>
-Based on Triton 3.2, aarch64
+
+#### Huawei Ascend（华为昇腾）[ascend](https://github.com/FlagTree/flagtree/blob/triton_v3.2.x/third_party/ascend)
+
+- Based on Triton 3.2, aarch64
+- Recommended: Use [Dockerfile-ubuntu22.04-python3.11-ascend](/dockerfiles/Dockerfile-ubuntu22.04-python3.11-ascend)
+- After registering an account at https://www.hiascend.com/developer/download/community/result?module=cann, download the cann-toolkit and cann-kernels for the corresponding platform.
+
 ```shell
-# Recommended: Use the Dockerfile flagtree/dockerfiles/Dockerfile-ubuntu22.04-python3.11-ascend
-# After registering an account at https://www.hiascend.com/developer/download/community/result?module=cann,
-# download the cann-toolkit and cann-kernels for the corresponding platform.
 # cann-toolkit
 chmod +x Ascend-cann-toolkit_8.3.RC1.alpha001_linux-aarch64.run
 ./Ascend-cann-toolkit_8.3.RC1.alpha001_linux-aarch64.run --install
@@ -108,21 +124,27 @@ git checkout -b triton_v3.2.x origin/triton_v3.2.x
 export FLAGTREE_BACKEND=ascend
 python3 -m pip install . --no-build-isolation -v
 ```
-* [hcu](https://github.com/FlagTree/flagtree/tree/main/third_party/hcu/) <br>
-Based on Triton 3.0, x64
+
+#### HYGON（海光信息）[hcu](https://github.com/FlagTree/flagtree/tree/main/third_party/hcu/)
+
+- Based on Triton 3.0, x64
+- Recommended: Use [Dockerfile-ubuntu22.04-python3.10-hcu](/dockerfiles/Dockerfile-ubuntu22.04-python3.10-hcu)
+
 ```shell
-# Recommended: Use the Dockerfile flagtree/dockerfiles/Dockerfile-ubuntu22.04-python3.10-hcu
 mkdir -p ~/.flagtree/hcu; cd ~/.flagtree/hcu
 wget https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/hcu-llvm20-df0864e-glibc2.35-glibcxx3.4.30-ubuntu-x86_64_v0.3.0.tar.gz
 tar zxvf hcu-llvm20-df0864e-glibc2.35-glibcxx3.4.30-ubuntu-x86_64_v0.3.0.tar.gz
 cd ${YOUR_CODE_DIR}/flagtree/python
 export FLAGTREE_BACKEND=hcu
 python3 -m pip install . --no-build-isolation -v
 ```
-* [enflame](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/enflame/) <br>
-Based on Triton 3.3, x64
+
+#### Enflame（燧原）[enflame](https://github.com/FlagTree/flagtree/tree/triton_v3.3.x/third_party/enflame/)
+
+- Based on Triton 3.3, x64
+- Recommended: Use the Docker image (2.4GB) https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/enflame-flagtree-0.3.1.tar.gz
+
 ```shell
-# Recommended: Use the Docker image (2.4GB) https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/enflame-flagtree-0.3.1.tar.gz
 mkdir -p ~/.flagtree/enflame; cd ~/.flagtree/enflame
 wget https://baai-cp-web.ks3-cn-beijing.ksyuncs.com/trans/enflame-llvm21-d752c5b-gcc9-x64_v0.3.0.tar.gz
 tar zxvf enflame-llvm21-d752c5b-gcc9-x64_v0.3.0.tar.gz
@@ -131,8 +153,10 @@ export FLAGTREE_BACKEND=enflame
 python3 -m pip install . --no-build-isolation -v
 ```
 
-* [nvidia](/third_party/nvidia/) <br>
-To build with default backends nvidia, amd, triton_shared cpu:
+#### NVIDIA [nvidia](/third_party/nvidia/)
+
+- To build with default backends nvidia, amd, triton_shared cpu:
+
 ```shell
 cd ${YOUR_LLVM_DOWNLOAD_DIR}
 # For Triton 3.1
@@ -172,7 +196,9 @@ unset LLVM_SYSPATH LLVM_INCLUDE_DIRS LLVM_LIBRARY_DIR
 ```
 
 ### Offline build support
+
 The above introduced how dependencies can be manually downloaded for various FlagTree backends during build time to avoid network environment limitations. Since Triton builds originally come with some dependency packages, we provide pre-downloaded packages that can be manually installed in your environment to prevent getting stuck at the automatic download stage during the build process.
+
 ```shell
 cd ${YOUR_CODE_DIR}/flagtree/python
 sh README_offline_build.sh x86_64  # View readme