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。

Cutout 的 generate-mesh Job 会把套索或 BEN2 Alpha 收紧为裁切范围，同时分别写出未乘选区 Alpha 的 Color、几何 selection 与局部分析图。Cutout 和 Balloon 只在启用 Normal 时运行 MoGe-2；Depth Balloon 返回浮点深度分析，Depth Surface 返回深度场。Blender 主线程统一创建单面基础网格、计算 o_balloon、绑定内部深度图片并组装四个独立 Geometry Nodes；Cutout、Balloon 与 Depth Balloon 的 camera-axis normal 会在最终网格求值后烘成 tangent-space Image。

Depth Balloon 的基面拟合使用四轮稳健加权回归，并对细长选区中方差不足的短轴设置相对主轴的方差下限。该约束只处理病态方向，不会移除长轴上由多数有效深度点支持的趋势。Blender 会把回归平面的符号和半深度倍率转换到 Cutout 的局部 YZ 纸面坐标；Geometry Nodes 计算 (Base Plane - 深度基值) × Depth Scale，因此 Depth Scale = 0 会同时消除深度图和 Base Plane 对深度分支的影响。

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；Cutout 的 Refine Selection 同样只消费 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.png 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。