# msIT (MindStudio Inference Tools)

msIT（MindStudio Inference Tools）是华为昇腾AI推理工具链，提供一站式推理开发能力，帮助用户进行模型迁移以及性能与精度的调试调优。该工具套件包含benchmark（性能测试）、debug（调试比对）、analyze（模型分析）、convert（模型转换）、profile（性能分析）、llm（大模型调试）、graph（图分析）、tensor-view（张量查看）等核心组件，支持TensorFlow、ONNX、Caffe、PyTorch等主流深度学习框架。

msIT面向昇腾硬件平台设计，核心目标是简化模型从训练环境到昇腾推理设备的迁移过程。通过提供自动化的精度比对、性能分析、算子支持度分析等功能，开发者可以快速定位模型迁移和部署过程中的精度问题与性能瓶颈，大幅提升AI应用开发效率。配套的msModelSlim工具还提供大模型量化压缩能力，支持W8A8、W8A16、W4A16等多种量化方案。

---

## msit benchmark - 推理性能测试

执行OM离线模型推理并测量吞吐率和时延性能。

```bash
# 基础推理测试 - 使用随机数据对OM模型进行纯推理
msit benchmark --om-model resnet50.om

# 指定输入数据进行推理测试
msit benchmark --om-model resnet50.om --input input_0.npy,input_1.npy --output ./results

# 多设备并行推理 - 在0,1,2,3号NPU上同时进行推理
msit benchmark --om-model resnet50.om --device 0,1,2,3 --divide-input 1

# 动态Shape模型推理
msit benchmark --om-model dynamic_model.om --dym-shape "input1:1,3,224,224" --output-size 10000000

# 启用Profiler采集性能数据
msit benchmark --om-model resnet50.om --profiler 1 --output ./profiling_results --loop 1

# 多线程推理模式
msit benchmark --om-model resnet50.om --pipeline 1 --threads 4 --loop 100
```

---

## InferSession Python API - 模型推理接口

基于AscendCL的Python推理接口，用于加载和执行OM离线模型。

```python
from ais_bench.infer.interface import InferSession
import numpy as np

# 初始化推理会话 - 在device 0上加载模型
session = InferSession(device_id=0, model_path="resnet50.om")

# 获取模型输入输出信息
inputs_info = session.get_inputs()
outputs_info = session.get_outputs()
print(f"模型输入: {[(inp.name, inp.shape, inp.datatype) for inp in inputs_info]}")
print(f"模型输出: {[(out.name, out.shape, out.datatype) for out in outputs_info]}")

# 准备输入数据
input_data = np.random.randn(1, 3, 224, 224).astype(np.float32)

# 执行静态模型推理
outputs = session.infer(feeds=[input_data], mode="static")
print(f"推理结果Shape: {outputs[0].shape}")

# 获取推理性能数据
exec_time = session.summary().exec_time_list[-1]
print(f"推理耗时: {exec_time:.2f} ms")

# 批量推理 - 使用pipeline接口提升吞吐
feeds_list = [[np.random.randn(1, 3, 224, 224).astype(np.float32)] for _ in range(10)]
batch_outputs = session.infer_pipeline(feeds_list=feeds_list, mode="static")

# 迭代推理 - 适用于自回归模型场景
# in_out_list: [-1, 1, 0] 表示第一个输入保持不变，第二个输入来自第二个输出，第三个输入来自第一个输出
iteration_outputs = session.infer_iteration(
    feeds=[input_data, input_data, input_data],
    in_out_list=[-1, 1, 0],
    iteration_times=5,
    mode="static"
)

# 释放资源
session.free_resource()
```

---

## MultiDeviceSession - 多设备并行推理

支持多NPU设备并行推理的会话管理接口。

```python
from ais_bench.infer.interface import MultiDeviceSession
import numpy as np

# 初始化多设备会话
multi_session = MultiDeviceSession(model_path="resnet50.om")

# 准备多设备输入数据: {device_id: [feeds1, feeds2, ...]}
devices_feeds = {
    0: [[np.random.randn(1, 3, 224, 224).astype(np.float32)]],
    1: [[np.random.randn(1, 3, 224, 224).astype(np.float32)]],
    2: [[np.random.randn(1, 3, 224, 224).astype(np.float32)]],
}

# 多设备并行推理
results = multi_session.infer(devices_feeds=devices_feeds, mode="static")

# 获取各设备推理结果
for device_id, outputs in results.items():
    print(f"Device {device_id} 输出Shape: {outputs[0][0].shape}")

# 获取端到端推理性能
perf_summary = multi_session.summary()
for device_id, times in perf_summary.items():
    print(f"Device {device_id} 端到端耗时: {times[0]:.2f} ms")
```

