流程编排

业务流程实现介绍

通过pipeline配置文件，Stream manager可识别需要构建的Element以及Element之间的连接关系，并启动业务流程。Stream manager对外提供接口，用于向Stream发送数据和获取结果，帮助用户实现业务对接。

Plugin表示业务流程中的基础模块，通过Element的串接构建成一个Stream。Buffer用于内部挂载解码前后的视频、图像数据，是Element之间传递的数据结构，同时也允许用户挂载元数据（Metadata），用于存放结构化数据（如目标检测结果）或过程数据（如缩放后的图像）。

图1 mxVision业务流程相关基础单元

表1 基础概念介绍
名称	类名称	说明	描述
Stream	MxStream	业务流	完整的推理业务流，由插件串流组成。
Stream manager	MxStreamManager	业务流管理模块	负责创建和销毁Stream，同时提供向其发送数据和获取结果的接口。
Plugin	MxPlugin	功能插件	业务流程中的功能模块，构成业务流的基础单元。
Element	无	功能元件	由插件so实例化生成的对象，同一个插件so可以实例化多个对象，如图1中两个图像缩放元件。
Plugin Buffer	MxpiBuffer	插件缓存	插件之间传递的数据，其内容为非结构化数据，例如解码前后的视频、图像数据。
Plugin Metadata	MxpiMetadata	插件元数据	插件生成的结构化数据，例如分类信息、目标信息。元数据依附在插件缓存上实现传递。

数据流程介绍

为了方便用户理解数据结构在插件间传递的过程，下面以一张图片作为输入，结合代码详细阐述这一数据传递过程。

图2 数据结构传递流程图

新建一个存储输入图片的MxstDataInput变量，通过ReadFile函数读取图片数据到dataBuffer变量。
```
MxStream::MxstDataInput dataBuffer;
APP_ERROR ret = ReadFile("./test.jpg", dataBuffer);
```

新建一个流管理的MxStreamManager对象并初始化，然后加载pipeline文件。

MxStreamManager *mxStreamManager = new MxStream::MxStreamManager();
ret = mxStreamManager->InitManager();
string streamsConfig = "detection.pipeline"; //detection.pipeline文件中可以有一个或多个业务流
APP_ERROR ret = mxStreamManager->CreateMultipleStreams(streamsConfig); //统一按照处理多个业务流的方式处理

通过SendData函数传递输入数据到“图片获取”模块。

ret = mxStreamManager->SendData(streamName, inPluginId, dataBuffer); //streamName是pipeline文件中业务流的名称；inPluginId为输入端口编号，对应输入元件的编号

在各个插件的Process函数中处理数据流程。

接受上一个插件的buffer数据及挂载在buffer上的metadata数据。

MxpiFrame inputMxpiFrame = GetHostDataInfo(*mxpiBuffer); //若数据在Device侧，则调用GetDeviceDataInfo函数
MxpiMetadataManager mxpiMetadataManager(*mxpiBuffer); //新建一个Metadata管理器对象
shared_ptr<void> metadata = mxpiMetadataManager.GetMetadata("keyName"); //根据key名称拿到挂载在buffer上的metadata数据，keyName通常为上一个插件的插件名

业务逻辑处理。

DataProcess(inputMxpiFrame, metadata, outputMetadata); //插件内部实现的数据处理功能，如：解码，缩放，推理等
mxpiMetadataManager.AddMetadata("pluginName", outputMetadata); //挂载outputMetadata数据到buffer上，keyName通常为当前插件的插件名pluginName

发送buffer数据到下一个插件。

SendData(inPlugin, *mxpiBuffer); //调用MxPluginBase的SendData方法将数据发送到下一个插件

通过GetResult函数获取最后一个插件的输出结果。

MxStream::MxstDataOutput* output = mxStreamManager->GetResult(streamName, outPluginId); //outPluginId为输出端口编号，对应输出元件的编号。

pipeline配置文件介绍

图3、图4为推理业务流pipeline配置文件样例，包括业务流名称、Stream配置、元件名称、插件名称、元件属性、下游元件名称。

图3 pipeline配置文件样例

图4 pipeline配置文件带nextMeta样例

配置文件以JSON格式编写，用户必须指定业务流名称、元件名称和插件名称，并根据需要，补充元件属性和下游元件名称信息，否则创建流会失败、产生错误，具体参见表2。

