一种基于Python的特定领域语言，用于在Tenstorrent硬件上编写高性能自定义内核。此项目正在积极开发中——请参阅[功能矩阵](docs/sphinx/specs/TTLangSpecification.md#appendix-d-functionality-matrix)了解当前的模拟器和编译器支持情况。 **目录：** [愿景](#1-vision) · [快速开始](#2-quick-start) · [文档](#3-documentation) · [贡献](#4-contributing) · [支持](#5-support) · [许可](#6-license) ## 1. 愿景 TT-Lang加入Tenstorrent软件生态系统，作为[TT-NN](https://docs.tenstorrent.com/tt-metal/latest/ttnn/index.html)和[TT-Metalium](https://docs.tenstorrent.com/tt-metal/latest/tt-metalium/index.html)之间一个既具表现力又符合人体工程学的中间地带，旨在提供一个集成模拟、性能分析和AI辅助开发工具的统一入口。 该语言被设计用于支持生成式AI工作流和一个健壮的工具生态系统：Python作为宿主语言，使得AI工具能够比直接翻译到TT-Metalium更可靠地将GPU DSL内核（Triton, CUDA, cuTile, TileLang）翻译到Tenstorrent硬件，同时与功能模拟的紧密集成将允许AI智能体自主提出内核实现、验证正确性并迭代配置。开发者应该能够在IDE中而非硬件上捕获错误和性能问题，功能模拟器可以尽早暴露错误。逐行性能指标和数据流图可以指导程序员和AI智能体轻松发现瓶颈和优化机会。 如今，Tenstorrent开发者面临一个选择：TT-NN提供了易于使用的高级操作，但缺乏自定义内核所需的表现力；TT-Metalium通过显式的底层内存和计算管理提供了完整的硬件控制。这并非TT-Metalium的缺点；它被设计为底层且具表现力的，提供对硬件原语的直接访问而无抽象开销，对于需要该级别控制的开发者来说，它很好地实现了其目的。问题在于没有一个中间地带，让编译器处理它最擅长的事情——资源管理、验证、优化——同时保持对应用层关注点的高度表现力。 TT-Lang通过渐进式披露弥合了这一差距：简单的内核只需要最少的规范，编译器从高级抽象中推断计算API操作、NOC寻址、DST寄存器分配等；而复杂的内核允许开发者打开引擎盖，直接定制流水线和同步细节。主要用例是模型部署的内核融合。通过TT-NN移植模型的工程师很快会遇到需要为性能而融合的操作，或TT-NN无法表达的模式，而这目前需要在TT-Metalium中重写，这需要数周时间，并要求全神贯注和硬件调试专业知识。TT-Lang使这种转变快速且正确：开发者可以获取一系列TT-NN操作，通过显式控制中间结果和内存布局来表达融合后的等效操作，通过模拟验证正确性，并将结果作为即插即用的替换集成到他们的TT-NN图中。 ## 2. 快速开始 ### 2.1 从PyPI安装 我们提供两个tt-lang包：[tt-lang](https://pypi.org/project/tt-lang/)包包含tt-lang编译器、Tenstorrent硬件支持，并依赖于`ttnn`、`pytorch`和一些较小的Python包；而[tt-lang-sim](https://pypi.org/project/tt-lang-sim/)仅包含功能模拟器（无编译器或硬件支持），且不依赖于`ttnn`。 首先，创建一个包含Python 3.11或更高版本（推荐python3.12）的隔离Python环境（venv, conda等）。例如： ``` python3 -m venv --prompt ttlang ttlang-venv source ttlang-venv/bin/activate ``` 在拥有Tenstorrent硬件的Linux机器上（Linux x86_64 / aarch64）： ``` pip install tt-lang tt-lang-setup # install matching sfpi runtime + copy tutorials ``` 仅在Linux或MacOS上使用功能模拟器，无需Tenstorrent硬件： ``` pip install tt-lang-sim tt-lang-setup # copy bundled tutorials to ./tutorials/ ``` `tt-lang-setup`是幂等的（可以多次运行而无累积副作用）。 它执行两件事，均在venv内部（无需sudo）： - 下载与已安装`ttnn`配套的sfpi编译器并将其解压到`/.../ttnn/runtime/sfpi/`下（仅限`tt-lang`安装）。 - 将捆绑的教程（`elementwise`, `matmul`, `broadcast`）复制到`./tutorials/`。 如需更精细的控制：`tt-lang-setup-host`仅运行sfpi步骤，`tt-lang-setup-tutorials -t `仅复制教程。 运行教程示例： ``` ttlang-sim tutorials/elementwise/step_4_multinode_grid_auto.py # simulated (no compilation, runs on CPU) python tutorials/elementwise/step_4_multinode_grid_auto.py # compiles and runs on hardware ``` 要开发tt-lang本身或调试编译器，请使用下面的Docker镜像或[从源代码构建](#25-building-without-docker)。 ### 2.2 预构建的Docker镜像 TT-Lang也可通过Docker镜像供用户和开发者使用。 提供两个镜像： | 镜像 | 用途 | 预安装tt-lang
（包括ttlang-sim） | 可以克隆/构建tt-lang吗？ | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | :-----------------------------------: | :----------------------: | | 
"dist" | 使用
ttlang-sim或Tenstorrent硬件运行tt-lang程序 | 是 | 否 | | 
"ird" | 从源代码开发和构建tt-lang | 否 | 是 | 两个镜像都可以与`ird reserve`一起使用（详见[容器构建文档](.github/containers/README.md)）。 ### 2.3  预构建的tt-lang（面向用户） 镜像: ghcr.io/tenstorrent/tt-lang/tt-lang-dist-ubuntu-22-04:latest ([所有版本](https://github.com/tenstorrent/tt-lang/pkgs/container/tt-lang-dist-ubuntu-22-04)) **dist**镜像包含一个完整的、已构建的tt-lang安装在`/opt/ttlang-toolchain`。使用它来编译和运行任何tt-lang程序，无需构建任何先决条件。 创建容器（一次性）： ``` docker run -d --name $USER-dist \ --device=/dev/tenstorrent/0:/dev/tenstorrent/0 \ -v /dev/hugepages:/dev/hugepages \ -v /dev/hugepages-1G:/dev/hugepages-1G \ -v $HOME:$HOME \ ghcr.io/tenstorrent/tt-lang/tt-lang-dist-ubuntu-22-04:latest \ sleep infinity ``` 打开shell： ``` docker exec -it $USER-dist /bin/bash ``` 登录时环境会自动激活。可以立即运行一个示例： ``` python /opt/ttlang-toolchain/examples/elementwise-tutorial/step_4_multinode_grid_auto.py ``` 要了解更多，请参加[导览](docs/sphinx/tour/index.md)，探索[编程指南](docs/sphinx/programming-guide.md)了解编译器选项、调试和性能工具，或使用[Claude Code](https://claude.com/claude-code)配合内置的[斜杠命令](docs/sphinx/claude-skills.md)来翻译内核、进行性能分析和优化。 ### 2.4  开发镜像（用于构建tt-lang） 镜像: ghcr.io/tenstorrent/tt-lang/tt-lang-ird-ubuntu-22-04:latest ([所有版本](https://github.com/tenstorrent/tt-lang/pkgs/container/tt-lang-ird-ubuntu-22-04)) **ird**镜像包含预构建的工具链（LLVM, tt-metal, Python venv），但不包含tt-lang本身。克隆仓库并基于该工具链进行构建。您可以并行维护多个克隆或分支，每个都有自己的构建目录。 要在本地Linux机器上直接使用Docker，首先创建一个容器（一次性）： ``` docker run -d --name $USER-ird \ --device=/dev/tenstorrent/0:/dev/tenstorrent/0 \ -v /dev/hugepages:/dev/hugepages \ -v /dev/hugepages-1G:/dev/hugepages-1G \ -v $HOME:$HOME \ -v $SSH_AUTH_SOCK:/ssh-agent -e SSH_AUTH_SOCK=/ssh-agent \ ghcr.io/tenstorrent/tt-lang/tt-lang-ird-ubuntu-22-04:latest \ sleep infinity ``` 打开shell： ``` docker exec -it $USER-ird /bin/bash ``` 在容器内部，克隆并构建： ``` git clone https://github.com/tenstorrent/tt-lang.git cd tt-lang cmake -G Ninja -B build -DTTLANG_USE_TOOLCHAIN=ON source build/env/activate cmake --build build ``` 验证构建： ``` ninja -C build check-ttlang-all ``` 运行一个示例： ``` python examples/elementwise-tutorial/step_4_multinode_grid_auto.py ``` `-DTTLANG_USE_TOOLCHAIN=ON`标志告诉CMake使用`/opt/ttlang-toolchain`中预构建的LLVM和tt-metal，而不是从源代码构建它们，这可以节省大量构建时间。 性能追踪（Tracy）默认启用。要禁用它，请在cmake配置命令中添加`-DTTLANG_ENABLE_PERF_TRACE=OFF`。有关分析工具的使用，请参阅[编程指南](docs/sphinx/programming-guide.md)。 ### 2.5 不使用Docker构建 要在没有Docker的情况下直接在主机上构建tt-lang，请参阅[构建系统文档](docs/sphinx/build.md)。它涵盖了先决条件、所有支持的构建模式（从子模块、可重用工具链、预构建工具链）以及版本兼容性。 ### 2.6 容器提示 要映射不同的TT设备，请更改`--device`参数（例如，`--device=/dev/tenstorrent/1:/dev/tenstorrent/0`）。 ### 2.7 功能模拟器 tt-lang包含一个功能模拟器，可以作为纯Python运行内核，无需Tenstorrent硬件或完整的编译器栈。使用它来验证内核逻辑并使用任何Python调试器进行调试： ``` ttlang-sim examples/eltwise_add.py ``` 模拟器通常在任何给定时间点支持比编译器更多的语言特性——请参阅[功能矩阵](docs/sphinx/specs/TTLangSpecification.md#appendix-d-functionality-matrix)了解当前覆盖范围。有关调试器设置和详细信息，请参阅[编程指南](docs/sphinx/simulator.md)。 ## 3. 文档 完整文档使用Sphinx构建。源代码位于[docs/sphinx/](docs/sphinx/)，涵盖： - [TT-Lang导览](docs/sphinx/tour/index.md) — TT-Lang功能介绍 - [编程指南](docs/sphinx/programming-guide.md) — 编译器选项、打印调试、性能工具 - [功能模拟器](docs/sphinx/simulator.md) — 无需硬件运行内核、调试设置 - [Claude技能](docs/sphinx/claude-skills.md) — 通过[Claude Code](https://claude.com/claude-code)进行AI辅助的内核翻译、性能分析和优化 - [构建系统](docs/sphinx/build.md) — 构建配置、工具链模式和版本兼容性 - [测试](docs/sphinx/testing.md) — 如何编写和运行测试 - [贡献者指南](docs/sphinx/contributor-guide.md) — 工作流程、验证、添加新操作 要在本地构建和查看Sphinx文档： ``` cmake -G Ninja -B build -DTTLANG_ENABLE_DOCS=ON cmake --build build --target ttlang-docs python -m http.server 8000 -d build/docs/sphinx/_build/html ``` ## 4. 贡献 我们欢迎贡献。请参阅[CONTRIBUTING.md](CONTRIBUTING.md)了解准则。 ### 4.1 开发者准则 请参阅Sphinx[贡献者指南](docs/sphinx/contributor-guide.md)和[代码风格准则](docs/sphinx/guidelines.md)了解编码标准、方言设计模式和测试实践。 ### 4.2 更新子模块版本 tt-mlir定义了兼容的LLVM和tt-metal版本。更新tt-mlir时，应更新其他子模块以匹配。 更新tt-mlir（并读取它期望的版本）： ``` cd third-party/tt-mlir && git fetch && git checkout && cd ../.. # 阅读此 tt-mlir 版本所期望的 LLVM 和 tt-metal 提交记录 grep LLVM_PROJECT_VERSION third-party/tt-mlir/env/CMakeLists.txt grep TT_METAL_VERSION third-party/tt-mlir/third_party/CMakeLists.txt ``` 更新LLVM到兼容版本： ``` cd third-party/llvm-project && git fetch && git checkout && cd ../.. ``` 更新tt-metal到兼容版本。规范的tt-metal版本位于`third-party/tt-metal-version`（一个tt-metal发布标签，例如`v0.69.0`）；有关派生的完整工件列表，请参阅[build.md](docs/sphinx/build.md#updating-tt-metal)。编辑该文件并以更新模式运行验证器，以签出匹配提交的子模块： ``` echo v0.69.0 > third-party/tt-metal-version .github/scripts/check-tt-metal-version.sh --update ``` 将所有子模块更新一起提交： ``` git add third-party/tt-mlir third-party/llvm-project third-party/tt-metal \ third-party/tt-metal-version pyproject.toml git commit -m "Update submodules to tt-mlir " ``` 构建系统会在配置期间验证SHA兼容性。如果子模块版本有意不匹配，请传递`-DTTLANG_ACCEPT_LLVM_MISMATCH=ON`或`-DTTLANG_ACCEPT_TTMETAL_MISMATCH=ON`以抑制检查。 ### 4.3 使用Pre-commit进行代码格式化 tt-lang使用[pre-commit](https://pre-commit.com/)在提交前格式化代码并强制执行风格准则。 安装并激活： ``` pip install pre-commit cd /path/to/tt-lang pre-commit install ``` Pre-commit会在`git commit`时自动运行。它使用[Black](https://github.com/psf/black)格式化Python代码，使用[clang-format](https://clang.llvm.org/docs/ClangFormat.html)（LLVM风格）格式化C++代码，移除尾随空白，并检查YAML/TOML语法。 如果pre-commit修改了文件，提交将被停止。暂存更改并重新提交： ``` git add -u git commit -m "Your commit message" ``` 要在所有文件上手动运行：`pre-commit run --all-files` ### 4.4 行为准则 本项目遵守[行为准则](CODE_OF_CONDUCT.md)。通过参与，您被期望维护此准则并尊重所有社区成员。 ## 5. 支持 - [GitHub问题](https://github.com/tenstorrent/tt-lang/issues) — 报告错误或请求功能 ## 6. 许可 本项目根据Apache许可证2.0获得许可 — 详见[LICENSE](LICENSE)文件。 第三方依赖项及其许可证列在[NOTICE](NOTICE)文件中。

标签：AI工具链, AI辅助开发, Bash脚本, GPU替代硬件, Python编程, SOC Prime, Tenstorrent硬件, 内核编程, 凭据扫描, 开发工具, 异构计算, 性能分析, 深度学习, 生成式AI, 硬件加速, 索引, 编译优化, 自定义内核开发, 计算图优化, 请求拦截, 软件生态系统, 逆向工具, 领域特定语言, 高性能计算