---

## msit debug compare - 模型精度比对

一键式全流程精度比对，支持ONNX、TensorFlow、Caffe等框架模型与昇腾OM模型的精度比对。

```bash
# ONNX模型与OM模型精度比对
msit debug compare \
    -gm /path/to/resnet50.onnx \
    -om /path/to/resnet50.om \
    -c /usr/local/Ascend/ascend-toolkit/latest \
    -o /path/to/output

# 指定输入数据进行精度比对
msit debug compare \
    -gm /path/to/model.onnx \
    -om /path/to/model.om \
    -i /path/to/input_0.bin,/path/to/input_1.bin \
    -o /path/to/output

# 动态Shape模型精度比对
msit debug compare \
    -gm /path/to/dynamic_model.onnx \
    -om /path/to/dynamic_model.om \
    -is "input_name:1,3,224,224" \
    -dr "input_name:1,3,200~256,200~256" \
    -o /path/to/output

# Caffe模型精度比对
msit debug compare \
    -gm /path/to/model.prototxt \
    -w /path/to/model.caffemodel \
    -om /path/to/model.om \
    -o /path/to/output

# 开启误差定位功能，自动定位首个精度问题节点
msit debug compare \
    -gm /path/to/model.onnx \
    -om /path/to/model.om \
    --locat True \
    --advisor \
    -o /path/to/output
```

---

## msit llm dump - 大模型推理数据落盘

提供大模型推理过程中的中间数据dump能力，支持加速库ATB和PyTorch场景。

```bash
# 基础用法 - dump模型拓扑和tensor数据
msit llm dump --exec "python run_inference.py" --type model tensor

# dump指定轮次的数据 (第1轮到第3轮)
msit llm dump --exec "python run_inference.py" --type model tensor -er 1,3

# dump指定算子的数据 - 仅dump编号为3的layer
msit llm dump --exec "python run_inference.py" --type model tensor -ids 3

# 仅dump layer层输出，不dump子算子 (节省磁盘空间)
msit llm dump --exec "python run_inference.py" --type model tensor -child False

# dump统计量而非全量tensor (节省磁盘空间)
msit llm dump --exec "python run_inference.py" --type model tensor stats

# 导出ONNX格式用于可视化网络结构
msit llm dump --exec "python run_inference.py" --type onnx

# 指定输出目录和设备
msit llm dump --exec "python run_inference.py" --type model tensor -o ./dump_output -device 0
```

---

## PyTorch场景数据dump - register_hook接口

通过PyTorch hook机制采集大模型推理数据。

```python
from msit_llm import DumpConfig, register_hook
from transformers import AutoTokenizer, LlamaForCausalLM
import torch

# 加载模型
tokenizer = AutoTokenizer.from_pretrained("/path/to/Llama-2-7b-hf", trust_remote_code=True)
model = LlamaForCausalLM.from_pretrained(
    "/path/to/Llama-2-7b-hf",
    trust_remote_code=True
).to('npu')  # 或 .to('cuda') / .to('cpu')

# 配置dump参数
dump_config = DumpConfig(
    dump_path="./dump_output",  # dump数据保存路径
    seed=2345,                   # 随机种子，确保可复现
    token_range=[0, 1, 2, 3, 4]  # dump指定token范围的数据
)

# 注册hook
register_hook(model, dump_config)

# 执行推理 - hook会自动采集数据
with torch.no_grad():
    inputs = tokenizer(
        "What's deep learning?",
        return_tensors="pt",
        truncation=True,
        max_length=10
    ).to('npu')

    if 'token_type_ids' in inputs:
        del inputs['token_type_ids']

    outputs = model.generate(**inputs, do_sample=False, max_new_tokens=10)

print(tokenizer.decode(outputs[0], skip_special_tokens=True))
# dump数据将保存在 ./dump_output 目录下
```

---

## msit llm compare - 大模型精度比对

ATB加速库与PyTorch模型的整网精度比对工具。

