跳至主要内容

安裝

本頁涵蓋 PyPI 快速安裝、本機建置需求、CMake 設定、可選的 Python 支援，以及文件站點。

快速安裝（PyPI）​

適用於已完成 CUDA 環境設定的 Python 使用者：

pip install loopformer

這會透過 scikit-build-core 從原始碼建置 Python 綁定與 CLI。需求如下：

  • PATH 中可找到 nvcc（建議 CUDA 12+）
  • NVIDIA GPU（預設目標為 H100 的 sm_90）
  • Python 3.9+

若要指定其他 GPU 架構：

CMAKE_ARGS="-DCMAKE_CUDA_ARCHITECTURES=80" pip install loopformer

如果你需要完整的 C++ 框架函式庫、CLI 可執行檔與測試目標，請改走下方的原始碼建置流程。

建置前置需求​

TinyLoop 需要：

  • CMake 3.18 以上
  • 含 nvcc 的 CUDA Toolkit
  • 支援 C++17 的主機編譯器
  • Python 3（供工具與可選綁定使用）

可選元件：

  • pybind11（用於 tinyloop_py）
  • Node.js（用於 Docusaurus 文件站點）

CUDA 架構選擇​

TinyLoop 預設使用 CMAKE_CUDA_ARCHITECTURES=90，對應 H100 等級硬體。

常見值：

GPU 家族架構
A10080
H10090

若未明確設定，倉庫預設為 H100。

設定（Configure）​

在倉庫根目錄執行：

cmake -S tinyloop -B tinyloop/build -DCMAKE_CUDA_ARCHITECTURES=90

若已安裝 pybind11，且 CMake 能找到 Python3 Development.Module，Python 綁定也會自動被設定。

建置（Build）​

cmake --build tinyloop/build -j

會產生：

  • tinyloop/build/tinyloop
  • tinyloop/build/libtinyloop_framework.a
  • tinyloop/build/tinyloop_py.*（當 Python 綁定可用時）
  • tinyloop/build/ 下的測試可執行檔

安裝（Install）​

cmake --install tinyloop/build --prefix /tmp/tinyloop-install

安裝內容包含：

  • TinyLoop::framework CMake target
  • include/tinyloop 下的公開標頭
  • lib/cmake/TinyLoop 下的套件中繼資料
  • tinyloop CLI 可執行檔

在其他 CMake 專案中使用 TinyLoop​

find_package(TinyLoop REQUIRED)

add_executable(my_runtime main.cpp)
target_link_libraries(my_runtime PRIVATE TinyLoop::framework)

Python 綁定建置說明​

只有在以下兩條件同時成立時才會建置綁定：

  • CMake 可找到 pybind11
  • 可用 Python3 Development.Module

成立後，模組介面包含：

  • Model.score()
  • Model.score_last()
  • Model.generate()
  • Model.generate_speculative()
  • prefix-cache 相關 helper

文件站點​

文件站位於 tinyloop/wiki。

安裝相依：

cd tinyloop/wiki
npm ci

本機啟動：

npm run start

靜態建置：

npm run build

建議的首次驗證​

建置後：

  1. 對真實 .tinyloop artifact 執行 inspect
  2. 執行小型 benchmark
  3. 執行 ctest --test-dir tinyloop/build --output-on-failure

若你有真實模型路徑：

TINYLOOP_TEST_MODEL_PATH=/absolute/path/to/model.tinyloop \
ctest --test-dir tinyloop/build --output-on-failure

常見環境問題​

Failed to find nvcc​

目前 shell 看不到 CUDA Toolkit。請檢查：

  • nvcc 已安裝
  • CUDA 二進位路徑已加入 PATH
  • CUDAToolkit_ROOT 指向正確 Toolkit

Python 模組沒有建出來​

請檢查：

  • pybind11 安裝位置可被 CMake 找到
  • Python 開發標頭存在
  • CMake 輸出有 Python3_Development.Module_FOUND