Files
ai-manju/references/pitfalls.md
T
rong a8e10b7b17 fix: 字幕按实测发声段对齐 + 静音镜/包装踩坑 (v1.2.1)
- 纠正 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 清单同步
2026-11-19 17:14:14 +08:00

17 KiB
Raw Blame History

踩坑速查(跨项目通用)

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. 细光分屏镜——细光变光柱、节点增生、双手越界。 截前 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 一次。