在开发环境中引入VisionFlow#

在安装之前，我们先介绍VisionFlow所支持的软件、硬件情况及开发语言。

软件上，VisionFlow支持Windows 10 1903及更高版本的系统，及支持在Ubuntu 22.04系统。考虑到Linux系统众多的发行版本及 复杂的软件依赖情况，我们建议您通过安装了 NVIDIA Runtime 的Docker运行我们的Linux版本的软件，以避免复杂的Linux运行环境配置以及可能由此导致的难以处理的各种问题。

硬件上，VisionFlow须要您的计算机拥有支持AVX2指令集的x86-64架构CPU，且至少有4GB的内存。这是VisionFlow运行的基础要求。 我们的算法支持使用NVIDIA GPU训练和推理，也支持仅使用CPU或Intel GPU进行推理。如果您打算使用NVIDIA GPU训练和推理，请确保你的NVIDIA GPU 硬件和驱动满足以下必要条件：

1. 从VisionFlow-0.9.0版本开始，仅支持计算能力范围满足：7.0 <= 计算能力 <= 12.0 的NVIDIA GPU硬件。你可以参考 CUDA GPU 计算能力 查看各个GPU型号的计算能力。

  1. 确保你的NVIDIA GPU驱动版本满足：Windows平台 >= 572.60, Linux平台 >= 570.133.07。

此外，如果的计算机上有Intel的GPU设备，请注意检查你的GPU驱动是否支持OpenCL 3.0标准。你可以下载 clinfo 工具，并执行 clinfo --prop Version 命令， 检查输出的内容中 CL_DEVICE_VERSION 属性的值是否都包含 OpenCL 3.0 字样。简单起见，你也可以直接下载并安装与您的硬件型号匹配的最新的 Intel Graphics Driver ， 以确保使用较新的驱动程序，避免可能存在的兼容性问题。

VisionFlow对于不同平台及开发语言的支持情况如下（其中实验性支持的接口后续可能发生变化）：

操作系统

开发语言

接口形式

功能范围

限制

Windows

C

cabi [cabi]

多数接口

Windows

C++

原生C++接口

全部接口

仅支持 VS2019 Release 模式

Windows

C++

cppabi [cppabi]

多数接口 [exp]

VS2013 及以上

Windows

CSharp

visionflow.cs

多数接口 [exp]

.NET 4 及以上，VS2013 及以上，语言版本 C# 5.0 及以上

Windows

Python

内嵌Python解释器

多数接口

Linux

C

cabi [cabi]

多数接口

Ubuntu22.04

Linux

C++

原生C++接口

全部接口

GCC11+Ubuntu22.04

Linux

C++

cppabi [cppabi]

多数接口 [exp]

Ubuntu22.04

Linux

Python

内嵌Python解释器

多数接口

C++ 开发环境配置#

对于C++开发人员来说，VisionFlow只是一个预编译的二进制库，需要作为项目的依赖添加。 不同的C++开发人员可能使用不同的项目构建工具，因此以下是使用几种常用构建工具将VisionFlow 集成到项目中的说明：

请将以下代码复制到你项目的 WORKSPACE 文件中，并将URL和SHA256替换为你想要使用的 VisionFlow版本的链接和SHA256哈希值：

http_archive(
    name = "visionflow_windows",
    url = "<VisionFlow_URL>",
    sha256 = "<VisionFlow_SHA256>",
)

http_archive(
    name = "visionflow_linux",
    url = "<VisionFlow_Linux_URL>",
    sha256 = "<VisionFlow_Linux_SHA256>",
)

在上面的代码中，将 <VisionFlow_URL> 替换为所需版本的 VisionFlow 下载链接，将 <VisionFlow_SHA256> 替换为相应版本的 SHA256 摘要。这将指示构建系统从指定的 URL 下载 VisionFlow，并使用提供的 SHA256 摘要进行验证。发布包的链接和 SHA256 都可以在 VisionFlow的发布邮件信息中找到。

然后你可以将 VisionFlow 作为依赖库在你的项目的 Bazel 目标中使用，如下所示：

cc_binary(
    name = "main",
    srcs = ["main.cpp"],
    deps = select({
        "@platforms//os:windows": ["@visionflow_windows//:visionflow"],
        "@platforms//os:linux": ["@visionflow_linux//:visionflow"],
    }),
)

在上述示例中，我们假设你的项目有一个名为 main 的 C++ 二进制目标，其中的 main.cpp 是你的源代码文件。通过添加 deps 部分，我们将 VisionFlow 添加为项目的依赖，使得你的 main 可以使用 VisionFlow 提供的功能。

确保根据你的项目目录结构和构建需求进行相应的调整。这个示例只是为了说明如何将 VisionFlow 添加到 Bazel 构建的项目中。

