# AI Service

## 运行架构

SnapForm 在独立的 Python 3.12 Environment 中运行常驻 HTTP Service，Blender 只通过标准库 `urllib.request` 提交任务，不把 AI 运行库载入 Blender Python。Service 只监听 `127.0.0.1`，请求使用随机 Token；同一 Storage Root 由 `service.lock` 保证只有一个实例。

Environment、模型和任务结果默认保存在 `~/.snapform`：

```text
~/.snapform/
├── .venv/
├── models/
├── jobs/
├── manifest.json
├── service.log
├── service.json       # Service 运行时存在
└── service.lock       # Service 运行时持有
```

不同 Blender 版本可共享此目录。也可以在 Extension Preferences 的 `Storage Root` 中修改位置。

## ONNX-only Environment

扩展不内置 `uv` 可执行文件或 AI 运行库。`Install Environment` 首先下载固定版本的 uv，校验 SHA-256 后解压到共享 Storage Root，再用它创建环境并安装：

- ONNX Runtime 1.24.4；Windows 使用 `onnxruntime-directml`
- NumPy 2.4.2、Pillow 12.1.1、PyAV 17.0.0、trimesh 4.11.2
- FastAPI 0.139.2、Uvicorn 0.51.0、huggingface-hub 1.4.1

运行环境不安装 PyTorch、TorchVision、xFormers，也不安装 DA3、MoGe、BEN2 或 utils3d 的 Python 源码包。模型推理和 SnapForm 所需的相机、点云、网格后处理均由 ONNX Runtime、NumPy 与内部实现完成。

Windows 当前发行环境提供 DirectML 与 CPU；`Auto` 优先使用 `DmlExecutionProvider`。显式指定不可用设备时会安全回退到 CPU。其他平台安装标准 ONNX Runtime，并按可用 provider 选择 CoreML、OpenVINO 或 CPU。

`manifest.json` 记录 Environment 版本、ONNX Runtime 版本、runtime variant 与设备列表。Manifest Revision 改变后需要重新执行 `Install Environment`。

## 模型

所有正式功能都使用 ONNX：

- MoGe-2 ViT-S、ViT-B、ViT-L Normal
- DA3 Small、DA3 Base
- BEN2 Base

首次安装自动下载 `MoGe-2 ViT-S Normal` 与 FP16 `BEN2 Base`，其他模型在 `Models` panel 按需下载。模型按 Hugging Face 仓库末段名称保存在 `~/.snapform/models/`，并保留仓库内部结构。声明了文件清单与校验值的模型会直接走 Hugging Face `resolve` 直链流式下载，跳过文件清单与 ETag 预校验；连接源不可达时使用 3 秒 TCP 与 TLS 建连超时，随后回退到 `https://models.omoolab.xyz/<repository-name>/<relative-path>`，并把 `models_from_r2` 写入 service.json，本次 service 周期内后续模型直接走 R2，不再重复等待 Hugging Face。建连成功后不限制模型文件读取时长。R2 文件会校验大小与 SHA-256。未声明清单的仓库仍使用 `huggingface_hub` 快照下载。可用 `HF_ENDPOINT` 指定 Hugging Face 镜像。

DA3 ONNX 使用模型的 camera decoder 恢复外参与内参；旧版 `Use Ray Pose` 参数只为任务协议兼容保留，不参与 ONNX 推理。MoGe-2 的 metric depth、normal、mask、normalized intrinsics，以及 BEN2 的 Alpha，均在 NumPy 后处理中恢复。


## 安装网络与镜像

安装器直接开始工作，不做阻塞式网络预检。依赖安装默认依次尝试清华、阿里云 PyPI 镜像并以 pypi.org 兜底，也可用 `UV_INDEX_URL` 显式指定。Windows 系统代理会注入子进程；同时支持 `HTTP_PROXY`、`HTTPS_PROXY` 与 `ALL_PROXY`。

uv 默认从 Astral 的 GitHub Release 下载，TCP 与 TLS 建连超过 3 秒时回退到 `https://mirror.omoolab.xyz/uv/<version>/`；镜像建连超时为 15 秒，避免较慢的 TLS 握手再次过早失败。两个来源使用相同的下载速度与连续字节进度显示，并共用固定 SHA-256 校验，建连成功后不限制文件读取时长。下载压缩包只作临时文件，提取完成后删除。模型下载不经过 GitHub。

首次安装按阶段分别显示 0–100%：uv 下载与解压、ONNX Environment 创建与依赖安装、MoGe-2 下载、BEN2 下载。进入下一阶段时进度条归零；若 uv 已存在则省略该阶段并重新编号。

## 生命周期

扩展启用后只查找已有 Service；第一次执行 AI 操作或点击 `Start` 时才启动。每个 Blender 客户端每 5 秒发送心跳，正常关闭时注销。最后一个客户端离开后，Service 保留模型缓存 20 秒再退出。

Service 全局同时执行一个 AI 任务。BEN2 独立缓存，深度模型只保留最近使用的一个；切换模型时释放旧会话。取消任务不会重启 Service，ONNX Runtime 当前调用返回后在最近检查点结束。

启动与崩溃信息写入 `~/.snapform/service.log`。

## 已知限制

DA3 ONNX 的注意力是朴素实现（`MatMul → Softmax → MatMul`），峰值显存与 `(帧数 × 每帧 patch 数)²` 成正比。迁移到 ONNX 前的 PyTorch 版使用 `scaled_dot_product_attention`（`XFORMERS_DISABLED=1`），按块计算注意力分数、不落地完整注意力矩阵，显存近似线性，因此视频能处理几十上百帧；ONNX 导出把 SDPA 回退成朴素注意力，多帧在中高分辨率下会显存爆炸（约 12 帧 @ 1008 即需 ~90 GB）。

Depth Plane 与 Surface 的视频、序列帧转换会复用同一个 ONNX Session 逐帧独立推理，再把结果合并到现有序列输出，因此峰值显存只取决于单帧分辨率。逐帧结果不保留 DA3 的跨视图尺度与相机位姿一致性，适用于当前逐帧动画结构。Debug 多帧输出仍使用联合推理，以保留多视图关系。

联合推理时，`da3_onnx.infer` 会在执行前按 `views × patches` 预估注意力张量，超过 4 GiB 直接报错并提示减少帧数或 Resolution Scale，避免 onnxruntime 报出难以定位的分配失败或 `UnicodeDecodeError`（DirectML 在中文 Windows 下报错信息为 GBK 编码，被 UTF-8 解码掩盖）。

待解决方向：

- 重新导出 DA3 ONNX，使用 ORT 的 `Attention` / `MultiHeadAttention` 贡献算子，或注入内存高效的注意力算子；
- 若未来需要统一坐标系的视频重建，可按小窗口分批推理，再对齐相机位姿与深度尺度。