表2 pipeline配置文件说明
名称	是否必选	描述
业务流名称（Stream）	必选	用于指定需要操作的Stream实体。例如Stream manager发送数据时，需要指定Stream名称。
Stream配置（Stream_config）	必选	设置Stream的配置参数。例如Device ID，即指定Stream运行在哪个设备上。
元件名称（Element）	必选	用于构建Stream中的插件实体，即插件的对象。与“下游元件名称”配合使用，用于定义元件间的连接关系。建议以插件基类名+序号命名，且保证Stream内名称唯一。
插件名称（Factory）	必选	用于构建元件。可通过插件参考中获取。
元件属性（Props）	可选	用于根据业务特点修改相应的配置参数。例如图像缩放插件中，指定输出图像的宽高。具体请参见插件参考，每个属性都有默认值。
下游元件名称（Next）	必选（除Stream中最后的元件）	用于根据具体业务，确定下游元件的功能。本插件产生的数据将传递给下游元件。若存在多个下游插件时，用逗号分隔，冒号后面添加端口号，用中括号包含在一起。
下游元数据接收元件名称（nextMeta）	可选	主要针对多输入端口的插件进行设置，确定下游元数据接收元件的功能。本插件产生的元数据将传递给下游元件，若存在多个下游插件时，用逗号分隔，用中括号包含在一起，可在冒号后面添加端口号用于指定相同下游元件时的输入顺序，若不添加端口号将以默认顺序输入。

其中，公共属性可直接在“props”属性内配置参数，具体配置说明请参见表3。

表3 插件公共属性配置说明
名称	是否必选	描述
dataSource	可选（建议使用上游的nextMeta属性进行替换。）	插件process函数处理的数据来源，Stream上游的mxVision插件，不支持Gstreamer原生插件。 string类型，默认为“auto”。该值由一个或多个上游插件的nextMeta属性所指定。若上游插件未设置nextMeta到该插件时，该插件输入以该插件的dataSource属性为准，反之以nextMeta为准。
status	可选	指定插件为同步或异步执行。int类型，取值范围[0, 1]，0为异步，1为同步，默认为0（异步执行），请用户谨慎设置。
deviceId	可选	指定插件运行的Device侧设备ID。int类型，默认为0。目前单个Stream只支持在一个Device上运行，请通过“Stream_config”指定“deviceId”。

不论属性值的数据类型是否为字符串，属性值都以字符串方式填写。例如"resizeWidth": "2048"，而非"resizeWidth": 2048。

多输入/输出插件的流程编排

当元件包含多个输出端口时，在“next”对应的value（值）中通过“[]”指定的多个元件，通过“,”区分，如图5所示。

图5 多输出元件流程编排样例

“[]”中指定的元件序号与当前元件的输出端口一一对应，即“[]”中第一个元件与当前元件的第0号端口关联，第二个元件与当前的第1号端口关联，以此类推。

批量设置deviceId

pipeline配置文件中添加“stream_config”字段对应的“deviceId”属性，默认为0，实现批量设置插件的Device ID，如图6所示。

每个Stream需要单独配置“stream_config”。

图6 批量设置Device ID

代码流程编排介绍

代码流程编排指通过类似深度学习框架构图的方式来创建Stream，避免编写复杂的pipeline文件，从而达到快速、高效实现流程编排的目的。关键功能参加如表4，编写样例请参见图7。

表4 功能说明
名称	类名称	说明	描述
PluginNode	PluginNode	插件节点	用于定义插件，包括插件名、类型、属性等。
Stream	Stream	业务流	完整的推理业务流，由插件串流组成。
Sequential Stream	SequentialStream	顺序式业务流	该业务流主要处理顺序式的业务，即插件之间关系只有前后的顺序关系。
Functional Stream	FunctionalStream	函数式业务流	该业务流可处理复杂的如多输入多输出的流程关系。

图7 代码流程编排使用样例图

代码流程编排的使用主要分为四个步骤：

属性配置。根据插件需要配置单独的属性，可选。
创建业务流，并设置芯片。业务流用于后续插件的拼接以及数据处理。
创建插件节点，并构造推理流图。
数据处理。创建输入对象后，通过Stream的SendData、GetResult接口来传入数据和获取结果。

父主题： 使用流程编排方式开发