nan
0c8d3a8988
- Updated version in pyproject.toml and blender_manifest.toml to 0.11.2. - Enhanced uv executable path documentation in client.py. - Added inference_mode parameter to reconstruct_request function in client.py. - Implemented uv download functionality in install_env.py with improved error handling and checksum verification. - Modified install_uv function to download and extract uv binary instead of using bundled version. - Updated job progress handling in operators.py to track progress stages. - Improved download progress reporting in worker.py and adjusted related tests. - Refactored tests to accommodate changes in status reporting and model downloading. - Removed vendor.lock.toml as part of the cleanup process.
6.0 KiB
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：
~/.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贡献算子，或注入内存高效的注意力算子； - 若未来需要统一坐标系的视频重建，可按小窗口分批推理，再对齐相机位姿与深度尺度。