我们推荐使用 CMake 的 FetchContent 来导入 VisionFlow。在你的项目中创建一个名为 find_visionflow.cmake 的文件，并在其中写入以下内容：

include(FetchContent)

FetchContent_Declare(
    visionflow
    URL <VisionFlow_URL>
    UPDATE_DISCONNECTED
)

FetchContent_GetProperties(visionflow)

if(NOT visionflow_POPULATED)
    FetchContent_Populate(visionflow)

    add_library(VisionFlow SHARED IMPORTED)
    set_target_properties(
        VisionFlow
        PROPERTIES
        IMPORTED_IMPLIB
        ${visionflow_SOURCE_DIR}/lib/visionflow.if.lib
        IMPORTED_IMPLIB_DEBUG
        ${visionflow_SOURCE_DIR}/lib/visionflow.if.lib
        IMPORTED_IMPLIB_RELEASE
        ${visionflow_SOURCE_DIR}/lib/visionflow.if.lib
        IMPORTED_LOCATION
        ${visionflow_SOURCE_DIR}/bin/visionflow.dll
        IMPORTED_LOCATION_DEBUG
        ${visionflow_SOURCE_DIR}/bin/visionflow.dll
        IMPORTED_LOCATION_RELEASE
        ${visionflow_SOURCE_DIR}/bin/visionflow.dll
        INTERFACE_INCLUDE_DIRECTORIES
        ${visionflow_SOURCE_DIR}/include
    )


    install(
        DIRECTORY
        ${visionflow_SOURCE_DIR}/bin/
        DESTINATION release
    )
endif()

接下来，你可以在你的 CMakeLists.txt 文件中包含 find_visionflow.cmake .

要将 VisionFlow 库添加到 Visual Studio 的 C++ 项目中，按照以下步骤进行操作：

  1. 参考 用安装程序安装VisionFlow库，将 VisionFlow 库安装到合适位置。

  2. 在 Visual Studio 中打开你的 C++ 项目。

  3. 在“解决方案资源管理器”中，右键点击项目，从上下文菜单中选择“属性”。

  4. 在“属性页”窗口中，导航到“配置属性” -> “VC++目录”。

  5. 在“包含目录”字段中，添加解压后 VisionFlow 包内的“include”文件夹的路径。 这个文件夹包含必要的头文件。你可以手动输入路径，也可以使用“…”按钮浏览并选择文件夹。

  6. 在“库目录”字段中，添加解压后 VisionFlow 包内的“lib”文件夹的路径。 这个文件夹包含必要的库文件。同样，你可以手动输入路径，也可以使用“…”按钮浏览并选择文件夹。

  7. 转到“配置属性” -> “链接器” -> “输入”。

  8. 在“附加依赖项”字段中，添加“visionflow.if.lib”。

  9. 点击“确定”以保存更改。

以上步骤说明了如何将 VisionFlow 库添加到 Visual Studio 中的 C++ 项目中。请注意根据你的 项目和文件路径，确保适当地调整路径。现在，你已经将预编译的 VisionFlow 包添加到了 Visual Studio 中的 C++ 项目中。然后注意确保在你的源文件中包含所需的 VisionFlow 头文件即可。

Note

VisionFlow的原生C++接口可能包含一些 C++17 语法，构建系统时，需要指定编译器使用C++17标准。 否则可能因为C++标准不同导致编译失败。

C#开发环境配置#

对于C#开发人员来说，VisionFlow 只是一个预编译的二进制库，需要作为项目的依赖添加。 VisionFlow 不仅提供了“visionflow.cs”源代码文件，还提供了基于.NET 6.0的预编译二进制库“csharp_visionflow.dll”。 要在 Visual Studio 中将 VisionFlow 库添加到你的C#项目中，请按照以下步骤进行操作：

  1. 从发布电子邮件中的链接下载预编译的 VisionFlow 包。

  2. 将 VisionFlow 包的内容解压到计算机上的所需位置。

  3. 在 Visual Studio 中打开你的 C# 项目。

注意，C#版本必须大于等于.NET 4。

如果你想要自己编译源代码，继续按照下步骤操作：

  1. 将 VisionFlow 发布包中的“csharp/visionflow.cs”文件复制到你的C#项目中的所需位置。

  2. 在“解决方案资源管理器”中点击“显示所有文件”，找到“visionflow.cs”并右键点击，选择“包括在项目中”。

  3. 将“bin”目录中的所有文件复制到生成“.exe”文件的文件夹中，或将“bin”添加到环境变量中。

  4. 对于目标框架为.NET Framework的C#项目，需要额外的配置。在“解决方案资源管理器”中，右键点击你的项目， 从上下文菜单中选择“属性”。选择“生成”，确保“首选32位”未选中 。

