# Nex Animation Studio · 长视频编导平台 面向 AI 长视频创作的本地工作台:**人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎**, 底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。 > 📖 **[打开图文使用手册](frontend/public/help.html)**(服务启动后也可访问 ) > > 手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。 > > 🧹 动代码或打部署包之前先读 **[工程规范与部署数据边界](docs/工程规范.md)**: > 目录职责、`scripts/` 准入规则、测试规范、改动后的最低验收三连,以及服务器上「什么该搬、什么不该搬」。 ``` ┌──────────────────────────────── Browser (Vue 3 + Vite) ────────────────────────────────┐ │ 项目总览 │ 资产库 │ 分镜与脚本 │ 调度中心 │ 质检与审核 │ 时间线合成 │ 导出与成本 │ └─────────────────────────────────────┬───────────────────────────────────────────────────┘ │ REST / JSON + multipart (vite proxy 或 nginx) ┌─────────────────────────────────────▼───────────────────────────────────────────────────┐ │ FastAPI (backend/app/api) system · library · storyboard · pipeline · delivery · agent │ │ services: importer prompt preflight dispatch execution quality timeline compose agent │ │ costing ffmpeg audio storage events status daemon │ │ providers: mock · http_generic · macos_say · comfyui + provider_models 模型注册表 │ └───────┬───────────────────────────────────────────────┬─────────────────────────────────┘ │ TASK_EXECUTOR=celery │ TASK_EXECUTOR=inline(单机自检) ┌───────▼───────────────┐ ┌──────────▼───────────────┐ │ Redis + Celery │ │ 进程内线程池 + │ │ worker(generate/audio/│ │ 守护线程(周期派发 + │ │ qc/compose/io)+ beat │ │ 断点续跑) │ └───────┬───────────────┘ └──────────┬───────────────┘ └───────────────► FFmpeg / ffprobe(转场、混音、响度、质检) ─◄──┘ │ Postgres / SQLite + MEDIA_ROOT 媒体库(/media 直出) ``` ### 仓库目录与脚本职责 ```text backend/ FastAPI 应用:app/api 路由 · app/services 编排 · app/providers 模型适配 · tests 回归用例 frontend/ Vue 3 + Vite 工作台(public/help.html 就是上面那份图文手册) scripts/ 只放启动 / 部署 / 运维脚本(下表);一次性验证探针不进这个目录 docs/ UI 规范、工程规范、H3 性能诊断记录 media/ 产物库(MEDIA_ROOT) models/ whisper 词级对齐权重 reports/ 阶段验收证据 .local/ 开发态日志与 pid .trash/ 删除暂存(本目录不是 git 工作区,删掉就没了) .env 本机配置与密钥(不进部署包) nex_animation.db 开发库 ``` | 脚本 | 干什么 | 在哪儿跑 | | --- | --- | --- | | `scripts/dev.sh` | 开发态前后端两个进程(后端 8000 + Vite 5173),缺 `.env` / `.venv` / `node_modules` 自己补 | 开发机 | | `scripts/server.sh` | 服务形态全生命周期:`install` `build` `start` `stop` `restart` `status` `verify` `logs` `systemd` | 服务器 | | `scripts/deploy.sh` | 打部署包(白名单 + 体检),或直接 rsync 上服务器并自动安装、重启 | 开发机 | | `scripts/seed.py` | 迁移「模型配置 + 加密主密钥 + 管理员」:`export` 导出、`install` 幂等落地 | 两端 | | `scripts/e2e_selfcheck.py` | 图2 全 12 节点端到端自检(真实 HTTP + ffprobe 实测产物) | 两端 | | `scripts/evidence_prune.py` | 清理 `reports/` 下过期的验收证据目录 | 开发机 | --- ## 1. 图1 模块规划 → 代码实现 | 模块 | 后端服务 / 接口 | 前端页面 | 关键能力 | | --- | --- | --- | --- | | **① 人物与声音资产库** | `app/api/platform.py`、`app/api/library.py`、`services/storage.py`、`services/audio.py` | `views/AssetLibrary.vue`、`views/tabs/Library.vue` | 平台级人物 / 场景 / 声线母版创建时始终全局,不绑定项目;项目目标只在「引入项目」时选择。母版可上传、AI 生成、编辑,项目资产可反向「上架平台」。图片支持大图预览,每个媒体可单独删除,不必删除母版。声线在创建时只录入基础设定,生成试听时再选真实模型;项目内继续维护定妆图/三视图/服装/表情、场景图、声线与项目素材;每次上传生成**新版本**,删除留痕 | | **② 分镜与脚本管理** | `app/api/storyboard.py`、`services/importer.py`、`services/prompt.py`、`services/preflight.py` | `views/tabs/Storyboard.vue`(分镜工作台) | Markdown/CSV/TSV/JSON/纯文本脚本导入 + 图片按镜号自动匹配关键帧(支持 zip);`shots/preview` 与 `dry_run` 先预览后落库;镜头增删改/排序、人物场景绑定、提示词组装与**版本留痕**、首尾帧/参考图上传;`shots/board` 轻量看板(逐镜预检)、`shots/bulk` 批量复制/移动/改参/删除、`shots/export` 反向导出 md/csv/json | | **③ 视频模型调度中心** | `app/api/pipeline.py`、`services/dispatch.py`、`services/capacity.py`、`services/execution.py`、`services/daemon.py`、`app/providers/*` | `views/tabs/Dispatch.vue` | 任务清单(预检驱动,可解释「为什么跳过/阻塞」)→ 入队 → 按 provider/model 并发槽位与 RPM 限流派发(**一个模型一行**,视频与 TTS 各自的限额互不串台) → 指数退避重试 → 中断任务断点续跑;模型注册表在线启停/设默认/调并发/调限流/注入故障演练 | | **④ 长视频合成引擎** | `app/api/delivery.py`、`services/timeline.py`、`services/compose.py`、`services/ffmpeg.py`、`services/quality.py` | `views/tabs/Review.vue`、`TimelineTab.vue`、`Delivery.vue` | 自动质检 7 项打分;人工审核合格/驳回重做;时间线(片段裁剪/转场/排序/字幕/配音/BGM/响度归一化);交付预检报告;4 档出片预设 + 校验和留档;成本台账与生成记录可复现 | | **底层:任务编排 + 项目数据库** | `app/models/*`、`app/db.py`、`services/events.py`、`services/status.py`、`services/costing.py` | `views/Dashboard.vue`、`ProjectDetail.vue`、`tabs/Overview.vue` | 12 张表(项目/人物/场景/声线/素材/素材版本/镜头/任务/审核/时间线/片段/字幕/音轨/导出/成本/生成记录/事件);任务幂等键、心跳、错误历史、检查点;全流程事件流与流程进度视图 | ## 2. 图2 业务流程 → 状态机与接口 流程节点定义在 `backend/app/services/status.py:PIPELINE_STAGES`,每个项目/镜头/任务的真实状态收敛成 `GET /api/projects/{id}` 的 `workflow[]`(`pending/active/done/failed`),前端 `WorkflowBar.vue` 直接渲染。 | # | 节点 | 主要接口 | 镜头状态流转 | | --- | --- | --- | --- | | 1 | 创建视频项目(可顺带勾选资源库母版 `platform_assets:[{owner_type,asset_id}]`) | `POST /api/projects`(返回 `imported_assets`/`import_failures`)、`GET /api/platform/assets?owner_type=human|scene|voice` | 项目 `draft` | | 2 | 导入分镜图片与脚本 | `POST /projects/{id}/shots/preview`、`POST /projects/{id}/import`(`dry_run`/`replace`/`keep_existing`/`images[]`/`archive`);看板与批量:`GET /projects/{id}/shots/board`、`POST /projects/{id}/shots/bulk`、`GET /projects/{id}/shots/export` | 新建镜头 → `ready` | | 3 | 绑定人物/场景与声音资产 | `POST /projects/{id}/shots/{sid}/bindings`、`/assets`、`/characters/{cid}/assets` | `binding → ready` | | 4 | 生成分镜任务清单 | `GET /projects/{id}/tasklist`、`POST /projects/{id}/tasks` | `ready → planned` | | 5 | 检查素材与参数 | `GET /projects/{id}/preflight`(逐镜头 `issues[{code,field,message,severity}]`) | 阻塞项阻止入队(可 `allow_unready`) | | 6 | 任务队列调度 | `POST /projects/{id}/dispatch`(`limit`/`drain`/`timeout`)、`GET /projects/{id}/queue` | `planned → queued → running` | | 7 | 调用视频模型 | 任务执行 `app/jobs/tasks.py` → `providers/*` | `running`(进度/心跳/尝试次数) | | 8 | 下载并保存视频 | 同上(产物落 `MEDIA_ROOT` 并注册资产) | `running → generated` | | 9 | 质量检查 | `GET /projects/{id}/qc`、`POST /projects/{id}/shots/{sid}/qc?drain=` | `generated → qc_passed`(失败 → `generated` + `quality_check_failed`) | | 10 | 人工审核 | `GET /projects/{id}/reviews`、`POST .../approve`、`POST .../reject` | `qc_passed → approved` / `rejected` | | 11 | 调整提示词重新生成(驳回回路) | `reject` 携带 `prompt`/`negative_prompt`/`regenerate` → 自动重排任务;`POST /projects/{id}/voiceover` 补配音 | `rejected → planned → running` | | 12 | 时间线合成 + 配音/字幕/混音 → 导出 | `POST /projects/{id}/timeline`、`/timeline/segments/{id}`、`/timeline/reorder`、`/timeline/subtitles`、`/timeline/audio`、`/timeline/settings`、`GET /timeline/report`、`POST /compose`、`GET /exports`、`GET /api/exports/{id}/download` | 项目 `composing → delivered` | 失败与恢复:`POST /api/tasks/{id}/retry|cancel`、`POST /projects/{id}/tasks/retry-failed`、`/tasks/cancel-active`、 `/projects/{id}/resume`(`running` 超过 `STALE_RUNNING_SECONDS` 视为中断并带上 checkpoint 续跑)。 ### 2.1 项目主页 LLM 总控台(`views/tabs/Overview.vue`) 项目主页顶部提供自然语言总控台:使用系统注册并启用的默认真实 LLM 盘点镜头、关键帧、模型能力和 当前阻塞,先落库为可审阅的执行计划,再由用户确认执行。LLM 不直接操作媒体或数据库,后端只接受 `resume / rewrite_shots / generate_keyframes / generate_shots / quality_check / approve_passed / build_timeline / compose` 八个白名单动作。主题或剧情变化时,`rewrite_shots` 会整组替换分镜、 按引用补齐缺失场景/人物、作废旧镜头产物并重建后续时间线;创建/删除项目、任意改资产文件或调用 任意 URL 仍不可用。 | 端点 | 用途 | | --- | --- | | `POST /api/projects/{id}/agent/plan` | 将自然语言目标转换为结构化计划并持久化 | | `GET /api/projects/{id}/agent/runs` | 查看当前与历史调度记录 | | `GET /api/projects/{id}/agent/runs/{run_id}` | 查询分步执行状态与结果 | | `POST /api/projects/{id}/agent/runs/{run_id}/execute` | 用户确认后执行,默认异步轮询 | | `POST /api/projects/{id}/agent/runs/{run_id}/cancel` | 请求在当前步骤结束后取消 | 审核门禁默认开启:未勾选「质检合格后允许 AI 代审」时,计划只能推进到人工审核前;只有用户显式授权后, `approve_passed` 才会以 `kind=agent` 单独留痕,绝不冒充人工审核。调度器拒绝 Mock LLM 和 Mock 媒体模型, 不会在真实模型缺失时静默回退。已完成且产物有效的步骤会跳过,失败步骤可从断点继续;实现见 `backend/app/services/agent.py`,契约测试见 `backend/tests/test_agent_orchestrator.py`。 ### 2.2 分镜工作台(`views/tabs/Storyboard.vue`) 分镜是几十上百镜的大页面,所以列表**不**走返回全字段的 `GET /shots`,而是按用途拆成三层: | 端点 | 用途 | 关键字段 | | --- | --- | --- | | `GET /projects/{id}/shots/board` | 看板/分镜表首屏,一次请求带齐指标与逐镜预检 | 每镜 `ready` + `issues[{code,field,message,severity}]`、缩略图地址、QC 分、绑定摘要;**不含** prompt 正文、版本、素材明细 | | `GET /projects/{id}/shots/{sid}` | 选中某镜时按需拉全量详情喂给检查器 | prompt / 素材 / QC 明细 / 配音 / `effective_*` | | `GET /projects/{id}/shots/export?fmt=md\|csv\|json` | 导出给编剧或外部工具 | md 与导入格式**双向可逆**,导出文件可直接再导回 | | `POST /projects/{id}/assets/generate` | 分镜关键帧 / 尾帧 / 参考图走独立图像模型 | `target_type=shot`、当前镜头提示词、人物/场景/镜头参考图;生成结果覆盖同一关键帧槽位的新版本 | 批量操作统一走 `POST /projects/{id}/shots/bulk`(`action=duplicate|delete|move|patch`):一次请求一个事务, 避免 N 个镜头触发 N 次全项目预检。`duplicate` 插在来源之后并重排镜号、不继承产物;`move` 支持 `index`(绝对落点)与 `delta`(相对位移);`patch` 拒绝批量改镜号(镜号需唯一)并在改到摄影参数后重算提示词。 写接口侧的约束也一并收紧:枚举字段与 `duration>0` 校验不过一律 400(原先静默写脏值)、镜号冲突返回 400 而非 500、 `seed` 允许显式清空、删除镜头后镜号自动续排。回归见 `backend/tests/test_storyboard_workbench.py`。 页面交互:网格 / 分镜表双视图(选择记在 `localStorage`)、搜索 + 状态/模式/排序筛选 + 仅看阻塞/缺关键帧、 HTML5 拖拽改镜序、Shift 范围勾选、批量复制/移到最前/统一改参数/删除。选中镜头后打开独立右侧宽抽屉, 四页签(镜头 / 资产 / 提示词 / 产物)不再挤压分镜看板;关键帧、尾帧、参考图、视频和配音均可在 图片 / 视频 / 音频统一灯箱中预览,并可直接打开原文件。资产页签内置「AI 生成关键帧」, 显示并选择当前真实图像模型,自动带入场景图、人物定妆图和镜头参考图,生成后直接成为 i2v 首帧。 检查器带脏标记与 `⌘S` 保存,快捷键 `J`/`K` 切镜、`X` 勾选、`Esc` 关闭。 卡片上的「生成」「审核」带 `?shot=` 深链到调度中心 / 审核页并自动选中该镜。 ## 3. 启动方式 ### 3.1 单机模式(无需 Redis/Postgres,适合开发、演示、自检) **一条命令搞定前后端:** ```bash ./scripts/dev.sh # 启动前后端(缺 .env / .venv / node_modules 会自己补) ./scripts/dev.sh status # 端口 / 健康 / 当前默认模型 / ComfyUI 连通性 ./scripts/dev.sh logs # 同时跟踪前后端日志(logs backend|frontend 看单个) ./scripts/dev.sh stop # 停止(按进程组回收,不留孤儿 vite / uvicorn worker) ./scripts/dev.sh restart --reload ``` 选项:`--backend-only` `--frontend-only` `--reload` `--no-install` `--backend-port N` `--frontend-port N` `--host ADDR`(换端口时 Vite 代理目标自动跟随)。 日志在 `.local/logs/`,pid 在 `.local/run/`。 **局域网访问(手机 / 同事的电脑打开同一套平台)** `dev.sh` 默认监听 `0.0.0.0`,启动时会把本机与局域网地址一起打出来: ```text 界面 http://127.0.0.1:5173 (Vite → 代理 /api、/media 到后端) 接口 http://127.0.0.1:8000/docs 局域网 http://192.168.2.19:5173 (同网段设备可直接打开) 局域网 http://192.168.2.19:8000/docs ``` - 同一网段的设备直接开 `http://<本机IP>:5173` 即可:`/api`、`/media` 都由 Vite 代理回后端, 接口返回的又都是相对路径,不会出现「图片只在这台机器上能看」。 - 只想给本机用:`./scripts/dev.sh --host 127.0.0.1`(`NEX_HOST` 环境变量同样生效)。 - mDNS 机器名(`http://<名>.local:5173`)已在 `frontend/vite.config.ts` 的 `server.allowedHosts: ['.local']` 里放行;换成自定义域名仍需显式加白名单, 否则 Vite 会返回 403 `Blocked request. This host (...) is not allowed.`。 - 🔒 鉴权默认开启(`AUTH_ENABLED=true`):首次启动自动播种管理员 `admin` / 初始口令 `admin1234` (`app/services/auth.py:bootstrap`,登录后应立即改密),会话走 `nex_session` Cookie, 脚本也可以用 `Authorization: Bearer `。模型配置与账号管理(`/api/providers`、`/api/users`) 只有管理员能写,观摩/制作角色可看可拍但不能改全平台配置。 本地调试嫌麻烦可在 `.env` 设 `AUTH_ENABLED=false` 关掉,但**别把关掉鉴权的实例裸露在公网上**。 脚本干了四件手工启动容易漏掉的事(都是踩过的坑): ① 统一从仓库根 `--app-dir backend` 启动,保证根目录 `.env` 一定被读到 (`.env` 被静默忽略时平台照旧跑 mock 且不报错); ② 用独立会话拉起进程,脚本/终端退出不会把服务一起带走; ③ Vite 加 `--strictPort`,端口冲突直接报错而不是悄悄换端口把前端代理和 e2e 自检打空; ④ 端口被外部进程占用时报出具体 pid,而不是卡在健康检查超时。 手工启动(想单独控制某个进程时): ```bash cp .env.example .env # 后端(SQLite + 进程内线程池 + 内置守护调度器);.env 已配好 SQLite/inline,可零环境变量启动 ../.venv/bin/pip install -r backend/requirements.txt ../.venv/bin/uvicorn app.main:app --app-dir backend --reload --port 8000 # 前端(另一个终端) cd frontend && npm install && npm run dev # http://localhost:5173 ``` `TASK_EXECUTOR=inline` 时 `POST /dispatch`、`/compose` 会同步排空队列并直接返回结果,页面无需等待 worker; `/health` 的 `executor`、`daemon.running` 可确认当前后端。 > **前端开发态代理**:`frontend/vite.config.ts` 必须把 `/api`、`/health`、`/media`、`/docs`、 > `/openapi.json` **五条路径一起**代理到后端。少代理任意一条,Vite 的 SPA 回退会用 > `index.html` 应答,前端拿到 `200` 却没有字段,对应面板就静默失效(侧边栏曾因此整块显示 > 「任务执行 —/ffmpeg 缺失/字幕烧录 滤镜缺失/调度守护 未运行」)。`src/store.ts` 现在会 > 校验 `typeof health.status === 'string'`,一旦代理缺失直接抛出可读错误而不是假装健康。 > > **后端换地址/换端口**:`NEX_BACKEND=http://127.0.0.1:8010 npm run dev`,无需改代码。 > **SQLite 路径**的父目录由 `app/db.py` 自动创建,`DATABASE_URL='sqlite://////tmp/nex_ui/ui.db'` > 可直接使用(注意 SQLite URL 是 6 个斜杠:3 个协议分隔 + 绝对路径根)。 ### 3.2 生产模式(Postgres + Redis + Celery worker/beat) ```bash cp .env.example .env # 修改数据库/Redis 口令 docker compose up --build # web:8080 api:8000 worker beat db redis ``` 或本机进程:`celery -A app.worker.celery_app worker -Q generate,audio,qc,compose,io,default -c 2` 与 `celery -A app.worker.celery_app beat`(beat 负责周期派发与断点续跑)。 ### 3.3 冒烟自检 `/health` 与 `/api/auth/state` 免登录(监控探针和登录页要用),其余 `/api/*` 在默认鉴权下需要先拿会话: ```bash curl -s localhost:8000/health | jq '.executor,.ffmpeg_capabilities,.auth_enabled,.frontend' curl -s localhost:8000/api/auth/state | jq '.auth_enabled,.login_hint' # 未登录也返回 200 # 读业务接口前先登录拿 Cookie(账号口令就是首启播种的那一对): curl -s -c /tmp/nex.jar -H 'content-type: application/json' \ -d '{"username":"admin","password":"admin1234"}' localhost:8000/api/auth/login > /dev/null curl -s -b /tmp/nex.jar localhost:8000/api/meta | jq '.presets,.options.transition' ``` `AUTH_ENABLED=false` 时可以省掉登录那两步直接 curl。 端到端业务自检(不只是接口活着)见 §6.2。 ### 3.4 服务器部署(一台机器一个端口) 开发态是「Vite 5173 + 后端 8000」两个进程;服务器上不需要 Vite—— `SERVE_FRONTEND=on` 让**同一个进程**既出 API 又发 `frontend/dist`, vue-router 的 history 回落已经处理好(地址栏直接刷 `/projects/3` 不会 404), 反向代理只需转发一处,`/api`、`/media`、`/docs` 与页面同源。 `SERVE_FRONTEND` 默认 `off`,所以开发与测试行为完全不变。 ```bash # ---- 开发机:打包(内容白名单 + 体检,体检不过直接报错不产出包)---- ./scripts/deploy.sh --check # 只看会带上什么、排掉什么 ./scripts/deploy.sh # → .local/deploy/nex_animation-<时间戳>.tar.gz ./scripts/deploy.sh --host deploy@10.0.0.8 \ --path /opt/nex_animation # 上传 + 远端 install + restart + status # ---- 服务器:落地 ---- tar -xzf nex_animation-*.tar.gz && cd nex_animation ./scripts/server.sh install # venv + 依赖 + npm build + 听写模型 + 建表灌种子数据 ./scripts/server.sh start # 单进程 uvicorn,默认 :8000 ./scripts/server.sh verify # 图2 全 12 节点真实 HTTP + ffprobe 自检 ./scripts/server.sh status # 端口 / 健康 / 默认模型 / ComfyUI 连通性 / 数据边界 sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \ && sudo systemctl daemon-reload && sudo systemctl enable --now nex-animation ``` `install` 首次生成的 `.env` 是**单机版**(SQLite + `TASK_EXECUTOR=inline` + `SERVE_FRONTEND=on`), 不是 `cp .env.example`——模板里那套是 Postgres + Redis + Celery 的容器形态,直接 cp 会因为 连不上 DB/Redis 而起不来。`inline` 的调度守护线程跑在进程内,所以服务形态**固定单进程**, 加 `--workers` 等于 N 份守护线程抢同一批任务重复派发;要横向扩展就切 `celery` 另起 worker。 **部署包里只有代码,没有你跑出来的内容**(`deploy.sh` 逐条体检,缺的多的直接 die): | 随包走 | 不随包走 | | --- | --- | | 表结构:应用首启 `app/db.py:init_db()` 自己 `create_all` + 补列 | `media/` 产物库——换环境是「迁移」不是「部署」,单独 rsync | | 模型配置 `model_specs` + 加密主密钥 `model_secret_keys`(`scripts/seed/`) | 项目 / 分镜 / 任务等业务数据(开发库全是过程产物) | | 管理员账号 `users`(仅 `admin`,沿用导出的口令哈希) | `.env`——ComfyUI 地址、数据库串都是机器相关的 | | 启动脚本与 `DEPLOY-INFO.txt`(包里有什么、服务器三步) | `backend/tests`、`reports/`、`docs/`、`models/`、`frontend/dist`(远端 build;`--with-dist` 可带上) | 主密钥跟包走是有意的:`model_specs.api_key` 是密文,换机器解不开就等于每台服务器都要重录一遍 各家 Key。代价是 `scripts/seed/` 属于**机密**——已 gitignore、随包走、包内是密文但主密钥也在里面, 按密钥对待。装完 `seed.py install` 会自检解密并打印当前默认模型;`--only-missing` 只补缺不覆盖 已有配置,`--dry-run` 先看将要发生什么,主密钥冲突时区分「没有解密依赖 → 换」与「有依赖 → 中止等你决策」。 > 服务器上没有 `whisper-cli` / 听写模型时,只有「台词听写质检」这一项不生效,其余流程照常; > `server.sh status` 会把它标成黄色告警而不是静默降级。`--no-asr` 可以跳过下载(465M 权重)。 ## 4. 模型与供应商 ### 4.0 真实模型:ComfyUI · MiniMax H3(已实跑通过) 模型接入地址 `http://10.100.53.199:9200`(ComfyUI 0.42 / GB10 单卡)。填好地址即自动登记进模型注册表: ```bash # .env(放仓库根;backend/ 下启动也会向上找到,见 app/config.py:_dotenv_candidates) COMFYUI_BASE_URL=http://10.100.53.199:9200 VIDEO_PROVIDER=comfyui VIDEO_MODEL=minimax-h3 ``` `cd backend && ../.venv/bin/uvicorn app.main:app --port 8000` 之后, 调度中心 → 模型注册表里 `comfyui/minimax-h3` 的 🔌 探测会列出机器上**真实存在**的 UNET / CLIP / VAE 文件名,可直接照着改 config,不必猜 `unet_name`。 | 项 | 实机口径 | | --- | --- | | 节点 | `MiniMaxH3ImageToVideo`(首帧/首尾帧/t2v)· `MiniMaxH3ReferenceToVideo`(参考图 r2v) | | 画布 | 模型原生 16:9 → **1312×736**(短边 768 档,最长边 ≤1344,边长必须是 32 的倍数);**1080p 是交付档**:出片仍按原生像素,合成端 lanczos 放大(`capabilities.upscale_to`),不额外花卡时 | | 时长 | 帧数必须落在 **17k+5** 网格:5s→**124 帧**(5.17s)… 15s→**362 帧**;模型只在 124–362 帧上训练过 | | 音轨 | 原生音画同步:`VAEDecode` + `VAEDecodeAudio` → `CreateVideo(fps=24)` → 一次成片自带 AAC | | 耗时 | 5s / 20 步 ≈ **18 分钟/镜头**(单卡串行,`COMFYUI_CONCURRENCY=1`;心跳每 `STALE_RUNNING_SECONDS/3` 续租,不会误判重跑) | | 反向提示词 | H3 无独立入口,适配器把 `negative_prompt` 折进提示词末尾的自然语言子句 | **踩过的两个坑**(已修 + 已锁测试,改适配器前请先读): 1. 参考图是 ComfyUI 的 autogrow 槽位(`COMFY_AUTOGROW_V3`)。ComfyUI 3.x 的 API prompt 必须使用 **“父输入.槽位”扁平键**:H3 为 `ref_images.ref_image_0`,Qwen-Image 为 `images.image_1`。传嵌套字典不会报错,但会被静默解析成空参考集,最终成图/成片与参考图无关。 2. 时长窗口不能只看节点参数下限(节点 `min=5` 帧)。低于 124 帧的时长虽然能对齐到 17k+5 网格(4s→107 帧、3s→73 帧),却落在模型训练区间之外,属于「语法合法但模型没见过」 的静默劣化,而且已经花掉一次真实渲染。因此 `capabilities` 的上下限必须满足: **两端对齐到帧网格后仍落在 124–362 帧内**(`tests/test_comfyui_adapter.py`)。 真实模型端到端验证走平台内链路:模型中心对 `comfyui/minimax-h3` 点 🔌 探测确认权重到位, 然后新建项目 → 分镜 → 派发,产物用 ffprobe 复核时长与音轨;单个镜头失败就在镜头详情里 「重新生成」,不必整项目重跑。整套 12 节点的自动化版本是 §6.2 的 `scripts/e2e_selfcheck.py` (mock 适配器,不烧卡时)。早期那些直连 ComfyUI 的一次性探针 (`comfyui_e2e.py` / `predator_meal_e2e.py` / `platform_full_e2e.py`)已完成使命, 归档在 `.trash/2026-11-01/scripts/`,不再进 `scripts/`。 #### 4.0.1 台词的语音来源:默认由 H3 直出原声(音画同步) H3 是原生音画同步模型,人声是**对着口型生成**在产物音轨里的。所以时间线出厂默认 `voice_source="native"`:镜头产物自带音轨时,台词直接用原声,片段时长 = 产物时长, **不再生成 TTS 覆盖**(`dispatch` 把这类镜头的配音计划标成 `skip` 并给出理由)。 以前的「单独 TTS + ffmpeg 合成」链路保留为 `dub`,随时可在 时间线 → 台词语音来源 切回。 错位的根因是口径不一致,不是 ffmpeg 混音不准:TTS 长度与停顿与画面无关,旧逻辑却把 片段拉到 `max(画面, 配音+留白)` 并定格补帧,于是出现「画面里人物闭着嘴、声音还在说」 (实测旧链路一条 5s 片段里 **57% 是静音**);改走原声后同一段产物 `silencedetect -35dB/0.35s` **测不出静音段**,音画长度天然相等。 音色不是模型随机挑的嗓子:生成时平台把**本镜每个说话人**声线的克隆样本按台词顺序喂进 `MiniMaxH3ReferenceToVideo.ref_audios.ref_audio_{0,1,2}`(`prompt.reference_voice_audios`, 上限 `Capabilities.max_reference_audios=3`)。用基频中位数 f0 做 A/B(shot26「俊杰」, 音色样本 120.3 Hz,同 seed 配对): | 喂进 ref_audios 的内容 | 产物 f0_med | 相对本人音色样本 | | --- | --- | --- | | 不喂任何参考音频 | 216.2 Hz | **+11.2 半音**(模型自己挑了把嗓子) | | 俊杰本人的音色样本 | 131.1 Hz | +1.5 半音 ✅ | | 俊杰本人的音色样本 + `