自动映射比对说明

set_dump_path API介绍

• 函数原型

  set_dump_path(dump_path=".", dump_tag="msit_dump", backend="pt")

• 功能说明

  用于设置dump数据目录，多卡推理时须保证每个进程都能调用该函数。

• 参数说明

  参数名	含义	是否必填	使用说明
  dump_path	dump数据保存路径	否	数据类型：str，当需要dump不同对话的数据时，建议设置该参数，否则会覆盖上一轮对话的数据。
  dump_tag	设置dump数据目录名称	否	数据类型：str，参数示例：dump_tag="dialog_0"，默认dump数据目录命名为msit_dump。
  backend	推理后端	否	数据类型：str，可选值[pt, acl]，pt表示pytorch-npu或pytorch-gpu推理，acl表示加速库推理。

• 返回值

  无

register_hook

• 接口说明：给模型添加hook，用于dump数据
• 接口原型：register_hook(model, config, hook_type="dump_data")

精度比对命令行介绍

msit llm compare --golden-path golden_dump_path --my-path my_dump_path

使用说明

1. torch-npu(gpu)模型推理数据dump

   支持torch模型推理数据的dump，包括tensor，模型拓扑信息等，提供python API来使能数据dump。1.0版本仅支持torch.nn.Module类算子数据的dump，torch其他api数据dump将在后续版本中支持。

   1. 快速开始

      修改原推理脚本，在模型初始化之后，插入如下代码：

      # (可选)在推理模型完成初始化之前，启动确定性计算
      方法1：通过DumpConfig设定
      from msit_llm import DumpConfig
      dump_config = DumpConfig(seed=2024)
      方法2：手动引入接口
      from msit_llm import seed_all
      seed_all(seed=2024)
      
      # 推理模型已完成初始化 => model
      
      from msit_llm import DumpConfig, register_hook
      dump_config = DumpConfig(dump_path="./")
      register_hook(model, dump_config)  # model是要dump中间tensor的模型实例，在模型初始化后添加代码
      # 继续原来的推理流程

   2. API说明

      参数名	含义	使用说明	是否必填	版本
      dump_path	设置dump的数据路径	数据类型：str，默认为当前目录。	否
      token_range	需要dump的token列表	数据类型：list。默认为[0]，只dump第0个token的数据。	否
      module_list	指定要hook的module类型	数据类型：list，默认为[]，即dump所有module的数据。	否
      tensor_part	指定要dump哪部分数据	数据类型：int，默认为2。当tensor_part=0时，只dump输入数据；当tensor_part=1时，只dump输出数据； 当tensor_part=2时，dump输入和输出的数据。	否
      device_id	指定要dump的device id	数据类型：int，默认为None 表示不限制 device。如指定 device_id=1，将跳过其他 device 的 dump。	否
      dump_last_logits	是否需要Dump 模型最后的输出logits	数据类型： bool, 默认为False, 当开启后，仅 Dump 模型最后输出的 logits ,模型中间layer 不会再输出。 可参考 [《logits精度比对》](加速库场景-输出Token的logits精度比对.md)	否
      mode	设置dump的模式	可以选择dump api 还是 module，默认是module，也可以传入数组['api', 'module']，表示两种都dump 。	否	7.0.0b530
      dump_weight	设置是否需要dump权重	数据类型:bool，默认是False，不dump。[dump落盘位置](#dump-落盘位置)	否	7.0.0b530
      layer_name	指定需要dump的layer名字	数据类型:str，可以通过该参数控制dump 的权重和tensor。支持 * 表示匹配0或多个随意字符，不支持其他的模式匹配。	否	7.0.0b530
      seed	设定启动确定性计算的种子	数据类型:int，可以通过该参数确定是否要启动确定性计算，输入的值表示固定随机性的种子值。	否	7.0.0rc730

   3. 使用示例

      仅dump 模型的第 0 个 block，假定第 0 个 block 的名字为：root.transformer.encoder.layers.0 。具体名字可以从model信息中获取。

      from msit_llm import DumpConfig, register_hook
      dump_config = DumpConfig(dump_path="./", layer_name='root.transformer.encoder.layers.0*')
      register_hook(model, dump_config)

      仅dump 模型的权重。

      from msit_llm import DumpConfig, register_hook
      dump_config = DumpConfig(dump_path="./", dump_weight=True)
      register_hook(model, dump_config)

      仅dump 模型的输出token的logits。

      from msit_llm import DumpConfig, register_hook
      dump_config = DumpConfig(dump_path="./", dump_last_logits=True)
      register_hook(model, dump_config)

2. 加速库模型数据 dump

   提供大模型推理过程中产生的中间数据的 dump 能力，包括：

   【Dump Tensor 能力】 用于保存 单 operation 或 图 operation 的输入输出及中间张量，主要精度比对时使用。

   【保存拓扑信息能力】 包含两个维度的拓扑信息的保存能力，分别为 Operation 维度和模型维度，Operation 维度的拓扑信息保存能力主要是保存 ATB 的 Operation 的拓扑信息，用于图结构分析；模型维度拓扑信息保存能力主要依赖于MindIE-LLM，用于保存MindIE-LLM内 model 的拓扑信息，进行模型结构分析，或自动精度比对，自动比对需要先知道模型拓扑信息。模型拓扑信息可以转换成 onnx，可以使用可视化工具打开查看。

   【保存 Operation 信息能力】 保存 ATB Operation 的多项属性，如参数、输入张量 Shape、输出张量 Shape 等。

   【保存 kernel 信息能力】 保存 kernel Operation 的多项属性，是比 ATB Operation 更细粒度，是 ATB Operation 的组成部分，多数是算子开发人员定位使用。

   【保存 cpu_profiling 数据能力】 保存 cpu profiling 信息，主要用于 host 侧性能定位，数据下发慢等问题，主要是算子开发、熟悉 atb 框架的开发人员定位使用。

   【保存 tiling 数据能力】 tiling 数据是 host 侧计算生成，用于 device 侧进行数据切分。主要用于算子开发人员定位算子精度异常问题。

   1. 使用方式

      msit llm dump --exec "<任意包含ATB的程序执行命令>" [可选参数]
      
      # dump 不同类型数据
      msit llm dump --exec "<任意包含ATB的程序执行命令>" --type model tensor # 常用用于自动比对
      msit llm dump --exec "<任意包含ATB的程序执行命令>" --type onnx # 常用于导出onnx查看网络结构
      
      # 仅dump layer 层的算子输出，常用于精度比对先找到存在问题的 layer 层。相比全量dump，可以节省磁盘空间和定位时间
      msit llm dump --exec "<任意包含ATB的程序执行命令>" --type model tensor -child False
      
      # dump 不同轮次数据
      msit llm dump --exec "<任意包含ATB的程序执行命令>" --type model tensor -er 1,1 # dump输出轮次为 1 的数据，根据实际情况指定。需要考虑是否有warmup，是否有prefill
      
      # dump 指定算子
      msit llm dump --exec "<任意包含ATB的程序执行命令>" --type model tensor -ids 3 # dump 编号为 3 的layer的输入输出数据
      msit llm dump --exec "<任意包含ATB的程序执行命令>" --type model tensor -ids 3_1 # dump 编号为 3 的layer数据中第 1 个子算子的输入输出数据

   2. 命令行参数

      参数名	描述	必选
      --exec	指定包含 ATB 的程序执行命令，使用示例： --exec "bash run.sh patches/models/modeling_xxx.py"。 注：命令中不支持重定向字符，如果需要重定向输出，建议将执行命令写入 shell 脚本，然后启动 shell 脚本。	是
      --type	dump 类型，默认为['tensor', 'model']。使用方式：--type layer tensor。可选项有： model: 模型拓扑信息。 layer: Operation 维度拓扑信息。 op: ATB Operation 信息。 kernel: kernel Operation 信息。 tensor: tensor 数据（默认）。 cpu_profiling: cpu profiling 数据。 onnx: onnx 模型。仅用于模型结构可视化。	否
      -sd，--only-save-desc	只保存 tensor 描述信息开关，默认为否，开启开关时将 dump tensor 的描述信息，使用方式：-sd。	否
      -ids，--save-operation-ids	设置 dump 指定 id 的算子的 tensor，默认为空，全量 dump。使用方式：-ids 2, 3_1 表示只 dump 第 2 个 operation 和第 3 个 operation 的第 1 个算子的数据，id 从 0 开始。若不确定算子 id，可以先执行 msit llm dump --exec xx --type model 命令，将 model 信息 dump 下来，即可获得模型中所有的算子 id 信息。	否
      -er，--execute-range	指定 dump 的 token 轮次范围，区间左右全闭，可以支持多个区间序列，默认为第 0 次，使用方式：-er 1,3 或 -er 3,5,7,7（代表区间[3,5]，[7,7]，也就是第 3，4，5，7 次 token）。	否
      -child，--save-operation-child	选择是否 dump 所有子操作的 tensor 数据，仅使用 ids 场景下有效，默认为 true。使用方式：-child True。	否
      -time，--save-time	选择保存的时间节点，取值[0,1,2,3]，0 代表保存执行前(before)，1 代表保存执行后(after)，2 代表前后都保存(both), 3 代表保存执行前的intensor和执行后的outtensor。默认值为 3。使用方式：-time 0	否
      -opname，--operation-name	指定需要 dump 的算子类型，只需要指定算子名称的开头，可以模糊匹配，如 selfattention 只需要填写 self。使用方式：-opname self。	否
      -tiling，--save-tiling	选择是否需要保存 tiling 数据，默认为 false。使用方式：-tiling。	否
      --save-tensor-part, -stp	指定保存 tensor 的部分，0 为仅 intensor，1 为仅 outtensor，2 为全部保存，默认为 2。使用示例：-stp 1。	否
      -o, --output	指定 dump 数据的输出目录，默认为'./'，使用示例：-o aasx/sss。	否
      -device, --device-id	指定 dump 数据的 device id，默认为 None 表示不限制。如指定 --device-id 1，将只 dump 1 卡的数据。	否
      -l, --log-level	指定 log level，默认为 info，可选值 debug, info, warning, error, fatal, critical。	否
      -h, --help	命令行参数帮助信息。	否
      -seed	设定确定性计算的种子，默认为None表示不开启确定性计算。如果设置种子，可以不输入。如果不输入那么为2024，如果输入那么需要输入一个能转换为int的值。使用示例：-seed 1。	否

3. 自动比对

   提供模型推理过程中出现的异常检测能力，如算子预算溢出、内存踩踏等，1.0版本仅支持溢出检测。

   图1 比对结果
   

   1. 使用方式

      msit llm compare -w -gp (path) -mp {path} [可选参数]

   2. 参数说明

      参数名	描述	是否必选
      --golden-path, -gp	标杆数据路径，支持单个数据文件路径或文件夹。	必选
      --my-path, -mp	待比较的数据路径，为单个数据文件路径。	必选
      --weight, -w	指定是否需要输出大模型反量化后权重和浮点权重的比较csv文件，不指定则不输出比较文件。	可选
      --op-mapping-file, -mf	算子类型映射关系文件路径，加速库模型与torch模型比对场景下按需提供。	可选
      --log-level, -l	日志级别，默认为info，可选值有：debug, info, warning, error, fatal, critical。	可选
      --output, -o	比对结果csv的输出路径。	可选
      -cmp-level,-cl	比对层级，默认比对layer，可选只有：layer，token。	可选
      --custom-algorithms, -alg	指定自定义比对算法，格式应为"python_file_path.py:function"。自定义算法最好为独立文件，方法示例："def foo(golden_tensor, my_tensor): return float_value, string_message"，使用方式：-alg python_file_path.py:foo python_file_path.py:foo2。	否
      --help,-h	命令行参数帮助信息。	否

   3. 大模型反量化后权重和浮点权重比对
      1. 使用场景：

         在大模型量化出现精度问题需要进行排查时，工具支持对大模型量化前后的权重进行比对。反量化后权重和浮点权重比应该是比较相似的，对此进行检查。

      2. 指令：

         msit llm compare -w -gp {path} -mp {path}

         -gp：量化前浮点权重路径，当前路径下需存在模型量化前浮点权重.safetensor文件。

         -mp：反量化后权重路径，当前路径下需存在模型反量化后浮点权重.safetensor文件。