内容
# 后台
[](https://github.com/lnguyen503/backlot/actions/workflows/ci.yml)
**本地 AI 生产工作室，驱动 ComfyUI 和 Blender — 可由人类（网页界面）和 AI 代理（MCP）控制，在您自己的 GPU 上运行，生成费用为 $0。**
后台封装了一个正在运行的 ComfyUI 服务器，带有类型引擎、无需构建的网页工作室和 MCP 服务器，因此相同的功能可以通过三种方式驱动：
1. **网页工作室** — `http://127.0.0.1:8765`：提示 → 图片/视频/音乐，画廊，编辑工具，故事板，自动导演。
2. **HTTP API** — 每个功能都是一个端点，带有 `wait` 标志（`POST /api/generate?wait=true` 在一次调用中返回已完成的资产），因此其他应用程序和脚本可以驱动它。
3. **MCP 服务器** — AI 代理（例如 Claude Code）获取 `list_workflows` / `run_workflow` / `direct_video` / `render_3d_animation` 工具，可以自主生成完成的视频。
> 后台是一个独立项目，与 Comfy Org（ComfyUI）或 Blender 基金会无关。名称仅用于描述。
## 功能
| 类型 | 功能 |
|---|---|
| **图片** | FLUX.1-dev · SDXL · FLUX Kontext 指令编辑 · SDXL 填充（遮罩笔刷）· Real-ESRGAN 提升 · Kontext 预设（替换背景，相机角度，重新照明，多视角） |
| **视频** | Wan 2.2（5B + 14B + Lightning 4 步）· LTX-Video · SVD 图片到视频 · 运动同步（参考剪辑 → 深度 → 重新造型主题） |
| **说话头像** | InfiniteTalk（Wan 2.1 14B 音频驱动肖像 — 照片级唇同步）· 多人双人镜头（每位演讲者音频路由到面部）· Sonic（旧版） |
| **音频** | ACE-Step 文本到音乐 · Kokoro TTS 配音（8 种声音） |
| **3D / Blender** | 无头 Blender 桥（bpy 运行器，GPU Cycles）· 深度序列导出 → **Wan VACE** 连贯重新造型动画（“一台相机移动，任意世界”）· SDXL 深度-ControlNet 每帧重新造型 |
| **故事板** | 想法 → LLM 起草的板（资产卡 + 面板）→ 一致的角色静止图像（Kontext 锚定）→ 动画 → 装配（交叉淡入，保留对话）→ LLM 评分的音乐 + 环境音 + 旁白 |
| **导演** | 一个前提 + 指导 → LLM 计划板，渲染参考/静止图像/剪辑，装配并评分一个完成的视频，自动（检查点 + 可恢复） |
| **质量控制** | 节拍检查（渲染前故障类别）· Gate-A ffmpeg 检查（冻结，响度，A/V 漂移）· 面部身份门 · 说话段姿势/表情检查 · 静止/剪辑 VLM 检查 |
| **身份** | 多镜头角色一致性：Kontext 面部锁定关键帧 → i2v → insightface + GFPGAN 重新锁定 |
所有内容都是 **工作流即配置**：一个功能 = 一个 YAML（参数，类型，边界）+ 一个 `workflows/` + `templates/` 中的 ComfyUI API 格式 JSON 模板。丢入一对， 它就会出现在 UI、HTTP API 和 MCP 中，无需代码更改。
## 要求
- **Python 3.11+**
- **正在运行的 ComfyUI 服务器**（默认 `127.0.0.1:8188`）以及您要的工作流所需的模型（参见 [模型](#模型)）
- **ffmpeg** 在 PATH 上（装配，转换；`imageio-ffmpeg` 轮子也可以）
- 可选：**Ollama**（`127.0.0.1:11434`）用于故事板/导演创作 + ✨ 提示辅助
- 可选：**Blender 4.2+/5.x** 用于 3D 通道（自动定位，或设置 `BLENDER_EXE`）
- 一个 CUDA GPU。Wan 14B / InfiniteTalk 需要 ≥24 GB VRAM（在 RTX 5090 上构建）；SDXL/SVD/LTX 通道运行在更少的内存上。
## 安装
```bash
git clone https://github.com/lnguyen503/backlot
cd backlot
python -m venv .venv
.venv/Scripts/pip install -e '.[dev]' # Windows（Linux/mac：.venv/bin/pip；zsh 中引号很重要）
```
编辑 `config/engine.yaml`：
- 将 `comfyui.base_url` / `ws_url` 指向您的 ComfyUI 服务器（默认值匹配本地安装）
- 可选地设置 `comfyui.*_dir` 路径（仅需要像图像到视频上传和模型检查这样的磁盘暂存功能）
运行工作室：
```bash
.venv/Scripts/python -m backlot.web.app # → http://127.0.0.1:8765
```
或在 Windows 上双击 `start.bat`。
运行测试套件：
```bash
.venv/Scripts/python -m pytest
```
## MCP 设置（从 AI 代理驱动）
将 MCP 服务器注册到您的代理主机。对于 Claude Code：
```bash
claude mcp add backlot -- <repo>/.venv/Scripts/python.exe -m backlot.mcp_server
```
暴露的工具：`list_workflows`，`describe_workflow`，`run_workflow`（阻塞或异步），`get_job_status`，`cancel_job`，`direct_video`（前提 → 完成的电影），`list_blender_scenes`，`render_3d_animation`（Blender 深度 → VACE 连贯剪辑）。
MCP 服务器实时读取工作流注册表 **每次调用** — 无需重启即可出现新的工作流 YAML。
## 模型
模型权重 **不** 被绑定 — 它们位于您的 ComfyUI 模型目录中。每个工作流 YAML 文档都需要什么。主要的：
| 工作流 | 权重 |
|---|---|
| `txt2img_flux` | FLUX.1-dev fp8 |
| `txt2img_sdxl`，`inpaint_sdxl` | SDXL base 1.0 |
| `edit_kontext` | FLUX.1 Kontext dev |
| `txt2vid_wan`，`img2vid_wan*` | Wan 2.2（TI2V 5B / I2V A14B + Lightning LoRA） |
| `txt2vid_ltx` | LTX-Video 2B |
| `img2vid_svd` | SVD（svd_xt） |
| `music_acestep` | ACE-Step 3.5B |
| `talkhost_infinitetalk*` | Wan 2.1 I2V 14B GGUF + InfiniteTalk（单/多）+ chinese-wav2vec2-base + lightx2v LoRA（通过 ComfyUI-WanVideoWrapper + KJNodes） |
| `vace_depth_video` | Wan 2.1 VACE（1.3B 或 14B） |
| `upscale_esrgan` | RealESRGAN_x4plus.pth |
| `txt2img_controlnet_depth_sdxl` | SDXL + control-lora-depth-rank256 |
faceswap 身份管道另外获取 `inswapper_128.onnx` + `GFPGANv1.4.onnx` 到 `models/`（gitignored）并使用 insightface `buffalo_l`。
### 所需的 ComfyUI 自定义节点
大多数工作流仅使用 **核心 ComfyUI 节点** — 股票安装运行图像，视频（Wan/LTX/SVD），音乐，Kontext 编辑，填充，升级，ControlNet 和整个 Blender→VACE 通道，无需额外节点。三个工作流需要自定义节点包（通过 ComfyUI-Manager 或 git 克隆到 `custom_nodes/`，然后重启 ComfyUI）：
| 工作流 | 自定义节点 |
|---|---|
| `talkhost_infinitetalk` / `talkhost_infinitetalk_multi` | [ComfyUI-WanVideoWrapper](https://github.com/kijai/ComfyUI-WanVideoWrapper) + [ComfyUI-KJNodes](https://github.com/kijai/ComfyUI-KJNodes) (kijai) |
| `talkhost_sonic` (旧版) | [ComfyUI_Sonic](https://github.com/smthemex/ComfyUI_Sonic) |
如果运行立即失败，出现类似 `MultiTalkWav2VecEmbeds` 或 `SONICSampler` 的节点名称的“无效提示/类类型未找到”错误，则是此表的原因。
**⚠ 许可注意：** 模型权重具有自己的许可，与此存储库的 MIT 代码许可无关。特别是 **FLUX.1-dev 是非商业**；Wan、LTX、SVD、ACE-Step 等都有自己的条款。在使用商业作品之前，请查看您使用的每个模型的许可。
## 从 AI 导演驱动
后台设计为由单独会话中的策略/创意代理 — **[ai-director](https://github.com/lnguyen503/ai-director)** — 通过具有人为门控支出的简单文件中继操作。规范协议位于 ai-director 存储库中；引擎侧摘要（消息格式，排序，追加日志和人为授权通道）在 [`docs/relay-protocol.md`](docs/relay-protocol.md) 中。艰苦的生产经验（故事板一致性，拼接，说话头像，VRAM 操作）位于 [`docs/production-notes.md`](docs/production-notes.md) 中。
## 布局
```
src/backlot/
engine/ 配置 · 注册表 · 参数注入 · ComfyUI 客户端 · WebSocket 监听器 · 作业管理器
web/ FastAPI 应用程序 + 无需构建的网页工作室（静态/index.html）+ 画廊存储 + 会话
storyboard/ 模型 · 存储 · LLM 代理 · 渲染 · 装配 · 模板 · 库 · 导演
blender/ 无头 bpy 运行器 + 场景库（深度序列，GPU Cycles）
qc/ 节拍检查 · Gate-A · 面部身份 · 说话质量控制 · 静止/剪辑 VLM 检查
pipelines/ 多镜头角色一致性管道
faceswap.py insightface + GFPGAN 身份重新锁定（GPU）
mcp_server.py MCP 适配器
workflows/ 每个功能一个 YAML（参数，边界，文档）
templates/ 匹配的 ComfyUI API 格式图
tests/ 单元测试套件（pytest）
scripts/ 开发/实时实用程序（scripts/live_run.py <workflow> '<json>'，演示制作，基准测试）
```
## 许可
MIT — 参见 [LICENSE](LICENSE)。模型权重和第三方组件保留其自己的许可。
