高性能 SDK 套件 - C# 接口

软件预览

C# 测试程序用于查看模型信息、执行单次或批量推理、输出 JSON，并进行多线程性能测试与一致性测试。

国内：https://gitee.com/dl-cv/OpenIVS
国外：https://github.com/dl-cv/OpenIVS

下图为当前 C# 测试程序加载手机屏幕实例分割模型后的真实推理结果。

引用文件

安装高性能 SDK 套件后，C# 项目引用：

C:\dlcv\Lib\site-packages\dlcvpro_infer_csharp\DlcvCsharpApi.dll

DlcvCsharpApi.dll 会读取模型授权类型并选择匹配的原生推理库；模型没有记录授权类型时，再根据当前授权设备自动选择。C# 项目只需要引用托管接口程序集。

OpenIVS 的 DlcvDemo 工程使用 .NET Framework 4.7.2、x64 和 OpenCvSharp 4.10，可作为引用方式与调用代码的参考。

常用接口

namespace dlcv_infer_csharp
{
    public class Model : IDisposable
    {
        public static bool EnableConsoleLog { get; set; }

        public Model();
        public Model(
            string modelPath,
            int device_id,
            bool rpc_mode = false,
            bool enableCache = false);

        public JObject GetModelInfo();
        public JObject GetCachedModelInfo();
        public JArray GetCachedMaxShape();
        public int GetMaxBatchSize();

        public Utils.CSharpResult Infer(Mat image, JObject params_json = null);
        public Utils.CSharpResult InferBatch(List<Mat> image_list, JObject params_json = null);
        public dynamic InferOneOutJson(Mat image, JObject params_json = null);

        public void FreeModel();
        public void Dispose();

        public bool IsDvpMode { get; }
        public static void ClearModelCache();
    }

    public static class ModelFactory
    {
        public static Model CreateFromIndex(int index);
    }

    public partial class Utils
    {
        public static void FreeAllModels();
        public static JObject GetDeviceInfo();
        public static JObject GetGpuInfo();
        public static Utils.CSharpResult OcrInfer(
            Model detectModel,
            Model recognizeModel,
            Mat image);
        public static List<Mat> VisualizeResults(
            List<Mat> images,
            Utils.CSharpResult result,
            Dictionary<string, object> properties = null);
    }
}

ModelFactory.CreateFromIndex 用于绑定已经登记的普通模型或流程模型索引。常规模型文件加载直接使用 new Model(...)。

加载模型

using dlcv_infer_csharp;

using (var model = new Model(modelPath, deviceId, rpc_mode: false, enableCache: false))
{
    JObject modelInfo = model.GetModelInfo();
}

参数说明：

参数	说明
`modelPath`	模型文件路径
`device_id`	`-2` 表示 OpenVINO，`-1` 表示 CPU，非负整数表示 GPU 编号
`rpc_mode`	对非 DVP、非 DVS 模型启用本地 RPC 进程调用
`enableCache`	按完整模型路径、设备和推理模式复用已加载的模型索引；DVS 流程模型会关闭此缓存

构造函数在模型加载成功后缓存模型信息与最大批量大小，并执行一次预热。加载失败时会抛出异常。

文件类型与调用方式

文件类型	调用方式
`.dvp`	通过本地 HTTP 后端加载和推理；服务不可用时会尝试启动后端并等待就绪
`.dvst`、`.dvso`	作为 DVS 流程模型加载，由流程执行器调用内部模型与处理模块
`.dvt`、`.dvo`	默认通过当前授权环境对应的原生推理 DLL 调用；勾选 RPC 模式后改用本地 `AIModelRPC.exe`
`.dvsp`	当前 `Model` 不支持直接加载，需要先生成 `.dvst` 或 `.dvso` 文件

DVP 和 DVS 的判断优先于 rpc_mode，因此 RPC 参数不会改变 .dvp、.dvst、.dvso 的调用方式。

获取模型信息与批量上限

JObject modelInfo = model.GetModelInfo();
int maxBatchSize = model.GetMaxBatchSize();

GetModelInfo() 根据当前模式从 HTTP 后端、DVS 流程对象、RPC 服务或原生 DLL 读取模型信息。返回字段由模型类型决定，常见内容包括任务类型、输入通道、类别数量、类别列表和类别映射。

