README.md

metadata

title: Blender Render Studio
emoji: 🎬
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.28.0
python_version: '3.12'
app_file: app.py
pinned: false
license: mit

Blender Render Studio

上传 .blend、纹理/缓存 ZIP 和 JSON 渲染配置，默认使用 GPU + Eevee 生成图片、帧序列或 MP4 视频。提供中文 Gradio 界面、API、MCP，以及可连续提交批次、断点续渲、下载结果的 Python 客户端。

1.2.0：默认 GPU + Eevee，保留 CPU / Cycles。 使用正式场景前必须通过 GPU / Eevee 自检；配置选中 GPU 不代表服务器已经提供可用的图形接口。失败时明确返回错误，不静默回退 CPU。

配置	执行方式
engine=EEVEE, device=AUTO（默认）	GPU 图形渲染；需可用的 OpenGL 或 Vulkan 驱动
engine=EEVEE, device=CPU	Mesa 软件 OpenGL；复杂场景可能很慢
engine=CYCLES, device=AUTO	GPU 光线追踪，优先 OptiX / CUDA
engine=CYCLES, device=CPU	Cycles CPU

graphics_backend 可选 opengl / vulkan，仅用于 GPU + Eevee；CPU Eevee 使用软件 OpenGL。gpu_size 可选 large / xlarge，仅影响 ZeroGPU 分配，后者消耗 2 倍配额。更大显存并不保证图形能力。自检报告包含实际 GPU 分区、图形驱动库及出图结果。

未指定 engine 的旧 JSON 采用新默认 Eevee；旧 CUDA / OPTIX 配置请显式增加 engine=CYCLES。已有任务的已保存配置不自动切换引擎，请重新创建任务，避免混合不同引擎的帧。

能做什么

• 上传单个已打包资源的 .blend，或包含工程与外部资源的 ZIP。
• JSON 设置场景、相机、视图层、分辨率、采样、降噪、透明背景、帧区间和 GPU 时间预算。
• Eevee / Cycles 与 CPU / GPU 可选；任务 JSON 的 device=CPU 始终直接在 CPU 执行。
• PNG 8/16 位、OpenEXR 16/32 位帧输出；PNG 序列合成 H.264 MP4。
• CPU 直接渲染，GPU 才按批申请，保存完成帧；取消、恢复、导出部分结果与日志。
• 使用同一套服务逻辑处理 UI、API 与 MCP 请求。

这是渲染服务：它保留模型、材质、灯光、动画与受支持的已烘焙缓存，但不会替用户建立动画。自动脚本、OSL、合成器与视频序列编辑器被禁用，不安装用户插件。长动画需要多次租约，不承诺免费、不承诺无限 GPU 时间，也不保证单帧超出平台时限的大场景能够完成。

部署到 Hugging Face

1. 新建 Gradio SDK、Python 3.12 的 Space，推荐设置为私有。
2. 把本项目根目录全部文件上传到 Space 根目录，保留此 README 的 YAML 配置。
3. 在 Space Settings 选择 ZeroGPU 硬件；是否可选取决于账号与平台当前资格。保留 RENDER_BACKEND=zerogpu 即可提供可选 GPU；默认任务使用 GPU + Eevee，必须先通过图形渲染自检。CPU Space 请明确选择 CPU。
4. 等待构建完成。requirements.txt 已包含 PyTorch；packages.txt 会安装 FFmpeg 与 Blender 的系统依赖。首次启动优先校验并安装 vendor/ 中的 Blender 5.2.2；未附带安装包时才从官方下载站下载。完整包已附带安装包，可避免下载站拒绝云平台访问的问题。
5. 打开「环境自检」页，先查看环境，先运行 GPU / Eevee 自检；选择 Cycles 时再运行 GPU / Cycles 自检。只有返回 ok=true 且 gpu_verified=true 才开始正式 GPU 任务。

若 ZeroGPU 自检失败，下载诊断日志；可以由你在 Space 设置中选择普通 NVIDIA GPU，并设置 RENDER_BACKEND=gpu。应用不会替你升级付费硬件。完整步骤、系统变量与问题排查见 部署文档。

立即试一个图片任务

在 Blender 中打开模型，先选择 File → External Data → Pack Resources，保存 .blend。不能内嵌的资源、外链 .blend 和已烘焙缓存放进工程目录，并执行 Make Paths Relative，将整个目录内容打包为 ZIP。

源码包自带 演示模型 demo.blend，可以先上传它确认流程，再上传自己的工程。

在界面上传工程，使用下面配置，然后依次点击「准备渲染任务」「检查场景与资源」「渲染下一批」「打包下载 / 合成视频」。动画可点击「连续渲染剩余帧」，应用会自动逐批执行，遇到错误或配额不足停止；随时可以点击「停止任务」并保留已完成帧。

{
  "mode": "image",
  "width": 640,
  "height": 360,
  "samples": 16,
  "frame": 1,
  "engine": "EEVEE",
  "device": "AUTO",
  "graphics_backend": "opengl",
  "gpu_size": "large",
  "batch_size": 1,
  "gpu_seconds": 120
}

