Inspector API¶
概述¶
Inspector API 提供了一個便捷的介面，用於分析 ETRecord 和 ETDump 的內容，幫助開發者深入瞭解模型架構和效能統計資訊。它構建在 EventBlock 類 資料結構之上，該結構組織了一組 Event，以便輕鬆訪問效能分析事件的詳細資訊。
使用者可以透過多種方式與 Inspector API 進行互動
請參考 e2e 用例文件，瞭解如何在實際示例中使用這些功能。
Inspector 方法¶
建構函式¶
- executorch.devtools.Inspector.__init__(self, etdump_path=None, etdump_data=None, etrecord=None, source_time_scale=TimeScale.NS, target_time_scale=TimeScale.MS, debug_buffer_path=None, delegate_metadata_parser=None, delegate_time_scale_converter=None, enable_module_hierarchy=False)¶
初始化一個 Inspector 例項，其底層 EventBlocks 使用提供的 ETDump 路徑或二進位制資料填充，並可選擇提供 ETRecord 路徑。
- 引數
etdump_path – ETDump 檔案路徑。必須提供此引數或 etdump_data。
etdump_data – ETDump 二進位制資料。必須提供此引數或 etdump_path。
etrecord – 可選的 ETRecord 物件或 ETRecord 檔案路徑。
source_time_scale – 從執行時檢索到的效能資料的時間刻度。執行時中預設的時間 hook 實現返回 NS。
target_time_scale – 使用者希望將效能資料轉換為的目標時間刻度。預設為 MS。
debug_buffer_path – 除錯緩衝區檔案路徑，包含 ETDump 引用的中間和程式輸出的除錯資料。
delegate_metadata_parser – 可選函式，用於從 Profiling Event 解析 delegate 元資料。預期函式簽名是：(delegate_metadata_list: List[bytes]) -> Union[List[str], Dict[str, Any]]
delegate_time_scale_converter – 可選函式，用於轉換 delegate 效能分析資料的時間刻度。如果未提供，則使用 target_time_scale/source_time_scale 的轉換比例。
enable_module_hierarchy – 在運算元圖中啟用子模組。預設為 False。
- 返回值
無
示例用法
from executorch.devtools import Inspector
inspector = Inspector(etdump_path="/path/to/etdump.etdp", etrecord="/path/to/etrecord.bin")
to_dataframe¶
- executorch.devtools.Inspector.to_dataframe(self, include_units=True, include_delegate_debug_data=False)¶
- 引數
include_units – 標頭是否應包含單位（預設為 true）
include_delegate_debug_data – 是否包含 delegate 除錯元資料（預設為 false）
- 返回值
返回一個 pandas DataFrame，其中包含 inspector 中每個 EventBlock 的 Event，每行代表一個 Event。
print_data_tabular¶
- executorch.devtools.Inspector.print_data_tabular(self, file=<sphinx_gallery.gen_rst._LoggingTee object>, include_units=True, include_delegate_debug_data=False)¶
以結構化表格格式顯示底層 EventBlocks，每行代表一個 Event。
- 引數
file – 列印到哪個 IO 流。預設為 stdout。如果在 IPython 環境（例如 Jupyter notebook）中則不使用。
include_units – 標頭是否應包含單位（預設為 true）
include_delegate_debug_data – 是否包含 delegate 除錯元資料（預設為 false）
- 返回值
無
示例用法
inspector.print_data_tabular()
請注意，delegate 效能分析事件的單位是“cycles”。我們正在努力將來提供一種設定不同單位的方法。
find_total_for_module¶
- executorch.devtools.Inspector.find_total_for_module(self, module_name)¶
返回指定模組中所有運算元的總平均計算時間。
- 引數
module_name – 要聚合的模組名稱。
- 返回值
名稱為“module_name”的模組中所有運算元的總平均計算時間（以秒為單位）。
示例用法
print(inspector.find_total_for_module("L__self___conv_layer"))
0.002
get_exported_program¶
- executorch.devtools.Inspector.get_exported_program(self, graph=None)¶
ETRecord 的訪問助手，預設為返回 Edge Dialect program。
- 引數
graph – 要訪問的圖的可選名稱。如果為 None，則返回 Edge Dialect program。
- 返回值
“graph”的 ExportedProgram 物件。
示例用法
print(inspector.get_exported_program())
ExportedProgram:
class GraphModule(torch.nn.Module):
def forward(self, arg0_1: f32[4, 3, 64, 64]):
# No stacktrace found for following nodes
_param_constant0 = self._param_constant0
_param_constant1 = self._param_constant1
### ... Omit part of the program for documentation readability ... ###
Graph signature: ExportGraphSignature(parameters=[], buffers=[], user_inputs=['arg0_1'], user_outputs=['aten_tan_default'], inputs_to_parameters={}, inputs_to_buffers={}, buffers_to_mutate={}, backward_signature=None, assertion_dep_token=None)
Range constraints: {}
Equality constraints: []
Inspector 屬性¶
EventBlock 類¶
透過 Inspector 例項的 event_blocks 屬性訪問 EventBlock 例項，例如
inspector.event_blocks
- class executorch.devtools.inspector.EventBlock(name, events=<factory>, source_time_scale=TimeScale.NS, target_time_scale=TimeScale.MS, bundled_input_index=None, run_output=None, reference_output=None)[source]¶
一個 EventBlock 包含與從執行時檢索到的特定效能分析/除錯塊相關聯的事件集合。每個 EventBlock 代表一種執行模式。例如，模型初始化和載入存在於單個 EventBlock 中。如果存在控制流，每個分支將由一個單獨的 EventBlock 表示。
- 引數
name – 效能分析/除錯塊的名稱。
events – 與效能分析/除錯塊相關聯的 Event 列表。
bundled_input_idx – 此 EventBlock 對應的 Bundled Input 的索引。
run_output – 從封裝的 Events 中提取的執行輸出。
Event 類¶
透過 EventBlock 例項的 events 屬性訪問 Event 例項。
- class executorch.devtools.inspector.Event(name, perf_data=None, op_types=<factory>, delegate_debug_identifier=None, debug_handles=None, stack_traces=<factory>, module_hierarchy=<factory>, is_delegated_op=None, delegate_backend_name=None, _delegate_debug_metadatas=<factory>, debug_data=<factory>, _instruction_id=None, _delegate_metadata_parser=None, _delegate_time_scale_converter=None)[source]¶
一個 Event 對應一個運算元例項，該例項具有從執行時檢索到的效能資料和從 ETRecord 獲取的其他元資料。
- 引數
name – 效能分析 Event 的名稱，如果沒有效能分析事件則為空。
perf_data – 與從執行時檢索到的事件相關聯的效能資料（可用屬性：p10, p50, p90, avg, min and max）。
op_type – 與事件對應的運算元型別列表。
delegate_debug_identifier – 與 instruction id 結合使用的補充識別符號。
debug_handles – 模型圖中與此事件相關的除錯控制代碼。
stack_trace – 將每個關聯運算元的名稱對映到其堆疊跟蹤的字典。
module_hierarchy – 將每個關聯運算元的名稱對映到其模組層次結構的字典。
is_delegated_op – 事件是否被 delegate。
delegate_backend_name – 此事件被 delegate 到的後端名稱。
_delegate_debug_metadatas – 原始 delegate 除錯元資料的字串列表，每個效能分析事件對應一個。如果提供瞭解析器，則作為 Event.delegate_debug_metadatas 可用；也作為 Event.raw_delegate_debug_metadatas 可用。
debug_data – 包含收集到的中間資料的列表。
_instruction_id – 用於符號化的 Instruction 識別符號。
_delegate_metadata_parser – _delegate_debug_metadatas 的可選解析器。
示例用法
for event_block in inspector.event_blocks:
for event in event_block.events:
if event.name == "Method::execute":
print(event.perf_data.raw)
[175.748, 78.678, 70.429, 122.006, 97.495, 67.603, 70.2, 90.139, 66.344, 64.575, 134.135, 93.85, 74.593, 83.929, 75.859, 73.909, 66.461, 72.102, 84.142, 77.774, 70.038, 80.246, 59.134, 68.496, 67.496, 100.491, 81.162, 74.53, 70.709, 77.112, 59.775, 79.674, 67.54, 79.52, 66.753, 70.425, 71.703, 81.373, 72.306, 72.404, 94.497, 77.588, 79.835, 68.597, 71.237, 88.528, 71.884, 74.047, 81.513, 76.116]
CLI¶
在您的終端中執行以下命令以顯示資料表。此命令產生的表格輸出與呼叫前面提到的 print_data_tabular 函式相同
python3 -m devtools.inspector.inspector_cli --etdump_path <path_to_etdump> --etrecord_path <path_to_etrecord>
請注意，etrecord_path 引數是可選的。
我們計劃將來擴充套件 CLI 的功能。
