README.md

---
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`。应用不会替你升级付费硬件。完整步骤、系统变量与问题排查见 [部署文档](docs/DEPLOY.zh-CN.md)。

## 立即试一个图片任务

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

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

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

```json
{
  "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 解压根目录为准，使用 `/`。

项目提供 [图片配置](examples/image.json)、[5 秒视频配置](examples/video.json)、[EXR 帧序列配置](examples/frames-exr.json)。实际耗时由场景决定，`gpu_seconds` 仅在 GPU 模式使用，CPU 任务使用 `cpu_timeout`。

## Agent 一条龙调用

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

```bash
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 和下载链接都应保密。

```bash
# 接着上一次任务继续，沿用服务端原配置和已经完成的帧。
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 文档](docs/API.zh-CN.md)。

## MCP

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

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

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

## 本机开发与验证

```bash
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。

```bash
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 个工具的发现/调用也已通过。详情见 [测试报告](docs/TEST_REPORT.zh-CN.md)。复杂工程、性能和长任务稳定性仍需按具体项目验证。详细规划、状态与限制见 [架构文档](docs/ARCHITECTURE.zh-CN.md)。

## 项目结构

| 路径 | 用途 |
| --- | --- |
| `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 配置说明](docs/GPU-EEVEE.zh-CN.md)。这份方案不会自动升级付费硬件；需要实际探针成功才能确认平台支持。