基于simplified key的运行时选择流程

本文介绍配置GenSimplifiedKey后的运行时流程。该机制用于从同一算子的多份预编译核函数（Kernel）binary中选择与本次调用条件匹配的一份。算子开发者负责提供回调和编译配置JSON；运行时框架负责调用回调、组装完整simplified key、查找并选择binary。

回调的实现见GenSimplifiedKey回调实现，JSON的提供和编译产物见simplified key二进制配置JSON。

运行时流程

在aclnnXxxGetWorkspaceSize阶段，运行时按以下顺序处理：

1. 加载算子包中的Host侧算子实现和binary_info_config.json，取得该OpType的binaryList及GenSimplifiedKey回调。
2. 根据本次调用的输入、输出、属性和目标AI处理器创建或复用TilingContext。
3. 调用算子注册的GenSimplifiedKey回调。回调读取TilingContext并写出自定义simplified key片段，例如custom_fp16。
4. 运行时框架补齐算子类型、确定性和实现模式等公共维度，生成完整simplified key，例如AddCustomTemplate/d=0,p=1/custom_fp16。
5. 运行时使用完整Key在binary_info_config.json的binaryList中查找，得到匹配的.o和配套.json路径，并加载对应binary。
6. 运行时调用已注册的TilingFunc，计算TilingData、workspace、BlockDim和TilingKey；随后创建executor并返回给调用方。
7. 在aclnnXxx执行阶段，运行时使用已选择的binary和前一阶段准备的Tiling结果下发核函数（Kernel）。

simplified key选择发生在Tiling之前的binary匹配阶段。GenSimplifiedKey不替代TilingFunc：前者用于选择哪份预编译binary，后者用于计算该binary本次执行需要的运行参数。

AddCustomTemplate示例

AddCustomTemplate预编译了FP16和FP32两份binary。其回调根据输入x的dtype生成片段，运行时完成后续选择：

表1 AddCustomTemplate运行时选择示例

本次调用	回调结果	运行时完整Key示例	选中的binary
x为FP16，y和z为FP16	custom_fp16	AddCustomTemplate/d=0,p=1/custom_fp16	AddCustomTemplate_FP16.o
x为FP32，y和z为FP32	custom_fp32	AddCustomTemplate/d=0,p=1/custom_fp32	AddCustomTemplate_FP32.o

这里的d=...和p=...由运行时按调用公共条件处理；算子开发者只维护最后的custom_fp16或custom_fp32片段。实际配置中同一份binary可以对应多个完整Key，以覆盖不同的确定性或实现模式组合。

开发者需要保证的对应关系

运行时能够选择正确binary的前提是两端使用同一套规则：

表2 编译侧与运行时回调侧的对应关系

编译侧	运行时回调侧
JSON为每个支持组合声明唯一的bin_filename和simplified_key。	GenSimplifiedKey对相同调用组合生成相同的simplified_key。
输入输出dtype、format、shape和属性组合与原型、核函数（Kernel）实现一致。	读取所有会影响binary选择的输入、输出、shape和属性，不遗漏组合维度。
编译产物将完整Key、.o路径和.json路径写入binary_info_config.json。	不拼接完整Key前缀，不加载文件，不选择binary。

例如，如果binary由两个输入的dtype共同决定，回调必须同时读取两个输入；只根据第一个输入生成Key会使不同组合落入同一个片段，导致查找错误或找不到binary。

失败处理

以下情况会导致本次调用无法通过自定义simplified key匹配到预编译binary：

• 未注册GenSimplifiedKey回调，或回调为空。
• 回调返回失败，例如输入描述为空或遇到未支持的dtype。
• 回调生成的片段为空、超长或与JSON中的simplified_key不一致。
• JSON未编译出该调用组合，或部署时缺少对应的.o、.json和binary_info_config.json。

因此，新增一种binary组合时必须同步完成三项工作：新增JSON项、更新回调分支、重新编译并部署算子包。只改其中一端都会破坏编译产物与运行时选择规则的一致性。

与两段式调用的关系

simplified key选择属于aclnnXxxGetWorkspaceSize阶段的准备工作。参数缓存命中时，运行时可以复用已保存的binary和Tiling信息；缓存未命中时，才执行上述回调、查找和Tiling流程。aclnnXxx执行阶段不重新生成Key，而是使用executor中已准备好的binary和Tiling结果。

相关文档

• 运行时加载机制：了解单算子两段式调用、缓存和通用binary匹配行为。
• GenSimplifiedKey回调实现：了解回调签名、注册方法和编写要求。
• simplified key二进制配置JSON：了解完整Key和binary路径如何写入编译产物。