# 内网模型服务与 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` 的原型) |