Initial commit: Hermes Agent Skills collection
This commit is contained in:
Debian
@@ -0,0 +1,124 @@
|
||||
# Ideogram 4 Local Execution in ComfyUI
|
||||
|
||||
Multiple paths exist to generate with Ideogram 4. The simplest is the cloud API node (`IdeogramV4`), but it requires a `comfy.org` API key. For local execution without cloud dependency, use the native `Ideogram4Scheduler` + model files.
|
||||
|
||||
## Path A: Cloud API Node (Simplest, but requires key)
|
||||
|
||||
**Node:** `IdeogramV4`
|
||||
**Location:** `comfy_api_nodes/nodes_ideogram.py`
|
||||
**Requires:** `COMFY_CLOUD_API_KEY` env var or login
|
||||
|
||||
**Error without auth:**
|
||||
```
|
||||
Unauthorized: Please login first to use this node.
|
||||
```
|
||||
|
||||
Works with structured JSON prompt (scene + style + background blocks). The easiest if you have the key.
|
||||
|
||||
---
|
||||
|
||||
## Path B: Local Native Pipeline (No API key, but 28 GB disk needed)
|
||||
|
||||
**Recommended when:** No comfy.org auth available or prefer full local execution.
|
||||
|
||||
### Required Model Files
|
||||
|
||||
| File | Size | Folder | Source |
|
||||
|---|---|---|---|
|
||||
| `ideogram4_fp8_scaled.safetensors` | ~8.6 GB | `models/diffusion_models/` | HuggingFace: `Comfy-Org/Ideogram-4` |
|
||||
| `ideogram4_unconditional_fp8_scaled.safetensors` | ~8.6 GB | `models/diffusion_models/` | HuggingFace: `Comfy-Org/Ideogram-4` |
|
||||
| `flux2-vae.safetensors` | ~320 MB | `models/vae/` | HuggingFace: `Comfy-Org/flux2-dev` |
|
||||
| `qwen3vl_8b_fp8_scaled.safetensors` | ~9.9 GB | `models/text_encoders/` | HuggingFace: `Comfy-Org/Qwen3-VL` |
|
||||
| `gemma4_e4b_it_fp8_scaled.safetensors` | ~5.4 GB (optional alt) | `models/text_encoders/` | HuggingFace: `Comfy-Org/gemma-4` |
|
||||
|
||||
**Total: ~28 GB**
|
||||
|
||||
### Model Verification Recipe
|
||||
|
||||
A file can have the correct size on disk but still fail to load with `SafetensorError: incomplete metadata`. This happens when a download is interrupted and resumed incorrectly, or when the file was copied incompletely.
|
||||
|
||||
Use this Python script to verify any `.safetensors` file before trusting it:
|
||||
|
||||
```python
|
||||
import struct, json, os
|
||||
|
||||
def verify_safetensors(path):
|
||||
"""Check header metadata against actual file size."""
|
||||
actual = os.path.getsize(path)
|
||||
f = open(path, 'rb')
|
||||
header_len = struct.unpack("<Q", f.read(8))[0]
|
||||
meta = json.loads(f.read(header_len))
|
||||
total = 8 + header_len
|
||||
for k, v in meta.items():
|
||||
if isinstance(v, dict) and "data_offsets" in v:
|
||||
total += v["data_offsets"][1] - v["data_offsets"][0]
|
||||
return {
|
||||
"actual_bytes": actual,
|
||||
"expected_bytes": total,
|
||||
"ok": total == actual,
|
||||
"header_keys": len(meta),
|
||||
"missing": total - actual if total > actual else 0,
|
||||
}
|
||||
|
||||
# Example
|
||||
result = verify_safetensors("models/text_encoders/qwen3vl_8b_fp8_scaled.safetensors")
|
||||
print(result)
|
||||
# If ok=False, the file is corrupt and MUST be re-downloaded.
|
||||
```
|
||||
|
||||
**Command line shortcut (in Container):**
|
||||
```bash
|
||||
python3 -c "
|
||||
import struct, json, os; p='/opt/ComfyUI/models/text_encoders/qwen3vl_8b_fp8_scaled.safetensors'
|
||||
f=open(p,'rb'); h=struct.unpack('<Q',f.read(8))[0]; m=json.loads(f.read(h))
|
||||
t=8+h; [t:=t+v['data_offsets'][1]-v['data_offsets'][0] for k,v in m.items()
|
||||
if isinstance(v,dict) and 'data_offsets' in v]
|
||||
print('ok=',t==os.path.getsize(p))
|
||||
"
|
||||
```
|
||||
|
||||
### Text Encoder Compatibility Note
|
||||
|
||||
Ideogram 4 supports **two** text encoders:
|
||||
- `qwen3vl_8b_fp8_scaled.safetensors` (Qwen3-VL, ~9.9 GB) — primary, higher quality
|
||||
- `gemma4_e4b_it_fp8_scaled.safetensors` (Gemma 4, ~5.4 GB) — lighter alternative
|
||||
|
||||
If one fails (e.g., corrupt download), try the other.
|
||||
|
||||
### ComfyUI BluePrint Workflow (API Format)
|
||||
|
||||
The canonical workflow is shipped as a BluePrint JSON in ComfyUI:
|
||||
```
|
||||
blueprints/Text to Image (Ideogram v4).json
|
||||
```
|
||||
|
||||
This uses the `Ideogram4Scheduler` + `DualModelGuider` with the two UNet files (conditional + unconditional) for asymmetric classifier-free guidance.
|
||||
|
||||
**Key nodes in the BluePrint:**
|
||||
- `Ideogram4Scheduler` → outputs SIGMAS (replaces BasicScheduler)
|
||||
- `DualModelGuider` → combines positive + unconditional models
|
||||
- `CFGOverride` → cfg schedule override (start/end percent)
|
||||
- `EmptyFlux2LatentImage` → 128-channel latent
|
||||
- `SamplerCustomAdvanced` → with euler + Ideogram4Scheduler sigmas
|
||||
|
||||
### Common Errors — Local Path
|
||||
|
||||
**1. `SafetensorError: incomplete metadata, file not fully covered`**
|
||||
- **Cause:** File is structurally corrupt (wrong tensor offsets in header).
|
||||
- **Fix:** Run verification recipe above. If `ok=False`, delete and re-download from HuggingFace.
|
||||
- **Important:** `ls -lh` showing the right size is NOT sufficient. The header values must match the data offsets.
|
||||
|
||||
**2. `Unauthorized: Please login first to use this node`**
|
||||
- **Cause:** Using `IdeogramV1`/`V2`/`V3`/`V4` API node without comfy.org auth.
|
||||
- **Fix:** Switch to local pipeline (`Ideogram4Scheduler` + model files), or add `COMFY_CLOUD_API_KEY`.
|
||||
|
||||
**3. `expected input[1, 128, 32, 32] to have 16 channels`**
|
||||
- **Cause:** Using FLUX.1 VAE (`ae.safetensors`) instead of `flux2-vae.safetensors`.
|
||||
- **Fix:** VAE must be `flux2-vae.safetensors` (or `taef2`).
|
||||
|
||||
## References
|
||||
|
||||
- ComfyUI BluePrints: `blueprints/Text to Image (Ideogram v4).json`
|
||||
- Model source: https://huggingface.co/Comfy-Org/Ideogram-4
|
||||
- Text encoder: https://huggingface.co/Comfy-Org/Qwen3-VL
|
||||
- Alternative encoder: https://huggingface.co/Comfy-Org/gemma-4
|
||||
Reference in New Issue
Block a user