# API预检
精度预检工具旨在计算单个API在整网计算中和标杆场景下的差异，对于无明确精度差异来源情况或者对模型了解不多的情形下都推荐使用预检工具，检查第一个步骤或Loss明显出现问题的步骤。它可以抓取模型中API输入的数值范围，根据范围随机生成输入，用相同的输入分别在NPU（GPU）和CPU上执行算子，比较输出差异。预检最大的好处是，它能根据算子（API）的精度标准来比较输出结果并判定其是否有精度问题。预检工具使用包含以下三步：dump、run_ut以及api_precision_compare。基本步骤如下：
1. 通过pip安装msprobe工具。 
   ```
   # shell
   pip install mindstudio-probe
   ```
   
   
2. 获取NPU和GPU的dump数据。
   
   PyTorch训练脚本插入dump接口方式如下：
   ```
   from msprobe.pytorch import PrecisionDebugger
   debugger = PrecisionDebugger(config_path='./config.json')
   ...
   debugger.start() # 一般在训练循环开头启动工具。
   ... # 循环体
   debugger.stop() # 一般在训练循环末尾结束工具。
   debugger.step() # 在训练循环的最后需要重置工具，非循环场景不需要。
   ```
   具体的config.json的配置要求请参见[介绍](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/02.config_introduction.md)。
   
   
3. 使用run_ut.py执行预检。
   
   ```
   msprobe -f pytorch run_ut -api_info ./dump.json
   ```
   这里-api_info指定的是[步骤2]导出的dump.json文件，表示整网计算过程中API的输入输出情况。执行完成run_ut命令之后将输出api_precision_compare_result_{timestamp}.csv和 api_precision_compare_details_{timestamp}.csv文。accuracy_checking_result_{timestamp}.csv属于API级，标明每个API是否通过测试。建议用户先查看accuracy_checking_result_{timestamp}.csv文件，对于其中没有通过测试的或者特定感兴趣的API，根据其API name字段在 accuracy_checking_details_{timestamp}.csv中查询其各个输出的达标情况以及比较指标。
   
   
4. 比对NPU和GPU预检结果。 
   ```
   msprobe -f pytorch api_precision_compare -npu /home/xxx/npu/accuracy_checking_details_{timestamp}.csv -gpu /home/xxx/gpu/accuracy_checking_details_{timestamp}.csv -o /home/xxx
   ```
   这里-npu指定[步骤3]NPU预检结果中accuracy_checking_details_{timestamp}.csv文件路径，-gpu指定GPU预检结果accuracy_checking_details_{timestamp}.csv文件路径， -o需指定执行比对结果的存盘路径。执行完成后输出api_precision_compare_result_{timestamp}.csv和 api_precision_compare_details_{timestamp}.csv文件。用户可以通过先查看api_precision_compare_result_{timestamp}.csv文件的Forward Test Success和Backward Test Success，判断是否存在未通过测试的API，再查看api_precision_compare_details_{timestamp}.csv文件的API详细达标情况。
   
   
详细工具的使用指导请参考[离线预检](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/07.accuracy_checker_PyTorch.md)介绍。