上传 JSON 文件后，它优先于编辑器内容。调整编辑器前请清空 JSON 文件上传框。若 ZIP 中有多个 .blend，设置 "blend_file": "project/scene.blend"，路径以 ZIP 解压根目录为准，使用 /。

项目提供 图片配置、5 秒视频配置、EXR 帧序列配置。实际耗时由场景决定，gpu_seconds 仅在 GPU 模式使用，CPU 任务使用 cpu_timeout。

Agent 一条龙调用

客户端可在 Windows、macOS 或 Linux 使用，服务部署目标为 Linux x64。客户端只需要安装 gradio_client：

python -m pip install "gradio_client>=2.0,<3"
python examples/client_render.py --space YOUR_NAME/YOUR_SPACE --project scene.zip --config examples/video.json --output outputs --self-test

私有 Space 或需要账号配额时，通过环境变量 HF_TOKEN 提供有权访问该 Space 的令牌，不要写进配置或源码。脚本在 outputs/render-job.json 保存任务 ID，遇到服务端错误、配额问题或没有进展会停止，尽量下载已完成帧和日志。任务 ID 和下载链接都应保密。

# 接着上一次任务继续，沿用服务端原配置和已经完成的帧。
python examples/client_render.py --space YOUR_NAME/YOUR_SPACE --resume-job --output outputs

# 指定已有任务 ID，也可换一台客户端电脑继续。
python examples/client_render.py --space YOUR_NAME/YOUR_SPACE --resume-job YOUR_JOB_ID --output restored

Space 重启、睡眠后的磁盘更替或过期清理可能使任务失效；保存本机任务 ID 不等于已备份帧文件。更多 API、MCP 文件上传说明见 API 文档。

MCP

应用启动时启用 mcp_server=True，原生 Streamable HTTP 地址为：

https://YOUR-SPACE-DOMAIN.hf.space/gradio_api/mcp/

参考 MCP 客户端配置。MCP 客户端的身份验证字段因产品而异；私有 Space 需要提供 HF 认证。Agent 本机的 C:\project\scene.zip 不会自动成为 Space 文件，先使用客户端上传或该 MCP 客户端支持的文件上传能力，再调用准备任务。上传本地大文件最直接的方式是使用上面的 Python 脚本。

本机开发与验证

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
# Debian/Ubuntu 上先安装 packages.txt 中的系统包；已有 Blender 时可设 BLENDER_BIN。
export RENDER_BACKEND=cpu
python app.py

浏览器访问 http://127.0.0.1:7860。完整依赖包含较大的 PyTorch CUDA 包，便于原样部署 ZeroGPU；CPU 逻辑测试本身不需要 GPU。

python -m pip install -r requirements-dev.txt
python -m pytest -q
# 真实启动 Gradio、上传工程与 JSON、用 CPU 渲染并验证下载：
python scripts/smoke_test.py

已完成初版 98 项 pytest 检查、离线安装修复后的 9 项运行时检查，以及真实 CPU 的 PNG、EXR、3 帧视频与文件 API 验证。实际 Hugging Face ZeroGPU 的 CUDA 自检、三帧动画及远程 MCP 10 个工具的发现/调用也已通过。详情见 测试报告。复杂工程、性能和长任务稳定性仍需按具体项目验证。详细规划、状态与限制见 架构文档。

项目结构

路径	用途
app.py	Gradio 界面、API、MCP 注册
service.py	任务、批次、GPU 租约、取消与导出
render_config.py	严格 JSON 校验及 JSON Schema
uploads.py	上传、ZIP 解压与路径校验
blender_runtime.py	官方 Blender 安装、子进程、超时与日志
render_worker.py	Blender 内的场景检查、设备选择与逐帧渲染
examples/	配置、自动渲染客户端、MCP 配置
scripts/create_demo.py	在 Blender 中生成自包含演示场景
scripts/smoke_test.py	真实 Gradio API 上传、CPU 渲染与下载检查
tests/	配置、上传、任务流程等测试
docs/	规划、部署与 API 说明

应用原创代码采用 MIT 许可；Blender、FFmpeg 等依赖保留各自许可。只上传你有权渲染的工程；推荐将本服务用于自己和受信任协作者的模型。

GPU + Eevee 的选择与检测（1.1.1）

界面的引擎和计算设备可独立选择，选择后自动更新 JSON。CPU + Eevee 仍为默认值。GPU + Eevee 要求服务器提供可用的硬件图形接口，用户自己的电脑不需要安装硬件或驱动。HF 的 GPU 计算能力并不自动证明 Eevee 图形渲染可用。

使用界面「运行 GPU / Eevee 自检」或 API eevee_gpu_self_test 做真实出图检测。只有 gpu_eevee_usable=true 才算通过；检测失败时保留用户选择、返回具体诊断，不偷偷把 CPU 软件绘制冒充 GPU。部署到提供完整图形驱动的 GPU 服务器后仍可使用相同选项。

图形 GPU 部署

普通图形 GPU 的 Docker 部署方案见 GPU + Eevee 配置说明。这份方案不会自动升级付费硬件；需要实际探针成功才能确认平台支持。