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/               任务产物与 job.log
├── environment.json    环境声明
├── manifest.json       已安装环境指纹
├── install.log         安装日志
└── server.log          带 Job ID 的任务主线与 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 与序列文件
server/model_catalog.py	Blender UI 与 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 铺回原图尺寸，并以中性法线填充无效区域。Blender 主线程负责采样深度属性、创建 Base Plane Empty、组装 O Balloon Shape 修改器，再根据最终评估网格的 TBN 把相机轴 normal 烘成 tangent-space Image 并接入统一的 O Image Layer 材质。

Cutout 的 generate-mesh 不复用上述裁切图作为 AI 输入。套索或 BEN2 结果仅写成几何 mask；MoGe 深度与法线始终分析完整图片。输入为 Upscale 结果时，请求会额外携带放大前的 analysis_input，推理读取该输入，颜色与几何 mask 仍读取当前高清图；Depth Balloon 会先把套索坐标缩放到分析分辨率，再限制有效深度。Blender 材质使用当前 Empty Image 的未裁切副本。

Image Box 与 Lasso 的 Refine Selection 使用 refine-image-mask Job。它与标准 remove-background Job 共用单图 BEN2 函数；Server 在推理前清空 polygon 外的 RGBA，推理后再次应用几何 mask，并返回局部 Alpha 与源图 bounds。Line、Polyline 与 Perspective 不提交 Job。

所有 BEN2 调用都在公共模型入口用输入 Alpha 遮住透明 RGB。Remove Background、Depth Plane、Surface 与 Image Refine 的正式结果保留源 RGB，只采用 BEN2 Alpha；Balloon 同样只消费 BEN2 Alpha。该边界既防止模型识别透明区隐藏内容，也避免把透明黑写回 Blender 后产生过滤黑边。

正式功能支持：

• MoGe-2 ViT-S、ViT-B、ViT-L Normal
• DA3 Small、DA3 Base
• BEN2 Base
• Real-ESRGAN General WDN x4v3、SAFMN Real x4、Real-ESRGAN x4plus

Upscale 使用上述三档 4× RGB 模型。正式 upscale-image Job 把结果写成 upscale.0001.png 起的序列并回写为 .upscale Image 数据块；对应 Debug Job 保留模型直通输出，便于横向比较。

首次安装会下载 MoGe-2 ViT-S Normal、BEN2 Base 与默认的 Real-ESRGAN General WDN x4v3。SAFMN Real x4 和 Real-ESRGAN x4plus 可在扩展偏好设置按需下载。模型保存在 models/，可由多个 Blender 版本共享。Server 会复用连续任务所需的同一 Session；切换模型族时释放旧 Session，推理资源异常时立即卸载当前高清 Session。

模型按目录声明的 Hugging Face 仓库下载，并以 OmooLab 镜像作为回退；未声明 Hugging Face 仓库的模型直接使用镜像。AnyImage 用同一个准备 Operator 封装 BlendJob 安装任务，并按状态显示 Set Up AI Environment… 或 Download Required Models…。

upscale-image 与 debug-upscale 共用模型推理。三个模型在模型层分块处理任意宽高输入；正式 Job 还应用输出上限、保留 Alpha 并导入 Blender。

任务生命周期

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

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

server.log 记录带时间、Job ID 与 Job Type 的排队、开始、成功、取消和失败主线，以及 Server 自身异常。Handler 细节与完整 traceback 写入对应 jobs/<job-id>/job.log，因此可先从主线定位 Job ID，再查看单个任务。

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

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

DA3 多帧限制

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

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