```bash
# ATB与PyTorch数据比对
msit llm compare \
    -gp /path/to/pytorch_dump \
    -mp /path/to/atb_dump \
    -o /path/to/output

# 指定比对层级 (layer/module/api/logits)
msit llm compare \
    -gp /path/to/golden_dump \
    -mp /path/to/my_dump \
    -cl layer \
    -o /path/to/output

# logits比对 - 定位第一个出现精度问题的token
msit llm compare \
    -gp /path/to/golden_logits \
    -mp /path/to/my_logits \
    -cl logits \
    -o /path/to/output

# 统计量比对
msit llm compare \
    -gp /path/to/golden_dump \
    -mp /path/to/my_dump \
    -st \
    -o /path/to/output

# 使用自定义比对算法
msit llm compare \
    -gp /path/to/golden_dump \
    -mp /path/to/my_dump \
    -alg custom_compare.py:my_compare_func \
    -o /path/to/output
```

---

## msit llm opcheck - 单算子精度预检

检测加速库算子精度是否达标，基于真实推理数据进行预检验证。

```bash
# 基础用法 - 全量算子预检
msit llm opcheck -i /path/to/msit_dump_{TIMESTAMP}/tensors/{device_id}_{PID}/{TID}/

# 指定算子ID进行预检
msit llm opcheck \
    -i /path/to/tensor_dump \
    -ids 24_1,2_3_5

# 指定算子类型进行预检
msit llm opcheck \
    -i /path/to/tensor_dump \
    -opname self,linear

# 指定精度指标 (绝对误差、余弦相似度、KL散度)
msit llm opcheck \
    -i /path/to/tensor_dump \
    -metric abs cos_sim kl

# 重新运行算子获取output (解决Atlas 300I Duo原地读写问题)
msit llm opcheck \
    -i /path/to/tensor_dump \
    -rerun

# 多进程加速预检
msit llm opcheck \
    -i /path/to/tensor_dump \
    -j 4
```

---

## msit convert - 模型转换

将ONNX、TensorFlow、Caffe、MindSpore等框架模型转换为昇腾OM离线模型。

```bash
# 使用ATC进行ONNX到OM转换
msit convert atc \
    --model resnet50.onnx \
    --framework 5 \
    --soc_version Ascend310P3 \
    --output resnet50

# 使用AOE进行模型转换及自动调优
msit convert aoe \
    --model resnet50.onnx \
    --job_type 2 \
    --output resnet50

# 使用MindIE-RT进行模型转换
msit convert aie \
    --golden-model resnet50.onnx \
    --output-file resnet50.om \
    --soc-version Ascend310P3
```

---

## msit analyze - 模型支持度分析

分析模型中算子在昇腾平台上的支持情况、约束条件和输入有效性。

```bash
# 分析ONNX模型的算子支持度
msit analyze \
    -gm /path/to/model.onnx \
    -o /path/to/output

# 分析Caffe模型 (需要权重文件)
msit analyze \
    -gm /path/to/model.prototxt \
    -w /path/to/model.caffemodel \
    --framework 0 \
    -o /path/to/output

# 指定芯片类型
msit analyze \
    -gm /path/to/model.onnx \
    -soc Ascend310P3 \
    -o /path/to/output
```

---

## msit profile - 性能分析

采集和分析昇腾设备上模型推理的性能数据。

```bash
# 安装profile组件
msit install profile

# 使用msprof采集性能数据
msit profile msprof --application="python inference.py" --output=/path/to/profiling

# 性能数据分析比对
msit profile analyze --input=/path/to/profiling --output=/path/to/report
```

---

## msModelSlim - 大模型量化

大模型训练后量化工具，支持W8A8、W8A16、W4A16等多种量化方案。

