704 lines
58 KiB
Markdown
704 lines
58 KiB
Markdown
# Nex Animation Studio · 长视频编导平台
|
||
|
||
面向 AI 长视频创作的本地工作台:**人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎**,
|
||
底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。
|
||
|
||
> 📖 **[图文使用手册](frontend/src/pages/Help.tsx)** —— 已搬进站内:启动后访问 <http://127.0.0.1:5173/help>,或点工作台顶栏的「手册」
|
||
>
|
||
> 手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。
|
||
>
|
||
> 🧹 动代码或打部署包之前先读 **[工程规范与部署数据边界](docs/工程规范.md)**:
|
||
> 目录职责、`scripts/` 准入规则、测试规范、改动后的最低验收三连,以及服务器上「什么该搬、什么不该搬」。
|
||
|
||
```
|
||
┌─────────── Browser (React 18 + Ant Design 5 + Vite + Zustand + Router 6) ─────────────┐
|
||
│ 项目总览 │ 资产库 │ 分镜与脚本 │ 调度中心 │ 质检与审核 │ 时间线合成 │ 导出与成本 │
|
||
└─────────────────────────────────────┬───────────────────────────────────────────────────┘
|
||
│ 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/ React 18 + Ant Design 5 + Vite + Zustand + React Router 6 工作台
|
||
(图文手册 = src/pages/Help.tsx,截图在 public/help/)
|
||
scripts/ 只放启动 / 部署 / 运维脚本(下表);一次性验证探针不进这个目录
|
||
docs/ UI 规范、工程规范、H3 性能诊断记录
|
||
media/ 产物库(MEDIA_ROOT) models/ whisper 词级对齐权重 reports/ 阶段验收证据
|
||
.local/ 开发态日志与 pid .trash/ 删除暂存(两者都不进 git,删掉就没了)
|
||
.env 本机配置与密钥(不进部署包) nex_animation.db 开发库
|
||
```
|
||
|
||
**`frontend/src/` 分层**(依赖只允许自上而下,页面之间不互相 import):
|
||
|
||
```text
|
||
api/ 唯一的 fetch 出口:信封自动拆包、detail 统一成 Error、401 跳登录
|
||
app/ 应用外壳:router.tsx 路由表(唯一一份)· layout/ 顶栏侧栏与 nav.tsx 两级导航表 · 鉴权闸门
|
||
pages/ 页面与项目子页(项目详情里的业务子页走 <Outlet/>,不是外壳页签),一屏一文件;
|
||
页面私有的类名常量/子组件留在文件底部
|
||
components/ 页面只从这里取组件,三个目录按职责分:
|
||
ui/ antd 的唯一封装层 + 自绘版式件(Button/Input/Checkbox/Menu/Overlay/Status
|
||
+ Field/Ctlbar/FormGrid/Table/Steps/Tabs/Pager/Rows…)
|
||
forms/ 选择器族(Select/MultiSelect/SecretInput + toOptions,本体是 antd Select)
|
||
media/ 带全局状态的媒体件(MediaThumb/AudioPlay/RecordAudio/MediaLightbox/VersionPanel…)
|
||
theme/ 只剩 antd.ts 一个文件,它是本站对 antd 的唯一改动清单:buildAntdTheme() 品牌色 + 表面色
|
||
+ 少数结构性 ComponentToken(几何/字阶/圆角/间距/断点一律用 antd 默认)· applyRootVars()
|
||
在 createRoot 之前把同一批 token 以 --ant-* 的名字铺到 :root · HEADER_HEIGHT 顶栏高度
|
||
stores/ zustand 切片:auth · theme · notice · project · models · system · audio · preview · recording
|
||
hooks/ use-async / use-polling / use-auto-refresh / use-local-storage(浮层外点关闭交给 antd,不再自己实现)
|
||
lib/ 纯函数与适配器:cn · format · media · pipeline · recorder · versions · layers
|
||
styles/ index.css(Tailwind @theme:语义名 → antd 落下来的 --ant-*,零像素,圆角与字阶只是别名)
|
||
· app.css(语义布局类 + 标签度量 --tag-* + 全站唯一允许写 .ant-* 的地方)
|
||
```
|
||
|
||
新增页面只做三件事:在 `pages/` 落文件 → 在 `app/router.tsx` 注册 → 复用 `components/*` 原语,
|
||
缺原语就补进 `components/`(不要复制粘贴样式)。加一类新母版、加一个项目环节(改 `app/layout/nav.tsx`
|
||
那张两级导航表 + `app/router.tsx` 子路由)、加一个页面内部页签同理:改表不改逻辑(见 `docs/工程规范.md` §1.1)。
|
||
|
||
**控件统一用 Ant Design 5**(2026-11-02 定案,此前「Radix primitives + 自有皮肤」那一版已废弃):
|
||
浮层定位、翻边避让、焦点圈定与归还、键盘、Esc 分层、锁滚动这些行为不再自己实现——
|
||
自己实现时「字段标题与控件不对齐」「下拉面板该翻不翻被压成 35px」这类问题修不完,
|
||
而每一项都是组件库早就解决过的。**尺子也交还给 antd**:自造的 `metrics.ts` / `palette.ts` /
|
||
`css-vars.ts` 三把尺子已删,`theme/antd.ts` 一处写完两件事——`buildAntdTheme(mode)` 只改品牌色、
|
||
表面色和少数结构性 ComponentToken(几何、字阶、圆角、间距、断点全用 antd 默认档位),
|
||
`applyRootVars(mode)` 在 `createRoot` 之前把 antd 算出来的 token 以 `--ant-*` 铺到 `:root`;
|
||
Tailwind 的 `@theme` 只是把 `--ant-*` 转发成语义类名,控件与自绘区读同一批变量,不可能漂成两套。
|
||
硬边界:全仓库只有 `theme/` · `app/`(`providers.tsx` 与外壳 `layout/` 四件套直接铺 `Layout.*`,
|
||
外壳没有第二份实现,包一层只会多一个名字)· `components/{ui,forms}` · `stores/notice.ts`
|
||
(antd `message` 的唯一出口)可以 `import 'antd'`——R8,探针第 5 道闸逐行扫,不再只写在文档里;
|
||
`.ant-*` 选择器只准出现在 `styles/app.css`;`pages/` 与 `app/` 里**一个原生 `<button>` / `<input>` /
|
||
`<select>` / `<textarea>` 都没有**,也不许给控件拼 `bg-`/`border-`/`rounded-`。裸 `<button>` 只许留在
|
||
「自定义表面族」里,判据是几何而不是长相:宽高由所在那块媒体/容器决定、antd 三档 24/32/40 套不进去的才算。
|
||
白名单就 7 个文件(`classaudit.mjs:CUSTOM_SURFACES`)——`ui/Controls`(Chip / TagChip 的叉)、
|
||
`ui/Overlay`(Scrim 整屏遮罩)、`media/MediaThumb`(封面角标与删除叉)、`media/AudioPlay`(走带键)、
|
||
`media/MediaLightbox`(灯箱翻页钮)、`media/VersionPanel`(版本缩略热区)、`pages/project/Storyboard`;
|
||
另有宿主标签不写字面量的 `ui/Tile`(`<As>`,见 `HOST_ELEMENT`)。
|
||
自绘区只剩三块并已在规范里登记边界:`Table`、`Steps`、媒体区(缩略图 / 播放条 / 录音 / 灯箱 / 时间线)。
|
||
再加一条 **ref 契约(R10)**:kit 组件一律 `forwardRef`,交给页面的 ref 只能是真实 DOM 节点,
|
||
antd 的 `InputRef` / `TextAreaRef` 在 kit 内部折掉(`lib/ref.ts`)——React 18 的函数组件收不到 ref,
|
||
`tsc` 不报错、像素不变,四处「点了不聚焦」就是这么静默死掉的(报告 26.6)。
|
||
这些边界都不靠自觉,两道闸各管一头:
|
||
|
||
- `node scripts/ui/classaudit.mjs`——**源码用词**(静态,五道检查,退出码 = 五项违规之和):
|
||
Tailwind 生成不出规则的**死类名**(v4 改过名的 `break-anywhere` 这类静默失效)/
|
||
绕过图标登记表的 `@ant-design/icons` import(只许 `components/icons/index.ts` 一处)/
|
||
未收口的裸 `<button>`(白名单外即违规;白名单文件一个 `nex-*` 标记都不写了也违规——说明这一族
|
||
已被 antd 取代,条目该从表里删)/ **浮层底部动作条**口径(不写 `size`、`type="primary"` ≤1、
|
||
`danger` 必须同带 `type="primary"`、最后一颗是主行动)/ **越界的 `import 'antd'`**(R8);
|
||
- `.venv/bin/python scripts/ui/visualcheck.py`——**渲染结果**(浏览器实测,逐路由 × 逐档宽度 × 明暗两色,
|
||
八类断言 + console / pageerror,逐条口径见 `docs/UI规范.md` §15.2):**先把 chromeless 的登录页量一遍再登录**
|
||
(登录后访问 `/login` 会被鉴权守卫弹回首页,登录后再量只会得到假故障);`:root` 上的 `--ant-*`
|
||
是否真的铺到、文字行高有没有塌成 px、侧栏选中态是否跟路由走(≤768 侧栏折叠,二级项在 hover 浮层里,
|
||
探针会把浮层打开确认那一条真的带 `.ant-menu-item-selected`)、请求的路由有没有被 `path:'*'` 静默重定向、
|
||
display utility 有没有被组件样式静默盖掉(R13 那条层叠陷阱)、横向溢出(祖先横向滚动盒或程序滚动的
|
||
裁切盒接住的不算——antd 页签条收溢出页签用的正是后者)、`overflow:hidden` 切掉的字、
|
||
**控件标签被省略号截掉**(分段 / 页签 / 按钮 / **下拉当前值**)、**4xx/5xx**(按 URL 分诊:素材文件在
|
||
开发库里缺失的 404 单独计数,接口 404 判失败并点名发出它的路由)。
|
||
|
||
选型理由、四层分工、咬过人的陷阱见 `docs/UI规范.md` §0(十四条硬规矩 R1–R14)与 §1。
|
||
旧的手写规范探针(`scripts/ui/legacy/{audit,metrics,vocab}.py`)已作废归档。
|
||
|
||
改过控件、表单或主题,提交前跑一遍 UI 体检(前端 5173 与后端 8000 需在跑):
|
||
|
||
```bash
|
||
cd frontend && npx tsc --noEmit && npm run build
|
||
node scripts/ui/classaudit.mjs # 源码用词闸(不用起服务)
|
||
NEX_WIDTHS=1440,992,768,430 NEX_THEMES=dark,light \
|
||
.venv/bin/python -u scripts/ui/visualcheck.py # 渲染结果体检 + 截图
|
||
```
|
||
|
||
体检默认量 dev server(5173):**`console` 那一项只能在 dev 上量**——React 与 antd 的告警是
|
||
DEV-only,拿 `NEX_UI_BASE=:4173` 量构建产物时它恒为 0,别把那份绿当证据。
|
||
|
||
| 脚本 | 干什么 | 在哪儿跑 |
|
||
| --- | --- | --- |
|
||
| `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` | `pages/AssetLibrary.tsx`、`pages/project/Library.tsx` | 平台级人物 / 场景 / 声线母版创建时始终全局,不绑定项目;项目目标只在「引入项目」时选择。母版可上传、AI 生成、编辑,项目资产可反向「上架平台」。图片支持大图预览,每个媒体可单独删除,不必删除母版。声线在创建时只录入基础设定,生成试听时再选真实模型;项目内继续维护定妆图/三视图/服装/表情、场景图、声线与项目素材;每次上传生成**新版本**,删除留痕 |
|
||
| **② 分镜与脚本管理** | `app/api/storyboard.py`、`services/importer.py`、`services/prompt.py`、`services/preflight.py` | `pages/project/Storyboard.tsx`(分镜工作台) | 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/*` | `pages/project/Dispatch.tsx` | 任务清单(预检驱动,可解释「为什么跳过/阻塞」)→ 入队 → 按 provider/model 并发槽位与 RPM 限流派发(**一个模型一行**,视频与 TTS 各自的限额互不串台) → 指数退避重试 → 中断任务断点续跑;模型注册表在线启停/设默认/调并发/调限流/注入故障演练 |
|
||
| **④ 长视频合成引擎** | `app/api/delivery.py`、`services/timeline.py`、`services/compose.py`、`services/ffmpeg.py`、`services/quality.py` | `pages/project/Review.tsx`、`Timeline.tsx`、`Delivery.tsx` | 自动质检 7 项打分;人工审核合格/驳回重做;时间线(片段裁剪/转场/排序/字幕/配音/BGM/响度归一化);交付预检报告;4 档出片预设 + 校验和留档;成本台账与生成记录可复现 |
|
||
| **底层:任务编排 + 项目数据库** | `app/models/*`、`app/db.py`、`services/events.py`、`services/status.py`、`services/costing.py` | `pages/Dashboard.tsx`、`pages/ProjectDetail.tsx`、`pages/project/Overview.tsx` | 12 张表(项目/人物/场景/声线/素材/素材版本/镜头/任务/审核/时间线/片段/字幕/音轨/导出/成本/生成记录/事件);任务幂等键、心跳、错误历史、检查点;全流程事件流与流程进度视图 |
|
||
|
||
## 2. 图2 业务流程 → 状态机与接口
|
||
|
||
流程节点定义在 `backend/app/services/status.py:PIPELINE_STAGES`,每个项目/镜头/任务的真实状态收敛成
|
||
`GET /api/projects/{id}` 的 `workflow[]`(`pending/active/done/failed`),前端 `components/media/WorkflowBar.tsx` 直接渲染。
|
||
|
||
| # | 节点 | 主要接口 | 镜头状态流转 |
|
||
| --- | --- | --- | --- |
|
||
| 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 总控台(`pages/project/Overview.tsx`)
|
||
|
||
项目主页顶部提供自然语言总控台:使用系统注册并启用的默认真实 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 分镜工作台(`pages/project/Storyboard.tsx`)
|
||
|
||
分镜是几十上百镜的大页面,所以列表**不**走返回全字段的 `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 <token>`。模型配置与账号管理(`/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/stores/system.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`,
|
||
React 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 半音 ✅ |
|
||
| 俊杰本人的音色样本 + `<Audio 1>` 标签 | 135.6 Hz | +2.1 半音(标签无增益) |
|
||
| 紫小慧的音色样本(女声喂男画面) | 177.8 Hz | 画面优先,性别冲突时以人物为准 |
|
||
|
||
要点:**参考音频真的能锁音色**(同性别误差 2 半音内);不给参考就会跑调;
|
||
性别冲突时模型以画面人物为准,所以 speaker→声线 的绑定必须准确(预检里
|
||
`voice_identity_risk` 就是盯这个)。产物确实没有音轨时自动回退配音,不会把台词变成哑巴。
|
||
|
||
**一镜多人说话**(`shot.lines` 里有多个 `character_id`)时,上面的表不够用了:
|
||
`MiniMaxH3ReferenceToVideo` 只有一个 `prompt` 文本入口,「这一句是谁说的」只能靠官方
|
||
语音标记表达——`<Audio j><d>台词</d>` 表示这段用 `ref_audio_j` 的嗓子(文本编码器
|
||
把标签与 prompt 裸拼,见 `comfy_text_encoders_minimax.py`)。因此 caption 里的说话人
|
||
**只走标签,绝不写角色名**(「俊杰台词:」会被原样念出来,见 4.0.2)。三处必须同时成立:
|
||
|
||
| 环节 | 位置 | 断掉的后果 |
|
||
| --- | --- | --- |
|
||
| 按逐句说话人收集音色,**顺序=开口顺序** | `prompt.dialogue_voices` | 第二个人没有参考音频,全片一个人说话 |
|
||
| 序号来自同一份列表 | `prompt.joint_voice_names` → `compose_joint_caption` | 标签把台词安到别人的嗓子上 |
|
||
| 只在「本镜不同说话人 ≤ 1」时才兜底标 `<Audio 1>` | `compose_joint_caption.audio_label` | 单人音色被套给整段对白 |
|
||
|
||
漏绑不报错,只会静默换声,所以预检加了 `joint_speaker_unbound`:某句台词的说话人拿不到
|
||
自己的参考音频(角色没设默认声线 / 声线缺克隆样本 / 超出 3 条上限)时点名告警。
|
||
|
||
#### 4.0.2 联合音视频模型的提示词契约:整段 caption 既被「看」也被「听」
|
||
|
||
H3 的文字入口只有一个 `prompt` 字段,**没有 chat 模板、没有 system/user 之分**,
|
||
文本编码器把整段文字同时当画面脚本和声音脚本。凡句子里出现「说/台词/配音/口型/
|
||
音画不同步/必须/严禁/为准」这类**关于声音或下指令**的说法,它就去念给你听——
|
||
项目 11《告诉你个小秘密第1期》v2 成片逐镜 ASR 实测:开头那两句莫名其妙的
|
||
「是这一镜的画面和石腰准和碍」,正是 `<Picture 1>是这一镜的画面。<Picture 2>是俊杰,
|
||
高大,和蔼` 被原样朗读(`drop_topic`/`sanitize_visual` 负责剔除)。
|
||
|
||
因此 `prompt.compose_joint_caption` 与通用提示词分道,规则是「**只写看得见的东西**」:
|
||
|
||
| 规则 | 做法 |
|
||
| --- | --- |
|
||
| 身份锚定不能写成句子 | 定语 `<Picture 3>中的紫小慧,…` 而非 `<Picture 3>是紫小慧`(`JOINT_REF_STYLE="prefix"` 可回退旧写法做 A/B) |
|
||
| 时长/画幅不进文字 | 它们是 `length/width/height` 结构化入参,写成「时长约 9 秒」就会被念出来 |
|
||
| 「谁在说话」不进文字 | 由**首帧构图**决定(`keyframe_speech_note` 只给图像模型)+ `<Audio n>` 标签;`speaking_subject_note` 那句构图描述写进 H3 文字就会被朗读 |
|
||
| 台词是最后一段 | 官方 `<d>…</d>` 段落,段间不补句号(会被当成句子结束、各配一段气口) |
|
||
| 表情里的「嘴」要改写 | 「嘴角上扬」→「面带笑意」:发声器官词会诱发即兴人声 |
|
||
| 台词时长按实测语速 | `JOINT_CPS_CJK=5.0` 字/秒(TTS 口径 4.3 + 标点停顿会多留 2s 空档,模型拿来念提示词),并允许**短于**分镜时长;帧数还要落在 `n % 17 == 5`@24fps 格点 |
|
||
|
||
回归用例:`tests/test_joint_caption.py`、`tests/test_speaking_subject.py`、
|
||
`tests/test_comfyui_adapter.py::test_joint_av_model_never_gets_a_spoken_negative`。
|
||
|
||
### 4.1 真实配音:macOS 系统语音(含外星语效果)
|
||
|
||
`macos_say` 适配器把系统 `say` 命令接入统一 TTS 任务、字幕对齐与混音链路,不需要
|
||
云服务密钥。启动后端时会自动登记为 `macos-say/system-voice`:
|
||
|
||
```bash
|
||
# 声线资产示例
|
||
{
|
||
"name": "女服务员 · Tingting",
|
||
"provider": "macos-say",
|
||
"provider_voice_id": "Tingting",
|
||
"language": "zh-CN",
|
||
"tuning": {"speed": 1.15}
|
||
}
|
||
|
||
# 外星语:Fred 低男声 + 降调/金属共振/颗粒化
|
||
{
|
||
"name": "铁血战士 · 外星低吼",
|
||
"provider": "macos-say",
|
||
"provider_voice_id": "Fred",
|
||
"language": "en",
|
||
"tuning": {"params": {"effect": "alien"}}
|
||
}
|
||
```
|
||
|
||
「资产库 → 声线」创建时只填写名称、语言、语速、音色和 `alien` 效果等基础设定,模型选择
|
||
移到「生成试听」步骤,并只列出真实 TTS 模型(Mock 不作为资产生成选项)。未就绪的模型仍可
|
||
选择并查看状态,生成时会返回具体缺失节点或服务错误,避免“探测失败就直接禁用”导致 IndexTTS2
|
||
无法选。IndexTTS2 必须提供参考音色:可上传一段音频,也可选择资产已有的音频;项目资产库同样
|
||
支持从当前声线的音频素材中选择参考音色。单独删除参考音频时会同步清理声线里失效的路径绑定;
|
||
若历史数据仍指向已删除文件,适配器会自动回退到模型配置的默认参考音频。适配器会用 ffmpeg
|
||
统一转为 24kHz 单声道 PCM WAV 并校验时长;未下载的系统音色或 ComfyUI 缺少 IndexTTS2 节点时
|
||
会明确报错,不会再生成只有 0.01 秒的静默文件。
|
||
|
||
IndexTTS2 是 ComfyUI 自定义节点,不是 Nex 内置推理器。目标 ComfyUI 需安装
|
||
[`ComfyUI-Easy-IndexTTS2`](https://github.com/yolain/ComfyUI-Easy-IndexTTS2),安装模型与 Python
|
||
依赖后重启 ComfyUI;`/object_info` 必须同时出现 `easy downloadIndexTTSAndLoadModel` 与
|
||
`easy indexTTSGenerateSimple`。Nex 不会在未经授权时远程安装节点或下载大模型。
|
||
|
||
在 9200 的 ComfyUI 主机上安装节点:
|
||
|
||
```bash
|
||
cd /dep/Bfmodeltest/ComfyUI-H3/custom_nodes
|
||
git clone https://github.com/yolain/ComfyUI-Easy-IndexTTS2
|
||
cd ComfyUI-Easy-IndexTTS2
|
||
/dep/Bfmodeltest/ComfyUI-H3/.conda-env/bin/pip install -r requirements.txt
|
||
# 重启启动 /dep/Bfmodeltest/ComfyUI-H3/main.py 的 ComfyUI 进程
|
||
```
|
||
|
||
注意:9200 当前运行 Python 3.13。`pynini==2.1.6` 没有 cp313 wheel,应先在同一 conda
|
||
环境执行 `conda install -c conda-forge "pynini=2.1.7"`;`transformers` 需限制在
|
||
`>=4.50,<5`,否则 IndexTTS2 vendored 的 4.x generation 实现无法导入;同时需要
|
||
`WeTextProcessing` 与 `accelerate`。9200 上已按此组合安装并完成真实参考音色生成验收。
|
||
|
||
节点首次生成时可按 `modelscope` 下载 IndexTTS-2 模型;也可按项目 README 将模型预置到
|
||
`ComfyUI/models/IndexTTS-2/`。重启后可检查:
|
||
|
||
```bash
|
||
curl -fsS 'http://10.100.53.199:9200/object_info/easy%20downloadIndexTTSAndLoadModel'
|
||
curl -fsS 'http://10.100.53.199:9200/object_info/easy%20indexTTSGenerateSimple'
|
||
```
|
||
|
||
Qwen-Image 生成同样支持参考图:平台和项目资产卡片都可选择当前人物/场景已有图片,或临时上传
|
||
一张图。适配器通过 `LoadImage` 和 `TextEncodeQwenImage21` 的
|
||
`images.image_N` autogrow 扁平槽位提交,并使用编码器输出的参考 latent;不选参考图时仍走
|
||
原有纯文生图流程。参考图存在时,输出画布会跟随第一张参考图的宽高比,这是该节点的原生行为。
|
||
Qwen Image 2.1 还要求提示词显式引用图片槽位;用户只写“参考图”时,适配器会自动在指令前
|
||
补充 `以<image1>为参考,按以下要求生成或编辑:`。室内/内景类短提示还会自动补充“镜头移到
|
||
建筑内部、不要展示外立面或室外庭院”的机位约束,否则模型常沿用参考图的外景构图。生成种子
|
||
同时由提示词、参考图和画布尺寸共同派生;用户未固定 seed 时,再次生成会得到新的随机结果,
|
||
不会因为平台资产 ID 相同而永久复用同一张图。
|
||
分镜关键帧从「分镜 → 资产 → AI 生成关键帧」发起,走同一个真实图像模型与 `AssetGenRequest`
|
||
链路;生成前会同步当前镜头的版本化提示词,结果写入镜头的 `keyframe` 资产槽位并递增版本,
|
||
因此后续 H3 i2v 会立即使用新首帧,无需手工再上传一次。
|
||
|
||
### 4.2 三关键帧真实成片示例(平台内跑法)
|
||
|
||
这条链路已经在真实 H3 上跑通过:三张关键帧 → 角色/场景/声线 → 真人报菜名 →
|
||
外星语回应 → H3 三段出片 → 审核 → 时间线混音 → 1080p 导出。现在直接在界面上走:
|
||
|
||
1. **资产库**录角色定妆图 / 场景图 / 声线;新建项目时可勾选要引入的资源库,避免每次重录;
|
||
2. **分镜**写三段镜头:有台词(真人)、有台词(外星语 + 变声)、无台词空镜各一段——
|
||
无台词是正常形态,平台不会为它编一句旁白;
|
||
3. 每段先出关键帧,再用 H3 i2v 出片;`voice_source=native` 时带原生音轨的镜头**不再叠加 TTS**(§4.0.1);
|
||
4. 质检 + 人工审核通过后,**时间线**混音、挂字幕,导出 1080p。
|
||
|
||
固化的 `predator_meal_e2e.py` 探针已归档到 `.trash/2026-11-01/scripts/`;它当年靠
|
||
「跳过已成功镜头」省卡时,今天这件事由平台的断点续跑与单镜头重新生成承担。
|
||
|
||
|
||
- **默认 `mock` 适配器**:不依赖任何供应商即可跑通全流程。视频以关键帧/定妆图为底图按运镜参数生成**真实可播放**的测试片段,配音按文本长度生成占位人声 WAV,因此质检、时长对账、转场、混音都能被完整验证。**它是流水线验证工具,不是 AI 视频模型。**
|
||
- **`http_generic` 适配器**:供应商协议骨架(提交任务 → 轮询 → 下载),各家(Veo/Kling/可灵/即梦等)请求体差异需实现各自的 adapter,不要假定开箱兼容。
|
||
- **模型注册表** `provider_models`:`GET/POST/PATCH/DELETE /api/providers`,可设默认模型、每模型并发上限与 RPM、时长/分辨率能力、每秒单价;调度中心页面支持💥注入 `failure_rate=1.0` 做故障演练。
|
||
- **真实大模型**:在「模型控制台 → 大模型」登记 OpenAI 兼容端点(如
|
||
`https://api.deepseek.com/v1` / `deepseek-v4-pro`),填写密钥并设为默认;密钥只以密文落库,
|
||
页面回显掩码。大模型只承担 chat / prompt 文本能力,不再提供文生图端点、图像模型或尺寸配置;
|
||
旧数据中的 `t2i` 模式、参考图/画幅字段和 `config.image` 会在保存或启动迁移时自动清理。
|
||
图像生成统一使用独立图像模型。Mock LLM 应在登记真实模型后停用,避免文本补全误走占位结果。
|
||
- 真实供应商通常要求**参考图公网可读**,请自行接入对象存储并注入签名 URL。
|
||
|
||
## 5. 质检与合成参数
|
||
|
||
| 项 | 默认 | 配置 |
|
||
| --- | --- | --- |
|
||
| 质检打分 | 解码完整性 30 / 时长偏差 20 / 分辨率 15 / 码率 10 / 黑屏 8 / 冻结 9 / 帧率 8,硬失败项(severity=error)直接判不合格 | `QC_DURATION_TOLERANCE`、`QC_MIN_BITRATE_KBPS`、`QC_BLACK_THRESHOLD` |
|
||
| 出片预设 | `draft_720p`(1280×720) · `vertical_720p`(720×1280) · `web_1080p`(1920×1080) · `vertical_1080p`(1080×1920) · `hq_1080p`(CRF18 slow) · `uhd_4k`(3840×2160 CRF18 slow) | `services/ffmpeg.py:EXPORT_PRESETS` |
|
||
| 时间线 | `fps/width/height`、`subtitle_mode`、`subtitle_style`、`voice_source`(`native`/`auto`/`dub`,见 §4.0.1)、`keep_shot_audio`、`voice_gain_db`、`bgm_gain_db`、`duck_bgm`、`target_lufs`、`lead/tail_padding_ms`、`hold_last_frame` | `PATCH /timeline/settings` |
|
||
| 转场 | xfade(有转场滤镜时)或直切;`XFADE_MAX_DURATION_MS` 限制 | `TARGET_LUFS` 控制 `loudnorm` 目标响度 |
|
||
|
||
**FFmpeg 能力探测**:`GET /health` 返回 `ffmpeg_capabilities`,字段为
|
||
`available / drawtext / subtitle_burn / subtitle_filter / xfade / concat / loudnorm /
|
||
blackdetect / freezedetect / font`。当 `subtitle_burn=false`(本机 ffmpeg 未编译
|
||
`subtitles/ass` 滤镜)时:
|
||
|
||
- 走**时间线默认设置**的字幕会被自动降级为「外挂字幕」,导出照常成功,并写入
|
||
`compose.subtitle_skipped` 警告事件(合成报告与事件流可见),**不会**让任务失败;
|
||
- 只有导出时**显式**传 `burn_subtitle=true` 才会中止任务并给出可执行的修复建议——
|
||
用户点名要烧字幕时绝不静默忽略;
|
||
- 外挂字幕随时可取:`GET /projects/{id}/timeline/subtitles?fmt=srt|ass`;
|
||
要真正烧录请换用带 libass 的 ffmpeg 构建(侧边栏此时以黄色标注「降级为外挂字幕」,
|
||
而缺 ffmpeg 本体才是红色「阻断合成」)。
|
||
|
||
## 6. 测试与自检
|
||
|
||
改完代码的**最低验收**(完整约定见 `docs/工程规范.md`):
|
||
|
||
```bash
|
||
cd backend && ../.venv/bin/python -m pytest -q # 全量回归,约 3 分钟,必须全绿
|
||
bash -n scripts/*.sh # 脚本语法(shellcheck 没装也别跳过这条)
|
||
cd frontend && npm run build # 类型与打包(tsc --noEmit && vite build)
|
||
node scripts/ui/classaudit.mjs # 前端用词闸(源码,秒级)
|
||
NEX_WIDTHS=1440,992,768,430 .venv/bin/python -u scripts/ui/visualcheck.py # UI 体检 + 截图
|
||
```
|
||
|
||
碰到派发 / 合成 / 部署链路的改动,再补一次 §6.2 的端到端自检——pytest 用 TestClient
|
||
在进程内测契约,测不出「这台机器上这套服务能不能交付」。
|
||
|
||
### 6.1 单元/接口回归(pytest + TestClient,进程内,无需起服务)
|
||
|
||
```bash
|
||
cd backend
|
||
DATABASE_URL='sqlite://////tmp/nex_tests/t.db' TASK_EXECUTOR=inline MEDIA_ROOT=/tmp/nexmeta \
|
||
../.venv/bin/python -m pytest -q # 12 个测试文件 / 115 个用例,全绿
|
||
```
|
||
|
||
覆盖:系统/健康/枚举、资产库与素材版本、脚本导入与图片匹配、
|
||
提示词组装与版本、入队预检与幂等、失败重试与错误留痕、断点续跑、质检打分、审核回路、
|
||
时间线重算与交付预检、导出成片与成本台账,以及 `tests/test_regression_fixes.py`
|
||
(14 个用例,专门锁定端到端验证中发现并修掉的缺陷:Markdown 文档标题误判为镜头、重复镜号触发
|
||
UNIQUE 500、上传响应回吐过期版本、`黑场` 转场常量拼写、流程节点按镜头计数导致 5/4 分母、
|
||
`review_state` 与审核记录 verdict 必须同源且无产物不得放行、**局部生成失败被整体成功掩盖**
|
||
(失败镜头的旧产物仍在磁盘上时,节点 8/9 也必须转红并从可用产物计数里扣除)、
|
||
限流容量行按 `(provider, model)` 去重且媒体类型跟随模型规格、项目队列不得混入其他项目任务、
|
||
平台人物创建时保持全局、单媒体删除及文件清理、IndexTTS2 参考音色上传与项目引入时的本地副本等)。
|
||
`tests/test_comfyui_adapter.py` 还会用本地假 ComfyUI 完整走一遍 IndexTTS2 节点探测、参考音频上传、
|
||
节点图提交、音频下载与产物校验,并锁定“缺少节点时不得提交任务”以及 Qwen 参考图 autogrow
|
||
连线与参考 latent 的行为。Qwen 参考图节点图已在 9200 实机生成验证。
|
||
`tests/test_agent_orchestrator.py` 覆盖 LLM 结构化计划、全流程白名单执行、Mock 拒绝、越权动作拒绝、
|
||
AI 审核授权门禁、空项目阻塞、已完成项目的幂等诊断,以及 `kind=agent` 审核审计隔离。
|
||
`tests/test_macos_say.py` 另外用系统 `say` 实测中文与外星语音频,并校验配音任务记录实际
|
||
供应商而非全局默认值。**Python 需 3.11+**
|
||
(系统自带 3.9 无法运行本项目)。
|
||
|
||
### 6.2 端到端业务自检(打真实服务 + ffprobe 实测)
|
||
|
||
```bash
|
||
# 终端 A:起后端(无需 Redis / Postgres / 供应商密钥)
|
||
cd backend && DATABASE_URL='sqlite://////tmp/nex_ui/ui.db' MEDIA_ROOT=/tmp/nex_ui/media \
|
||
TASK_EXECUTOR=inline MAX_SHOT_RETRIES=2 RETRY_BACKOFF_BASE_SECONDS=1 \
|
||
RETRY_BACKOFF_MAX_SECONDS=2 ../.venv/bin/uvicorn app.main:app --port 8000
|
||
# 后三个变量只是把「失败重试」的退避从默认几十秒压到 1~2s,让第 16 步不必干等
|
||
# 终端 B:跑图2 全 12 节点
|
||
NEX_BASE=http://127.0.0.1:8000 ../.venv/bin/python scripts/e2e_selfcheck.py
|
||
```
|
||
|
||
`scripts/e2e_selfcheck.py` 会新建一个独立项目,按图2 顺序跑完 12 个节点(**含「生成失败重试」
|
||
与「审核驳回 → 改提示词 → 重新生成」两条回路**),并真的下载产物用 ffprobe 校验镜头与成片
|
||
(时长 / 分辨率 / 编码 / 音轨),任一环节不符合预期就打印接口原文并以退出码 1 结束。
|
||
它只依赖 HTTP 与本机 ffprobe,不需要知道后端 `MEDIA_ROOT`。也可 `NEX_BASE=http://127.0.0.1:5173`
|
||
走前端代理,顺带验证代理配置是否正确。服务端开着鉴权(默认值)时脚本会先自动登录换 Cookie
|
||
(账号取 `NEX_USER` / `NEX_PASS`,缺省用 `/api/auth/state` 回传的初始管理员),
|
||
所以部署完在服务器上直接 `./scripts/server.sh verify` 就能跑,不用手工准备会话。
|
||
|
||
第 [16] 步用 `PATCH /api/providers/{id}` 给 mock 视频模型注入 `failure_rate=1.0`,验证节点 8
|
||
判定为「否」时的完整链路:按上限重试并逐次留痕 → 镜头落 `failed` 且不产脏数据 → 流程节点转红
|
||
并写明原因 → 修复配置后 `POST /tasks/retry-failed` 一键重跑 → 节点重新全绿,跑完自动把注入复原。
|
||
开跑前的 [00] 步还会先清掉上一轮中断残留的注入,因此脚本可以反复执行。
|
||
|
||
### 6.3 前端构建
|
||
|
||
```bash
|
||
cd frontend && npm run build # tsc --noEmit && vite build
|
||
# 当前 103 modules → 17 个 chunk,JS 合计 ~907 KB(gzip ~296 KB)+ CSS 98 KB(gzip 19 KB)
|
||
# 首屏只下载 index(~411 KB/131 KB gzip) + 共享原语 ui(~80 KB/26 KB gzip) + 当前页 chunk;
|
||
# 手册 /help 也是懒加载页面(Help chunk 42 KB / 12 KB gzip),不再是一份独立静态 HTML
|
||
```
|
||
|
||
## 7. 边界与说明
|
||
|
||
- 平台保证的是**工程可靠性**(幂等、重试、断点续跑、限流、质检、留痕),不保证供应商永不失败,也不保证模型生成的人物绝对一致——一致性靠资产库定妆图 + 提示词约束 + 人工审核共同兜底。
|
||
- 登录鉴权(会话 Cookie + 角色闸门)与供应商密钥加密落库**已内置并默认开启**,页面只回显掩码;
|
||
公网部署仍建议放在 HTTPS 反代后面,并把 `MEDIA_ROOT` 放在受控存储上。关掉鉴权只适合可信内网。
|
||
- 媒体文件一律由后端 `/media/*` 直出,前端不拼本地路径;导出记录保留 `checksum`、`size_bytes`、`elapsed_ms` 便于对账。
|
||
- 变更类接口统一返回 `{ok, result, summary}`(前端 `src/api/client.ts` 自动拆包),错误体统一读 `detail`;只读接口大多直接返回资源对象,**两个例外**是 `GET /api/projects/{id}` 与 `GET /api/projects/{id}/summary`——它们也带信封(前端已统一处理,写脚本时记得拆开或自动拆)。
|
||
|
||
### 7.1 前后端契约(已用回归用例锁死,改动前请先跑 `tests/test_regression_fixes.py`)
|
||
|
||
- **`review_state` ∈ `pending / pass / fail`**(`app/constants.py:ReviewVerdict`,与
|
||
`ReviewRecord.verdict` 同源)。它和镜头 `status`(`approved/rejected/…`)是两个字段,
|
||
分镜卡片按前者显示人工结论;写成 `approved` 会让每个合格镜头都标红成「被驳回」。
|
||
- **人工审核必须在产物之后**:镜头没有 `output_path` 时 `POST /approve` 直接 400,
|
||
对应图2「质检(9)→ 人工审核(10)」的先后顺序。
|
||
- **流程节点计数按镜头去重**:`workflow[]` 每项是 `{key,label,state,done,total,detail}`,
|
||
同一镜头驳回重做会产生多条任务,计数必须按镜头去重(否则节点 6 永远 active、
|
||
节点 4 会出现 5/4);`done` 恒 ≤ `total`。
|
||
- **`/health` 是前端侧边栏的唯一数据源**:`{status, app, executor, ffmpeg,
|
||
ffmpeg_capabilities{available,drawtext,subtitle_burn,subtitle_filter,xfade,concat,loudnorm,
|
||
blackdetect,freezedetect,font}, database, model_specs, daemon{enabled,running,executor,
|
||
inline_pending,loops,last_dispatched,last_error,last_tick}}`,前端会校验字段类型,
|
||
拿不到合法 JSON(例如代理漏配)时直接报错而不是显示「未知」。
|
||
- **响应三套约定**:写接口 = `{ok, result, summary}` 信封;绝大多数只读接口 = 裸资源对象
|
||
(`{shots,count}`、`{timeline,report}`、`{preflight,summary}`…);错误 = `detail`。
|
||
例外只有 `GET /projects/{id}` 与 `GET /projects/{id}/summary` 也走信封。
|
||
另外 `PATCH /timeline/settings` 的参数需要再包一层 `{"settings": {...}}`。
|
||
- **交付文案里的项目名**:`workflow[0].detail` 只在项目名不含 `《` 时补书名号,避免渲染成《《…》》。
|
||
- **限流容量行 `GET /api/projects/{id}/queue` 的 `capacity[]`**:一个 `(provider, model)` 只允许一行,`media_type / concurrency_limit / rpm_limit / enabled` 必须取自该模型的 `ModelSpec`。曾因任务派生的容量键一律写成 `media_type="video"`,配音模型多出一行默认限额
|
||
(2 并发 / 30 RPM)的幽灵记录,并按 `provider|model` 覆盖掉真正的 TTS 行(4 / 120),派发时的 `headroom()` 与模型注册表的 `load` 一起被降级。
|
||
- **局部失败不许被整体成功掩盖**:节点 8「调用视频模型」/节点 9「下载并保存视频」的进度按
|
||
**可用产物**计数,停在 `failed` 的镜头即使磁盘上还留着上一次的旧产物也要从分子里扣掉,
|
||
且节点状态必须是 `failed`。曾因按「产物文件是否存在」直接计数,重做失败的镜头仍显示
|
||
「生成成功 4/4 [done]」,界面上完全看不见图2 节点 8 的「否」分支。
|