Files
ai-manju/references/models.md
T
admin 9981d02fa4 docs: 30113 启动参数按实机 argv 复核修正
实机 argv 无 --reserve-vram,改为 --disable-smart-memory;补 2026-11-19 实测标注。
2026-11-19 18:59:21 +08:00

737 lines
56 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 内网模型服务与 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`**)<br>(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`…,提示词用 `<Picture 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/<pid>` 复核「删前有 → 删后无」,
并查 `/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-<uuid8>` / `manju-t2i-<uuid8>` 提交并把 `clientId` 写进台账;清理时 `GET /api/history/<pid>` 读回 `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/<pid>` 抽产物清单 | ❌ `DELETE /history/<pid>` 实测 **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/<pid>` + `/api/queue` 复核 | ❌ 200 空 body **不等于删除成功**,删不存在的 pid 也是 200 |
| `GET /api/history/<pid>` 读 `prompt[3]["client_id"]` 判归属 | ❌ 官方删除接口**不带任何归属校验**:谁都能 `{"delete":[别人的 pid]}`,所以必须客户端先拦 |
| 扩展 `GET /api/manju/cleanup/ping` / `POST .../purge` | ❌ 扩展装了才可用;未装时脚本自动降级 |
**顺序铁律(装了扩展时,与旧版不同)**:
`GET /api/history/<pid>` 抽产物清单 + `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/<pid>` 变成 `{}` 且 `/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 <pid> --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 名由模板动态查,不用手填 `<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` | ✅ 通(响应带 `<think>`) |
| `/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` 的原型) |