Implement BiRefNet and HAT Sharper models with background removal capabilities
- Added validation documentation for AI model tiers. - Introduced `background.py` for background removal logic, including inference functions for alpha and foreground extraction. - Created `onnx_birefnet.py` to handle BiRefNet model sessions and alpha inference. - Developed tests for background models, ensuring proper dispatch and session reuse. - Added tests for BiRefNet ONNX model to validate alpha output and error handling for invalid values. - Implemented model export scripts for BiRefNet and HAT Sharper, ensuring proper weight compression and licensing. - Created `deform_sampling.py` for deformable convolution operations used in BiRefNet. - Added utility functions for compressing ONNX weights without altering graph arithmetic. - Introduced a reference plane node for depth field adjustments in geometry processing.
This commit is contained in:
@@ -0,0 +1,42 @@
|
||||
## Purpose
|
||||
|
||||
为深度生成、图片超分和背景移除提供各三款用途明确的正式模型，使偏好选择、首次安装、模型下载和服务就绪状态表达相同的模型集合，并让新用户以轻量模型开始使用。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 三类模型采用固定三档集合
|
||||
系统 SHALL 按以下顺序提供九款正式模型：Depth 为 MoGe-2 ViT-S Normal、MoGe-2 ViT-B Normal、MoGe-3 ViT-L；Upscale 为 Real-ESRGAN General WDN x4v3、Real-ESRGAN x4plus、Real HAT GAN x4 Sharper；Background 为 BiRefNet Lite、BEN2、BiRefNet HR-matting。各类别第一项 SHALL 为新偏好的默认值。
|
||||
|
||||
#### Scenario: 查看模型选项
|
||||
- **WHEN** 用户查看偏好或模型下载列表
|
||||
- **THEN** 每个类别恰好显示上述三款模型，顺序一致，模型名、用途、许可证和下载体积对应实际资源
|
||||
|
||||
#### Scenario: 服务离线时显示目录
|
||||
- **WHEN** 服务尚未启动而界面需要展示模型
|
||||
- **THEN** 本地目录与服务启动后返回的正式模型集合一致
|
||||
|
||||
### Requirement: 首次安装仅要求三个默认模型
|
||||
系统 SHALL 将 MoGe-2 ViT-S Normal、General WDN x4v3 和 BiRefNet Lite 作为默认环境初始化所需的模型集合，其他模型按用户选择下载。
|
||||
|
||||
#### Scenario: 新安装完成初始化
|
||||
- **WHEN** 推理环境和三个默认模型都已就绪，其他六款尚未下载
|
||||
- **THEN** AI 初始化状态为就绪，默认功能可运行
|
||||
|
||||
#### Scenario: 选择未下载的高档模型
|
||||
- **WHEN** 用户执行功能时选中的非默认模型尚未就绪
|
||||
- **THEN** 系统指出需要下载该模型，不使用其他模型替代本次请求
|
||||
|
||||
### Requirement: 有效偏好保留且退役选择明确处理
|
||||
系统 SHALL 保留仍属于所选类别的持久化模型键，并将退役或无效的偏好值归一为类别默认值；服务收到未知或退役模型键时 SHALL 返回明确错误。
|
||||
|
||||
#### Scenario: 用户已有 BEN2 偏好
|
||||
- **WHEN** 更新后读取有效的 BEN2 背景移除选择
|
||||
- **THEN** 继续选择 BEN2
|
||||
|
||||
#### Scenario: 用户已有 PiSA-SR 偏好
|
||||
- **WHEN** 更新后读取已退役的 PiSA-SR 超分选择
|
||||
- **THEN** 当前有效选择为 General WDN x4v3，界面与后续请求一致
|
||||
|
||||
#### Scenario: 旧请求直接指定退役模型
|
||||
- **WHEN** 服务收到指定 DA3、MoGe-2 L、SAFMN 或 PiSA-SR 的请求
|
||||
- **THEN** 返回未知或不可用模型错误，不加载或下载退役资源
|
||||
@@ -0,0 +1,59 @@
|
||||
## Purpose
|
||||
|
||||
让用户通过同一个背景移除功能选择轻量、通用或精细抠图模型，并在静态图、多帧图与 HDR 图片中得到尺寸、透明度和资源生命周期一致的结果，保留已有图片编辑语义。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 背景模型选择贯穿真实执行
|
||||
系统 SHALL 使用当前选择的 BiRefNet Lite、BEN2 或 BiRefNet HR-matting 执行所有支持的背景移除输入路径，模型名称 SHALL 与下载、进度和实际加载的资源一致。
|
||||
|
||||
#### Scenario: 切换到精细抠图
|
||||
- **WHEN** 用户选择已经下载的 BiRefNet HR-matting 并执行背景移除
|
||||
- **THEN** 使用该模型推理，输出和进度不再固定指向 BEN2
|
||||
|
||||
### Requirement: 输出有限的连续透明度
|
||||
每款背景模型 SHALL 产出与分析图片尺寸一致、有限且位于 `[0,1]` 的连续 Alpha。模型适配 SHALL 保持其官方输出语义，支持发丝、毛绒和半透明边缘的连续透明度。
|
||||
|
||||
#### Scenario: 半透明边缘
|
||||
- **WHEN** HR-matting 对包含薄纱或细发丝的图片输出中间透明度
|
||||
- **THEN** 后处理保留有效的中间 Alpha 值，不将其强制二值化或按单图极值重新拉伸
|
||||
|
||||
#### Scenario: 无效预测
|
||||
- **WHEN** 模型返回错误形状或包含 NaN、Inf 的透明度
|
||||
- **THEN** 任务明确失败，并保留可诊断的模型错误信息
|
||||
|
||||
### Requirement: 保持已有前景和 HDR 编辑行为
|
||||
系统 SHALL 沿用既有前景 RGB 与源 Alpha 合成规则，支持静态前景、多帧前景及 HDR 的 Alpha-only 输出；HDR 结果 SHALL 保持原始浮点 RGB。
|
||||
|
||||
#### Scenario: HDR 背景移除
|
||||
- **WHEN** 用户对浮点 HDR 图片使用任意背景模型
|
||||
- **THEN** 用分析输入预测 Alpha，将结果应用到原始图片，并保留原始 HDR RGB 数值
|
||||
|
||||
#### Scenario: 多帧透明前景
|
||||
- **WHEN** 用户对支持的多帧输入执行背景移除
|
||||
- **THEN** 每帧使用选定模型，保持帧数、编号、尺寸与已有透明度合成约定
|
||||
|
||||
### Requirement: 模型资源可复用且可释放
|
||||
系统 SHALL 为相同模型和设备复用会话，在模型切换、资源关闭时释放旧会话，并使取消与失败遵循既有任务清理行为。
|
||||
|
||||
#### Scenario: 连续帧复用
|
||||
- **WHEN** 多帧任务连续处理同一模型和设备
|
||||
- **THEN** 各帧复用已加载会话，取消后停止后续推理并清理未完成任务产物
|
||||
|
||||
#### Scenario: 切换背景模型
|
||||
- **WHEN** 用户从 Lite 切换到 BEN2 或 HR-matting
|
||||
- **THEN** 实际推理使用新选择，并释放原先背景模型占用的会话资源
|
||||
|
||||
### Requirement: 新背景模型经过真实运行验收
|
||||
BiRefNet Lite SHALL 在发布前通过 CPU / DirectML 数值和图片验证，HR-matting SHALL 通过 CPU 验证；记录真实下载体积、加载与热推理耗时、峰值资源占用及边缘效果。Lite SHALL 比 BEN2 下载体积更小，并在相同测试条件下至少降低热推理耗时或峰值占用中的一项。
|
||||
|
||||
#### Scenario: 确定轻量默认模型
|
||||
- **WHEN** Lite 的正式资产准备发布
|
||||
- **THEN** 存在与 BEN2 的同条件对照和质量检查记录，且其轻量收益满足要求
|
||||
|
||||
### Requirement: HR-matting 使用 CPU
|
||||
HR-matting SHALL 暂时固定使用 CPU。模型选项 SHALL 标明 CPU，进度 SHALL 显示实际设备；会话缓存 SHALL 按实际 CPU 设备复用。
|
||||
|
||||
#### Scenario: GPU 偏好下选择 HR-matting
|
||||
- **WHEN** 全局设备为 DirectML，用户选择 HR-matting
|
||||
- **THEN** 创建 CPU 会话并显示 CPU 进度，保持 HR 的 2048 像素输入及连续 Alpha 语义
|
||||
@@ -0,0 +1,49 @@
|
||||
## Purpose
|
||||
|
||||
为图片超分增加用户已比较确认的 HAT Sharper 细节增强选项，提供可验证的小体积模型资源，并使最终两倍尺寸、透明度、多帧处理和大图分块行为与现有超分功能一致。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: HAT Sharper 提供可验证的小体积资源
|
||||
系统 SHALL 提供官方 Real HAT GAN x4 Sharper 对应的模型资产，完整记录上游来源、文件大小及校验信息。发布文件 SHALL 小于 60 MB，保持 FP32 输入输出，并通过 CPU / DirectML 与原始 FP32 参考的数值对照。
|
||||
|
||||
#### Scenario: 校验发布模型
|
||||
- **WHEN** 对预先固定的样图执行正式导出资产
|
||||
- **THEN** 输出全部有限，未裁剪的 `[0,1]` 标度输出误差满足 MAE ≤ 0.0005、P99 ≤ 0.005、最大误差 ≤ 0.02
|
||||
|
||||
#### Scenario: 实验精度路径失败
|
||||
- **WHEN** 导出或运行路径在验收中产生 NaN、Inf 或超过预设误差
|
||||
- **THEN** 该资产不能登记为可发布模型，也不能标记验收完成
|
||||
|
||||
### Requirement: 三款超分均保持最终两倍输出
|
||||
系统 SHALL 对限制后的分析输入保持宽高各 2 倍的最终输出；HAT 与现有两款 Real-ESRGAN SHALL 保持相同的透明度合成和帧输出约定。
|
||||
|
||||
#### Scenario: 普通与透明静态图片
|
||||
- **WHEN** 用户用 HAT Sharper 放大宽 W、高 H 的分析输入
|
||||
- **THEN** 最终图片尺寸为 `2W×2H`，原始 Alpha 按现有超分规则缩放并合成
|
||||
|
||||
#### Scenario: 多帧输入
|
||||
- **WHEN** 使用 HAT Sharper 处理支持的多帧输入
|
||||
- **THEN** 每帧输出保持两倍尺寸及既有编号，帧间复用模型资源
|
||||
|
||||
### Requirement: 分块支持合法图片尺寸且控制边界误差
|
||||
HAT SHALL 支持小图、奇数尺寸和跨多个分块的输入，输出覆盖全部像素；分块配置 SHALL 通过纹理、细线和透明边缘样图检查，并相对完整参考记录接缝误差。
|
||||
|
||||
#### Scenario: 奇数尺寸与边缘块
|
||||
- **WHEN** 输入宽高不是分块步长的整数倍
|
||||
- **THEN** 结果保持准确的两倍尺寸，边缘完整，没有空白条带或重复像素区
|
||||
|
||||
#### Scenario: 自然纹理跨越接缝
|
||||
- **WHEN** 对固定跨缝样图检查最终 2× 输出
|
||||
- **THEN** 没有由拼接造成的可见直线接缝，并记录相对整图参考的接缝和内部误差
|
||||
|
||||
### Requirement: 推理取消和资源错误可处理
|
||||
系统 SHALL 沿用超分任务的取消、会话复用和资源释放机制；资源不足时 SHALL 报告当前模型及可操作的调整建议。
|
||||
|
||||
#### Scenario: 分块间取消
|
||||
- **WHEN** 用户取消正在处理多块图片的 HAT 任务
|
||||
- **THEN** 后续块停止推理，未完成产物按现有任务规则清理
|
||||
|
||||
#### Scenario: 显存或内存不足
|
||||
- **WHEN** 当前设备无法完成 HAT 推理
|
||||
- **THEN** 返回包含模型和设备上下文的资源错误，提示减小分析输入或选择更轻量模型
|
||||
@@ -0,0 +1,38 @@
|
||||
## Purpose
|
||||
|
||||
确保正式模型目录、本地资产准备和远端镜像对应同一套可验证资源，并在模型退役时明确清理其源码登记、开发权重缓存及远端对象，使用户下载和开发工具持续使用有效模型。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 资产准备与发布跟随正式清单
|
||||
`model prepare` 和 `model sync` SHALL 覆盖九款正式模型的完整文件集合，对每个文件验证大小和 SHA-256；缺失、损坏或无法验证的资产 SHALL 明确失败。
|
||||
|
||||
#### Scenario: 新模型资产损坏
|
||||
- **WHEN** HAT 或 BiRefNet 的本地文件与登记大小或哈希不一致
|
||||
- **THEN** 准备或发布失败，该模型不被标记为完整就绪
|
||||
|
||||
#### Scenario: 新镜像验收
|
||||
- **WHEN** 新模型上传到 R2
|
||||
- **THEN** 使用实际下载来源回读并校验完整文件，记录每款模型的来源、大小、哈希和就绪结果
|
||||
|
||||
### Requirement: 退役资源在各发布入口一致移除
|
||||
DA3 全部现存变体、MoGe-2 ViT-L Normal、SAFMN 和 PiSA-SR SHALL 从正式模型集合、自动准备、下载和生产推理入口退役；对应专用源码、导出登记与专用构建依赖 SHALL 清理。
|
||||
|
||||
#### Scenario: 执行正式准备命令
|
||||
- **WHEN** 完成本次模型调整后运行模型准备或同步
|
||||
- **THEN** 只准备和发布九款正式模型，不下载、导出或上传退役模型
|
||||
|
||||
### Requirement: 远端和本地退役清理采用明确对象清单
|
||||
本次退役清理 SHALL 在新模型通过发布验收后执行。清理前 SHALL 列出并保存归属于退役模型的本地目录、开发缓存文件与 R2 对象键，仅操作核对过的目标，并在结束后复查对象存在性。
|
||||
|
||||
#### Scenario: 清理 DA3 远端残留
|
||||
- **WHEN** R2 中仍存在未列入正式模型清单的 DA3 变体
|
||||
- **THEN** 将归属已确认的 DA3 对象纳入本次退役清单、删除并复查，不能将停止上传视为删除完成
|
||||
|
||||
#### Scenario: 相邻目录包含其他资源
|
||||
- **WHEN** 模型目录或桶内同时存在保留模型、其他对象或用户产物
|
||||
- **THEN** 清理范围严格限定于已列出的退役目标，其他资源保持原样
|
||||
|
||||
#### Scenario: 部分对象清理失败
|
||||
- **WHEN** 本地或 R2 删除未能完整完成
|
||||
- **THEN** 记录成功与失败目标，报告未完成项，并在复查全部通过前保持退役任务未完成
|
||||
Reference in New Issue
Block a user