跳转至

开始使用

安装 SaigeVision 运行时 C/C++ SDK，以便在 Visual Studio 项目中使用，或尝试运行示例项目。

最低和推荐系统要求

项目 最低需求* 推荐配置
OS Windows 10 64bit or Ubuntu 20.04, 22.04
CPU Intel Core i7
RAM 16GB 32GB
GPU GeForce RTX 2060 6GB GeForce RTX 3090 24GB

* "Minimum Requirements" 的意思是 SaigeResearch 已通过自身实验确认，可以在此环境中成功执行检测。根据使用的模型和数据，以及同时运行的其他任务，它可能在更低的规格下运行，或者在更高的规格下无法运行。

先决条件

  • SaigeVision Installer
  • NVIDIA Windows Driver 471.96 (*reference)
  • SaigeVision 授权加密狗
  • Windows
    • (Example execution) Visual Studio 2017 or later, Windows 10 SDK
  • Linux
    • gcc, g++ 9.4.0 or later
    • (Example build) CMake 3.28 or later

Windows

安装文件列表

项目 位置
动态库
- SaigeVision.dll
- SaigeVision_Impl.dll
可执行文件
- ErrorMsg.exe
- Examples.exe
- SaigeVisionDoctor.exe
- SaigeVisionPrompt		 {安装路径}\SaigeVision\engine\bin
静态库
- SaigeVision.lib		 {安装路径}\SaigeVision\engine\lib
C/C++ 头文件
- SaigeVisionAPI.h
- SaigeVisionUtil.h
- saige_error.h
- SaigeVisionAPI_V1.h		 {安装路径}\SaigeVision\engine\include
Python 环境 {安装路径}\SaigeVision\python
Python 模块 {安装路径}\SaigeVision\module
配置文件
- log4cxx.xml
- runtime.conf		 {安装路径}\SaigeVision\conf
示例项目 {安装路径}\SaigeVision\engine\Examples
OpenCV 等 {安装路径}\SaigeVision\engine\third_party

Note

从版本 2.8.0 开始，OpenCV 等第三方库文件夹被排除在外。

可执行文件

  • ErrorMsg.exe - 一个命令行程序，允许您通过输入错误代码来检查错误消息。
  • Examples.exe - 从示例项目构建的可执行文件。您可以直接运行示例程序，而无需自行构建。
  • SaigeVisionDoctor.exe - 一个命令行程序，用于验证 SAIGE VISION 和运行时 SDK 是否已正确安装。
  • SaigeVisionPrompt - 一个工程师的命令行处理器，用于在 SAIGE VISION 环境中执行各种命令。

配置文件

  • log4cxx.xml - 日志配置文件，位于 {安装路径}\SaigeVision\engine\logs 目录中。
  • runtime.conf - 用于连接 SAIGE VISION 企业版中央服务器的配置文件。


在 Visual Studio 项目中使用 SaigeVision 运行时 C/C++ SDK

Visual Studio 项目配置

要在您的 Visual Studio 项目中使用 SaigeVision 运行时 C/C++ SDK，请按照以下步骤操作，前提是安装过程已成功完成，并且已正确设置了 SAIGE_HOME 环境变量。

  1. 将目标平台设置为 x64。

  2. 将两个 DLL 文件 SaigeVision.dll 和 SaigeVision_Impl.dll 复制到应用程序的可执行文件路径，或者将包含这些 DLL 文件的文件夹路径添加到系统环境变量 PATH 中。

    如果您仅通过 Visual Studio 运行应用程序，您也可以按以下方式进行设置：

​ 前往项目属性，在 调试 → 环境 下添加 PATH=$(SAIGE_HOME)\SaigeVision\engine\bin;%PATH%。

    <p align="center"><img src="../assets/getting_started/vs_setting_1.png"></p>
  1. 在 C/C++ → 常规 → 附加包含目录 下，添加 $(SAIGE_HOME)\SaigeVision\engine\include。

  2. 在 链接器 → 常规 → 附加库目录 下，添加 $(SAIGE_HOME)\SaigeVision\engine\lib。

  3. 在 链接器 → 输入 → 附加依赖项 下，添加 SaigeVision.lib;。

头文件

