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.
2026-09-10 20:50:44 +08:00
parent 8ae3c1d5b7
commit e8129fe495
70 changed files with 1890 additions and 1208 deletions
--- a/openspec/changes/simplify-ai-model-tiers/.openspec.yaml
+++ b/openspec/changes/simplify-ai-model-tiers/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-10
--- a/openspec/changes/simplify-ai-model-tiers/design.md
+++ b/openspec/changes/simplify-ai-model-tiers/design.md
@@ -0,0 +1,117 @@
+## Context
+
+模型矩阵见 [proposal.md](proposal.md)。当前模型清单已有 MoGe-3，Upscale 已统一最终 2×，背景移除虽有偏好项，Operator 和缓存仍直接绑定 BEN2。`model prepare` / `model sync` 从清单生成文件集合，远端上传采用逐文件复制。
+
+相关在途 change 包括 `add-moge3-model`、`add-pisa-sr-two-times-upscale`、`add-ben2-hdr-support` 和 `organize-tool-cli`。实施基于工作区实际调用链，承接其有效行为；模型成员和默认值以本提案为准。
+
+## Goals
+
+- 用同一模型清单驱动偏好、初始化、Job 参数、模型下载和镜像资产。
+- 将各模型差异限制在适配器与少量推理配置中，复用现有图像准备、Alpha 合成、缓存和事务处理。
+- 以可复现资产和 CPU / DirectML 真实推理验证完成接入，保持三档与资源需求的说明准确。
+
+## Decisions
+
+### HR-matting 设备决议（2026-09-10）
+用户确认保留 HR-matting，暂时仅支持 CPU。2048 输入的 ONNX 在 CPU 上通过原始实现对照，DirectML 在最后解码阶段产生明显误差，多种分块导出未通过验证。正式版本采用已验证的原始 GridSample 导出结构，HR 选项标明 CPU，进度与会话缓存使用实际 CPU 设备。Lite 和 BEN2 继续使用所选设备。
+
+### 1. 固定三类各三款，默认入口统一
+
+模型键建议如下；已有保留模型沿用当前键：
+
+| 分类 | 模型键，按界面顺序 | 默认 |
+|---|---|---|
+| Geometry | `MOGE2_VITS_NORMAL`、`MOGE2_VITB_NORMAL`、`MOGE3_VITL` | 第一项 |
+| Upscale | `REALESRGAN_GENERAL_WDN_X4V3`、`REALESRGAN_X4PLUS`、`HAT_GAN_X4_SHARPER` | 第一项 |
+| Background | `BIREFNET_LITE`、`BEN2_BASE`、`BIREFNET_HR_MATTING` | 第一项 |
+
+界面显示用途与模型名：Depth 为快速/均衡/精细，Upscale 为快速/通用/精细，背景移除为快速/通用/精细抠图。说明展示真实模型特点，下载体积来自文件清单；档位名称不作为逐图质量保证。
+
+扩展偏好读取入口集中在 `preferences.py`。初始化所需模型从三个类别的默认值派生；新安装只准备 MoGe-2 S、WDN 和 BiRefNet Lite。读取持久化选择时，保留有效键，类别外的键归一为该类别默认值。外部提交未知或退役模型键的 Job 明确失败，避免静默使用不同模型。
+
+背景模型资源分类改为职责名称 `background`，同步修改生产者和消费者。依赖 BEN2 名称的公共常量、缓存接口和进度文案按实际职责重命名；BEN2 专用 ONNX 适配器继续明确命名。
+
+### 2. 背景移除共享编排，按模型适配 Alpha
+
+```mermaid
+flowchart TD
+    A[扩展偏好选择模型] --> B[公共输入准备与模型就绪检查]
+    B --> C[背景移除 Job]
+    C --> D{模型适配器}
+    D --> E[BiRefNet Lite 1024]
+    D --> F[BEN2 当前配置]
+    D --> G[BiRefNet HR-matting 2048]
+    E --> H[原图尺寸的有限连续 Alpha]
+    F --> H
+    G --> H
+    H --> I[现有 Alpha 合成与前景输出]
+    I --> J[主线程更新图片或 HDR Alpha]
+```
+
+公共编排从 `models/ben2.py` 调整为背景移除职责模块。Lite 和 HR-matting 使用一个 BiRefNet 适配模块及各自配置，保留官方 RGB 归一化、输入尺寸、输出激活和缩放约定。BiRefNet 的概率 Alpha 按官方语义处理，避免套用 BEN2 的输出归一化造成半透明区域失真。
+
+共享输出为原始分析图片尺寸的 `float32` Alpha，范围 `[0,1]`，保留连续透明度。静态前景、多帧前景和 HDR 的 Alpha-only 路径复用当前协议；原图颜色与已有 Alpha 的合成遵循现有行为。Blender 输入准备复用 `common`，Server 复用自身 `media` 和模型工具。
+
+缓存按模型、目录及设备识别，会话在切换和关闭时释放。同模型多帧复用会话，取消和推理失败继续遵守现有 Job 清理流程。
+
+BiRefNet 先在隔离导出环境固定上游版本、checkpoint、许可证和预处理，再确定可通过数值验证的存储精度。Lite 约 90 MB、HR-matting 约 444 MB 仅作为评估参考；正式大小和哈希以导出文件为准。默认 Lite 需在同一设备与样图上证明比 BEN2 更低的下载体积，且热推理耗时或峰值占用至少一项更低，并记录另一项和边缘效果。
+
+### 3. HAT Sharper 使用压缩权重、FP32 运算
+
+HAT 上游源码固定到 `1638a9a822581657811867bf670717f8371fc3e5`，使用官方 Sharper 检查点中的 `params_ema`。离线导出关闭常量折叠，以免预展开注意力偏置扩大文件；浮点权重存为 FP16，在原图运算前 Cast 回 FP32。输入输出保持 FP32，正式 Runtime 沿用 ONNX。
+
+实验记录：
+
+| 项目 | Sharper 实测 |
+|---|---|
+| 参数量 | 20,772,507 |
+| FP32 ONNX | 87,221,721 bytes |
+| 压缩权重 ONNX | 45,874,438 bytes |
+| DirectML，RTX 5070 Ti，256×256 输入 | 热推理中位数约 0.563 秒 |
+| 与 FP32 PyTorch 对照，4 张裁片 | 最大样本 MAE 0.000190，最大像素误差 0.007370 |
+| 执行检查 | CPU 与 DirectML 通过；DirectML profile 的计算事件均在 GPU |
+
+检查点 SHA-256：`5800b67136006eb8cab3b4ed7c8d73b6a195bb18e6cc709b674f9aa069c00271`。实验压缩模型 SHA-256：`032d8b03c704220a08d91465a822aca252c1d6e63db20c3cf23c5fb67f3d2366`。正式导出器规范化后重新记录产物哈希，并执行同样的精度校验。
+
+参考：[本地验证报告](../../../.model-cache/hat-validation/report.md)、[官方 HAT](https://github.com/XPixelGroup/HAT)。本地报告位于忽略目录，上表和哈希作为 change 的持久验证摘要。
+
+全 FP16 和已试的混合精度运算在 DirectML 中产生 NaN，因此选择已经验证的 FP32 运算方案。该选择优化磁盘和下载成本，运行内存按 FP32 计算评估。Sharpness 是用户已比较确认的视觉偏好，产品说明应表达细节增强，而非原始噪点保真。
+
+### 4. Upscale 沿用 2×，HAT 使用独立分块参数
+
+共享超分路径仍为：RGB 推理 4× → Lanczos 缩至 2× → 合成按现有规则缩放的原始 Alpha。多帧、输入尺寸上限、取消与错误处理保持同一流程。
+
+HAT 采用固定 256×256 ONNX 输入，通过 padding 与分块支持任意合法图片尺寸。先以已测的 48 像素边距、160 像素有效步长作为正式候选；两个 Real-ESRGAN 保持各自当前配置。参数通过模型明确选择，共享拼接实现。
+
+在 448×224 样图上，Sharper 的接缝梯度误差从边距 16 的 4.17 降到边距 48 的 1.44（8-bit 单位），代价是该图从 2 块增加到 6 块。实施时补充自然纹理跨缝、细线、奇数尺寸、小图和透明图片验证；可见接缝存在时先修正分块，验证通过后确定发布资产。
+
+### 5. 从新模型发布推进退役资产清理
+
+```mermaid
+flowchart TD
+    A[锁定上游版本与导出配置] --> B[生成并验证三款新模型]
+    B --> C[九款正式清单与初始化更新]
+    C --> D[model prepare 校验本地资产]
+    D --> E[model sync 发布并回读校验]
+    E --> F[列出退役本地路径与 R2 对象]
+    F --> G[按核对过的清单删除退役对象]
+    G --> H[检查新资产可下载及退役对象不存在]
+```
+
+退役范围为 DA3 全部现存变体、`moge-2-vitl-normal-onnx`、`safmn-real-x4` 和 `pisa-sr`。DA3 从实际本地目录及远端对象清单识别，覆盖已知 BASE、SMALL 和发现的其他 DA3 变体。清理对应专用源码、导出器、构建登记、依赖和开发源权重缓存。
+
+R2 逐文件上传不会自动清理旧对象。本次退役作为有明确对象清单的一次性迁移：保存删除前清单，确认完整前缀属于该模型，先验证新资源再删除并复查。`model sync` 继续按正式清单发布；其他远端对象维持原样。用户自行配置的模型缓存按显式列出的模型目录操作，用户图片与 Job 产物保持独立。
+
+## Risks / Trade-offs
+
+- Lite 已通过 CPU / DirectML 对照；HR 固定使用 CPU → 逐图误差、边缘效果和资源成本记录于本 change，设备限制明确显示在选项中。
+- HAT 比当前 x4plus 更慢，较宽边距增加推理次数 → 默认继续使用 WDN，记录热推理与整图耗时，验证取消响应和资源释放。
+- HR-matting 高分辨率 CPU 峰值工作集约 19.3 GB → 标明 CPU 与高资源成本，保留 Lite 和 BEN2 供日常使用。
+- 多个相关 change 在工作区并行演进 → 开始实施时核对真实调用链和改动，保持 MoGe-3、HDR 与 2× 输出的行为覆盖；本提案只覆盖模型调整。
+- 远端删除不可依赖重新同步自动恢复 → 发布前固定可复现来源、大小和哈希；清理失败时保留明确的未完成对象清单，修复后逐项继续。
+
+## Migration Plan
+
+先完成新模型资产验证，再统一模型选择和生产调用，最后发布并回读新镜像、清理退役模型。有效的已有模型偏好保留，退役选择归一到类别默认值；首次安装改用三个轻量默认模型。
+
+实施运行相关行为测试和全量测试，确认正常退出，并检查退役引用、依赖与打包清单。验证记录写入本 change；用户文档构建和扩展打包保持独立于本次实施任务。
--- a/openspec/changes/simplify-ai-model-tiers/mirror-validation.json
+++ b/openspec/changes/simplify-ai-model-tiers/mirror-validation.json
@@ -0,0 +1,53 @@
+[
+  {
+    "model": "BIREFNET_LITE",
+    "ready": true,
+    "files": [
+      {
+        "url": "https://models.omoolab.xyz/birefnet-lite/model.onnx",
+        "bytes": 112968598,
+        "sha256": "6e2a9844c57b080e95a402722ddcae5660e6f254a04d3e003347f06f587b71fe"
+      },
+      {
+        "url": "https://models.omoolab.xyz/birefnet-lite/LICENSE.txt",
+        "bytes": 1066,
+        "sha256": "92a7089e0915fc32bc40067560b398f1e6a7a5958abd7d04eda393629a5acefb"
+      }
+    ],
+    "execution": "passed"
+  },
+  {
+    "model": "BIREFNET_HR_MATTING",
+    "ready": true,
+    "files": [
+      {
+        "url": "https://models.omoolab.xyz/birefnet-hr-matting/model.onnx",
+        "bytes": 529467341,
+        "sha256": "b3abc34843a4d96f669ca9fb1a2a16b3417ab8b91c987573fdbda36d20514133"
+      },
+      {
+        "url": "https://models.omoolab.xyz/birefnet-hr-matting/LICENSE.txt",
+        "bytes": 1066,
+        "sha256": "92a7089e0915fc32bc40067560b398f1e6a7a5958abd7d04eda393629a5acefb"
+      }
+    ],
+    "execution": "passed"
+  },
+  {
+    "model": "HAT_GAN_X4_SHARPER",
+    "ready": true,
+    "files": [
+      {
+        "url": "https://models.omoolab.xyz/hat-gan-x4-sharper/model.onnx",
+        "bytes": 45874438,
+        "sha256": "032d8b03c704220a08d91465a822aca252c1d6e63db20c3cf23c5fb67f3d2366"
+      },
+      {
+        "url": "https://models.omoolab.xyz/hat-gan-x4-sharper/LICENSE.txt",
+        "bytes": 11342,
+        "sha256": "a91d57ebad8955a1757be7891ca2da8e07493e662f0e34e1e1926571e05f37fc"
+      }
+    ],
+    "execution": "passed"
+  }
+]
--- a/openspec/changes/simplify-ai-model-tiers/proposal.md
+++ b/openspec/changes/simplify-ai-model-tiers/proposal.md
@@ -0,0 +1,38 @@
+## Why
+
+当前模型选项的资源梯度和用途不够清晰，PiSA-SR 的下载体积与实际效果不符合使用需求，背景移除也缺少轻量默认模型。HAT Sharper 已通过本地效果比较和 ONNX 验证，适合将三个 AI 功能统一整理为各三档，并完成退役模型的资产清理。
+
+## What Changes
+
+| 功能 | 第一档，默认 | 第二档 | 第三档 |
+|---|---|---|---|
+| 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 |
+| Remove Background | BiRefNet Lite | BEN2 | BiRefNet HR-matting |
+
+- **BREAKING**：移除 MoGe-2 ViT-L Normal、SAFMN、PiSA-SR 的正式选项和实现；清理 DA3 的现行残留及对应本地、R2 模型资产。
+- **BREAKING**：背景移除默认模型改为 BiRefNet Lite，模型选择、AI 环境初始化、下载和缓存统一按背景移除职责组织。
+- 接入 HAT Sharper，采用已验证的 FP16 权重存储、FP32 运算 ONNX 路径，沿用最终 2× 输出，完成适配 HAT 的分块验证。
+- 接入 BiRefNet Lite 与 HR-matting，按官方预处理和 Alpha 输出语义验证 Lite 的 CPU / DirectML 和 HR-matting 的 CPU、效果、体积和资源占用；HR 选项明确标注 CPU。
+- 九款正式模型统一驱动界面、下载、就绪判定和 `model prepare` / `model sync`；清理退役源码、导出器、专用依赖、缓存及远端对象。
+
+## Capabilities
+
+### New Capabilities
+
+- `ai-model-tiers`：三类各三款模型、默认选择及初始化下载行为。
+- `background-removal-models`：三款背景模型的选择、推理、Alpha 契约和资源生命周期。
+- `hat-upscale`：HAT Sharper 的小体积 ONNX、2× 输出和分块处理。
+- `model-asset-retirement`：正式模型资产准备、镜像校验和退役对象清理。
+
+### Modified Capabilities
+
+当前 `openspec/specs` 尚无已发布 capability。本提案承接已有 MoGe-3、2× Upscale 和 HDR 输入实现，以本次模型矩阵确定后续正式选项。
+
+## Impact
+
+- `server/model_catalog.py`、`preferences.py`、`properties.py`、AI Setup 与相关 Operator：模型分类、默认值和下载选项。
+- `server/models`、`server/model_manager.py`、背景移除 Job：模型适配、推理分派、会话复用与释放。
+- `tools/models`、`pyproject.toml`、`uv.lock` 及相关测试：可复现导出、专用依赖清理和资产校验。
+- 项目模型目录、开发缓存与 `omoolab-r2:ai-models`：新资产发布和退役对象清理。
+- 本次生成规划文件；实施验证结果记录在 change 内，运行时依赖沿用现有 ONNX 体系。
--- a/openspec/changes/simplify-ai-model-tiers/retirement-results.json
+++ b/openspec/changes/simplify-ai-model-tiers/retirement-results.json
@@ -0,0 +1,267 @@
+{
+  "results": [
+    {
+      "kind": "r2",
+      "path": "DA3-BASE/model.onnx",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "DA3-SMALL/model.onnx",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "moge-2-vitl-normal-onnx/model.onnx",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "pisa-sr/LICENSE-APACHE.txt",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "pisa-sr/LICENSE-MODEL.txt",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "pisa-sr/NOTICE.txt",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "pisa-sr/decoder.onnx",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "pisa-sr/encoder.onnx",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "pisa-sr/noise.npy",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "pisa-sr/unet-full.onnx",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "pisa-sr/unet-pixel.onnx",
+      "removed": true
+    },
+    {
+      "kind": "r2",
+      "path": "safmn-real-x4/safmn-real-x4.onnx",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "D:\\Projects\\AnyImage\\models\\DA3-BASE",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "D:\\Projects\\AnyImage\\models\\DA3-SMALL",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "D:\\Projects\\AnyImage\\models\\moge-2-vitl-normal-onnx",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "D:\\Projects\\AnyImage\\models\\safmn-real-x4",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "D:\\Projects\\AnyImage\\models\\pisa-sr",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.anyimage\\models\\moge-2-vitl-normal-onnx",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.anyimage\\models\\safmn-real-x4",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.anyimage\\models\\pisa-sr",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3-BASE",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3-GIANT-1.1",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\.locks\\models--depth-anything--DA3-GIANT-1.1",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3-LARGE-1.1",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3-SMALL",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3NESTED-GIANT-LARGE-1.1",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--mindqtrl--DA3-LARGE-1.1-ONNX",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\.locks\\models--mindqtrl--DA3-LARGE-1.1-ONNX",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--Ruicheng--moge-2-vitl",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--Ruicheng--moge-2-vitl-normal",
+      "removed": true
+    },
+    {
+      "kind": "local",
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--Ruicheng--moge-2-vitl-normal-onnx",
+      "removed": true
+    }
+  ],
+  "remote_remaining": [],
+  "retained_changed": [],
+  "retained_objects": [
+    {
+      "Path": "BEN2-ONNX/onnx/model_fp16.onnx",
+      "Name": "model_fp16.onnx",
+      "Size": 219121675,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-08-14T09:16:42.426271600+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "birefnet-hr-matting/LICENSE.txt",
+      "Name": "LICENSE.txt",
+      "Size": 1066,
+      "MimeType": "text/plain; charset=utf-8",
+      "ModTime": "2026-09-10T18:25:27.626890000+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "birefnet-hr-matting/model.onnx",
+      "Name": "model.onnx",
+      "Size": 529467341,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-09-10T18:25:26.979196800+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "birefnet-lite/LICENSE.txt",
+      "Name": "LICENSE.txt",
+      "Size": 1066,
+      "MimeType": "text/plain; charset=utf-8",
+      "ModTime": "2026-09-10T18:14:05.058461000+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "birefnet-lite/model.onnx",
+      "Name": "model.onnx",
+      "Size": 112968598,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-09-10T18:14:04.582138300+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "hat-gan-x4-sharper/LICENSE.txt",
+      "Name": "LICENSE.txt",
+      "Size": 11342,
+      "MimeType": "text/plain; charset=utf-8",
+      "ModTime": "2026-09-10T16:58:24.978566500+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "hat-gan-x4-sharper/model.onnx",
+      "Name": "model.onnx",
+      "Size": 45874438,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-09-10T16:58:24.123871100+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "moge-2-vitb-normal-onnx/model.onnx",
+      "Name": "model.onnx",
+      "Size": 419411850,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-08-14T00:42:46.699086800+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "moge-2-vits-normal-onnx/model.onnx",
+      "Name": "model.onnx",
+      "Size": 140852051,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-08-14T00:27:11.713132700+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "moge-3-vitl-onnx/backbone.onnx",
+      "Name": "backbone.onnx",
+      "Size": 1324190318,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-09-10T10:38:13.252671700+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "moge-3-vitl-onnx/refiner.onnx",
+      "Name": "refiner.onnx",
+      "Size": 157729628,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-09-10T10:38:07.481681400+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "realesr-general-wdn-x4v3/realesr-general-wdn-x4v3.onnx",
+      "Name": "realesr-general-wdn-x4v3.onnx",
+      "Size": 4867419,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-08-23T00:00:31.076651000+08:00",
+      "IsDir": false
+    },
+    {
+      "Path": "realesrgan-x4plus/realesrgan-x4plus.onnx",
+      "Name": "realesrgan-x4plus.onnx",
+      "Size": 67051618,
+      "MimeType": "application/octet-stream",
+      "ModTime": "2026-08-23T00:02:33.710120800+08:00",
+      "IsDir": false
+    }
+  ]
+}
--- a/openspec/changes/simplify-ai-model-tiers/retirement.json
+++ b/openspec/changes/simplify-ai-model-tiers/retirement.json
@@ -0,0 +1,131 @@
+{
+  "remote": "omoolab-r2:ai-models",
+  "local": [
+    {
+      "path": "D:\\Projects\\AnyImage\\models\\DA3-BASE",
+      "owner": "D:\\Projects\\AnyImage\\models"
+    },
+    {
+      "path": "D:\\Projects\\AnyImage\\models\\DA3-SMALL",
+      "owner": "D:\\Projects\\AnyImage\\models"
+    },
+    {
+      "path": "D:\\Projects\\AnyImage\\models\\moge-2-vitl-normal-onnx",
+      "owner": "D:\\Projects\\AnyImage\\models"
+    },
+    {
+      "path": "D:\\Projects\\AnyImage\\models\\safmn-real-x4",
+      "owner": "D:\\Projects\\AnyImage\\models"
+    },
+    {
+      "path": "D:\\Projects\\AnyImage\\models\\pisa-sr",
+      "owner": "D:\\Projects\\AnyImage\\models"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.anyimage\\models\\moge-2-vitl-normal-onnx",
+      "owner": "C:\\Users\\icrdr\\.anyimage\\models"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.anyimage\\models\\safmn-real-x4",
+      "owner": "C:\\Users\\icrdr\\.anyimage\\models"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.anyimage\\models\\pisa-sr",
+      "owner": "C:\\Users\\icrdr\\.anyimage\\models"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3-BASE",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3-GIANT-1.1",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\.locks\\models--depth-anything--DA3-GIANT-1.1",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\.locks"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3-LARGE-1.1",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3-SMALL",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--depth-anything--DA3NESTED-GIANT-LARGE-1.1",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--mindqtrl--DA3-LARGE-1.1-ONNX",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\.locks\\models--mindqtrl--DA3-LARGE-1.1-ONNX",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\.locks"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--Ruicheng--moge-2-vitl",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--Ruicheng--moge-2-vitl-normal",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    },
+    {
+      "path": "C:\\Users\\icrdr\\.cache\\huggingface\\hub\\models--Ruicheng--moge-2-vitl-normal-onnx",
+      "owner": "C:\\Users\\icrdr\\.cache\\huggingface\\hub"
+    }
+  ],
+  "objects": [
+    {
+      "path": "DA3-BASE/model.onnx",
+      "size": 412856697
+    },
+    {
+      "path": "DA3-SMALL/model.onnx",
+      "size": 105484029
+    },
+    {
+      "path": "moge-2-vitl-normal-onnx/model.onnx",
+      "size": 1324265014
+    },
+    {
+      "path": "pisa-sr/LICENSE-APACHE.txt",
+      "size": 11358
+    },
+    {
+      "path": "pisa-sr/LICENSE-MODEL.txt",
+      "size": 14206
+    },
+    {
+      "path": "pisa-sr/NOTICE.txt",
+      "size": 1081
+    },
+    {
+      "path": "pisa-sr/decoder.onnx",
+      "size": 99084589
+    },
+    {
+      "path": "pisa-sr/encoder.onnx",
+      "size": 68426712
+    },
+    {
+      "path": "pisa-sr/noise.npy",
+      "size": 32896
+    },
+    {
+      "path": "pisa-sr/unet-full.onnx",
+      "size": 1732713007
+    },
+    {
+      "path": "pisa-sr/unet-pixel.onnx",
+      "size": 1732713007
+    },
+    {
+      "path": "safmn-real-x4/safmn-real-x4.onnx",
+      "size": 22657477
+    }
+  ]
+}
--- a/openspec/changes/simplify-ai-model-tiers/specs/ai-model-tiers/spec.md
+++ b/openspec/changes/simplify-ai-model-tiers/specs/ai-model-tiers/spec.md
@@ -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** 返回未知或不可用模型错误，不加载或下载退役资源
--- a/openspec/changes/simplify-ai-model-tiers/specs/background-removal-models/spec.md
+++ b/openspec/changes/simplify-ai-model-tiers/specs/background-removal-models/spec.md
@@ -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 语义
--- a/openspec/changes/simplify-ai-model-tiers/specs/hat-upscale/spec.md
+++ b/openspec/changes/simplify-ai-model-tiers/specs/hat-upscale/spec.md
@@ -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** 返回包含模型和设备上下文的资源错误，提示减小分析输入或选择更轻量模型
--- a/openspec/changes/simplify-ai-model-tiers/specs/model-asset-retirement/spec.md
+++ b/openspec/changes/simplify-ai-model-tiers/specs/model-asset-retirement/spec.md
@@ -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** 记录成功与失败目标，报告未完成项，并在复查全部通过前保持退役任务未完成
--- a/openspec/changes/simplify-ai-model-tiers/tasks.md
+++ b/openspec/changes/simplify-ai-model-tiers/tasks.md
@@ -0,0 +1,41 @@
+## 1. 核对基础与验证 BiRefNet
+
+- [x] 1.1 核对当前 MoGe-3、2× Upscale、HDR 和工具 CLI 的真实调用链，记录受影响入口及工作区已有修改，确认模型矩阵与相关 change 的衔接。
+- [x] 1.2 固定 BiRefNet Lite 的上游版本、权重和许可证，完成隔离环境的可复现导出；交付通过结构检查的 ONNX、来源、大小和 SHA-256。
+- [x] 1.3 固定 BiRefNet HR-matting 的上游版本、权重和许可证，完成隔离环境的可复现导出；交付通过结构检查的 ONNX、来源、大小和 SHA-256。
+- [x] 1.4 在运行前固定 BiRefNet 数值容差和样图，对 Lite 执行原始实现与 CPU / DirectML 的逐图比较，对 HR-matting 执行 CPU 比较并记录 DirectML 失败及用户确认的 CPU 限制；验证连续 Alpha、尺寸、有限值及官方预处理一致性，记录结果。
+- [x] 1.5 用同一组发丝、毛绒、细杆、薄纱与普通主体样图比较 Lite、BEN2 和 HR-matting，记录下载体积、加载/热推理耗时、峰值内存/显存及边缘效果；验证 Lite 满足轻量默认门槛。
+
+## 2. 固化 HAT Sharper 资产
+
+- [x] 2.1 将已验证的 Sharper 导出流程整理到 `tools/models`，固定源码和 checkpoint，采用 FP16 权重存储、FP32 运算；验证完整资产小于 60 MB 并记录可复现来源与哈希。
+- [x] 2.2 对正式导出资产复跑 CPU / DirectML 数值对照，检查全部有限且符合 `hat-upscale` 预设门槛；交付样图、误差、加载和热推理记录。
+- [x] 2.3 以 256 像素 tile、48 像素边距验证 HAT 拼接，覆盖跨缝纹理、细线、小图、奇数尺寸和透明图；交付与整图参考的对照，确认最终 2× 无可见拼接直线。
+
+## 3. 统一三档目录与默认设置
+
+- [x] 3.1 将正式目录调整为九款模型及对应分类、用途和真实资源信息；更新目录与下载测试，验证每类恰好三款且保留顺序一致。
+- [x] 3.2 将默认模型及扩展偏好读取统一到对应入口，背景默认改为 Lite；测试有效旧选择保留、退役偏好归一和直接提交退役 Job 键报错。
+- [x] 3.3 更新 AI Setup、默认所需模型、离线目录与下载界面；测试仅三个默认模型就绪时初始化完成，非默认模型按需提示下载。
+
+## 4. 接入背景移除与超分
+
+- [x] 4.1 将背景移除公共编排、模型资源分类和缓存接口按业务职责整理，保留各模型专用适配器；运行会话复用、模型/设备切换和关闭释放测试。
+- [x] 4.2 接入 BiRefNet 官方输入和 Alpha 后处理，更新 Job、Operator、进度文案与实际模型选择；测试三款真实分派、有限连续 Alpha 和无效预测失败。
+- [x] 4.3 让三款背景模型贯穿静态、多帧、源 Alpha 和 HDR Alpha-only 流程；运行对应行为测试，验证 HDR RGB 保持以及取消/失败清理。
+- [x] 4.4 将 HAT Sharper 接入共享超分及模型专属分块配置，保持两款 Real-ESRGAN 的已有配置；测试准确 2× 尺寸、透明度、多帧、取消和资源错误。
+- [x] 4.5 运行真实背景移除与 HAT Job，验证模型切换、重复执行和服务关闭后的资源状态；记录正式输入准备和输出路径的端到端结果。
+
+## 5. 清理退役实现与准备发布
+
+- [x] 5.1 清理 DA3 现行残留及 MoGe-2 L、SAFMN、PiSA-SR 的专用实现、旧导出器、构建登记和测试；沿真实调用链检查旧引用，确认保留模型仍有有效行为覆盖。
+- [x] 5.2 清理退役模型的专用依赖并同步必要锁文件，核对 Manifest 和打包清单；运行依赖及打包内容测试，确认新增导出依赖隔离于正式 Runtime。
+- [x] 5.3 将三款新资产纳入 `model prepare` / `model sync`，执行 `uv run model prepare`；验证九款模型完整文件集合、损坏文件报错和校验信息。
+- [x] 5.4 运行全部相关测试及 `uv run pytest`，确认正常退出；检查最终差异和注册清单，确保原有有效功能与其他工作区修改完整。
+
+## 6. 镜像发布与退役对象清理
+
+- [x] 6.1 执行 `uv run model sync` 发布正式资产，从实际下载地址回读新模型并校验大小和哈希；确认下载后的模型可就绪和执行。
+- [x] 6.2 枚举 DA3 全部现存变体、MoGe-2 L、SAFMN、PiSA-SR 的本地模型目录、开发缓存及 R2 对象；交付具体删除清单，验证本地绝对路径和远端前缀归属。
+- [x] 6.3 在新资产验收后按清单删除退役对象，逐项复查本地与远端状态；确认保留模型和其他资源完整，失败项保留为未完成任务。
+- [x] 6.4 将实际模型矩阵、导出来源与哈希、真实推理和质量记录、测试结果及镜像清理结果写入本 change 的验证记录，确认各项任务的验收证据齐全。
--- a/openspec/changes/simplify-ai-model-tiers/validation.md
+++ b/openspec/changes/simplify-ai-model-tiers/validation.md
@@ -0,0 +1,94 @@
+# 实施验证
+
+## 基线与入口
+
+开始实施时 `git status --short` 仅有本 change 未跟踪，生产代码无已有未提交修改。
+
+- Geometry：Operator → Geometry Job → ModelManager → MoGe-2 / MoGe-3 ONNX；保留 MoGe-3 三步细化。
+- Upscale：Operator → Upscale Job → `models/upscale.py` → ONNX 分块 → Lanczos 2× 与源 Alpha 合成。
+- 背景移除：Operator 当前硬编码 BEN2；Job 调用 `models/ben2.py`，HDR 已使用 Alpha-only 返回，输入准备复用 `common`。
+- 模型入口：`preferences.py`、`properties.py`、`server/model_catalog.py`、`server/model_manager.py`；背景资源分类当前为 `ben2`。
+- 资产入口：`uv run model prepare` / `uv run model sync` → `tools/models/cli.py`；上传为逐文件 `rclone copyto`。
+- 当前生产源码未发现 DA3 实现；本地及 R2 残余仍需枚举。历史 OpenSpec 记录不作为现行调用链。
+
+衔接 `add-moge3-model`、`add-pisa-sr-two-times-upscale`、`add-ben2-hdr-support`、`organize-tool-cli`，模型成员以本 change 为准。
+
+## BiRefNet 来源
+
+| 模型 | 官方权重与源码仓库 | 固定 revision |
+|---|---|---|
+| Lite | ZhengPeng7/BiRefNet_lite | aa62cd87eafb9cc43056d08ef3615a14628b831d |
+| HR-matting | ZhengPeng7/BiRefNet_HR-matting | 5d6b6f8adcb5b417c871b1d84ceaae9871355b7f |
+
+两款模型卡标注 MIT，正式导出结构检查通过，许可证随模型发布。
+
+Lite 固定权重 SHA-256：`4417d89795250e698c3cb0ae8df15743810065f646f48a694fdfa7ca052d0815`；HR：`a5a4de698739ea5e0e8bbab28e1b293dde95092b87a442d566cbc585c53cef55`。许可证固定到 BiRefNet revision `ebcc0bc8ec7fe919cec829f2dea656b3078acddc`，1,066 bytes，SHA-256 `92a7089e0915fc32bc40067560b398f1e6a7a5958abd7d04eda393629a5acefb`。
+
+数值测试开始前固定 Alpha 容差（激活后、浮点范围 0–1）：FP32 ONNX 对原始 FP32 实现的 MAE ≤ 0.0002、P99 ≤ 0.002、Max ≤ 0.01；压缩权重资产 MAE ≤ 0.002、P99 ≤ 0.02、Max ≤ 0.1。所有输出必须有限、尺寸准确、处于 0–1。容差不得根据测得误差放宽。
+
+固定样图使用作者官方演示中的 Helicopter、Jewelry、My_Love、My_MiSheng、Windmill，另补发丝、毛绒及薄纱覆盖；记录来源与逐图结果。性能测量使用同一批源图、同一 Runtime/设备并分开运行模型。
+
+补充 Alpha Matting Evaluation 官方测试集中的 `net.png`（薄网纱）和 `plasticbag.png`（透明塑料）；来源 `https://www.alphamatting.com/datasets.php`，仅用于本地评估。
+
+Lite 通过七图 CPU / DirectML 对照的正式资产：112,968,598 bytes，SHA-256 `6e2a9844c57b080e95a402722ddcae5660e6f254a04d3e003347f06f587b71fe`。FP16 权重存储与完全无损的静态常量压缩，FP32 运算。最大误差 0.041951，符合预设门槛。CPU 热推理约 2.85 秒；同输入 BEN2 CPU 约 3.84–3.90 秒，Lite 下载成本更低且 CPU 更快。正式 DirectML 与端到端结果见下表。
+
+HR 的 DirectML 最后一层解码器有稳定偏差；用户于 2026-09-10 确认保留 HR，暂时仅支持 CPU。正式资产使用原始 GridSample 结构和 FP16 权重存储，不采用失败的分块或混合精度实验。HR 选项、实际 Job 设备和缓存键均明确使用 CPU。
+
+## 公共背景编排
+
+`models/background.py`、`get_background` / `release_background` 与资源分类 `background` 已统一。保留 `onnx_ben2.py` 专用适配器。三款模型已通过静态、多帧、连续 Alpha、源 Alpha 合成和缓存切换测试；既有 HDR RGB 保持、取消和失败清理测试通过。
+
+## 正式背景模型验收
+
+正式导出命令：`uv run --script tools/models/birefnet_export.py --variant lite --destination models/birefnet-lite`；HR 使用 `--variant hr-matting --destination models/birefnet-hr-matting`。导出器固定上游代码、权重与许可证。Lite 重复导出哈希完全相同。
+
+| 模型 | ONNX bytes | SHA-256 |
+|---|---:|---|
+| Lite | 112968598 | `6e2a9844c57b080e95a402722ddcae5660e6f254a04d3e003347f06f587b71fe` |
+| HR-matting | 529467341 | `b3abc34843a4d96f669ca9fb1a2a16b3417ab8b91c987573fdbda36d20514133` |
+
+ORT 1.24.4；DirectML 使用 RTX 5070 Ti。Lite 正式资产的七图 CPU / DirectML 误差通过既定门槛；最终 DirectML 记录确认实际加载 DmlExecutionProvider。HR 七图 CPU 与原始 FP32 对照全部通过，最差 MAE 0.000001987、P99 0.000020504、Max 0.000103504；输出均为有限的 2048×2048 连续 Alpha，生产适配器恢复源图尺寸。
+
+| 模型 / 设备 | 加载秒 | 七图热推理秒 | 峰值工作集 GB | 峰值进程提交 GB |
+|---|---:|---:|---:|---:|
+| Lite / DirectML | 2.728 | 0.05895–0.05961 | 0.802 | 6.729 |
+| BEN2 / DirectML | 1.154 | 0.11591–0.11801 | 0.604 | 6.519 |
+| HR / CPU | 4.318 | 21.718–23.437 | 19.278 | 22.596 |
+
+Lite 与 BEN2 用同一七图、同一 Runtime 配置串行运行，每图三次，表中取每图最后一次。HR 每图两次，CPU 配置为八线程。工作集与提交量来自 Windows 进程计数器，不将其表述为独立显存测量。Lite 满足体积更小且热推理更快的默认门槛；其加载和峰值内存并不全面优于 BEN2。
+
+视觉检查 `.model-cache/birefnet/quality-1.png`、`quality-2.png`：三款均能提取人物、猫、直升机和风车细杆；HR 更明显保留薄网纱和透明塑料的中间透明度，猫须细节更完整。普通珠宝场景 HR 会残留叶片背景，Lite / BEN2 的主体分离更干净。第三档表示高分辨率 matting 用途，不保证对所有主体都更好。源图与逐图 Alpha/PNG、耗时/误差 JSON 保存在 `.model-cache/birefnet`。
+
+## 集成与回归
+
+- 三类各三款，共九款；默认集合为 MoGe S、Lite、WDN。默认值由目录统一提供，偏好读取集中于 `preferences.py`。保留模型沿用原 Blender 枚举编号，有效 BEN2 / x4plus / MoGe 选择保留，退役偏好归一到默认，直接提交退役 Job 键报错。
+- `uv run model prepare` 成功，九款模型共 13 文件全部通过大小和 SHA-256 校验。
+- 真实 JobServer：Lite 连续两次、BEN2、HR CPU、HAT 连续两次全部成功，Alpha 源尺寸/有限范围及 HAT RGBA 准确 2× 输出检查通过。Lite 第二次加载 0 ms；HR 完整 Job 24.08 秒；HAT 两次完整 Job 3.41 / 0.60 秒。服务关闭后全部资源键为空。记录：`.model-cache/tier-job-validation/results.json`。
+- `uv run pytest -q --tb=short`：1227 passed，51 subtests passed，178.55 秒，正常退出。随后补齐退役偏好持久化归一，对应偏好与初始化测试再次通过：23 passed、2 subtests passed。曾因本地 bpy 安装缺少资源而失败，重新安装锁定的 bpy 4.5.3 后通过；渲染测试明确启用 Cycles。`pyproject.toml`、`uv.lock`、Manifest 未改变，新增模型导出依赖位于隔离脚本，正式 Runtime 无新增依赖。
+- 实施过程中另有节点源文件、节点测试和 `.blend` 资产并行修改；保留这些变化，本任务未修改对应节点逻辑。
+
+## 镜像与退役清单
+
+`uv run model sync` 正常完成。三款新模型共六个文件从 `https://models.omoolab.xyz` 实际地址回读，大小、SHA-256 和就绪检查全部通过；回读资产依次通过 Lite DirectML、HR CPU、HAT DirectML 生产适配器推理，关闭后缓存为空。完整 URL、大小、哈希与执行结果见 `mirror-validation.json`。
+
+精确清理清单见 `retirement.json`：19 个本地模型/专用缓存目录、12 个 R2 对象。每个本地绝对路径已检查属于其声明的模型或缓存根目录。全部逐项删除并复查不存在，失败项为零；镜像保留的 13 文件大小与删除前一致，项目模型目录只剩九款。用户目录保留的 BEN2、WDN、x4plus 哈希复核通过。结果见 `retirement-results.json`。
+
+清理后的 `uv run model prepare` 再次成功，九款模型共 13 文件大小和 SHA-256 全部通过。OpenSpec strict 校验通过，本次修改的 `git diff --check` 通过。
+
+## HAT Sharper 正式导出
+
+`uv run --script tools/models/hat_export.py --destination .model-cache/hat-sharper-export --checkpoint <已验证官方权重>` 成功退出。
+
+- 上游：XPixelGroup/HAT，revision `1638a9a822581657811867bf670717f8371fc3e5`。
+- Checkpoint SHA-256：`5800b67136006eb8cab3b4ed7c8d73b6a195bb18e6cc709b674f9aa069c00271`，严格加载 `params_ema`。
+- ONNX：45,874,438 bytes，SHA-256 `032d8b03c704220a08d91465a822aca252c1d6e63db20c3cf23c5fb67f3d2366`，与原实验资产完全相同。
+- Apache 2.0 许可证随资产保存，完整资产小于 60 MB。结构检查通过。
+- 导出时去除 BasicSR 训练注册器，初始化使用等价 PyTorch 工具；官方 forward 保持不变。FP16 initializer 在 FP32 图计算前 Cast 恢复。
+
+正式资产 ORT 1.24.4、CPU / DirectML 各 4 张 256×256 样图（bread、village、indoor、indoor_grain）逐图对照全部通过；每图执行两次。最差 MAE 0.000190、P99 0.000613、Max 0.007376，全部有限。CPU 加载 1.19 秒、热推理 14.43–14.90 秒；本次 DirectML 热推理 0.787–0.811 秒。性能为当前机器本次运行记录，不将历史不同负载下的耗时作为同条件对照。
+
+详细记录：`.model-cache/hat-sharper-export/numerics.json`；复测脚本 `.model-cache/validate_hat_formal.py`；原始 PyTorch 参考与样图见 `.model-cache/hat-validation` 和原实验临时目录。
+
+HAT 拼接验收：321×163 自然屋顶纹理、跨缝细线、渐变 Alpha，另有 7×5 和 1×1 小图。原始 PyTorch 整图使用与分块一致的反射边界，DirectML 用 256 tile / 48 border，均缩至最终 2×。检查整图参考、分块结果和 8 倍差异图，未见拼接直线。细线图接缝带 MAE 为 0.223（8-bit），与整图 MAE 0.213 接近。
+
+对照图和逐图记录：`.model-cache/hat-sharper-export/seams/*-comparison.png`、`results.json`；脚本 `.model-cache/hat_seams.py`。参考图不是不同构图或不同缩放的替代品。