AnyImage/docs/service.md

AI Service

AI Service

Environment 指磁盘上已安装的 Python、依赖及模型执行组件；Service 是由 Environment 启动、接收 Blender 任务的 常驻 HTTP 进程。manifest.json 记录当前 Environment 的安装信息；Service 的 /health 返回进程状态和 实例标识。项目发布前不维护安装清单或任务协议的兼容版本号。

Extension 本身不包含 Torch。Install Environment 使用 uv 创建独立 Python 3.12 环境，并安装。机器上即使没有安装 uv 或 Python 也没关系：安装程序由 Blender 自带的 Python 启动，缺 uv 时会解包扩展内置的对应平台二进制，再用它下载 Python 3.12 与全部依赖。uv 会缓存在扩展存储目录下，后续安装直接复用。 安装不做网络预检，直接开始；环境变量仍可切换镜像与代理：PIP_INDEX_URL（PyPI 镜像）、 SNAPFORM_TORCH_INDEX（PyTorch 索引）、HF_ENDPOINT（Hugging Face 镜像）、 HTTP(S)_PROXY/ALL_PROXY（代理）。未指定 PyPI 镜像时， pip 安装失败会自动依次重试镜像（清华、阿里云）；模型下载不预探测，官方 Hugging Face 失败后自动回退 OmooLab R2（models.omoolab.xyz），并校验文件大小和 SHA-256。 GitHub 不再参与安装：DA3、BEN2、uv 已内置，缺少内置文件会直接报错提示重新安装，不再下载兜底。 单独下载模型时遵循同样的顺序：Hugging Face（可用 HF_ENDPOINT 指定其他入口）失败后自动切换到 OmooLab R2，不再使用 ModelScope。 Windows 上代理若只在系统设置里而未写入环境变量，安装程序会尝试自动从系统代理注入子进程。

• PyTorch 2.9.1
• TorchVision 0.24.1
• xFormers 0.0.33.post2（与 PyTorch 2.9.1 对应，仅 Windows/Linux；macOS 无 wheel 自动跳过）
• 固定到已验证 commit 的 Depth Anything 3
• 固定到已验证 commit 的 BEN2
• FastAPI 0.139.2 与 Uvicorn 0.51.0
• DA3 与 BEN2 源码包随扩展打包，安装时复制到临时目录后由 uv 本地安装，完成后立即清理 （无需访问 GitHub）；SnapForm 直接调用 DA3 底层 export 接口，gs_ply 导出不会触发 gs_video 渲染，因此不需要 gsplat 与 C++ 编译工具链
• vendor/ 是不进入 Git 的本地缓存；vendor.lock.toml 固定下载 URL、commit/version 与 SHA-256，patches/<包名>/ 进入 Git 并存放 SnapForm 对源码的覆盖文件（移除 xformers 硬依赖、export 入口改懒加载、 射线位姿的 3×3 QR 分解在 MPS 上改走 CPU）， pack.py 打包时自动套入官方包，扩展 zip 内才是修补后的版本；更新上游只需替换官方包 并核对覆盖文件是否仍适用
• addict 2.4.0（补充 DA3 上游包元数据暂未声明的运行依赖）

安装 Environment 时会自动选择 PyTorch 后端：检测到 NVIDIA 驱动则安装 CUDA 12.8 版本，否则安装 CPU 版；macOS 始终安装 CPU 版 PyTorch（MPS 包含其中）。CPU 可以用于验证，但实际推理通常很慢。 Extension Preferences 的 Device 决定正式功能的推理设备，默认取本机最快的 CUDA/MPS，否则 CPU；Debug 面板的 Debug Device 只影响 Debug 任务。两处设备选项都只列出本机支持的设备： Windows 不显示 MPS，机器上没有可用 NVIDIA 驱动时不显示 CUDA。Environment 安装完成时会检测真实 可用的设备并写入 manifest.json，设备列表以该检测结果为准。 CUDA 12.8 的 PyTorch wheel 自带 CUDA 运行库，无需安装 CUDA Toolkit；只需要 NVIDIA 驱动 ≥ 570（数据中心显卡可用更老驱动）。驱动不满足或没有 NVIDIA 显卡时， 设备会自动回退到 CPU（macOS 为 MPS），只有显式选择 CUDA 才会报错。

macOS（Apple Silicon）会自动从 PyPI 安装 CPU 版 PyTorch，推理设备默认使用 MPS （Apple Metal）加速，也可以在设备选项里切换 CPU。PyTorch 自 2.3 起不再提供 Intel Mac（x86_64）轮子，Intel Mac 暂不支持。DA3 射线位姿估计中的 3×3 QR 分解在 MPS 上尚未实现，SnapForm 的覆盖文件会单独把该分解放到 CPU 执行，其余推理仍走 MPS。

Extension 启用后只会查找已有的共享 Service，不会主动启动新进程。第一次执行 AI 操作或在侧边栏 手动点击 Start 时才会启动 Service。Service 只绑定回环地址，并让操作系统分配动态端口；第一个实例把 端口、进程和随机 Token 写入 service.json，其余 Blender 通过标准库 urllib.request 连接同一个 Service。service.lock 保证同一 Storage Root 同时只有一个 Service，Token 则阻止同机其他进程直接调用接口。Service 全局同时只执行一个 AI 任务。

每个 Blender 会注册独立客户端并每 5 秒发送心跳。正常关闭 Blender 时先注销自身；如果当前 Service 就是由这个 Blender 启动的，会直接终止它，无需等待。异常退出的客户端会在 10 秒后过期；Service 在最后一个客户端离开后仍会保留模型缓存等待 20 秒再退出，作为 Service 由其他进程启动等场景的兜底。 取消任务不会重启 Service，并会保留已经加载的模型； 如果取消发生在一次不可中断的 Torch 调用中，任务会在该调用返回后的最近检查点结束。

侧边栏 AI Service 面板以 Running (Clients: n) 表示空闲服务，以 Running (Busy) 表示正在执行任务， 并显示缓存模型和活动任务。Blender 完成结果导入时会立即释放当前任务对应的本地 Busy 快照，无需等待 下一次 Service 轮询。空闲且只有当前 Blender 连接时，可以清理模型缓存、重启或停止 Service； 多客户端或任务执行期间不会允许破坏共享服务。

BEN2 在首次使用后保持加载；DA3 保留最近使用的一个模型。切换 DA3 模型时会释放旧模型；加载时如果 显存不足，会先释放另一类缓存模型并重试。

Environment Manifest Revision 变化时，旧 Environment 需要重新执行 Install Environment。 Service 的启动和崩溃日志写入 ~/.snapform/service.log。

Environment、模型和任务结果默认保存在用户主目录的 ~/.snapform：

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

models/ 下每个模型一个文件夹，命名统一带前缀：DA3 为 da3_*（如 da3_small、da3_base）， BEN2 为 ben2_*（如 ben2_base）。旧版无前缀的 DA3 文件夹会在首次使用时自动改名为新名称。

不同 Blender 版本安装相同 Extension 后会共用这个目录。也可以在 Extension Preferences 的 Storage Root 中修改共享位置。不要把模型写入 Extension 安装目录， 因为该目录可能只读，并且升级时会被替换。不要同时从多个 Blender 实例执行 Install Environment；Service、任务队列和模型读取可以共享。