```python
import torch
import torch_npu
from transformers import AutoTokenizer, AutoModel
from msmodelslim.pytorch.llm_ptq.llm_ptq_tools import Calibrator, QuantConfig

# 加载模型
tokenizer = AutoTokenizer.from_pretrained('./chatglm2', local_files_only=True)
model = AutoModel.from_pretrained('./chatglm2', local_files_only=True).npu()

# 准备校准数据
calib_list = [
    "中国的首都在哪里？",
    "请做一首诗歌：",
    "我想要学习python，该怎么学习？",
    "请帮我写一篇关于大模型推理优化的任职报告：",
    "中国最值得去的几个景点"
]

def get_calib_dataset(tokenizer, calib_list, model):
    calib_dataset = []
    for calib_data in calib_list:
        inputs = tokenizer([calib_data], return_tensors='pt').to(model.device)
        calib_dataset.append([inputs.data['input_ids'], inputs.data['attention_mask']])
    return calib_dataset

dataset_calib = get_calib_dataset(tokenizer, calib_list, model)

# W8A8量化配置
quant_config = QuantConfig(
    a_bit=8,                    # 激活值量化位宽
    w_bit=8,                    # 权重量化位宽
    disable_names=[             # 回退到浮点的层
        'transformer.encoder.layers.0.self_attention.query_key_value',
        'transformer.encoder.layers.0.self_attention.dense'
    ],
    dev_id=model.device.index,
    dev_type='npu',
    act_method=3,               # 激活值量化方法: 1=min-max, 2=histogram, 3=自动混合
    pr=0.5,
    mm_tensor=False
)

# 执行量化校准
calibrator = Calibrator(model, quant_config, calib_data=dataset_calib, disable_level='L0')
calibrator.run()

# 保存量化权重 (safetensors格式用于MindIE部署)
calibrator.save('./quant_weight', save_type=['numpy', 'safe_tensor'])
print('量化完成！')
```

---

## W8A16/W4A16量化配置

仅权重量化方案，适用于显存受限场景。

```python
from msmodelslim.pytorch.llm_ptq.llm_ptq_tools import Calibrator, QuantConfig

# W8A16量化配置
quant_config_w8a16 = QuantConfig(
    w_bit=8,                    # 权重8bit量化
    a_bit=16,                   # 激活值保持16bit
    disable_names=[],
    dev_id=model.device.index,
    dev_type='npu',
    w_sym=False,                # 非对称量化
    mm_tensor=False
)

# W4A16量化配置 (更激进的压缩)
quant_config_w4a16 = QuantConfig(
    w_bit=4,                    # 权重4bit量化
    a_bit=16,                   # 激活值保持16bit
    disable_names=[],
    dev_id=model.device.index,
    dev_type='npu',
    w_sym=False,
    mm_tensor=False
)

# 执行量化
calibrator = Calibrator(model, quant_config_w8a16, calib_data=dataset_calib, disable_level='L0')
calibrator.run()
calibrator.save('./quant_weight_w8a16', save_type=['safe_tensor'])
```

---

## 模型拓扑可视化

将ATB模型拓扑信息转换为ONNX格式进行可视化。

```python
from msit_llm.common.json_fitter import atb_json_to_onnx

# 读取dump出来的layer拓扑信息
layer_topo_info = "./msit_dump/model/xxx_layer.json"

# 转换为onnx格式 (可用Netron等工具打开查看)
model_level = 1  # 可视化深度，1表示只显示顶层节点
atb_json_to_onnx(layer_topo_info, model_level, {})

# 生成完整深度的可视化模型
atb_json_to_onnx(layer_topo_info, None, {})  # model_level=None表示最大深度
```

---

## 设置日志级别

配置msModelSlim和msit工具的日志输出级别。

```python
from msmodelslim import set_logger_level

# 设置日志级别: notset, debug, info, warn, warning, error, fatal, critical
set_logger_level("info")

# 查看详细调试信息
set_logger_level("debug")

# 仅显示错误和严重问题
set_logger_level("error")
```

---

## 总结

msIT工具链覆盖了AI模型从开发到部署的完整推理优化流程。通过benchmark组件可以快速评估模型在昇腾设备上的性能表现；debug compare和llm compare组件提供从传统小模型到大语言模型的全场景精度比对能力；convert组件支持多框架模型到昇腾OM格式的无缝转换；profile组件则提供深入的性能分析和瓶颈定位功能。

对于大模型应用场景，msIT的llm组件提供了完整的精度调试工具链，包括数据dump、自动比对、单算子预检等功能，配合msModelSlim的量化压缩能力，开发者可以在保持模型精度的前提下显著降低模型体积和推理延迟。整体工具链采用统一的命令行接口设计（msit <task> <sub_task>），支持CLI和Python API两种使用方式，适合集成到自动化CI/CD流程中，实现模型迁移和部署的标准化与自动化。