Update README.md

README.md

@@ -1,3 +1,125 @@
----
-license: mit
----
+---
+license: mit
+language:
+- en
+tags:
+- ONNX
+- ONNXRUNTIME
+- AXEngine
+---
+
+## 简介
+
+**PyAXEngine** 基于 cffi 模块实现了 Axera NPU Runtime 的 Python API，其 Python API 与 ONNXRuntime 高度兼(相)容(似)，并同时支持开发板和M.2算力卡形态，方便开源社区开发者使用
+Python 脚本快速构建 NPU 推理脚本
+
+支持芯片
+
+- AX650N
+- AX630C
+
+环境版本
+
+- python >= 3.8
+- cffi >= 1.0.0
+- ml-dtypes >= 0.1.0
+- numpy >= 1.22.0
+
+*需要注意的是，如果您的开发环境是算力卡，那么更建议您优先考虑使用 [pyAXCL](https://github.com/AXERA-TECH/pyaxcl) 进行项目开发；pyAXCL 项目完整包含了算力卡形态的全部 API，更适合用于正式部署；PyAXEngine 项目更适合算法工程师进行快速原型验证，且用于计算卡环境时，PyAXEngine 不能调用编解码等模块(不是 PyAXEngine 的设计目标)。*
+
+*AX650 SDK 2.18，AX620E SDK 3.12 以前的版本不支持 bf16，llm 模型会有返回 unknown 的 dtype问题，请注意升级*
+
+*如果您评估认为不知道如何升级 SDK，也可以提交 issue 索要下载，不需要更新完整 SDK，只更新 libax_engine.so 即可*
+
+## 快速上手
+
+基于社区开发板 **爱芯派Pro(AX650N)** 进行展示
+
+### 获取 wheel 包并安装
+
+- [下载链接](https://github.com/AXERA-TECH/pyaxengine/releases/latest)
+- 将 `axengine-x.x.x-py3-none-any.whl` 拷贝到开发板上，执行 `pip install axengine-x.x.x-py3-none-any.whl` 安装
+
+### 简单示例
+
+当前示例需要分别依赖 PIL 和 OpenCV，可以用 `pip install pillow opencv-python-headless` 安装。其中 `opencv-python-headless` 是 OpenCV 的 headless 版本，不依赖 GUI(非 headless 的版本需要依赖 OpenGL ES，运行环境中并没有)。
+
+```python
+将 [classification.py](https://github.com/AXERA-TECH/pyaxengine/blob/main/examples/classification.py) 拷贝到开发板上并执行。
+
+```bash
+root@ax650:~/samples# python3 classification.py -m /opt/data/npu/models/mobilenetv2.axmodel -i /opt/data/npu/images/cat.jpg
+[INFO] Available providers:  ['AXCLRTExecutionProvider', 'AxEngineExecutionProvider']
+[INFO] Using provider: AxEngineExecutionProvider
+[INFO] Chip type: ChipType.MC50
+[INFO] VNPU type: VNPUType.DISABLED
+[INFO] Engine version: 2.10.1s
+[INFO] Model type: 0 (single core)
+[INFO] Compiler version: 1.2-patch2 7e6b2b5f
+  ------------------------------------------------------
+  Top 5 Predictions:
+    Class Index: 282, Score: 9.774
+    Class Index: 278, Score: 8.981
+    Class Index: 277, Score: 8.453
+    Class Index: 281, Score: 8.321
+    Class Index: 287, Score: 7.924
+  ------------------------------------------------------
+  min =   0.890 ms   max =   22.417 ms   avg =   1.119 ms
+  ------------------------------------------------------
+```
+
+示例也演示了如何选择计算设备：这意味着既可以在 **AX650/AX630C** 等开发板上运行，也可以在 AX650 M.2 算力卡上运行。
+
+切换计算设备的方式是通过 `-p` 参数指定，如 `-p AxEngineExecutionProvider` 表示使用开发板上的 NPU 进行推理，而 `-p AXCLRTExecutionProvider` 表示使用 M.2 算力卡进行推理。
+注意：在使用 M.2 算力卡进行推理时，需要将算力卡插入宿主机上，并且已经安装驱动，详见： [axcl](https://axcl-docs.readthedocs.io/zh-cn/latest/)。
+
+```bash
+root@ax650:~/samples# python3 classification.py -m /opt/data/npu/models/mobilenetv2.axmodel -i /opt/data/npu/images/cat.jpg -p AXCLRTExecutionProvider
+[INFO] Available providers:  ['AXCLRTExecutionProvider', 'AxEngineExecutionProvider']
+[INFO] Using provider: AXCLRTExecutionProvider
+[INFO] SOC Name: AX650N
+[INFO] VNPU type: VNPUType.DISABLED
+[INFO] Compiler version: 1.2-patch2 7e6b2b5f
+  ------------------------------------------------------
+  Top 5 Predictions:
+    Class Index: 282, Score: 9.774
+    Class Index: 278, Score: 8.981
+    Class Index: 277, Score: 8.453
+    Class Index: 281, Score: 8.321
+    Class Index: 287, Score: 7.924
+  ------------------------------------------------------
+  min =   1.587 ms   max =   12.624 ms   avg =   1.718 ms
+  ------------------------------------------------------
+root@ax650:~/samples# python3 classification.py -m /opt/data/npu/models/mobilenetv2.axmodel -i /opt/data/npu/images/cat.jpg -p AxEngineExecutionProvider
+[INFO] Available providers:  ['AXCLRTExecutionProvider', 'AxEngineExecutionProvider']
+[INFO] Using provider: AxEngineExecutionProvider
+[INFO] Chip type: ChipType.MC50
+[INFO] VNPU type: VNPUType.DISABLED
+[INFO] Engine version: 2.10.1s
+[INFO] Model type: 0 (single core)
+[INFO] Compiler version: 1.2-patch2 7e6b2b5f
+  ------------------------------------------------------
+  Top 5 Predictions:
+    Class Index: 282, Score: 9.774
+    Class Index: 278, Score: 8.981
+    Class Index: 277, Score: 8.453
+    Class Index: 281, Score: 8.321
+    Class Index: 287, Score: 7.924
+  ------------------------------------------------------
+  min =   0.897 ms   max =   22.542 ms   avg =   1.125 ms
+  ------------------------------------------------------
+```
+
+## 社区贡献者
+
+- [zylo117](https://github.com/zylo117): 提供了基于 cffi 的 AXCL Runtime Python API 实现
+- [nnn](https://github.com/nnn112358)，[HongJie Li](https://github.com/techshoww) 和 [Shinichi Tanaka](https://github.com/s1tnk) 报告 cffi 的使用问题，[Shinichi Tanaka](https://github.com/s1tnk) 提供了解决方案
+
+
+## 关联项目
+
+- [ax-samples](https://github.com/AXERA-TECH/ax-samples)
+- [ax-llm](https://github.com/AXERA-TECH/ax-llm)
+- [Pulsar2](https://pulsar2-docs.readthedocs.io/zh-cn/latest/)
+- [AXCL](https://axcl-docs.readthedocs.io/zh-cn/latest/)
+- [pyAXCL](https://github.com/AXERA-TECH/pyaxcl)