SDK 代理集成¶

代理后端是设备上模型的重要组成部分，因为它们在定义行为方面具有灵活性。这种灵活性的副作用是它充当不透明转换。这会模糊在后处理中很有价值的丰富关联和变异。

例如，如果两个不同的运算符融合在代理中发生，后处理将无法分离这两个转换。

具体来说，它使得通过委托图关联运行时信息（例如分析结果）变得困难。代理调试标识符提供了一个框架，通过该框架，代理作者可以传播此信息并将其用于运行后分析。

准备工作分为三个阶段

提前 (AOT)：代理作者生成一个 调试句柄映射。
运行时：代理作者使用 AOT 中注册的 代理调试标识符 在 调试句柄映射 中进行日志记录。
反序列化：代理作者为代理事件中的自定义元数据提供一个解析器。

提前¶

代理作者通过从后端实现返回 调试句柄映射 来传播在降低的后端中发生的转换。

生成调试句柄映射¶

调试句柄映射 通过将 代理调试标识符 映射到调试句柄来传达在后端中发生的转换。

代理调试标识符 是为表示运行时期间的兴趣点而生成的或用户提供的标识符。回想一下，调试句柄是模型图中运算符实例的唯一标识符。

例如

{ 0: (10, 11), 1: (11, 12) }: 运行时中的标识符 0 和 1 分别对应于具有调试句柄 (10, 11) 和 (11, 12) 的运算符。
{ “fused_op_1_2_3”: (11, 12, 15) }：运行时中的标识符 “fused_op_1_2_3” 对应于具有调试句柄 (11, 12, 15) 的运算符，而 11、12、15 对应于运算符 1、运算符 2 和运算符 3。

注意

标识符是一种将运行时结果连接到模型图的方法；标识符的解释由代理作者定义。

调试句柄映射 是通过使用 DelegateMappingBuilder 构建的，并作为 PreprocessResult 的一部分返回。

class PreprocessResult:
    processed_bytes: bytes = bytes()

    debug_handle_map: Optional[
        Union[Dict[int, Tuple[int]], Dict[str, Tuple[int]]]
    ] = None

PreprocessResult 的定义在此。

DelegateMappingBuilder¶

DelegateMappingBuilder 是一个用于管理和构建调试句柄映射的辅助类。构建器的结果应该在构建 PreprocessResult 时传入。

DelegateMappingBuilder 的定义在此

可以以两种模式之一构建 DelegateMappingBuilder 实例：手动标识符或生成的标识符。

# Manual Identifiers, Default
builder = DelegateMappingBuilder(generated_identifiers=False)

# Generated Identifiers
builder = DelegateMappingBuilder(generated_identifiers=True)

使用 手动标识符，用户在创建条目时传入 代理调试标识符。使用 生成的标识符，构建器将自动分配一个 代理调试标识符。

要向 调试句柄映射 添加条目，请使用 insert_delegate_mapping_entry。它将一个 fx.Node(s) 或调试句柄 (s)（来自 node.meta[“debug_handle”]）关联到一个可选的 代理调试标识符（用于手动标识符）。记录的标识符将从调用中返回。

def insert_delegate_mapping_entry(
    self,
    nodes: Optional[Union[Node, List[Node]]] = None,
    handles: Optional[Union[int, List[int]]] = None,
    identifier: Optional[Union[int, str]] = None,
) -> Union[int, str]:

要检索 调试句柄映射，请使用 get_delegate_mapping。

def get_delegate_mapping(
    self,
) -> Union[Dict[int, Tuple[int]], Dict[str, Tuple[int]]]

AOT 映射的演示示例可以在此找到

运行时¶

对应于 AOT 映射，运行时随后定义了通过这些事件记录的功能。

实时日志记录¶

ExecuTorch 允许您实时记录日志。实时日志记录 在执行发生时可获得时间戳时非常有用。它提供最小的开销，对于作者来说调用起来直观。

要实时记录事件（例如，明确表示分析开始和结束），event_tracer_start_profiling_delegate 用于创建一个 EventEntry，而 event_tracer_end_profiling_delegate 用于为提供的 EventTracer 结束 EventEntry。

要使用 event_tracer_start_profiling_delegate 启动一个 EventTracerEntry，代理调试标识符（AOT 提供给 debug_handle_map）作为名称或 delegate_debug_id 参数传入，具体取决于 代理调试标识符 类型（分别为 str 和 int）

EventTracerEntry event_tracer_start_profiling_delegate(
    EventTracer* event_tracer,
    const char* name,
    DebugHandle delegate_debug_id)

为了结束一个 EventTracerEntry，只需将原始的 EventTracerEntry 提供给 event_tracer_end_profiling_delegate。

此外，还可以选择在此处记录额外的运行时 metadata。

void event_tracer_end_profiling_delegate(
    EventTracer* event_tracer,
    EventTracerEntry event_tracer_entry,
    const void* metadata = nullptr,
    size_t metadata_len = 0)

后期时间记录¶

ExecuTorch 还允许您进行后期时间记录。某些运行时设置在执行过程中无法访问时间戳。后期时间记录 使得作者仍然能够记录这些事件。

为了记录后期事件（例如，同时记录开始时间和结束时间），event_tracer_log_profiling_delegate 将使用实时记录 API 中使用的参数组合和时间戳进行调用。

void event_tracer_log_profiling_delegate(
    EventTracer* event_tracer,
    const char* name,
    DebugHandle delegate_debug_id,
    et_timestamp_t start_time,
    et_timestamp_t end_time,
    const void* metadata = nullptr,
    size_t metadata_len = 0)

可以在这里找到运行时代码演示。

从委托事件中显示自定义元数据¶

如上所述，用户可以在运行时记录 API 中记录一个字节数组以及他们的委托分析事件。我们通过 Inspector API 为用户提供这些数据以供后期处理。

用户可以在创建 Inspector 实例时传入一个元数据解析器。解析器是一个可调用对象，它反序列化数据并返回字符串列表或包含键值对的字典。然后，反序列化后的数据将被添加回事件块中的对应事件，以供用户使用。以下是如何编写此解析器的示例。

注意：反序列化器的输入是一个列表，其中每个条目都是一系列字节（本质上每个条目都是一个不可变的字节数组）。用户应该遍历此列表，反序列化每个条目，然后以预期格式返回它，该格式可以是字符串列表或字典。

Inspector(
    etdump_path=etdump_path,
    # Optional
    etrecord=etrecord_path,
    # Optional, only needed if debugging was enabled.
    buffer_path=buffer_path,
    delegate_metadata_parser=parse_delegate_metadata
)


def parse_delegate_metadata(delegate_metadatas: List[bytes]) -> Union[List[str], Dict[str, Any]]:
    metadata_str = []
    for metadata_bytes in delegate_metadatas:
        metadata_str += str(metadata_bytes)
    return metadata_str