注意，C#版本必须大于等于.NET 6.0。

  1. 在“解决方案资源管理器”中右键单击您的项目，然后从上下文菜单中选择“添加” -> “项目引用”。

  2. 点击左侧列表的“浏览”，并选择下方“浏览”，添加“bin”目录中的“csharp_visionflow.dll”。

  3. 勾选“csharp_visionflow.dll”，然后点击下方的“确定”。

  4. 将“bin”目录中的所有文件复制到生成“.exe”的文件夹中，或将“bin”添加到环境变量中。

现在你已经将预构建的 VisionFlow 包添加到了 Visual Studio 中的C#项目中。

Note

要查看语言版本，只需右键点击项目，在上下文菜单中选择“属性”，然后进入“生成”选项卡，在右下角点击“高级”即可。

Python 开发环境配置#

VisionFlow 的 Python 库可以通过 VisionFlow 内嵌的 Python 解释器使用。 内嵌解释器位于 VisionFlow 内的 bin 目录，名为 python.exe （Windows 系统）或 python （Linux 系统）。

在该内嵌解释器中通过 import visionflow 即可引入 VisionFlow 库。该解释器包括了 VisionFlow 库的代码补全信息。

这个解释器可以和其他 Python 解释器一样使用。直接运行将打开交互式命令行界面，可以用来执行 Python 脚本，也可以配置到 IDE 中使用代码补全和调试功能。

Python IDE 环境配置#

如果你需要使用 IDE 来编辑或调试与 VisionFlow 有关的 Python 项目，你可以按照以下步骤进行操作， 将 VisionFlow 库和内嵌的解释器应用到 Visual Studio Code 或 PyCharm 的 Python 项目中：

  1. 在 Visual Studio Code 中打开你的 Python 项目，或新建一个项目。

  2. 安装微软官方发布的Python拓展，你可以在 Visual Studio Code 的扩展市场中搜索 ms-python.python。

  3. 按 Ctrl+Shift+P 打开命令面板，输入 Python: Select Interpreter 并回车， 在弹出的“选择解释器”对话框中输入或浏览选择内嵌 Python 解释器的路径。 或者，打开一个 Python 源文件，在窗口下角会显示当前使用的 Python 解释器，点击它并选择内嵌 Python 解释器。

  1. 在 PyCharm 中打开你的 Python 项目，或新建一个项目。

  2. 打开设置，选择“Python”-“解释器”，或者，点击窗口右下角的 Python 版本号，选择“解释器设置”。

  3. 如果你之前已设置过 VisionFlow 内嵌解释器，在下拉列表中应该能找到它，直接选择并应用即可。

  4. 要添加 VisionFlow 解释器，点击“添加解释器”—“添加本地解释器”。

  5. 在“环境”选择“选择现有”，“Python 路径”选择 VisionFlow 内嵌解释器。等候 PyCharm 识别并验证解释器后确定即可。

完成以上配置后，你就可以在 IDE 的 Python 项目中使用 VisionFlow 的 Python 库和代码补全功能了。

配置 Python 虚拟环境#

在 Python 项目中，使用虚拟环境来管理项目依赖，能够避免多个 Python 项目之间的依赖冲突、 保持系统 Python 环境的干净整洁、同时也方便项目部署和迁移。

下面以虚拟环境管理工具 virtualenv 为例，介绍基于 VisionFlow 内嵌 Python 解释器创建虚拟环境的方法：

  1. 在你的 Python 项目根目录打开命令行工具。

  2. 使用 VisionFlow 内嵌 Python 解释器，执行命令 <path/to/visionflow>/bin/python.exe -m venv .venv 在你项目的 .venv 目录下创建虚拟环境。

  3. 新创建的虚拟环境中 VisionFlow 的代码补全不完整，请执行以下步骤：

    1. 安装相关生成工具，用你虚拟环境中的 Python 解释器执行命令 .venv/Scripts/python.exe -m pip install mypy。

    2. 用工具生成 VisionFlow 的代码补全表，执行命令 .venv/Scripts/stubgen.exe -p visionflow -o .venv/Lib/site-packages。

  4. 在上一节“Python IDE 环境配置”中选择 Python 解释器路径时，选择你项目中的解释器路径，即 .venv/Scripts/python.exe。

Note

如果你内嵌 Python 解释器的路径中含有中文等非 ASCII 字符，在用 PowerShell 执行上述第 2 步时可能会遇到编码问题。

你可以尝试使用命令提示符（cmd）执行该命令。

脚注：

[exp] (1,2,3)

实验性的接口后续可能发生变化。

[cabi] (1,2)

cabi相关接口头文件位于SDK包内 include/cabi 目录内。

[cppabi] (1,2)

cppabi相关接口头文件位于SDK包内 include/cppabi 目录内。