# 内网模型服务与 API 用法 > **本技能是编排层**:出图、出视频都调内网 HTTP 端点。本文是端点、节点图与调用约定的**唯一真相源**。 > 2026-11-11 逐条实机核对;**2026-11-13 重核并合并为单实例**(`/system_stats`、`/object_info`、三种模态实跑验证)。 > **2026-11-17 新增 `192.168.1.23:30121`(DCU K100 64 GB)**:H3 音画同出 I2V 实测跑通(576×1024 / 175 帧 / 93 min), > 台词镜头改走这条,详见 [native-av.md](native-av.md)。旧 DCU `192.168.1.24` 仍然不可达,两台不是一台机。 > 部署拓扑、4 GiB cgroup 限制、补丁集与 pod 重建后的恢复步骤,见部署侧文档 > `~/WorkBuddy/2026-11-08-19-43-52/deploy/k8s-nvidia/deploy-as-built.md`。 > 所有地址都是**内网明文 HTTP**;本机代理会把响应改写成 `text/html`,调用**必须绕过代理**(见 §3.2)。 --- ## 0. 服务地图:1 个多模态实例 + 2 个回退端点 + 2 个辅助 > ⚠️ **2026-11-13 重大变更:三个 ComfyUI 已合并为一个实例。** > **`192.168.1.30:30113`(ComfyUI 0.45.0)一个端点同时提供 H3-Image 文生图、H3 视频(带音轨)、Wan2.2 I2V。** > 能力差异只取决于**权重 + 节点图**,不取决于容器:0.45 核心自带 `MiniMaxH3` / `MiniMaxH3Image` / > `Wan21` / `Wan22` 与 `nodes_wan.py` / `nodes_minimax_h3.py`,权重挂在共享 NFS 上按需软链。 > 部署拓扑、4 GiB 内存硬限、补丁集与**pod 重建后的恢复步骤**见部署侧文档 > `~/WorkBuddy/2026-11-08-19-43-52/deploy/k8s-nvidia/deploy-as-built.md`。 | 能力 | 模型 | 端点 | ComfyUI | 音轨 | 状态 | |---|---|---|---|---|---| | **文生图** | MiniMax H3-Image | **`http://192.168.1.30:30113`**(int8_convrot)/`http://192.168.1.23:30121`(w4a8) | 0.45.0 | — | ✅ 两台都在线 | | **台词镜头(首选)** | MiniMax H3 `fl2va` **音画同出 I2V** | **`http://192.168.1.23:30121`(K100 64 GB)** | 0.45.0 | ✅ aac | ✅ **对白镜主用**,20 步 / 576×1024 / 90 min 一镜 → [native-av.md](native-av.md) | | **视频①(静音)** | MiniMax H3(w6a8,原生同步音频) | `http://192.168.1.30:30113` | 0.45.0 | ✅ aac | ✅ **仅 T2V**(20 步 / 无 LoRA);该卡 I2V 必 OOM | | **视频②(静音动作)** | Wan2.2 I2V A14B(双专家 + 4-step LoRA) | 同一个 `30113`;`30121` 也有同一套权重 | 0.45.0 | ❌ | ✅ 主用(4 步 / 两段式) | | 回退·视频 | H3 / WAN | `http://192.168.1.30:30111` / `:30112` | **0.45.0** | H3 ✅ | **已并入 30113**(Service selector 改指),端口照旧可用、调用方零改动 | | 旧 DCU | MiniMax H3-Image(w4a8) | `http://192.168.1.24:30120` | 0.45.0 | — | ⚠️ **整机不可达**(不是 30121,别混) | | 文(辅助) | `ipass-all` LLM 代理(OpenAI 兼容) | `http://192.168.1.30:30084` | — | — | 运行中,需 API Key | | 文(辅助) | `embed-bge` 向量化 / rerank | `http://192.168.1.24:8801` | — | — | ⚠️ 已下线(随 DCU 一起挂) | > 🔴 **H3 的 I2V 是「看卡说话」,不是「看端口说话」:** > - `30113`(2080Ti **22 GB**):给 `MiniMaxH3ImageToVideo` 塞 `first_frame` 会走 `vae.encode()` 并把 video VAE > 持有到采样期,TE 14.96 G + VAE 4.97 G 焊死 → 必 `CUDA out of memory`(2026-11-14 干净态重放复现)。 > **该卡只有 T2V 可用**;要首帧锁图就用 A14B(§1)。 > - `30121`(DCU **K100 64 GB**,2026-11-17 起):**I2V 完全可用**,带原生对白音轨,实测 576×1024 / 175 帧 / 93 分钟。 > 台词镜头走这条 → 详见 **[native-av.md](native-av.md)**。 > - 两边节点图差异只有 VAE/权重与 ROCm 补丁,采样链路都是 `SamplerCustomAdvanced`。 **一卡一实例**:30113 独占 1 张 2080 Ti(22 GB,`nvidia.com/gpu: 1`)并受 4 GiB cgroup 内存硬限, **所有请求只能串行**,并发必 OOM(exit 137)。`30111` / `30112` 现在是同一实例的别名,**同样只能串行**。 **版本差异仍然存在,不要照搬**:DCU 是 ROCm、K8s 是 CUDA。K8s 侧 0.38 核心已于 2026-11-13 下线 (三个端口现已统一为 0.45),但 **DCU(ROCm)与 K8s(CUDA)之间**的采样节点、`SaveVideo.format`、内存补丁、 量化档位仍不通用。跨端点复用工作流前先查 `/system_stats` 的版本。 > **2026-11-13 起:三个端口全部指向同一个 0.45.0 实例。** > 旧的 `comfyui-wan-h3` / `comfyui-wan-a14b` deployment 已 scale 到 0, > 两个旧 Service 的 selector 改指 `app=comfyui-wan-h3image`, > NodePort 30111 / 30112 **保持不变** —— 调用方零改动,但自动获得 0.45 的全部能力。 > 实测三个端口的 `/system_stats` 均为 `0.45.0`、1060 个节点。 > **节点层面 30113 是旧 30112 的严格超集**(实机核对): > 旧 30112 共 964 个节点、30113 共 1060 个,**30112 没有任何独有节点**; > 30113 多出的 96 个全是 0.45 新增(Breeze / HeyGen / Kling / Flux3 / Bria 等)。 > 6 个共有节点的签名差异**全部是「30113 多一个可选参数」**(如 `CreateVideo.chroma_subsampling`), > 向后兼容。**所以旧工作流可原样使用**,已用生产工作流实测通过。 --- ## 1. 两个视频模型怎么选 | 维度 | H3(视频①) | Wan2.2 A14B(视频②) | |---|---|---| | 定位 | 有声音、画质优先、环境音/对白镜头 | 静音动作镜头、批量抽卡、快速迭代 | | 端点 | **30113**(0.45,主用);30111/30112 已并入同一实例 | **30113**(0.45,主用);30112 已并入同一实例 | | 输入 | **2080Ti 上仅 T2V 验证通过**;`first_frame` 图生视频会 OOM(见 §0 警告 / §4.3) | **图生视频为主**(I2V 模型,给首帧最佳),也能纯文生 | | 音轨 | **原生同步音频**,提示词里写 `overall_soundscape:` / `non_diegetic_music:` | 无,需后期用 `tts.py` + `render.py` 混音 | | 安全规格 | 30113 实测 **320×192 / 22 帧 / 20 步**;0.38 上 960×544 / 33 帧通过;DCU 1344×768 / 24 帧 | **832×480 / 81 帧(4n+1)/ 4 步 / 16 fps** | | 单段时长 | 22 帧 @24fps ≈ 0.9 s;0.38 的 33 帧 ≈ 1.6 s | 81 帧 @16fps ≈ 5 s | | 实测耗时 | 30113 上 20 步含冷加载约 7–10 min(其中加载占 4–7 min) | 4 步,明显快;同样含冷加载 | | 采样接口 | **0.45(CUDA):`SamplerCustomAdvanced`**(无 SigmaShift);0.45(ROCm/DCU):`KSampler`+`MiniMaxH3SigmaShift`;0.38:`SamplerCustomAdvanced` | `WanImageToVideo` → `ModelSamplingSD3(shift=5)` → `KSamplerAdvanced` ×2(双专家接力) | | 禁用项 | **turbo LoRA**(合进 w6a8 量化权重 → 画面全 NaN)、`int8_convrot`(DCU 黑屏) | 超分辨率/帧数 → CUDA OOM;`--force-fp16` → 崩溃 | **决策树** ``` 镜头需要原生环境音/同期声? → H3 T2V(30113,20 步、无 LoRA) 要用已有首帧/锚图驱动生成视频? → A14B I2V(30113);**不要给 H3 塞 first_frame**,2080Ti 上必 OOM 只要画面、要快速抽卡/批量出静音片段? → A14B(30113,同一实例,4 步) 要出角色锚图或分镜首帧? → H3-Image(30113,见 §2) ``` > 三者现在**同一个端点、同一个容器**,切换模型只是换节点图,不换地址;但共享一张 22 GB 卡与 4 GiB 内存, > **必须串行**。H3 的音频是模型生成的**整体声场**,不是指定台词的配音。角色对白仍走阶段 3 的 `tts.py`; > 两者在 `render.py` 里注意别叠成双份。 --- ## 2. 文生图:MiniMax H3-Image(出锚图与首帧) > **2026-11-13 实测更新**:原默认端点 DCU `192.168.1.24:30120` **整机已不可达**(30120 / 8801 两个端口 TCP 均 CLOSED)。 > 当前可用的是 K8s `192.168.1.30:30113`,而且它**同时承担 H3 视频与 WAN I2V**(见 §0)。 > 两端**节点图完全一致**,只有权重名不同 —— 脚本已改成自动探测权重,换端点不用改代码。 ### 2.0 两个端点怎么选 | 端点 | ComfyUI | DiT 权重 | 状态 | 备注 | |---|---|---|---|---| | **`192.168.1.30:30113`** | 0.45.0 | `minimax_h3_image_pruned_int8_convrot.safetensors` | ✅ 在线(K8s 出图默认) | 4 GiB cgroup 硬限 + MEM4G 补丁集;单次 1024²≈178s、2048²≈208s;**同一实例兼跑两种视频,请求要串行** | | **`192.168.1.23:30121`** | 0.45.0 | `minimax_h3_image_pruned_w4a8.safetensors` | ✅ 在线(**K100 64 GB,对白镜主力**) | 64 GB 全驻、无内存墙;同一实例有 H3 视频 + WAN + 三套 VAE,**出图与 90 分钟的视频任务抢队列时排到最后** | | `192.168.1.24:30120` | 0.45.0 | `minimax_h3_image_pruned_w4a8.safetensors` | ❌ 2026-11-13 实测整机不可达 | 同一台还托管过 LLM 代理(30084)与 embed-bge(8801)。**注意与 30121 不是一台机** | **节点图两套完全一样**,照搬不会错;只有 `UNETLoader.unet_name` 不同: | 端点 | `unet_name` | 为什么不能换 | |---|---|---| | DCU 30120 | `..._w4a8.safetensors` | **不要用 int8_convrot** —— gfx928 上 convrot 的 `rint` 有 bug → NaN → 纯黑图 | | K8s 30113 | `..._int8_convrot.safetensors` | **没有 w4a8** —— w4a8 的 CUDA 加速路径要求 sm_80,2080Ti 是 sm_75 跑不了 | > ⚠️ 这两条规则方向相反,**千万别照搬**。 > 另一个坑:2080Ti(sm_75)无原生 bf16,ComfyUI 会退回 fp32 把未量化层撑大。 > 30113 靠 `should_use_bf16()` 补丁放开了软件模拟 bf16 —— **绝不能改成 fp16**: > fp16 动态范围仅 ±65504,H3-Image 的 adaln/timestep 缩放会溢出成 inf → NaN → 出图全黑。 ### 2.1 K8s 30113 的运行约束(与 DCU 完全不同) 30113 跑在**租户 4Gi cgroup 硬限、无 swap**里,是当前**唯一的主用端点**(图 + H3 视频 + WAN)。几条必须知道的: | 项 | 值 | |---|---| | 启动参数 | `--cache-none --disable-pinned-memory --disable-cuda-malloc --disable-smart-memory`(**禁 `--fp16-unet`**)
(2026-11-19 实测 argv 复核:已无 `--reserve-vram`,改为 `--disable-smart-memory`) | | 内存墙 | TE(14.96GB) 与 DiT(19.5GB) 共存于 22GB 卡,必须「换入换出」;靠 MEM4G 补丁集(14 处,7 族)解决 | | 显存账 | TE 14960MB → 卸载后 8MB(延迟 GC 打破引用环 + VRAM 换回 mmap 视图) | | 耗时 | 1024²≈178s;视频 20 步约 7–10 min(**其中 4–7 min 是冷加载**) | | 串行 | **一个 pod 一张卡**;图、H3 视频、WAN 全在这一个实例里,**三者互为并发冲突** | | 恢复 | `/local` 是 emptyDir,**pod 重建后必须跑 `/basedir/apply-multimodal.sh`**,否则只剩出图能力(见部署侧 `deploy-as-built.md` §6) | | 清理 | **未装** `manju-cleanup` 扩展 → 走 `cleanup.commands` 的 `kubectl exec` 降级模板(已默认配好) | 出图端点 `output` 根是 `/comfyui/output`(软链到 PVC `/basedir/output`),与 30111/30112 一致, `cleanup.commands` 已默认带 `http://192.168.1.30:30113` 这条模板。 ### 2.2 参数与提示词 | 项 | 值 | |---|---| | DiT | 见 §2.0 端点表(权重名随端点变,脚本自动探测) | | CLIP | `qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`(与视频共用),`type="minimax"` | | VAE | `minimax_h3_image_vae_fp16.safetensors`(1.1G,optional 入参) | | 核心节点 | `MiniMaxH3ImageConditioning`(输出 `CONDITIONING` + `LATENT`)→ `KSampler` → `VAEDecode` → `SaveImage` | | 采样 | **6 步 / cfg 1.0 / euler + simple**(蒸馏模型,加步数无益) | | 分辨率 | 宽高 **32 对齐**,2048² 起;**16 MP(4096² / 5472×3072)效果最好**,低于 4 MP 发软 | | 速度 | DCU 上 16 MP 约 40 s/step;30113 上 1024²/2048² 各 6 步 = 170/208 s | | 提示词 | **一段长英文描述**(构图+材质+光线+镜头),不是关键词堆砌;官方用 qwen3.5-9b 扩写,本机没装,手写或走 LLM 代理 | | 参考图编辑 | optional `images`(`image_1`…,提示词用 `` 指代)——**本环境未验证,别当已支持** | ### 2.3 出图后必须自检(2026-11-13 加入) H3-Image 在**量化档位不对**时会**出图成功但内容是纯黑/纯色**: ComfyUI 侧 `status.completed=True`、`outputs` 有文件、**不报任何错**。 不自检就会把废图当成品记进台账,等审片才发现。 `tools/submit_t2i.py` 现在每次出图后自动做 PNG 自检(零依赖,解 IHDR + IDAT 采样像素): ``` [SANITY] work/EP01/images/S01.png -> ok(2048x2048, 168733 colors, mean=72.3, std=57.8) ``` 判定规则:颜色数 ≤ 8 判「单色」;亮度标准差 < 3.0 判「纯色」。 **自检不通过时脚本退出码为 1,且跳过自动清理** —— 保留服务端 history 与产物当排查证据。 ### 2.4 脚本用法 ```bash # 权重不用填:脚本读端点 /object_info/UNETLoader 自动挑(w4a8 / int8_convrot) python3 tools/submit_t2i.py --ep EP01 --shot S01 --prompt-file 40_prompts/S01.t2i.txt python3 tools/submit_t2i.py --prompt "A lone figure on a misty pier, ..." --out assets/characters/ling.png python3 tools/submit_t2i.py --ep EP01 --shot S03 --width 4096 --height 4096 --force ``` 落到 `work/EPxx/images/Sxx.png`——正是 `submit_i2v.py` 期望的首帧路径,阶段 0 / 阶段 4 由此闭环。 --- ## 3. ComfyUI 通用 API(30111 / 30112 / 30113 三个端口指向同一实例) ### 3.1 端点表(新版标准路径带 `/api` 前缀) 官方 master 的 `add_routes()` 会把每个 `@routes.*` 自动复制一份 `/api` + 原路径,源码注释明确 "Currently both the old endpoints without prefix and new endpoints with prefix are supported"。 **优先用 `/api` 前缀**(官方文档与 ComfyUI Cloud 都用这个),无前缀是等价别名。 先 `GET /api/system_stats` 探测,不可用自动回退无前缀。现网 0.38 / 0.45 三条线都实测 `/api/history`、`/api/queue`、`/api/free` 可用。 | 方法 | 路径 | 用途 / 返回 | |---|---|---| | GET | `/api/system_stats` | 存活、ComfyUI 版本、`system.argv` 启动参数、设备与显存。**换模型/换版本先打这个** | | GET | `/api/object_info/{class_type}` | 该节点的 required / optional 入参、输出类型。节点字段对不上就查这里 | | POST | `/api/upload/image` | multipart,字段 `image`(文件)+ `overwrite=true` → `{"name": "..."}`,填进 `LoadImage` | | POST | `/api/prompt` | body `{"prompt": {节点图}, "client_id": "..."}` → `{"prompt_id", "node_errors"}` | | GET | `/api/history/{prompt_id}` | 轮询:`status.completed`、`status.messages`(含 `execution_error`)、`outputs` | | GET | `/api/history` | 全量历史(网络超时后确认任务是否已提交) | | GET | `/api/view?filename=&subfolder=&type=output` | 下载图片/视频二进制 | | GET | `/api/queue` | `queue_running` / `queue_pending`,提交前确认空闲 | | POST | `/api/interrupt` | 中断当前执行,可带 `prompt_id` | | POST | `/api/history` | `{"delete": [pid, ...]}` **批量**删生成记录。**`{"clear": true}` 会清掉全部任务,禁用** | | POST | `/api/queue` | `{"delete": [pid, ...]}` 删队列残留 | | POST | `/api/free` | `{"unload_models": true, "free_memory": true}` 设队列 flag,下一个队列循环才真正卸载模型/释放显存 | | POST | `/api/jobs/{id}/cancel`、`/api/jobs/cancel` | 新版标准:运行中的任务中断、待执行的出队,返回 `{"cancelled": bool}`;已完成/未知 ID 是幂等空操作 | | DELETE | `/userdata/{file}` | **只删 `ComfyUI/user/` 下的用户数据**(workflows / settings),与 `output/` 无关 | | DELETE | `/api/assets/{id}` | 需 `--enable-assets`;删的是 asset 数据库引用,不是 output 文件。现网实测 503 `SERVICE_DISABLED` | 三个删除类 POST 一律返回 **200 空 body**(别用 `json.loads()` 去解),而且是**幂等**的: 实机验证 `POST /api/history {"delete":["不存在的 uuid"]}` 照样返回 200 空 body。所以 - **不能把 200 当「删除成功」**,必须删后再 `GET /api/history/` 复核「删前有 → 删后无」, 并查 `/api/queue` 确认该 pid 不在 running / pending; - `GET /history/{pid}` 的 `{}` 有**三义**(排队中 / 执行中 / 不存在,外加 `MAXIMUM_HISTORY_SIZE=10000` 淘汰旧记录),单看 `{}` 什么也断定不了,判据必须是删前删后的对比; - `history` 是**内存态**(Pod 重启即失),`output/` 文件在 PVC / 宿主盘上是持久的 —— **「记录没了、文件还在」是最常见的残留形态**。 `/prompt` 返回的 `node_errors` 必须判空;`prompt_id` 只代表**已接受**,不代表开始渲染,更不代表完成。 ### 3.2 八个必踩的坑 1. **`/prompt` 必须包一层 `{"prompt": ...}`**。仓库里的 `*.json` 工作流多是**裸节点图**,直接 `curl -d @xx.json` 会 400。 2. **绕过本机代理**:Python 用 `urllib.request.build_opener(urllib.request.ProxyHandler({}))`;curl 加 `--noproxy '*'`。否则明文 HTTP 被改写成 `text/html`。 3. **轮询判据**:`status.completed` + `outputs` 同时满足才算完成;先扫 `status.messages` 里的 `execution_error`。 4. **网络超时 ≠ 未提交**:重试前先查 `/history/{pid}`,否则会重复消耗算力。 5. **惰性加载**:空闲不占显存,首次提交要 1–3 分钟(H3-K8s 冷启动更久,约 3–4 分钟),别误判成挂了。 6. **串行提交**:30113 一个实例同时承担图与两种视频,受 4Gi cgroup 硬限且无 swap,**并发必 OOM(exit 137)**。 7. **200 空 body ≠ 删除成功**:见 3.1。删完必须复核,报告里要区分「已确认(删前有→删后无)」与「幂等 200,删前就无此记录」。 8. **官方删不了 `output/` 文件**:`DELETE /userdata/{file}` 只管 `user/` 目录,`/api/assets` 默认关闭且管的是数据库引用。社区只有两条路:装自定义节点补标准 `DELETE` 路由,或在服务端文件系统上精确删(见 3.4)。 ### 3.3 最小提交骨架(可直接复制) ```python import json, time, urllib.parse, urllib.request COMFY = "http://192.168.1.30:30113" # 图 / H3 视频 / WAN 全在这一个实例;30111/30112 是它的别名 opener = urllib.request.build_opener(urllib.request.ProxyHandler({})) # 必须 def get(path, timeout=30): return json.loads(opener.open(COMFY + path, timeout=timeout).read()) def post(path, payload, timeout=60): req = urllib.request.Request(COMFY + path, data=json.dumps(payload).encode(), headers={"Content-Type": "application/json"}) return json.loads(opener.open(req, timeout=timeout).read()) assert get("/system_stats")["devices"] # 健康检查 graph = {...} # 节点图,见 §4 r = post("/prompt", {"prompt": graph, "client_id": "manju-t2i-demo"}) if r.get("node_errors"): raise RuntimeError(r["node_errors"]) pid = r["prompt_id"] while True: h = get("/history/" + urllib.parse.quote(pid)) if pid in h: item = h[pid] if any(m[0] == "execution_error" for m in item["status"].get("messages", [])): raise RuntimeError(item["status"]["messages"]) if item["status"].get("completed") and item.get("outputs"): f = next(x for out in item["outputs"].values() for k in ("images", "videos", "gifs") for x in out.get(k, [])) q = urllib.parse.urlencode({"filename": f["filename"], "subfolder": f.get("subfolder", ""), "type": f.get("type", "output")}) open("out.bin", "wb").write(opener.open(COMFY + "/view?" + q, timeout=300).read()) break time.sleep(5) ``` 产物落在服务端 `/home/ComfyUI/output/`(DCU,宿主机同路径)或 `/comfyui/output/`(K8s),用 `/view` 拉回,不要去猜路径。 ### 3.4 生成后清理:清掉 ComfyUI 记录与产物(必做) **为什么必须做**:`/view` 下载的只是副本。服务端 `output/` 里的 mp4 / png、`input/` 里上传的首帧、以及 `history` 里的整段节点图与提示词**都还在**。DCU 的 `/home/ComfyUI/output` 与 K8s 的 PVC 是持久存储,不会随任务结束消失;而 `history` 只是内存态(Pod 重启即没),所以**记录没了文件还在**是最常见的残留。 #### 只删「自己发起的任务」:归属模型(本版本核心) 现网 `history` 是**全局共享**的:`30112` 上 151 条里绝大多数是别人的任务,`30120` 上 23 条的 `client_id` 也各不相同(该机已下线,数据为下线前实测)。ComfyUI 把 `client_id` 持久化在 history 项 `prompt[3]["client_id"]`(0.38 / 0.45 实机核对都成立),这就是归属凭证。 | 层 | 凭证 | 作用 | |---|---|---| | 1 | 本地台账 `promptId` | 只有本技能提交的任务才会写进 `a14b_runs.json` / `t2i_runs.json`,天然是「自己发起」的白名单 | | 2 | 台账 `clientId` | 两个提交脚本改用 `manju-i2v-` / `manju-t2i-` 提交并把 `clientId` 写进台账;清理时 `GET /api/history/` 读回 `client_id` 精确比对 | | 3 | 服务端二次校验 | 扩展在服务端再判一次 `client_id ∈ clientIds ∪ ownerPrefixes`;`requireOwner=true` 且无凭证时 **fail-closed,一律拒绝** | 未通过归属的 pid 会从删除列表里剔除:既不调 `POST /api/history`,也不调 `POST /api/queue`,更不删文件。老台账没记 `clientId` 的历史任务,把那些 `client_id` 加进 `cleanup.clientIds`(或调整 `ownerPrefixes`)才会被清。**禁用 `{"clear": true}`**。 #### 官方没有删产物的接口 → 用扩展补上 官方 `server.py` 只有记录删除与显存释放;`DELETE /userdata/{file}` 只管 `ComfyUI/user/`,`/api/assets` 删的是数据库引用且现网 503。**本技能自带扩展 `assets/comfyui-manju-cleanup/`**:整目录拷到 `ComfyUI/custom_nodes/` 并重启进程即可。它注册到 `PromptServer.instance.routes`,官方 `add_routes()` 会自动镜像出 `/api` 前缀(master 源码逐行核对),所以带不带前缀都能用。 | 路由 | 作用 | |---|---| | `GET /manju/cleanup/ping` | 探活、返回 output/input/temp 根目录、是否要求 token | | `POST /manju/cleanup/purge` | `{"pids":[...], "client_ids":[...], "owner_prefixes":[...], "dry_run":true, "purge_input":false, "require_owner":true}` | 扩展**只接受 pid**,自己从服务端 `history` 反查该 pid 的 outputs/inputs,绝不接受任意文件路径;再校验 `client_id` 归属、`realpath` 必须落在对应根目录(拒绝绝对路径 / `..` / 符号链接 / 目录),并做跨任务引用计数(被别的 pid 引用的文件判 `shared` 跳过)。`dry_run` 默认 `true`,可选环境变量 `MANJU_CLEANUP_TOKEN` 开鉴权(对应 `cleanup.token`)。它**不删 history/queue 记录** —— 那部分继续走官方标准接口。 #### 社区怎么弄的(2026-11-12 核实) | 来源 | 结论 | |---|---| | 官方 `server.py`(master) | `post_history` / `post_queue` 支持 `clear` 与 `delete` 列表,逐项调 `delete_history_item` / `delete_queue_item`,一律 `web.Response(status=200)`;`post_free` 只 `set_flag("unload_models" / "free_memory")`;`/api` 前缀路由是自动复制的,**没有任何删磁盘文件的路由** | | 官方文档 `docs.comfy.org/.../comms_routes` | 路由表列了 `POST /history`(清除/删除历史项)、`POST /queue`、`POST /free`、`DELETE /userdata/{file}`(删用户数据文件) | | ComfyUI Cloud API 文档 | `POST /api/history {"delete":[...], "clear":true}`、`DELETE /api/assets/{id}`(云端,删数据库记录 + 存储内容);说明 `/api` 前缀是官方方向 | | Runflow《Every ComfyUI API Endpoint》 | "History accumulates without bound. Periodically clear it with POST /history in long-lived deployments" | | ArcReel 一手调研 | `GET /history/{pid}` 的 `{}` 三义、`MAXIMUM_HISTORY_SIZE = 10000` 淘汰旧记录,判完成不能只看 `{}` | | 社区自定义节点 | `comfyui_extra_api` 提供 `DELETE /comfyapi/v1/output-images/{filename}`;`ComfyUI-api-tools` 提供 `DELETE /api-tools/v1/images/output/{filename}`。都是**补上官方缺失的删文件路由** | | **本技能扩展** | `manju-cleanup` 不走「按文件名删」的路子,而是按 `pid + client_id` 从服务端 history 反查产物,天然带归属与防误删;见上节 | | 社区通用做法 | 没装节点时,服务端脚本 / cron 定期清 `output/`;缺点是会误删别人**还没导出**的产物 | **现网实机核实**(三个端点 `0.38.0` / `0.45.0`): | 能做的(标准接口) | 不能做的 | |---|---| | `GET /api/system_stats` 探前缀 | ❌ 没有删除 `output/` 文件的 HTTP 路由 | | `GET /api/history/` 抽产物清单 | ❌ `DELETE /history/` 实测 **405**(官方只支持 POST 带 body) | | `POST /api/history {"delete":[...]}` 批量删记录 | ❌ `DELETE /userdata/{file}` 只管 `ComfyUI/user/`,不管 `output/` | | `POST /api/queue {"delete":[...]}` 删队列残留 | ❌ `/api/assets` 实测 **503 SERVICE_DISABLED**,要 `--enable-assets` 且删的是数据库引用 | | `POST /api/free {...}` 释放模型显存 | ❌ `{"clear": true}` 会误删别人的任务,禁用 | | 删后 `GET /api/history/` + `/api/queue` 复核 | ❌ 200 空 body **不等于删除成功**,删不存在的 pid 也是 200 | | `GET /api/history/` 读 `prompt[3]["client_id"]` 判归属 | ❌ 官方删除接口**不带任何归属校验**:谁都能 `{"delete":[别人的 pid]}`,所以必须客户端先拦 | | 扩展 `GET /api/manju/cleanup/ping` / `POST .../purge` | ❌ 扩展装了才可用;未装时脚本自动降级 | **顺序铁律(装了扩展时,与旧版不同)**: `GET /api/history/` 抽产物清单 + `client_id` → **归属闸门**(不归属的直接剔除,绝不进删除列表) → `POST /manju/cleanup/purge {"dry_run":true}` 服务端预览 → `POST /manju/cleanup/purge {"dry_run":false}` 删服务端文件 → 批量 `POST /api/history` + `POST /api/queue` 的 `{"delete": [...]}` → **复核** `GET /api/history/` 变成 `{}` 且 `/api/queue` 里不再出现该 pid → 整批结束 `POST /api/free`。 **为什么换成「先删文件再删记录」**:purge 依赖 history 反查文件名,记录一删就永远查不到产物了。旧版的「先抽清单 → 删记录 → 复核 → 删文件」只在**没装扩展**的降级路线里保留(那时清单由客户端自己抽)。少了复核就是把幂等 200 当成真删了。 **工具**:`tools/cleanup_comfyui.py`,零依赖、绕代理、默认 dry-run、自动探测 `/api` 前缀与扩展并回退。报告里每条任务都打印 `✅ 自己的任务 / ⛔ 拒绝(非本人任务)`、`client_id` 与归属理由。 **扫描范围**:脚本**递归扫工作空间下所有 `t2i_runs.json` / `a14b_runs.json`**,而不是只认固定路径 —— 因为 `submit_t2i.py` 把台账写在 `os.path.dirname(out)`,台账位置随输出路径变: | 出图方式 | 台账落点 | |---|---| | `--ep EP01 --shot S01` | `work/EP01/images/t2i_runs.json` | | 裸 `--out assets/characters/ling.png` | `assets/characters/t2i_runs.json`(**跟图片同目录**) | 漏扫后者的后果是**角色锚图产物永远留在服务端**(2026-11-13 实测漏洞,已修 + 已加回归断言)。因此**不带 `--ep` 跑一次**可以把锚图与集外任务一起清掉。 每个任务的**实际端点取自台账里的 `endpoint` 字段**(而非配置里的全局值),锚图与首帧不在同一端点时也不会清错地方。 ```bash python3 tools/cleanup_comfyui.py --ep EP01 # 预演:打印归属判定、将删的记录与产物清单 python3 tools/cleanup_comfyui.py --ep EP01 --apply # 真清(含删后复核) python3 tools/cleanup_comfyui.py --ep EP01 --apply --free # 整批做完统一释放模型 python3 tools/cleanup_comfyui.py # 不带 --ep:连锚图/集外任务一起清 python3 tools/cleanup_comfyui.py --ep EP01 --shot S03 --apply --purge-input python3 tools/cleanup_comfyui.py --prompt-id --endpoint http://192.168.1.30:30112 \ --client-id manju-i2v-ab12cd34 --apply # 显式任务必须给归属凭证 ``` 两个提交脚本支持 `--cleanup`(导出后自动清)、`--no-cleanup`(本次跳过);`config.cleanup.auto = true` 可设为默认自动。 钩子只清该镜的记录与产物,**不会每镜 `/free`** —— 4Gi 环境下重新加载模型要几分钟,整批归档后统一释放一次才对。 **文件怎么删:扩展优先,两条降级路线兜底** 1. **扩展(推荐)**:装了 `manju-cleanup` 的端点,脚本自动探测 `/api/manju/cleanup/ping` 并走 `purge`;`cleanup.nodeApi` 可显式指定前缀。服务端逐文件返回 `deleted / dry-run / missing / shared / refused / skipped-input / error`,脚本原样打印,不会含糊地说「已清理」。 2. **社区 DELETE 插件**:`cleanup.deleteApi` = `comfyui_extra_api` / `api-tools`,只管不带子目录的图片。 3. **文件系统模板**:`cleanup.commands` 按端点配 shell 模板,`{files}` 逐个 `shlex.quote`。没配就只打印精确清单、**绝不假称已删**。三条路线都受归属闸门约束。 **部署扩展**(DCU 30120 已实装并验证;K8s 当前选择不重启,下面的 patch 命令留作以后要改用 HTTP 接口时再执行,**目前未执行**): ```bash # ── DCU 30120(已实装):宿主 /home/ComfyUI 是 bind mount,重启容器即持久生效 # client/push.sh 与 client/remote.sh 是项目里的 xop+sshpass 辅助脚本(凭据不落明文); # 也可以换成自己的 scp / ssh。__P__ 由 remote.sh 在本地展开为 sudo 密码。 bash client/push.sh assets/comfyui-manju-cleanup/__init__.py /tmp/manju_cleanup_init.py bash client/remote.sh 'echo __P__ | sudo -S -p "" mkdir -p /home/ComfyUI/custom_nodes/comfyui-manju-cleanup && echo __P__ | sudo -S -p "" cp /tmp/manju_cleanup_init.py /home/ComfyUI/custom_nodes/comfyui-manju-cleanup/__init__.py' bash client/remote.sh 'echo __P__ | sudo -S -p "" docker restart comfyui-h3' curl -s --noproxy '*' http://192.168.1.24:30120/api/manju/cleanup/ping # 实测 200 # ── K8s 30113(ComfyUI 根 /comfyui-0.45);30111 / 30112 是同一实例的别名,根目录相同 # custom_nodes 在镜像内,用 ConfigMap 单文件挂载 export KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong # 本机默认 context 是 orbstack,不是这个集群 kubectl -n wuguirong create configmap manju-cleanup-node \ --from-file=__init__.py=assets/comfyui-manju-cleanup/__init__.py # 已创建,无副作用 for d in comfyui-wan-h3 comfyui-wan-a14b; do kubectl -n wuguirong patch deploy "$d" --type=json -p='[ {"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-","value":{"name":"manju-cleanup","mountPath":"/comfyui/custom_nodes/comfyui-manju-cleanup/__init__.py","subPath":"__init__.py","readOnly":true}}, {"op":"add","path":"/spec/template/spec/volumes/-","value":{"name":"manju-cleanup","configMap":{"name":"manju-cleanup-node"}}} ]' done # 30113 的 ComfyUI 根是 /comfyui-0.45,挂载路径要跟着变(此条未在现网验证) kubectl -n wuguirong patch deploy comfyui-wan-h3image --type=json -p='[ {"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-","value":{"name":"manju-cleanup","mountPath":"/comfyui-0.45/custom_nodes/comfyui-manju-cleanup/__init__.py","subPath":"__init__.py","readOnly":true}}, {"op":"add","path":"/spec/template/spec/volumes/-","value":{"name":"manju-cleanup","configMap":{"name":"manju-cleanup-node"}}} ]' # ⚠ patch 会触发 rollout(Pod 重建):history 是内存态,重启会清掉**所有人**的记录。 # 而且 30113 的 rollout 会重建 /local(emptyDir)→ 权重软链全部丢失,必须重跑 # /basedir/apply-multimodal.sh 才能恢复视频能力。只在队列空闲且明确确认后执行; # 当前未执行,K8s 走下面的 kubectl exec 降级模板。 curl -s --noproxy '*' http://192.168.1.30:30111/api/manju/cleanup/ping python3 tools/selftest_cleanup.py # 本地 mock 自检,26 项断言 ``` **现网选择:K8s 不重启,走 `kubectl exec` 降级模板**(归属闸门照常生效、零重启、零副作用)。三条模板已作为默认值写进 `assets/config.template.json` 与 `cleanup_comfyui.py` 的 `DEFAULT_CLEANUP`,`setup` 生成的工作空间直接可用。 > **2026-11-13 更新**:三个端口现在都指向同一个 pod,**三条模板的 pod 选择器必须统一成 `app=comfyui-wan-h3image`**。 > 旧模板用 `app=comfyui-wan-a14b` / `app=comfyui-wan-h3` 找 pod——那两个 deployment 已 scale 到 0, > 会取到**空 pod 名**导致 `kubectl exec` 报错。 ```json "commands": { "http://192.168.1.30:30112": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"", "http://192.168.1.30:30111": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"", "http://192.168.1.30:30113": "KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong exec $(KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong kubectl -n wuguirong get pods -l app=comfyui-wan-h3image -o jsonpath='{.items[0].metadata.name}') -c comfyui -- sh -c \"cd {root} && rm -f -- {files} {temp_files}\"" }, "outputRoot": "/comfyui/output", "inputRoot": "/comfyui/input" ``` 三条模板已在现网用「删不存在文件」实测 rc=0。已有工作空间若把 `cleanup.commands` 覆盖成 `{}`,删掉该键(用脚本默认值)或手工补回模板才生效。要连上传首帧一起删,在模板里另加 `cd {input_root} && rm -f -- {input_files}`。 > **30113 的特殊性**:主用端点**没有装** `manju-cleanup` 扩展(且它是 4 GiB cgroup 硬限的单实例,patch rollout 会重建 `/local`、丢权重软链,重启成本最高),所以**必须**走 `commands` 模板这一条降级路线;`cleanup_comfyui.py` 会自动探测到扩展不存在并降级,不会卡住。 **`cleanup` 段关键字段**(完整默认配置见 `assets/config.template.json`): | 字段 | 默认值 | 说明 | |---|---|---| | `requireOwner` | `true` | 归属校验失败一律拒绝、不调任何删除接口 | | `clientIds` / `ownerPrefixes` | `[]` / `["manju-"]` | 补老台账没记 `clientId` 的任务 / 前缀白名单 | | `nodeApi` | `""` | 自动探测 `/api/manju/cleanup`,探测不到就降级 | | `commands` | 30113 / 30111 / 30112 三条 `kubectl exec` 模板 | 见上,K8s 不重启也能删产物(30113 是主用那条) | | `outputRoot` / `inputRoot` | `/comfyui/output` / `/comfyui/input` | K8s Pod 内路径 | | `deleteApi` / `token` | `""` | 社区 DELETE 插件 / 扩展鉴权,现网都未启用 | | `free` | `false` | 整批结束加 `--free` 才释放模型 | | 占位符 | 含义 | |---|---| | `{files}` / `{temp_files}` | `output` / `temp` 产物,含 `subfolder`,逐个 shell 转义 | | `{input_files}` | 上传的首帧图,仅 `purgeInput=true` 时非空 | | `{root}` / `{input_root}` | 服务端 output / input 根,自带转义,**模板里别再包引号** | DCU 30120 已装扩展、走 HTTP purge,不用配模板;要给它配兜底才用 `ssh` + `docker exec comfyui-h3`,output 根 `/home/ComfyUI/output`。K8s 的 pod 名由模板动态查,不用手填 ``。上传首帧可能被多个镜共用,默认**只列不删**;扩展会做跨任务引用计数,被别的 pid 引用的一律判 `shared` 跳过。 **清理边界(别越界)**:只清服务端、只清自己发起的任务。本地已导出的成片、`40_prompts/` 提示词原文、`30_shots.json`、`50_manifest.json` 一律保留;台账默认只移除 `promptId` 并记 `cleanedAt`,`--purge-ledger` 才删整条。导出闸门会拦下「本地成片缺失或小于 `minBytes`」的条目,防止**没导出就把服务端证据清了**;归属闸门会拦下台账无 `clientId` 且 `client_id` 不在白名单的条目,防止**把别人的任务当自己的清掉**。只按 `prompt_id` 精确删,禁用 `{"clear": true}`。 --- ## 4. 各模型 API 用法 ### 4.1 Wan2.2 A14B(视频②,`submit_i2v.py` 已封装) **优先用现成脚本**,不要手写工作流: ```bash python3 tools/submit_i2v.py projects/EPxx/30_shots.json # 全部 python3 tools/submit_i2v.py projects/EPxx/30_shots.json --only S03 # 单镜重做 ``` 端点取 `config/pipeline.json → videoModel.endpoint`,**默认 `30113`(0.45,主用)**;填 `30112` 也完全等价——三个端口指向同一个实例。 工作流要点(脚本内 `build_workflow()`):双专家各跑 2 步,`UNETLoader` 用 `weight_dtype="default"`(文件原生 fp8), `CLIPLoader` 的 `type="wan"`,`WanImageToVideo` 接 `start_image`,两个分支各挂 **`ModelSamplingSD3 shift=5`**, `SaveVideo` 用 `format="auto"`。 常量:`wan2.2_i2v_{high,low}_noise_14B_fp8_scaled.safetensors` + `wan2.2_i2v_lightx2v_4steps_lora_v1_{high,low}_noise.safetensors` + `umt5_xxl_fp8_e4m3fn_scaled.safetensors` + `wan_2.1_vae.safetensors`。 **2026-11-13 实测**(30113):480×480 / 17 帧 / 4 步 → h264 mp4 87 KB,17 帧全部互异(17k–27k 种颜色)。 **迁移验证**:把 30112 上一条**生产工作流原样**(16 节点,432×768 / 81 帧 / 双专家 / lightx2v LoRA) 提交到 30113,成功出片 —— 证明 30112 → 30113 无需改工作流。 | 0.45 与 0.38 的差异(照搬会退化,但不会报错) | 0.45(30113) | 0.38(30112) | |---|---|---| | `ModelSamplingSD3 shift=5` | **必需**(官方模板如此) | 同样需要;旧版脚本漏挂,画面会发软/漂移 | | `UNETLoader.weight_dtype` | `default`(用文件原生 fp8) | 同为 `default` 可用;写 `fp8_e4m3fn` 会多一次转换 | | `SaveVideo.format` | `auto` / `mp4` / `mkv` / `webm` / `mov` 均合法 | `auto` / `mp4` / `mkv` / `webm` | | 串行 | 与 H3、出图共用同一实例 | 与 30111 共用同一张卡 | 项目仓库里还有个通用客户端(不在本技能内):`deploy/k8s-nvidia/api/submit.py --model 14b --prompt "..." --image frame.png --out clip.mp4`。 ⚠️ 该脚本**默认值仍指向已下线的 5B 档**,必须显式 `--model 14b`。 ### 4.2 MiniMax H3 视频 on DCU(0.45.0,`KSampler` 路线) ```python P = "A serene mountain lake at sunrise, slow cinematic drift. overall_soundscape: soft wind, distant birds. non_diegetic_music: calm ambient piano." g = { "1": {"class_type":"UNETLoader","inputs":{"unet_name":"minimax_h3_fl2va_pruned_w6a8.safetensors","weight_dtype":"default"}}, "2": {"class_type":"CLIPLoader","inputs":{"clip_name":"qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors","type":"minimax"}}, "3": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_video_vae_fp16.safetensors"}}, "4": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_audio_vae_fp32.safetensors"}}, "5": {"class_type":"MiniMaxH3SigmaShift","inputs":{"model":["1",0],"shift_video":12.0,"shift_audio":3.0}}, "6": {"class_type":"MiniMaxH3ImageToVideo","inputs":{"clip":["2",0],"vae":["3",0],"prompt":P, "width":768,"height":448,"length":124}}, # 图生视频加 "first_frame":["LoadImage",0] "7": {"class_type":"KSampler","inputs":{"model":["5",0],"seed":42,"steps":20,"cfg":1.0, "sampler_name":"res_multistep","scheduler":"simple","positive":["6",0], "negative":"","latent_image":["6",1],"denoise":1.0}}, "8": {"class_type":"VAEDecode","inputs":{"samples":["7",0],"vae":["3",0]}}, "9": {"class_type":"VAEDecodeAudio","inputs":{"samples":["7",0],"vae":["4",0]}}, "12": {"class_type":"H3AudioClean","inputs":{"audio":["9",0]}}, # ★ ROCm 必需 "10": {"class_type":"CreateVideo","inputs":{"images":["8",0],"fps":24,"audio":["12",0]}}, "11": {"class_type":"SaveVideo","inputs":{"video":["10",0],"filename_prefix":"H3_out","format":"auto"}}, } ``` - **`H3AudioClean` 是自写节点**(`/home/ComfyUI/custom_nodes/H3AudioClean.py`):ROCm 下音频 VAE 输出混 NaN,AAC 编码器会拒收。**只有 DCU 线要插**,CUDA 线上这个节点不存在,照搬会 `class_type not found`。 - **0.45 的 `SaveVideo.format` 传 `"auto"`**:它是 `COMFY_DYNAMICCOMBO_V3`,传 `"video/h264-mp4"` 会被静默丢弃并报缺参数。 - 必须用本地 `MiniMaxH3*` 节点,云端 `MinimaxHailuo03*` 需登录授权,不可用。 ### 4.3 MiniMax H3 视频 on K8s(0.45 @30113 主用;30111/30112 为同一实例别名) > ⚠️ **此配方只适用于 T2V(纯文生视频)。** 不要照 §4.2 的说明往 `MiniMaxH3ImageToVideo` > 里加 `first_frame` / `last_frame`:2080Ti 22 GB 上 I2V 会 `CUDA out of memory`(2026-11-14 > 干净态重放复现,见 §0 警告)。首帧锁图请用 Wan2.2 I2V A14B 或 DCU 线。 **主用 `30113`(0.45)**。节点图与 DCU 完全不同:**不带 `MiniMaxH3SigmaShift`**,走 `SamplerCustomAdvanced` + `BasicGuider` / `BasicScheduler` / `RandomNoise`。同一张图在 `30111`(0.38)上也能跑。 已实测(30113):20 步 / 320×192 / 22 帧 / 带 aac 音轨 / 22 帧全部互异(37k–42k 种颜色)。 ```python P = ("A neon-lit rainy alley at night, a motorcycle rolls slowly toward camera. " "overall_soundscape: rain on asphalt, distant traffic. non_diegetic_music: low synth drone.") g = { "2": {"class_type":"CLIPLoader","inputs":{"clip_name":"qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors","type":"minimax","device":"default"}}, "3": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_video_vae_fp16.safetensors"}}, "4": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_audio_vae_fp32.safetensors"}}, "5": {"class_type":"UNETLoader","inputs":{"unet_name":"minimax_h3_fl2va_pruned_w6a8.safetensors","weight_dtype":"default"}}, "7": {"class_type":"MiniMaxH3ImageToVideo","inputs":{"clip":["2",0],"vae":["3",0],"prompt":P, "width":320,"height":192,"length":22}}, # ⚠️ 保持 T2V:加 first_frame 会在 2080Ti 上 OOM "8": {"class_type":"BasicGuider","inputs":{"model":["5",0],"conditioning":["7",0]}}, "9": {"class_type":"KSamplerSelect","inputs":{"sampler_name":"res_multistep"}}, "10": {"class_type":"BasicScheduler","inputs":{"model":["5",0],"scheduler":"simple","steps":20,"denoise":1.0}}, "11": {"class_type":"RandomNoise","inputs":{"noise_seed":1}}, "12": {"class_type":"SamplerCustomAdvanced","inputs":{"noise":["11",0],"guider":["8",0], "sampler":["9",0],"sigmas":["10",0],"latent_image":["7",1]}}, "13": {"class_type":"VAEDecode","inputs":{"samples":["12",0],"vae":["3",0]}}, "14": {"class_type":"VAEDecodeAudio","inputs":{"samples":["12",0],"vae":["4",0]}}, "15": {"class_type":"CreateVideo","inputs":{"images":["13",0],"audio":["14",0],"fps":24,"bit_depth":8,"color_space":"sRGB"}}, "16": {"class_type":"SaveVideo","inputs":{"filename_prefix":"video/h3","format":"auto","video":["15",0]}}, "17": {"class_type":"SaveImage","inputs":{"images":["13",0],"filename_prefix":"h3/frame"}}, # 抽帧自检用 } r = post("/prompt", {"prompt": g}) # 别直接 -d @裸 json ``` - **参数固定为 20 步 / `res_multistep` + `simple` / cfg 1.0 / 无 LoRA**。这是唯一稳定出画面的组合。 - **不要加 `first_frame` / `last_frame`**:`nodes_minimax_h3.py:155-179` 在该分支执行 `vae.encode()`, video VAE 被 conditioning 持有到采样期,TE 14.96 G + VAE 4.97 G 无法卸载 → 采样 OOM。 这套 4 GiB + 22 处 MEM4G 补丁的低显存方案**只在 T2V 上验证过**,I2V 是未覆盖的回归。 - `SaveImage` 保留:验证空白帧靠的就是逐帧数颜色;0.38 上只挂 `CreateVideo` 会报 `Prompt has no outputs`。 - 尺寸:0.45 实测 320×192 / 22 帧;0.38 实测 960×544 / 33 帧。更大规格在 0.45 未验证,从小往上加。 | 项 | **0.45(30113 主用;30111/30112 为同一实例别名)** | 0.38(已下线,历史数据) | DCU 0.45(30120,⚠️ 已下线) | |---|---|---|---| | 采样 | `SamplerCustomAdvanced` + `BasicGuider/BasicScheduler/RandomNoise` | 同左 | `KSampler` + `MiniMaxH3SigmaShift` | | SigmaShift | **不要挂** | 不要挂 | 必需(`shift_video=12 / shift_audio=3`) | | 音频清洁 | **不需要**(CUDA 音频正常,节点不存在) | 不需要 | 必须 `H3AudioClean` | | 输出 | `SaveVideo format="auto"`(`mp4`/`mkv`/`webm`/`mov` 也合法) | `format="auto"` 或 `"mp4"`+`codec="h264"` | `format="auto"` | | 启动参数 | **禁 `--fp16-unet`**(会毁掉 H3-Image 的 bf16 路径) | 必须 `--fp16-unet`(否则算 NaN) | `--use-pytorch-cross-attention` | | 内存 | 4 GiB 硬限 + MEM4G 补丁集 | 4 GiB 硬限 + 0.38 版补丁 | 64 G 全驻,无墙 | | turbo LoRA | **禁用**(合进 w6a8 → 全 NaN) | 同样禁用 | — | | 实测规格 | 320×192 / 22 帧 / 20 步 | 960×544 / 33 帧 / 20 步 | 1344×768 / 24 帧 | ### 4.4 H3-Image 文生图(首帧/锚图) ```bash # 技能脚本:读 config/pipeline.json 的 imageModel,输出到 work/EPxx/images/Sxx.png # 权重不用填 —— 脚本读端点 /object_info 自动挑(DCU=w4a8 / K8s-30113=int8_convrot) python3 tools/submit_t2i.py --ep EP01 --shot S01 --prompt-file 40_prompts/S01.t2i.txt python3 tools/submit_t2i.py --prompt "A lone figure on a misty pier, ..." --out assets/characters/ling.png ``` 等价节点图(API 格式)——**两个端点通用,只有 unet_name 不同**: ```python g = { "1": {"class_type":"UNETLoader","inputs":{"unet_name":"<按端点选,见 §2.0>","weight_dtype":"default"}}, "2": {"class_type":"CLIPLoader","inputs":{"clip_name":"qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors","type":"minimax","device":"default"}}, "3": {"class_type":"VAELoader","inputs":{"vae_name":"minimax_h3_image_vae_fp16.safetensors"}}, "4": {"class_type":"MiniMaxH3ImageConditioning","inputs":{"clip":["2",0],"vae":["3",0], "prompt":PROMPT,"width":2048,"height":2048}}, # vae / images 是 optional "5": {"class_type":"ConditioningZeroOut","inputs":{"conditioning":["4",0]}}, "6": {"class_type":"KSampler","inputs":{"model":["1",0],"seed":42,"steps":6,"cfg":1.0, "sampler_name":"euler","scheduler":"simple","positive":["4",0],"negative":["5",0], "latent_image":["4",1],"denoise":1.0}}, "7": {"class_type":"VAEDecode","inputs":{"samples":["6",0],"vae":["3",0]}}, "8": {"class_type":"SaveImage","inputs":{"images":["7",0],"filename_prefix":"H3IMG"}}, } ``` 实机 `/object_info` 核对(**30113 与 DCU 签名一致**):`MiniMaxH3ImageConditioning` required = `clip, prompt, width, height`;optional = `vae, images`;输出 = `CONDITIONING, LATENT`。宽高 `step=32`、`max=16384`,`0` 表示按参考图/默认 2048。 > ⚠️ 出图成功 ≠ 内容正确。量化档位不对时会静默出纯色图 —— 跑完必须看自检输出(见 §2.3)。 ### 4.5 MiniMax H3 音画同出(台词镜头唯一正路) 带台词的人物镜头**不再事后贴嘴**:用 `http://192.168.1.23:30121`(K100 64 GB)的 H3 `fl2va` 做 **首帧锁图 I2V + 原生对白/环境音**,一条图同时出画面与声音,口型原生对齐。 ```bash python3 tools/queue_h3_native.py --ep EP01 # 整集排队(不等待) python3 tools/fetch_h3_native.py --ep EP01 # 任意时刻取回 python3 tools/submit_h3_native.py --ep EP01 --shot S04 --seconds 7.3 # 单镜 ``` 规格:576×1024 / 24 fps / `length=17k+5`(训练区间 124–362 帧)/ 20 步 `res_multistep`+`simple` / `CreateVideo.bit_depth=8` / 单镜 ≈ 90 min。**节点图、提示词五段式、时长网格、排队与丢失自检全部见 [native-av.md](native-av.md)**;本文件不再重复。 --- ## 5. 辅助模型 API(策划、扩写、检索) ### 5.1 LLM 代理 `ipass-all`(阶段 1 拆剧本 / 扩写提示词) OpenAI 兼容,**需要 API Key**,用 xop 注入,密钥不落明文: ```bash # 列模型(返回 x_ipass_upstreams,含 slot 路由表) xop run --secret K=llm_key -- bash -c 'curl -s --noproxy "*" -m 10 \ -H "Authorization: Bearer $K" http://192.168.1.30:30084/v1/models' < /dev/null # 对话:必须按 slot 前缀路由 xop run --secret K=llm_key -- bash -c 'curl -s --noproxy "*" -m 60 \ -X POST http://192.168.1.30:30084/qwen/v1/chat/completions \ -H "Authorization: Bearer $K" -H "Content-Type: application/json" \ -d "{\"model\":\"qwen3.8-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"把这段戏拆成 8 个镜头\"}]}"' < /dev/null ``` | slot 路径 | 可用 model | 实测 | |---|---|---| | `/qwen/v1/chat/completions` | `qwen3.8-flash` | ✅ 通(有 `reasoning_content`,`max_tokens` 别给太小) | | `/deepseek/v1/...` | `deepseek-flash`, `deepseek-v4-pro` | ✅ 通 | | `/minimax/v1/...` | `MiniMax-M3`, `MiniMax-M3.1-Flash` | ✅ 通(响应带 ``) | | `/glm/v1/...` | `GLM-5.3-Flash` | ⚠️ 曾报周/月用量上限,按 `/v1/models` 的 `x_ipass_upstreams` 看状态 | > **坑**:直连 `http://192.168.1.30:30084/v1/chat/completions` 一律报 `model_not_found / 上游 v1 不存在或已停用`——它按 **slot 前缀**分流,`/v1/models` 只是聚合视图。模型名也必须写该 slot 下的准确 id。 ### 5.2 `embed-bge`(向量化 / rerank,免密钥) > ⚠️ **2026-11-13:服务已下线** —— `192.168.1.24:8801` TCP CLOSED(随 DCU 整机一起挂)。 > 下面的调用方式留作恢复后参考;当前**设定检索、去重、语义回填这些环节没有可用的向量服务**, > 需要的话只能退回纯关键词匹配,或等 DCU 恢复。 ```bash curl -s --noproxy '*' -X POST http://192.168.1.24:8801/v1/embeddings \ -H 'Content-Type: application/json' \ -d '{"model":"BAAI/bge-large-zh-v1.5","input":"湖面泛起薄雾"}' # 1024 维 ``` - 模型名必须是 **`BAAI/bge-large-zh-v1.5`**;写 `bge-large-zh` 会 404 `The model ... does not exist`。 - 另有 `/v1/models`、`/v1/rerank`、`/v1/score`、`/pooling`、`/health`,都是 POST(除 `/v1/models`、`/health`)。 - 用途:长剧本按语义检索源节拍、跨集角色设定去重;不参与出图出片。 --- ## 6. 开工前健康自检 ```bash # ① 主用端点(30113):在线 + ComfyUI 0.45 + 显存 U=192.168.1.30:30113 curl -s --noproxy '*' -m 8 "http://$U/system_stats" \ | python3 -c "import json,sys;d=json.load(sys.stdin);print('ComfyUI',d['system']['comfyui_version'],'|',d['devices'][0]['name'],'|',round(d['devices'][0]['vram_free']/1048576),'MB free')" # ② 能力自检:UNETLoader 必须列出 4 个扩散模型(图 + H3 视频 + WAN high/low) curl -s --noproxy '*' -m 8 "http://$U/object_info/UNETLoader" | python3 -c " import json,sys d=json.load(sys.stdin)['UNETLoader']['input']['required']['unet_name'][0] print(len(d),'models:'); [print(' ', x) for x in d] assert len(d)>=4, '缺权重 -> 跑 /basedir/apply-multimodal.sh(pod 重建后软链会丢)' " # ③ 旧端点(可选,回退用) for U in 192.168.1.30:30111 192.168.1.30:30112; do printf "%-24s" "$U" curl -s --noproxy '*' -m 8 "http://$U/system_stats" | head -c 80; echo done # ④ 对白镜主力(30121,K100 64 GB):必须看到 4 个 UNET(H3 视频 / H3 图像 / WAN high+low) U=192.168.1.23:30121 curl -s --noproxy '*' -m 8 "http://$U/system_stats" | python3 -c "import json,sys;d=json.load(sys.stdin);v=d['devices'][0];print('ComfyUI',d['system']['comfyui_version'],'|',v['name'],'|',round(v['vram_total']/1048576),'MB |',round(v['vram_free']/1048576),'MB free')" curl -s --noproxy '*' -m 8 "http://$U/object_info/UNETLoader" | python3 -c " import json,sys d=json.load(sys.stdin)['UNETLoader']['input']['required']['unet_name'][0] print(len(d),'models:',d) assert any('fl2va' in x for x in d), '缺 H3 视频权重 → I2V 跑不了' assert any('image' in x for x in d), '缺 H3 图像权重 → 出不了首帧' " # 旧 DCU 30120(**与 30121 不是一台机**)已下线,留作恢复后检查用 for U in 192.168.1.24:30120 192.168.1.24:8801; do printf "%-24s" "$U"; curl -s --noproxy '*' -m 6 "http://$U/system_stats" | head -c 40; echo; done ``` **② 是合并后的关键判据**:只有 1 个 `minimax_h3_image_*` 说明 `/local/models` 的软链没了(pod 重建), 不是模型坏了 —— 跑一次 `/basedir/apply-multimodal.sh` 即恢复,见部署侧 `deploy-as-built.md` §6。 再按 §3.2 判一次启动参数:**30113 应有 `--cache-none`,且绝不能有 `--fp16-unet`**(会毁掉 H3-Image 的 bf16 路径 → 全黑图); 30111 则相反,必须有 `--fp16-unet`;30112 上看到 `--force-fp16` 要停手(fp8 升 fp16 撞 4 GiB)。 容器 `memory.events` 的 `oom_kill` 必须保持 0;若日志出现 `No working comfy-aimdo install detected` 且没打补丁,会退回 legacy 并在 30 秒内 exit 137。 --- ## 7. 硬约束速查(别照搬) | 约束 | 归属 | |---|---| | 明文 HTTP 必须绕代理 | 全部 | | `/prompt` 要 `{"prompt": ...}` 外层 | 全部 | | 串行提交、网络超时先查 `/history` | 全部(30113 承接全部三种模态) | | **DCU 禁用 int8_convrot**(gfx928 `rint` bug → NaN → 纯黑图) | H3-Image@DCU | | **K8s-30113 只能 int8_convrot**(无 w4a8,sm_75 跑不了 w4a8 CUDA 路径) | H3-Image@K8s | | **DCU-30121(K100/ROCm)只能 w4a8**,同样禁 `int8_convrot`;与 30113 的方向再次相反 | H3-Image@30121 | | **H3 的 I2V 只在 64 GB 卡(30121)可用**;30113(22 GB)塞 `first_frame` 必 OOM | H3 视频 | | **30121 禁调 `/api/free`**:会崩服务(约 20 s 自愈,期间排队任务全丢) | 30121 | | **`queue` / `history` 是内存态**:实例重启 → 排队的任务静默消失,`{}` 有排队/执行中/不存在三义,必须与 `/queue` 交叉核对 | 全部 | | **30113 禁 `--fp16-unet`**(动态范围 ±65504 → adaln 缩放溢出 → NaN → 全黑);必须走 bf16 软件模拟 | 30113 | | **出图后看自检输出**(`[SANITY]`),纯色图 = 量化档位错,不是提示词问题 | H3-Image | | 不用 turbo LoRA(合进 w6a8 → 全黑,4 步/6 步都试过) | H3 量化版 | | 不照搬 `H3AudioClean`(仅 ROCm 需要) | DCU ↔ K8s | | 不照搬采样节点与 `SaveVideo.format`(动态组合,别传 `video/h264-mp4`) | 0.45 ↔ 0.38 | | `--force-fp16` 对 A14B 是禁用;`--fp16-unet` **30111 必需、30113 禁用** | K8s | | 不需要 `ComfyUI-WanVideoWrapper`;不需要 CLIP-Vision 权重(`start_image` 走 VAE) | 30113 | | **pod 重建后跑 `/basedir/apply-multimodal.sh`**,否则只剩出图能力 | 30113 | | 分辨率 / 帧数上限:A14B 832×480 / 81 帧;H3 在 0.45 实测 320×192 / 22 帧(0.38 上 960×544 / 33 帧通过) | K8s | | 任何消耗算力的步骤,生成前展示清单并取得明确授权 | 本技能规则 | --- ## 8. 相关文件 | 位置 | 内容 | |---|---| | 部署侧 `deploy/k8s-nvidia/deploy-as-built.md` | **单实例部署 as-built**(不在技能包内):拓扑、4 GiB 限制、补丁集、pod 重建恢复、排障 | | 本技能 `tools/submit_h3_native.py` | **H3 音画同出提交器**(台词镜头,64 GB 卡);`queue_/fetch_h3_native.py` 是排队与取回 | | 本技能 `references/native-av.md` | **台词镜头唯一正路**:为什么放弃事后 lip-sync、节点图、五段式提示词、时长网格、排队与丢失自检 | | 本技能 `tools/submit_i2v.py` | A14B 图生视频提交器(阶段 4;节点图已对齐 0.45) | | 本技能 `tools/submit_t2i.py` | H3-Image 文生图提交器(阶段 0 / 4 首帧) | | 本技能 `references/submit-i2v.md` | 提交协议、预检、哈希命名与授权闸门 | | 项目 `deploy/k8s-nvidia/REPORT-multimodal.md` | 本次合并的完整排查报告(含误判纠正与验证数据) | | 项目 `deploy/k8s-nvidia/apply-multimodal.sh` | 权重软链恢复脚本(部署时拷到 `/basedir/`) | | 项目 `deploy/k8s-nvidia/deployment-multimodal.patch.json` | 追加 initContainer 的持久化补丁 | | 项目 `deploy/dcu-hygon/H3-USAGE.md` | H3 视频 + H3-Image 节点图与踩坑全文(DCU 线) | | 项目 `deploy/dcu-hygon/H3-ON-DCU.md` | DCU 部署实录(as-built) | | 项目 `deploy/k8s-nvidia/H3-ON-2080.md` | H3 on 2080Ti(4Gi 墙补丁 / Dynamic VRAM) | | 项目 `deploy/k8s-nvidia/A14B-USAGE.md` | A14B 参数表与能力边界 | | 项目 `deploy/k8s-nvidia/api/wan22_h3_api.json` | H3 实测跑通的裸 workflow(**提交前要包 `prompt`**) | | 项目 `client/h3_image_gen_k8s.py` | H3-Image 客户端(本技能 `submit_t2i.py` 的原型) |