# SOLA Demo 示例包

## 概述

SOLA Demo 示例包提供 SOLA Runtime API 基础示例、设备与模型工具、通用推理框架、BERT 和 ResNet50 模型部署示例，以及多媒体处理示例。

各类示例的目录和适用场景如下：

| 类型 | 目录 | 适用场景 |
| ---- | ---- | ---------- |
| Runtime API 基础示例 | `introduction` | 学习流、事件、内存拷贝、回调和基础推理流程 |
| 设备与模型工具 | `utils` | 查询设备信息、解析模型，以及测试 PCIe 带宽和内存拷贝延迟 |
| 通用推理框架 | `inference` | 通过配置文件运行单模型推理、性能测试和精度测试 |
| BERT 模型部署 | `models/bert` | 运行 BERT-Base 和 BERT-Large 推理并验证结果 |
| ResNet50 模型部署 | `models/resnet50` | 运行 ResNet50 图像分类并验证结果 |
| 多媒体处理 | `multimedia` | 运行视频解码、JPEG 解码、图像裁剪和缩放程序 |

### 多媒体硬件加速器

墨芯首代 Antoum 芯片集成了多媒体硬件加速器套件，包括：

- 4 个视频解码器引擎，支持 H.264、H.265 等编码格式，支持以高达 60 FPS 的速度解码 32 路 1080p 视频。
- 1 个视频编码器引擎。
- 4 个 JPEG 编解码器引擎，支持以高达 435 FPS 的速度解码 4 路 1080p 图像。
- 4 个图像处理引擎，支持多路图像的裁剪与缩放。

当前示例包提供以下多媒体处理示例，不提供视频编码示例：

| 类型          | 示例程序     | 说明                                  |
| ------------- | ------------ | ------------------------------------- |
| JPEG 图片解码 | `AppJpegDec` | 将 JPEG 格式图片解码为 NV12 格式      |
| 视频解码      | `AppDec`     | 使用 MOFFETT Video Codec SDK 解码视频 |
| 视频解码      | `ffmpegDec`  | 使用 FFmpeg 解码视频                  |
| 视频解码      | `decode.py`  | 使用 OpenCV Python 接口解码视频       |
| 图像处理      | `AppPpb`     | 图片缩放和裁剪                        |

`AppDec`、`ffmpegDec` 和 `decode.py` 支持视频文件及 HTTP、RTMP 和 RTSP 在线视频流，支持最高 3840×2160 的输入分辨率，并可通过 `frame_stride` 设置抽帧间隔。视频封装格式的支持范围取决于底层组件的解封装能力；参数范围和配置方式详见 SOLA Demo 包内 `multimedia/AppDecode/README.md`。

多媒体示例默认保存处理结果。仅进行性能或稳定性测试时，可将 `save_file` 设置为 `0`；需要保存结果时，请根据输入视频时长、视频路数和抽帧间隔为输出目录预留空间。

## 准备运行环境

- 安装 SOLA Toolkit，详见{ref}`《SOLA Toolkit 安装指南》 <install-sola-toolkit>`。
- 安装 `wget`、`tar`、CMake 3.13 或更高版本、支持 C++17 的 GCC 7.x 或更高版本，以及 OpenGL 运行库。也可在解压后执行 `sudo sh install_dependencies.sh` 尝试安装基础依赖。
- 获取 SOLA Demo 包并解压缩。

  ```bash
  wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.14/sola-demo/sola-demo-3.18.0.tar.gz
  tar -zxvf sola-demo-3.18.0.tar.gz
  ```

- 将当前 Shell 的语言环境设置为英文，设置方式详见包内 `README.md`。
- 运行 BERT 模型示例前，安装 <a href="https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html" target="_blank">Anaconda 或 Miniconda</a>，并按 `models/bert/README.md` 创建 Python 3.10 环境。
- 运行多媒体示例前，按 `multimedia/README.md` 安装和配置 FFmpeg 与 OpenCV。

模型和数据集默认下载到 `~/sola_demo_downloads`，并解压到 `~/sola_demo_assets`。ResNet50 BF16 预处理数据约为 8.3 GB；如需使用该数据，还需为下载包、其他模型数据和运行输出预留额外空间。

## 编译并运行示例

根目录、模型目录和多媒体目录使用独立的构建流程，根据示例类型在对应目录中执行命令。

| 示例类型 | 工作目录 | 构建方式 | 运行和验证 |
| ---------- | -------- | -------- | ------------ |
| Runtime API 基础示例、设备与模型工具、通用推理框架 | SOLA Demo 根目录 | 执行 `./build.sh` | 编译产物位于 `build/bin`，运行方式详见 `introduction/README.md`、`utils/README.md` 和 `inference/README.md` |
| BERT 模型 | `models/bert` | 执行 `./prepare.sh` 准备模型和数据，再执行 `./build.sh` | 执行 `./run.sh` 运行推理，执行 `./verify.sh` 验证结果 |
| ResNet50 模型 | `models/resnet50` | 执行 `./prepare.sh` 准备模型和数据，再执行 `./build.sh` | 执行 `./run.sh` 运行推理，执行 `./verify.sh` 验证结果 |
| 多媒体处理 | `multimedia` | 按 `multimedia/README.md` 安装依赖后执行 `./build.sh` | 编译产物位于 `multimedia/build`，运行方式详见各子目录中的 `README.md` |