版本兼容性与自动升级

概览

升级 VisionFlow 版本前，建议先查看工程/模型与目标版本之间的兼容性。兼容性信息可以帮助你判断旧工程是否可以直接打开、旧模型是否可以继续使用，以及升级结束后用户是否需要额外操作。

兼容性结果主要回答以下问题：

1. 旧工程数据升级后，用户是否还可以按原方式继续使用；

2. 旧版本已经训练好的模型是否还可以继续复用；

3. 新版本是否可以打开或升级旧工程/旧模型。

同一次版本升级中，工程、模型和打开/升级能力可能得到不同的兼容结果。例如，旧工程可以升级到新版本，但由于算法变化，旧模型不能继续复用，需要通过工程重新训练后再导出。

兼容性等级

兼容性等级按影响从小到大分为以下几档。查看兼容性结果时，可以先看等级，再根据说明决定是否需要重新训练或调整工程。

兼容性等级说明

等级	表示什么	你需要做什么
完全兼容（Fully Compatible）	升级对工程和模型没有实质影响。	可以直接使用旧工程和旧模型，不需要额外操作。
需要人工介入后兼容（Requires Manual Intervention Compatible）	升级后可以继续使用，但需要用户额外处理。	按兼容性说明检查工程，必要时重新设置参数、重新训练模型、调整视图或重新验证结果。
不兼容（Not Compatible）	旧工程或旧模型不能按原方式继续使用。	无法进行升级，继续兼容旧数据或旧模型已经没有实际价值。需要按提示信息操作，在新版本重新准备工程、重新训练模型。

如果结果是“需要人工介入后兼容”，不要只看总体等级。请继续查看工程兼容性和模型兼容性的具体说明，确认需要处理的是工程配置、模型复用，还是升级路径本身。

如何阅读兼容性结果

兼容性结果通常包含以下 3 个视角。用户升级工程时，建议优先关注工程兼容性和模型兼容性；允许强制升级（技术兼容性）用于判断是否存在可打开或可升级的路径。它只表示是否存在技术升级路径，不代表无视风险。

兼容性结果说明

视角	你可以用它判断什么	常见后续操作
工程兼容性（Project）	旧工程升级后是否还能按原方式继续编辑、运行和保存。	检查参数、标注、视图和流程配置，必要时根据提示信息重新调整。
模型兼容性（Model）	旧版本训练出的模型是否还能继续推理，以及结果是否可信。	如果提示不兼容或需要人工介入，应通过原始工程重新训练或重新验证模型效果。
允许强制升级（Force Upgrade Allowed）	新版本是否可以打开或升级旧工程数据。	如果不兼容，则无法升级。请使用新版本重建工程。

技术兼容决定 能不能打开或升级工程；工程性兼容决定 升级后工程要不要调整；模型兼容决定 升级后旧模型能不能继续复用。一个版本可能在技术上可升级，但在模型视角上仍然不兼容。这种情况下，原始旧工程可以被升级到新版本，但用户不能继续依赖旧模型，需要在新版本中重新训练并导出。

VisionFlow 提供了多种方式查询兼容信息：

1. 你可以查阅文档中附带的 版本兼容性了解当前版本的库与旧版本库的兼容性关系；

2. 你可以找到 VisionFlow 库中附带的命令行工具并执行 visionflow.exe compatibility来查看各个历史版本之间的兼容性关系；

3. 你可以找到 VisionFlow 库中附带的命令行工具并执行 visionflow.exe compatible <project_path.vlow>来查看某个具体的工程与当前库版本之间的兼容性关系及升级路径；

4. 你可以通过 visionflow::Project 中兼容性相关的接口获取某个具体工程与当前库版本的兼容性等级和兼容性信息，具体请查看相关接口；

5. 你还可以通过调用 Compatibility列出的接口获得任意工程无关或有关（需要给出工程中包含的工具的信息）的兼容性信息。

Note

为了降低单一工具功能发生更改时对不同用户的影响，我们也会在每个版本详细记录和区分不同工具的兼容性，从而避免用户没有使用到的工具的变化对用户造成不兼容影响。

查看版本兼容性表

版本兼容性 文档由兼容性表自动生成。表格按“新版本 -> 旧版本 -> 模块 -> 维度”展开，每一行给出对应视角的兼容等级和说明。

表格中的模块包括两类：

• 工程数据管理：全局工程数据管理层面的兼容性；

• 具体工具名称：某个工具自身的兼容性，例如 Detection、OCR、Segmentation 等。

表格中的“允许强制升级（Force Upgrade Allowed）”来自技术兼容性：只要技术兼容性不是“不兼容”，就表示存在可执行的打开或升级路径。但这并不代表升级后完全不需要操作，也不代表旧模型一定可以继续复用。是否需要重新设置参数、重新训练或调整工程，应以工程兼容性和模型兼容性两行的等级及说明为准。

阅读表格时建议按以下顺序进行：

1. 找到当前旧版本；

2. 先查看 工程数据管理，确认全局工程数据是否可以升级；

3. 再查看工程中实际使用的工具；

4. 分别检查 工程 和 模型 两个维度，确认是否需要调整工程或重新训练模型；

5. 如果看到 不兼容，不要继续尝试升级，应先确认是否存在替代迁移方案或者在新版本重新构建工程。

自动升级

对于可以升级的工程，VisionFlow 会在打开或升级时自动进行兼容性处理。VisionFlow 的每个版本通常只支持将前一个或有限个旧版本的工程直接升级上来，但一般情况下支持链式升级。例如，当前工程由 V1 版本的库创建，希望升级到 V3，但 V3 只支持从 V2 升级上来；这时可以先下载 V2 版本的库，将工程升级到 V2，再使用 V3 版本的库将工程升级到 V3。

链式升级时，需要按升级路径逐步处理工程：

1. 使用 V2 版本打开 V1 工程；

2. 按提示完成升级，并保存为新的 V2 工程文件；

3. 使用 V3 版本打开刚保存的 V2 工程；

4. 再次按提示完成升级并保存；

5. 不要跳过升级路径中的关键版本。

可以通过 visionflow::Project::UpgradePath() 或执行 visionflow.exe compatible <project_path.vlow>查询某个工程到当前库版本的升级路径，并根据返回路径依次使用对应库版本对工程进行升级。对于旧模型无法继续复用的情况，会提示原始旧工程的升级路径。

升级后验证

升级完成后，建议至少检查以下内容：

1. 工程/模型可以正常打开、运行、保存和再次打开；

2. 关键工具的参数、标注、ROI、视图和流程连接符合预期；

3. 推理流程可以正常运行，没有缺失模型、缺失参数或工具报错；

4. 如果模型兼容性是“不兼容”，应通过旧工程重新训练模型，并重新验证推理效果；

5. 如果模型兼容性不为“不兼容”， 这里仍是旧模型的推理效果，请按需要通过原始工程升级后，重新训练模型，并验证新模型的推理效果。