AnyImage/docs/server.md

Job Server

AnyImage 把 AI 与媒体处理放在独立 Job Server 中运行，使 Blender Python 保持轻量。安装和使用问题见安装与首次配置与常见问题。

架构

flowchart LR
    Blender["Blender Operator"] --> Runtime["JobRuntime"]
    Runtime --> Queue["FIFO Queue"]
    Queue --> Job["AnyImage Job"]
    Job --> Media["Media"]
    Job --> Models["ModelManager"]
    Job --> Geometry["Geometry"]
    Job --> Outputs["Outputs"]
    Outputs --> Directory["Job Directory"]
    Directory --> Blender

每个 Blender 实例拥有自己的 Server 进程，连接绑定到本机随机端口和 Instance ID。多个实例可以共享 Storage Root，但各自维护进程、队列和内存中的模型 Session。

BlendJob 提供 Runtime、HTTP transport、队列、状态和取消协议。AnyImage 的 Operator 负责业务参数，Server Job 负责工作流编排，结果由 Operator 在 Blender 主线程中导入。

Storage Root

默认位置为 ~/.anyimage：

~/.anyimage/
├── .venv/              Python Environment
├── models/             ONNX 模型
├── jobs/               任务产物
├── environment.json    环境声明
├── manifest.json       已安装环境指纹
├── install.log         安装日志
└── server.log          Server 日志

更改 Storage Root 相当于切换整套 Environment、模型和任务数据。目录说明见模型、设备与存储。

模块关系

模块	职责
runtime.py	Environment、Server 生命周期、任务状态与 Storage Root
server/jobs/	按功能编排完整任务
server/media/	图片、视频和序列输入
server/models/	ONNX Session 与模型 Prediction
server/geometry/	投影、网格和 Surface 数据转换
server/outputs/	NPZ、EXR、PNG 与序列文件
model_catalog.py	Blender UI 的模型声明与本地就绪检查
server/model_catalog.py	Server 的模型下载与推理声明

调用方向从 Job 指向媒体、模型、几何和输出模块。模型层返回内存数据，输出层管理文件，Blender 数据始终由 Operator 的 Response 创建。

Environment 与模型

Environment 使用 Python 3.12、ONNX Runtime、NumPy、Pillow、PyAV、trimesh、FastAPI 和 Uvicorn。Windows 使用 DirectML 或 CPU；其他平台根据支持情况使用 CoreML、OpenVINO 或 CPU。

Balloon 的 analyze-balloon Job 会裁切套索输入并清零选区外 RGBA。Contour 用 BEN2 回传最大连通轮廓；Depth 用 MoGe-2 对有效相机距离稳健拟合二维基面，并把物理距离换算为不受绝对拍摄距离影响、未截断的相对深度信号。Job 同时把 MoGe normal 转换为 tangent-space 纹理，铺回原图尺寸并以中性法线填充无效区域。Blender 主线程负责采样深度属性、创建 Base Plane Empty、组装 O Balloon Shape 修改器与 O Balloon Layer 材质。

图片 Box、Lasso 与 Perspective 的可选 Remove Background 使用 extract-image-background Job。它与标准 remove-background Job 共用单图 BEN2 去背景函数，再叠加图片工具专属的 polygon mask、局部 bounds 与透明 Padding。

正式功能支持：

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

首次安装会下载 MoGe-2 ViT-S Normal 与 BEN2 Base。模型保存在 models/，可由多个 Blender 版本共享。Server 缓存 BEN2 和最近使用的一个深度模型，以控制内存占用。

模型下载优先使用 Hugging Face，并以 OmooLab 镜像作为回退。AnyImage 用同一个准备 Operator 封装 BlendJob 安装任务，并按状态显示 Set Up AI Environment… 或 Download Required Models…；Use Mirror 属性只影响 Environment Bootstrap，不改变模型下载策略。Blender UI 通过同一个状态函数检查 Environment 指纹与默认模型文件：缺 Environment 时执行完整安装，只有默认模型缺失时仅提交补齐模型任务。

任务生命周期

Server 在第一次提交 Job 或手动 Start 时启动。任务进入单 Worker FIFO Queue，同一时间执行一个推理、下载或媒体任务。

Job 被接受时，Runtime 创建 opaque ID 和对应目录。进度保存在 Server 内存中，Blender 定期轮询状态。取消会在下载分块或一次 ONNX 调用结束后的检查点生效。

Blender 正常退出或禁用扩展时会停止所属 Server；Server 也监视父进程，在异常退出后自行结束。

Environment 安装发生在 Server 启动前，使用 install.log 记录过程。安装完成后的模型下载是普通 Job，与推理共享队列、进度和取消机制。

DA3 多帧限制

DA3 ONNX 的联合注意力显存随帧数和分辨率快速增长。Depth Plane 动画采用逐帧推理并复用 Session，使峰值显存接近单帧任务；代价是各帧不共享相机位姿与深度尺度。

DA3 Debug 保留联合推理，用于检查模型原始多帧行为。Server 会在预计注意力张量过大时提前报错，此时应减少帧数或 Resolution Scale。