项目设置完成后，您可以包含 SaigeVision 头文件以使用 SaigeVision API。

  • SaigeVisionAPI.h 定义了 SaigeVision 推理功能的核心函数、常量、结构和标志。要使用 SaigeVision 的推理功能，该文件是必需的。

  • SaigeVisionUtil.h 包含运行示例代码所需的实用函数，例如处理图像数据和可视化推理结果。虽然是可选的，但这些实用函数便于使用 SaigeVision 进行测试。


构建和运行示例

Visual Studio 项目配置 部分中提供的所有指南已在示例项目中应用。如果您已成功完成 安装 过程，可以按照以下说明构建和运行 SaigeVision 示例。

构建

启动位于 {安装路径}\SaigeVision\engine\Examples\VS2017\Examples.vcxproj 的 Visual Studio 项目文件。

Warning

当您第一次打开项目时，Visual Studio 可能会在解决方案检查中提示进行 SDK 升级建议，这取决于您的 Visual Studio 版本。在这种情况下，选择 不升级。


将构建目标设置如下：

  • 配置：Debug 或 Release
  • 平台：x64

Note

如果找不到包含目录，请尝试运行 生成 → 清理解决方案。


如果构建成功，可执行文件 Example.exe 将在路径 VS2017\x64\{Debug 或 Release} 中创建。

运行示例

有两种方法可以运行已构建的示例：

  • 在 Visual Studio 中通过选择 开始调试（快捷键 F5）或 开始执行（不调试）（快捷键 Ctrl + F5）来运行示例应用程序。

  • 通过终端（cmd 或 PowerShell）运行 Example.exe。

    Warning

    在终端中运行时，确保从 VS2017 路径执行，以避免相对路径问题。

    例如，如果安装路径是 C:\Saige，您应在终端中按以下方式运行：

    PS C:\Saige\SaigeVision\engine\Examples\VS2017> .\x64\Release\Example.exe

当您运行示例项目时，可以选择所需的示例来执行推理任务。


安装

使用 SaigeVision 安装程序安装 SaigeVision，并参考提供的安装指南以获取详细说明。

SAIGE_HOME 环境变量

运行 SaigeVision 安装程序时，系统会提示您指定安装路径。安装完成后，此路径将自动设置为环境变量 SAIGE_HOME。

安装选项

在 SaigeVision 安装过程中，运行时 SDK 将始终安装，而开发者选项是可选的。根据您的需求，您可以仅安装运行时 SDK，或同时安装运行时 SDK 和开发者选项。


通过 SaigeVision 安装程序安装的运行时 SDK 组件如下所示。

Linux

安装

将 SDK 压缩包解压到您希望的位置。

示例： 

tar -xzf SaigeVision_Release_Linux_x64_2.8.0.tar.gz -C ${installation_path}

安装文件列表

项目 位置
动态库
- libSaigeVision_Impl.so		 {installation_path}\SaigeVision\engine\bin
C/C++ 头文件
- SaigeVisionAPI.h
- SaigeVisionUtil.h		 {installation_path}\SaigeVision\engine\include
Python 环境 {installation_path}\SaigeVision\python
Python 模块 {installation_path}\SaigeVision\module
示例项目 {installation_path}\SaigeVision\engine\Examples

构建和运行示例

在 Linux 上使用 SaigeVision SDK 运行程序之前，请始终执行 setenv.sh。

source {installation_path}/SaigeVision/setenv.sh
!!! note setenv.sh 设置的环境变量如下： | 环境变量 | 描述 | | --- | --- | | SAIGE_HOME | SaigeVision SDK 的安装路径 | | SVSDK_LOG_CONF | 示例中使用的默认日志配置文件路径 | | PYTHONPATH | Python 模块的位置 | | PYTHONHOME | Python 的路径 | | LD_LIBRARY_PATH | 运行 SDK 所需的附加库路径 |


构建

要使用 SaigeVision SDK，请链接提供的 SDK 库和 Python 库。要在 Linux 上构建示例，请使用 CMake 构建系统。以下是使用 CMake 链接 SDK 提供的库的方法：

find_library(SAIGE_VISION libSaigeVision_Impl.so PATH $ENV{SAIGE_HOME}/SaigeVision/engine/bin)
find_library(PYTHON_LIBS libpython3.8.so PATH $ENV{SAIGE_HOME}/SaigeVision/python)
有关详细信息，请参考 SaigeVision/engine/Examples/CMakeLists.txt。

提供了一个脚本可直接构建示例。运行 SaigeVision/engine/Examples/build.sh。 该脚本将在子文件夹中创建一个构建目录，并在该目录中生成示例二进制文件。