GetCachedModelInfo()、GetCachedMaxShape() 返回加载阶段缓存信息的副本。GetMaxBatchSize() 至少返回 1，批量推理数量不应超过模型支持的最大值。

图像输入

Model 接收 OpenCvSharp 的 Mat，三通道输入使用 RGB 顺序。Cv2.ImRead 默认得到 BGR 图像，需要先转换：

using (Mat source = Cv2.ImRead(imagePath, ImreadModes.Unchanged))
using (var rgb = new Mat())
{
    Cv2.CvtColor(source, rgb, ColorConversionCodes.BGR2RGB);
    Utils.CSharpResult result = model.Infer(rgb);
}

四通道图像可使用 ColorConversionCodes.BGRA2RGB，灰度图保持原通道。相机已经输出 RGB 时可直接传入。

推理参数

var inferParams = new JObject
{
    ["threshold"] = 0.5f,
    ["with_mask"] = true,
    ["calc_mean"] = false
};

Utils.CSharpResult oneResult = model.Infer(rgb, inferParams);
Utils.CSharpResult batchResult = model.InferBatch(imageList, inferParams);
dynamic jsonResult = model.InferOneOutJson(rgb, inferParams);

Infer：单张图像，返回结构化结果。
InferBatch：多张图像，返回顺序与输入列表一致。
InferOneOutJson：单张图像，返回适合序列化的 JSON；mask 会转换为点集或空对象。
threshold：结果筛选阈值。
with_mask：控制是否返回 mask。
calc_mean：显式控制前景与背景均值计算；省略时使用模型默认设置。

结构化结果

public partial class Utils
{
    public struct CSharpObjectResult
    {
        public int CategoryId { get; set; }
        public string CategoryName { get; set; }
        public float Score { get; set; }
        public float Area { get; set; }

        public bool WithBbox { get; set; }
        public List<double> Bbox { get; set; }
        public bool WithMask { get; set; }
        public Mat Mask { get; set; }
        public JObject ExtraInfo { get; set; }

        public bool WithAngle { get; set; }
        public float Angle { get; set; }
        public bool WithMean { get; set; }
        public double ForegroundMean { get; set; }
        public double BackgroundMean { get; set; }
    }

    public struct CSharpSampleResult
    {
        public List<CSharpObjectResult> Results { get; set; }
        public bool? Ok { get; set; }
        public string Reason { get; set; }
    }

    public struct CSharpResult
    {
        public List<CSharpSampleResult> SampleResults { get; set; }
    }
}

CSharpResult.SampleResults：批量中的每张图像对应一个结果。
CSharpSampleResult.Results：当前图像中的对象列表。
CSharpSampleResult.Ok、Reason：流程模型的判定状态与原因；未配置判定模块时为 null。
普通检测框的 Bbox 为 [x, y, w, h]；旋转框的 Bbox 为 [cx, cy, w, h]，角度保存在 Angle，单位为弧度。
Mask 为 OpenCV 矩阵，非目标像素为 0，目标像素为 255。
折线等扩展信息保存在 ExtraInfo。

设备信息

JObject gpuInfo = Utils.GetGpuInfo();
JObject deviceInfo = Utils.GetDeviceInfo();

GetGpuInfo() 直接通过 NVML 枚举 NVIDIA GPU，不依赖推理 DLL 的设备信息导出函数。GetDeviceInfo() 使用当前已加载的推理 DLL，优先调用 dlcv_get_device_info，不可用时调用 dlcv_get_gpu_info。

释放资源

优先使用 using 或显式 Dispose() 释放单个模型：

var model = new Model(modelPath, deviceId);
try
{
    // 推理
}
finally
{
    model.Dispose();
}

Utils.FreeAllModels() 会遍历当前进程中已经加载的推理 DLL，释放全部模型，并清理 C# API 与流程模块的模型缓存。调用后不能继续使用原模型实例。

软件预览​

引用文件​

常用接口​

加载模型​

文件类型与调用方式​

获取模型信息与批量上限​

图像输入​

推理参数​

结构化结果​

设备信息​

释放资源​