LiteRT 加速器測試套件 (ATS)

LiteRT 加速器測試套件 (ATS) 是一項全方位的工具，可用於驗證功能正確性，並評估與 LiteRT 架構整合的自訂加速器實作項目效能。

總覽和核心功能

ATS 的主要功能是針對目標加速器執行預先定義的機器學習模型，並將結果與 LiteRT 標準 CPU 後端進行比較。

  • 驗證：套件會比較加速器產生的輸出張量 (啟用) 與已知良好的 CPU 後端產生的輸出張量，進行數值驗證。確保加速器實作維持必要的精確度和正確性。
  • 效能指標：自動擷取並記錄重要的效能詳細資料，包括延遲和其他相關指標，並提供給使用者。
  • 執行：測試通常會在目標裝置 (例如 Android 手機) 上執行，並由 殼層指令碼包裝函式管理，該函式會使用 adb (Android Debug Bridge) 工具處理檔案傳輸和設定。

測試資料 (模型)

ATS 套件會使用一系列廣泛使用的.tflite模型做為測試資料。輸入資料會根據資料類型隨機產生，並可視需要設定種子。

包含的模型

系統會自動納入並下載下列模型進行測試 (如有變更，恕不另行通知)：

  • hf_all_minilm_l6_v2
  • hf_mobilevit_small
  • qai_hub_midas
  • qai_hub_real_esrgan_x4plus
  • torchvision_mobilenet_v2
  • torchvision_resnet18
  • torchvision_squeezenet1_1
  • u2net_lite
  • whisper_tiny_decoder
  • whisper_tiny_encoder
  • yamnet
  • yolo11n

手動擷取模型

雖然模型會在 bazel run 期間自動下載，但您可以使用 wget 手動擷取整個模型集：

wget -p -O <target_file> https://storage.googleapis.com/litert/ats_models.tar.gz

使用 Bazel 定義 ATS 套件

使用 litert_define_ats Bazel 巨集，設定及定義專為加速器設計的 ATS 測試目標。

巨集會自動建立兩個可執行的目標：

  1. 標準裝置端 JIT 測試 (用於執行和驗證)。
  2. 專用的 AOT「僅編譯」模式測試 (適用於主機編譯)。

使用範例 litert_define_ats

這個範例會為後端名稱為 example 的加速器，定義名為 example_ats 的 ATS 套件：

# Emits aot-mode and jit-mode test targets, one for running compilation test on host
# and another for running JIT and inference on device
# These targets are named with their respective suffix attribute.
litert_define_ats(
    name = "example_ats",
    backend = "example",
    compile_only_suffix = "_aot",
    do_register = [
        "*mobilenet*",
    ],
    extra_flags = ["--limit=1"],
    jit_suffix = "",
)

執行

如要執行以 Android 為目標的標準測試 (可處理所有 adb 作業)：

# Handles environment setup, and build + push of library and data dependencies to the device,
# executes the suite on the target.
bazel run -c opt --config=android_arm64 :example_ats

如要執行預先編譯測試，請按照下列步驟操作：

# Handle environment setup, and builds library dependencies for host platform.
# Executes the ats compile only flow. The "--compile_mode" flag is already
# bound to the program arguments.
bazel run :example_ats_aot

Linux 執行 (主機)

如要在 Linux 執行 ATS，且 ATS 與建構作業在同一部機器上執行，使用者必須直接使用 :ats 二進位檔：

bazel run -c opt :ats

IoT 執行

如要執行 IoT，使用者必須在主機上建構二進位檔，並手動推送至裝置。

指令列旗標

ats 可執行檔接受多個標記，可精細控管測試和報表。

檢舉 類型 說明
--backend std::string 必要。要當做受測加速器 (「實際」) 使用的 LiteRT 後端。選項為 cpu、npu 或 gpu。
--compile_mode bool 如果設為 true，系統會在工作站上執行 AOT 編譯步驟，而非在裝置上執行。注意：這個選項會自動繫結至「aot」建構目標，因此不必明確設定。
--models_out std::string 儲存副作用序列化 (編譯) 模型的目錄路徑。僅適用於 AOT 或 JIT 編譯。
--dispatch_dir std::string 包含加速器調度程式庫的目錄路徑 (適用於 NPU)。
--plugin_dir std::string 包含加速器編譯器外掛程式庫的目錄路徑 (適用於 NPU)。
--soc_manufacturer std::string 要進行 AOT 編譯的 SOC 製造商 (與 NPU 編譯相關)。
--soc_model std::string 要進行 AOT 編譯的 SOC 模型 (與 NPU 編譯相關)。
--iters_per_test size_t 每次測試要執行的疊代次數，每次疊代都會使用不同的隨機張量資料。
--max_ms_per_test int64_t 逾時前執行各項測試的時間上限 (以毫秒為單位)。
--fail_on_timeout bool 執行逾時時，測試是否應失敗。
--csv std::string 儲存 CSV 格式詳細報表的檔案路徑。
--dump_report bool 是否要將整個報表詳細資料直接傾印至使用者的控制台輸出內容。
--data_seed std::optional<int> 單一隨機數值，用於產生全球資料。
--do_register std::vector<std::string> 明確納入特定測試的 RegEx (例如 *mobilenet*)。
--dont_register std::vector<std::string> 排除特定測試的 RegEx。
--extra_models std::vector<std::string> 要新增至測試套件的目錄或模型檔案 (選用)。
--limit int32_t 限制註冊及執行的測試總數。
--quiet bool 在測試執行期間，盡量減少記錄輸出內容。