运行示例

要运行示例，请将所需的测试类型（det、cls、seg、iad、ien 或 ocr）指定为第一个参数。

${SAIGE_HOME}/SaigeVision/engine/Examples/build/Examples iad


示例代码指南

您可以在 'Examples' 项目的源文件中查看所有示例代码。可以随意修改代码，以根据需要使用 SaigeVision 推理功能。每个示例都在注释中包含基本的使用说明，这可能对您有所帮助。

除了 'SaigeVisionAPI.h' 和 'SaigeVisionUtil.h'，示例代码还包括各种 C/C++ 标准库。示例中使用的 C++ 版本为 C++17。

有关使用 SaigeVision 推理功能的详细指南，请参考 开发者指南 和 API 参考。

调整详细级别

增加 'verbosity' 变量将为控制台输出添加更多信息，并启用检测结果的可视化。

  • 0：显示使用推理 API 所用时间（毫秒）。
  • 1：输出模型信息和推理选项。
  • 2：输出每个图像路径和可读的推理结果。
  • 3：激活其他推理选项并显示相应的结果。
  • 4：使用 OpenCV 显示可视化的推理结果。

错误处理方法

几乎所有 SaigeVision API 都返回整数类型的错误代码。值为 0 或更高表示成功，而负值表示错误。

当将错误代码传递给 'SaigeStrError' 函数时，它返回一个描述该代码对应错误的 C 字符串（'char*'）。

在示例代码中，错误处理方法根据具体情况有所不同。每个 API 函数的错误处理方法如下：

API 处理方法
SaigeCreateInferenceHandle
SaigeCreateInferenceResult
SaigeGetInferenceOption
SaigeSetInferenceOption
SaigeDestroyInferenceHandle
SaigeDestroyInferenceResult		 如果创建了句柄，则销毁它并终止应用程序。
SaigeGetModelInfo 将错误消息打印到控制台。由于推理过程可以继续，因此继续执行。
SaigeGetImageData
SaigeInferFromByteArrray
SaigeInferFromMultipleByteArray		 跳过当前图像并在循环中继续下一个推理（在 'for' 循环中使用 'continue'）。
SaigeGetInferenceResult{result_name} 销毁句柄并终止应用程序。

示例）当 SaigeSetInferenceOption 中发生错误时

retval = SaigeSetInferenceOption(handle, &options, flags);
if (retval < 0) {
    std::cerr << "SaigeSetInferenceOption() failed - " << SaigeStrError(retval) << std::endl;
    SaigeDestroyInferenceHandle(handle);
    SaigeDestroyInferenceResult(result);
    return retval;
}
在此情况下，设置推理选项的 API 调用失败。

首先，它将错误发生的位置和错误消息输出到标准错误（stderr）。

由于在推理选项设置失败后继续执行会变得困难，因此销毁推理句柄和结果句柄，并使用 'return retval' 异常终止应用程序。

重要注意事项

  • 为防止内存泄漏，请使用 'SaigeFreeImageData()' 释放由实用函数 'SaigeGetImageData()' 加载的图像数据。
  • 在示例中，读取包含韩文字符的图像路径的代码设置为仅识别 UTF-8 Unicode。如果在使用 'SaigeGetImageData()' 时由于韩文路径出现问题，请按以下步骤操作并重新运行示例：
    1. 打开“设置”应用，进入“时间和语言”菜单。
    2. 选择“语言”并点击“更改系统区域设置”下的“管理语言设置”。
    3. 勾选“测试版：使用 Unicode UTF-8 提供全球语言支持”复选框，然后点击“确定”。

    4. 按提示重新启动系统。
  • 对于不正确的图像路径，错误处理有限，程序可能会在没有特定消息的情况下终止。计划在未来更新中通过 C++17 文件系统支持改进此问题。

（重要）推荐的 NVIDIA 驱动程序版本和设置

由于 NVIDIA 显卡驱动程序可能存在潜在的错误或副作用，推理时间可能会异常延长。我们建议遵循以下指南：

  • NVIDIA GeForce RTX 30 系列及以下：驱动程序版本：471.96 链接
  • NVIDIA GeForce RTX 40 系列及以上：驱动程序版本 515.15 或更高（或最新版本）
  • NVIDIA 控制面板设置
    • 低延迟模式：开启
    • 电源管理模式：优先最大性能