- 纠正 render.md/pitfalls.md「按设计时间缩放字幕」错误做法,改为只认实测发声段 - 新增 scripts/align_subtitles.py(泛化对齐工具,配置外置、支持 dump-segs/init-config/dry-run) - render_native.py 加 --ass 参数,读对齐 ASS 不被内置设计时间轴覆盖 - pitfalls/native-av/README/SKILL 补六条踩坑;install.sh 清单同步
17 KiB
17 KiB
踩坑速查(跨项目通用)
I2V 服务端
- 不要
--force-fp16:会把 fp8 权重升成 fp16,是常见崩溃根因;去掉后低内存 cgroup 也稳定。 - 按启动参数预检,不按 RAM 硬挡:查服务端
/system_stats的argv,不要凭宿主内存判断能否跑。 - 跨 prompt 传 conditioning 常被服务端权限封死:分阶段/接力方案不要做,每段独立、自包含。
- 网络超时不能证明任务未提交;重试前先查状态,避免重复消耗算力。
- 单段约 5 秒;要更长用
tpad=stop_mode=clone克隆尾帧,清单里标"pad": true。 - 纯 I2V 服务没有文生图权重(
/object_info看CheckpointLoaderSimple.ckpt_name是否为空):首帧必须外部生成。无首帧模式人脸锁不住,别指望用它替代角色锚图省成本。 - H3 的 I2V 看卡不看端口(2026-11-17 更新):
30113(2080Ti 22 GB)给MiniMaxH3ImageToVideo塞first_frame会走vae.encode()并把 video VAE 焊住,采样期必CUDA out of memory—— 该卡只有 T2V。30121(DCU K100 64 GB)I2V 完全可用,带原生对白音轨,台词镜头走这条(见 native-av.md);要静音首帧锁图、又不想等 90 分钟,仍用 A14B。
首帧图
- 图像生成结果常在右下角带平台水印;
delogo在部分静态 ffmpeg 上参数解析异常,改用crop=W:(H-70):0:0裁掉底部带最稳——不拉伸、不补假像素,I2V 的ImageScale crop=center会自动居中裁成 9:16。 - 省额度做法:三张分镜首帧合并成一次横排三格拼图,本地等分裁切;三格同图还顺带保证角色一致。
- 拼图切片必须按文件名时间正序:
ls -1t按修改时间倒序会把最后一张当第一张,导致 S01 拿到 S16 的画面。生成名带 ISO 时间戳时,用ls -1 <dir>/*.png | sort正序再每 3 格顺序映射。切完先抽查首/中/尾三类内容再提交。 - 首帧带可读文字 → I2V 会把它当动态内容重绘成乱码。首帧必须"无文字",文字一律后期烧。
- 首帧手部畸形(爪状/多余手指)→ I2V 只会继承并放大,必须换图,改提示词没用。
运动提示词 / 漂移
- 正向锁要写成可判定状态,不要只写否定句:写"双臂垂在体侧 / 手始终低垂 / 细光保持细线 / 双手不触及不跨越 / 不转身 / 不变走廊",并把禁止句放最后强调。
- 对「几乎静止」的镜头,显式禁止场景补全:
no ceiling / no floor / no perspective vanishing point / no camera movement / never become a bright band。 - Wan2.2 两类高频漂移,正向锁压不住,直接用
keepSeconds:- 静止人物镜——末帧必抬手 / 转正;
- 细光分屏镜——细光变光柱、节点增生、双手越界。 截前 1.2–2.5s 稳定段慢放到目标时长,慢放反而强化"静止对峙"观感,比反复抽卡省时间。
- 唯一值得重跑的是硬伤:首帧乱码文字被重绘、首帧手部畸形——必须换首帧图。
- 发现漂移只处理该镜,换提示词即换哈希、旧片段不覆盖,留作候选。
配音 / 字幕
- edge-tts 免费免密钥,商用授权需自行核对微软条款;免密钥不等于可商用。
- 先量实测时长再回填分镜
duration;不要加快语速硬塞。长句可能超出模型标称时长,用pad:true让tpad=clone补足。 - 旁白唯一性要显式校验:手写多句时易重复或漏填。加
len(lines) == len(set(lines))断言,并比对剧本表与30_shots.json的line逐字一致。改词后必须删除对应vo_NN.mp3再跑tts.py,否则脚本按文件存在跳过、配音与字幕不一致。 - 静态 ffmpeg 带 libass,
ass滤镜支持fontsdir,中文用系统字体(如 PingFang.ttc)。竖排标注用 ASS 的\N逐字分行,别让生成模型画文字。 - ASS 标点落单:折行逻辑不要把标点当独立 part;标点直接并入当前行,末尾若只剩标点则并回上一行。
- HUD 时间窗按累计
duration算:绑最后一镜起点 +0.5~2.8s 时,抽帧验收要抽窗口内(如 88s),抽窗口外会误以为 HUD 没烧上。
对白 / 口型(2026-11-17 结论:不要再事后贴嘴)
- 事后 lip-sync 三条路线全废:Wav2Lip 96×96 贴回 = 嘴部一块糊,与照片级画质断层;LatentSync 需要 8–18 GB 专用显存,22 GB 卡上装不下第二套大模型;InfiniteTalk 一镜 78 分钟且油画感、发蓝、背景糊、身份漂移。判据:贴嘴的画质上限由 lip-sync 模型决定,不由锚图决定。
- 正路:H3
fl2va音画同出 + 首帧锁图(30121,64 GB)。一条节点图同时出画面 / 人声 / 环境音,口型原生对齐。详见 native-av.md。 - 分镜要跟着改:走音画同出后必须在生成前定死正反打,每镜单人位;"先拍双人镜后期切嘴"这个思路不成立。双人同框只在无人说话、或只有一人有台词时用,并写
Only <name> speaks+<other> keeps lips closed。 - 台词即字幕:原生音轨不可编辑,台词改了只能重跑该镜。所以台词先定稿,字幕文本直接用提示词里的引号原文,不要跑 ASR 反推(转写只用来验收)。 但字幕时间轴例外——提示词里的设计秒数不能直接用,必须按实测发声段重排(见本节末 2026-11-19 补)。
- 沉默段也要写:
silence./lips parted, breath audible。不写模型会自己编声音,甚至编出第二个人说话。 - 验收靠转录比对:
AudioTranscribe转写返回的 mp4 音轨,与提示词台词逐字比对(实测一字不差);再抽首/中/末帧看口型。别用"听起来像"糊过去。
长任务:排队与实例重启(血泪)
- 单镜 90 分钟级,绝不能挂进程等:会话被回收、终端断掉后服务端仍在跑,但 pid 丢了就再也取不回来。正确做法是「排队 → 落盘
prompt_id→ 事后取回」三件套。 queue与history都是内存态:实例一重启(重部署、崩了自愈、换权重)排队的任务静默消失,不报任何错。实测 15:16 排 7 镜,15:43 实例重部署,队列清空、7 镜全丢,直到次日才发现。GET /history/<pid>返回{}有三义(排队中 / 执行中 / 不存在),单看它判不了任何事。判据必须交叉核对/queue:running+pending 为 0 且 history 也查不到 → 任务已丢,重排。- 排完 5 分钟内做一次存在性自检(
queue_h3_native.py --check),交付前再核一次;不要只信本地 map。 /api/free在 DCU 上会崩服务(约 20 s 自愈),且崩溃会连带清空队列与 history —— 这是"任务莫名消失"的常见真因。- 交付话术:
prompt_id存在 ≠ 已提交成功 ≠ 正在跑 ≠ 已完成。只有/view拉回本地且字节数合理,才能说"已生成"。
ffmpeg / 缝合
- 不要 brew 装:macOS 12 + Homebrew 6 有 dav1d Ruby bug。用
pip install --user imageio-ffmpeg(静态版)。 - 去水印用
crop+pad,不要 drawbox(遮罩留痕)。 - A14B/I2V 视频通常没有水印,默认
--crop-bottom 0,不要白裁画面。 zoompan落版:d取总帧数(2s×30fps=60),s=720x1280:fps=30并补format=yuv420p,才能与主线 concat 一次编码。- 缝合顺序:先逐段标准化(裁带 / 居中填充 / 30fps / tpad clone 补足精确时长),再一次 concat + 烧 ASS,避免多次重编码掉画质。
原生音画镜专用(render_native.py,2026-11-18 补)
- 两条缝合路线别混:台词镜(原生 aac 音轨)走
render_native.py;只有无音轨镜/旁白镜才走render.py。 给原生音画镜套render.py= 双份人声 + 强加落版 + 强改 720×1280 掉画质。 - 按源实际时长拼,不按设计时长:用
probe_duration()读每镜真实时长累计。按30_shots.json的设计duration硬拼, 源实际常长零点几秒,逐镜累积后音画明显错位。 🔴 字幕时间轴不能照[Audio]设计时间(含按源实际/设计缩放)——H3 实际发声与设计系统性错位, 照抄会让字幕整体早于口型 0.5–1.5 s。必须按实测发声段对齐,见下方 2026-11-19 补。 - 字幕取 h3v3
[Audio]:正则0.0s-0.9s: "台词"解析,台词用引号内原文(=定稿逐字),不做 ASR 反推。 台词正文必须写中文全角引号「“ ”」,半角"会破坏正则;半角逗号也统一全角。 - 画面瑕疵遮盖:局部乱码字(药盒假中文)→
crop+boxblur+overlay轻度模糊;模型自发时间戳/座位数字 → 纯黑实心drawbox盖住。 用boxblur盖时间戳会在静态 ffmpeg 上出亮块更显眼;矩形要够宽包住整串字符。坐标基于 576×1024,换分辨率要重量。 - 保留原生音轨:标准化只
setsar=1,fps=24,format=yuv420p,-map 0:a原样带过去,全程不叠 TTS。 - 出片核验:打印的 Stream 行里必须有 aac 音轨;只有画面没声音 = 缝合失败。
字幕对齐 / 静音镜 / 包装(2026-11-19 EP01 复盘补)
- 🔴 字幕时间轴只认实测发声段,不认设计时间:
[Audio]里的秒数是设计值,H3 实际语速/停顿/起句延迟与它系统性错位, 照抄或按比例缩放都会让字幕早于口型且逐句累积。正解:silencedetect=noise=-32dB:d=0.12测真实发声段, 逐句映射后重排时间(tools/align_subtitles.py,--dry-run先看)。台词原文不动,只改时间。 - 别指望 ASR 做时间对齐:
AudioTranscribe当天连续 3 次 900 s 超时(整机/6 s/7 s 切片都超时)。波形检测更稳更准。 - 段索引同阈值生成:
ALIGN表的发声段索引必须与silencedetect用同一套参数,混用 -38dB 与 -32dB 的结果会让 台词落到极短气口上(EP01 曾把 0.14 s 气口当台词、强拉成 0.45 s)。改完先--dry-run核对每句时间。 - 静音镜会自发吐音:设计为
SILENT SHOT的镜头(如静物特写)H3 仍可能吐出人声/英文。交付前逐镜volumedetect: 首尾是底噪(约 -58/-65 dB)而中段突然 -14 dB = 模型吐音,用-af volume=0整段静音再拼。这是音轨问题,改字幕无效。 - 画面文字 ≠ 字幕:生成图里药盒/包装上的字母是像素本身,不是后期烧的字幕;审片看到"英文"先抽帧分辨来源,别误判。
- 包装叠字统一一种形式:角标用
BorderStyle=1+ 深色描边 + 透明底,别用BorderStyle=3实心底框(突兀的"蓝底白字")。 - 角标别和对白重复:同一信息(如"十七例不良反应")不要既做对白字幕又做数据角标,二选一,否则同屏重复。
- 精修只动后期、不重跑模型:字幕错位/单镜吐音/包装样式问题都能纯 ffmpeg 后期修复,别重跑 90 min/镜的音画同出。
选机(2026-11-19 实测补)
192.168.1.30:30113不是 4 GB 弱机,是 RTX 2080 Ti / 23.1 GB(显存足够,K8s cgroup 才是 4 GiB 内存硬限)。 出图权重是int8_convrot(CUDA 正确档,DCU 禁)。但慢:单张约 190s vs DCU 23 的 52s,慢约 4 倍。- 30 连续出图后服务会整体崩:三个端口(30111/30112/30113)同时 Connection refused(机器 ping 通,是 K8s pod 崩重启,非 OOM)。
kubectl 不在 PATH 时无法快速恢复 → 音画同出任务别排到 30,回退 DCU 23(
192.168.1.23:30121)。 - 30 上 I2V 仍不可用:虽带 fl2va_w6a8 + qwen3vl + video/audio VAE 全套权重,23 GB 显存扛 576×1024×20 步存疑,且服务先崩,没测成。 「I2V 只能在 64 GB 卡」的判据不变。
清单 / 可复现
- 提示词每次重写会导致一致性崩且无法复现;固定描述段逐字复用,变量只在
30_shots.json。 - 分镜表不结构化 → 时长、编号、台词全靠记;用
manju.py validate前置拦截。 submit_i2v.py与manju.py hash-file的哈希算法可能不同(前者read().strip(),后者不一定)。预估新哈希要先统一 strip,否则会误以为没换哈希。manju.py manifest保留已有 attempts,扩表时旧记录不会被覆盖;但新提示词哈希全变,脚本按哈希命名会全部 FRESH 重生成,不会误用旧片段。- 不做归档 → 第二集找不到第一集设定;
50_manifest.json必须保留 attempts 历史。
配置 / 依赖
- 工具脚本只用 Python 标准库;配置与清单一律 JSON,避免 YAML 依赖。
- 路径解析三级回退:
MANJU_ROOT环境变量 → cwd 向上找config/pipeline.json→ 脚本上级目录。先 cd 到工作空间根再运行脚本。 - 密钥不落明文:端点如需鉴权,走环境变量或密钥工具,不要写进
config/pipeline.json。
生成后清理(ComfyUI 残留)
/view拉回的只是副本:服务端output/里的 mp4/png、input/里上传的首帧、以及history里的节点图与提示词原文全都还在。共享服务上等于把素材留在别人能看到的地方。- 标准接口优先:新版官方路径带
/api前缀(/api/history、/api/queue、/api/free),无前缀是等价别名;脚本先探/api/system_stats,不支持自动回退。 - 官方删除接口不带任何归属校验:
POST /api/history {"delete":[pid]}谁都能调,而30112上 151 条历史里绝大多数是别人的任务。必须先读 history 项里的client_id判归属(台账clientId>cleanup.clientIds>ownerPrefixes);requireOwner=true时未通过一律拒绝、不调任何删除接口。--prompt-id显式清任务要带--client-id。 client_id的位置在内存态与 HTTP 序列化态不同(关键坑,2026-11-12 修):ComfyUI 0.38 的 HTTP 序列化布局是prompt = [number, prompt_id, graph, extra_data, [...]],client_id在prompt[3];但 0.45 的内存态prompt_queue.history是prompt = [extra_data, number, graph],client_id在prompt[0]。扩展从内存态读,若只查[3]会在 0.45 上读出空串 → 归属校验全失败、所有任务清不掉。扩展与客户端都已兼容两种布局(先查[3]/[0],再退化递归找),改client_id_of时别再写死[3]。回归测试见scripts/selftest_cleanup.py。- 先读后删:
GET /api/history/<pid>抽outputs清单 → 再批量POST /api/history {"delete":[...]}+/api/queue。删了就再也查不出服务端留下了什么。 - 装了扩展时顺序反过来:
purge依赖 history 反查产物文件名,必须先删文件再删记录;旧顺序只适用于没装扩展的降级路线。见 models.md §3.4。 - 200 空 body ≠ 删除成功:这些 POST 幂等,删不存在的 pid 也返回 200。必须删后复核
GET /api/history/<pid>(判据是「删前有 → 删后无」)并查/api/queue;{}还有排队 / 执行中 / 不存在三义,单看{}判不了任何事。 history是内存态、文件是持久态:Pod 重启后记录自然消失,output/却还在 PVC / 宿主盘上。别把「重启过了」当成「清理过了」。- 官方删不了
output/文件(已核对server.py与官方文档):DELETE /userdata/{file}只管ComfyUI/user/,DELETE /api/assets/{id}默认 503 且删的是数据库引用。首选技能自带扩展assets/comfyui-manju-cleanup/:只传 pid,服务端从 history 反查文件、二次校验归属、做路径逃逸与跨任务引用计数;装到custom_nodes/并重启进程即可,官方add_routes()自动镜像/api前缀。降级路线:社区comfyui_extra_api/ComfyUI-api-tools补标准DELETE(配cleanup.deleteApi),或在服务端文件系统上精确删(cleanup.commands)。没配模板时脚本只列清单,不要报「已清理」。 - 扩展只按 pid 反查,不接受任意路径:这是防误删的关键,别改成「客户端传文件名列表」。它还会把被别的 pid 引用的文件判
shared跳过(共用首帧 / 同名产物);dry_run默认true,MANJU_CLEANUP_TOKEN可开鉴权。 - 重启 ComfyUI ≠ 清理,而且会清掉别人的记录:
history是内存态,重启后所有人的记录一起消失;扩展此时按 pid 反查不到,返回exists=false / owned=false并拒绝删文件(DCU 2026-11-12 部署重启后实测:23 条 history 归零,purge 对历史 pid 一律拒绝)。所以「重启前的残留产物」只能用cleanup.commands按文件名清;部署扩展需要重启时,先确认队列空闲并知会同机用户。 {"clear": true}是地雷:会清掉同一个 ComfyUI 上所有人的任务,只按prompt_id精确删。- 别清错对象:本地已导出的成片、
40_prompts/、30_shots.json、50_manifest.json是流水线资产,一律保留;导出闸门会拦下本地成片缺失/过小的条目,防止没导出就把证据删了。 outputs里可能回带type=input的源素材(LoadVideo / 预览节点),它和output不同根,分流处理,别混进{files}一起rm。/free别每镜调:它只设队列 flag,下一个队列循环才卸载;4Gi 环境重新加载模型要几分钟。整批归档后统一--free一次。