使用 litert_device_script 建構 ATS 的公用程式

ATS 目標使用者會自動執行的項目包括殼層進入點，這個進入點會處理所有環境設定，以及在目標裝置與完成建構的主機不同時 (例如 adb push)，推送任何必要程式庫。

這項功能是透過 litert_device_script 公用程式以一般方式提供，ATS 建構作業會在幕後使用這些公用程式。加速器必須完成註冊程序，才能存取這項建構功能。除了支援 ats 之外，這些公用程式也可以獨立運作，模擬要在建構主機以外的裝置上執行的 cc_binary 和 cc_test，並推送必要的依附元件。

後端註冊

如要啟用新加速器，以便搭配 litert_device_script (和 ATS) 使用，必須在 litert_device_common.bzl Bazel 檔案中註冊所需程式庫。註冊作業會根據專屬的「後端」名稱進行，該名稱會對應至一組可建構或預先編譯的程式庫，LiteRT 必須使用這些程式庫，才能搭配該加速器運作。

註冊步驟

  1. 定義 BackendSpec 函式：建立函式，傳回包含新加速器規格的字典。

  2. 指定程式庫 (libs)：這是元組清單，詳細說明共用程式庫的 Bazel 目標路徑，以及裝置連結器尋找該程式庫時所需的環境變數 (LD_LIBRARY_PATH)。

    • Dispatch 程式庫：執行階段必須使用。
    • 編譯器外掛程式庫：AOT 編譯模式需要這個程式庫。

  3. 指定程式庫名稱 (plugin、dispatch)：提供外掛程式和調度程式庫的檔案名稱。

  4. 註冊規格：將新的規格函式併入主要 _Specs 函式，透過專屬後端 ID 提供該函式。

註冊範例 (_ExampleSpec)

以下 litert_device_common.bzl 中的程式碼說明如何註冊「example」快速鍵：

def _ExampleSpec():
    return {
        # The unique backend ID
        "example": BackendSpec(
            id = "example",
            libs = [
                # Dispatch Library and how to find it on device
                ("//third_party/odml/litert/litert/vendors/examples:libLiteRtDispatch_Example.so", "LD_LIBRARY_PATH"),
                # Compiler Plugin Library
                ("//third_party/odml/litert/litert/vendors/examples:libLiteRtCompilerPlugin_Example.so", "LD_LIBRARY_PATH"),
            ],
            plugin = "libLiteRtCompilerPlugin_Example.so",
            dispatch = "libLiteRtDispatch_Example.so",
        ),
    }

# ... (Other specs are defined here)

def _Specs(name):
    # Your new spec function must be included here
    return (_QualcommSpec() | _GoogleTensorSpec() | _MediatekSpec() | _CpuSpec() | _GpuSpec() | _ExampleSpec())[name]

善用「litert_device_exec」註冊功能

註冊後，請搭配使用 litert_device_exec 和相關巨集與新的 backend_id。這個巨集會自動將必要程式庫和任何指定的資料檔案與目標二進位檔組合在一起。

cc_binary(
    name = "example_bin",
    srcs = ["example_bin.cc"],
)

litert_device_exec(
    name = "example_bin_device",
    backend_id = "example",  # Uses the libraries registered under "example"
    data = [
        "//third_party/odml/litert/litert/test:testdata/constant_output_tensor.tflite",
    ],
    target = ":example_bin",
)

執行這項目標 (bazel run ... :example_bin_device) 將會：

  1. 建構 example_bin C++ 二進位檔。
  2. 將二進位檔 libLiteRtDispatch_Example.so、libLiteRtCompilerPlugin_Example.so 和 .tflite 檔案推送至裝置。
  3. 使用 adb shell 執行二進位檔。

裝置路徑注意事項：裝置上檔案的標準位置會對應 Bazel 的執行檔樹狀結構，具體來說是 /data/local/tmp/runfiles/runfiles_relative_path。裝置指令碼會自動處理動態連結器適當路徑的設定。

編譯模式 (AOT)

對於支援預先 (AOT) 編譯步驟的加速器，ATS 可以在專用的「編譯模式」中執行。

  • 用途：這個模式設計為在工作站 (主機) 上執行，而非目標裝置。這項工具會編譯指定目標硬體的模型，但不會執行模型。
  • 輸出：所有已編譯的模型都會輸出至工作站上的指定目錄。
  • 啟用：ATS 建構巨集會針對為主機平台建構的程式庫，發出特定目標。您可以使用 --compile_mode 旗標在任何二進位檔上啟用這項流程，但這項流程會自動繫結至 AOT 建構的引數。

未來擴展

除了完整模型外，這套件也預計會擴充，納入單一作業 (ops) 的專屬測試。