h3-opt

主打：苹果平台极致性能 — Mac Ultra / Apple Silicon 上把 MiniMax-H3 + antirez/h3.c 拧到 秒级试片，再按需爬升到可交付。不 fork Metal。

仓库名 h3-ops · CLI h3ctl · 产品名 h3-opt（optimize for Apple）。

Goal → reality (read this first)

Brand	h3-opt — Apple-first extreme performance for local H3
Goal	Mac Ultra 上 MiniMax-H3 秒级出图/试片（再升到可交付）
How	Pin h3.c fast knobs (snap / warm session), exclusive GPU, zero mlx fight, measure denoise vs e2e
Not	CUDA / Comfy 通用栈；不重写 Metal 内核（antirez 管算子，我们管极致路径）
Today	M3 Ultra 96GB: snap cold e2e ~35s（TE + DiT load + denoise）。秒出 = h3ctl warm 常驻后再抽
Speed rules	≥64GB 禁止默认 SSD stream；snap 用 layers40·reuse1；draw/preview 开 token-reduction

h3ctl doctor          # mlx / rivals must be clear — 性能第一原则
h3ctl run --preset snap --prompt-file examples/smoke.prompt.txt -o out/snap.mp4
h3ctl warm --preset snap   # interactive：首镜仍冷，之后 denoise 秒级
h3ctl chain --manifest examples/wuxia_chain.json --preset film_draft -o out/wuxia_chain

h3.c alone: wrong cwd、无锁、容易一上来就跑 14 分钟 hero。
h3-opt 把苹果上的 极致快路径做成默认产品（snap → draw → preview → deliver）。

_{h3-opt · 武侠横幅 · film_master 1248×704 · Ultra · h3ctl run --preset film_master}

Official module	Open?	Local stand-in
H3-Context-IR	API only	cir — compile / validate / revise / emit
H3-Base	weights open	ops — doctor / gate / run / batch
H3-Regenerate-2K	API only	hd — native → upscale → optional cloud 2K

Truth artifact: ContextDoc JSON (schema). MP4 is a projection of doc + seed + preset.
Status: Phase 0–4 MVP shipped (ops + cir + hd). Phase 5 = cloud adapters. See DESIGN.md.

Quick start

git clone https://github.com/quantz8a/h3-ops.git
cd h3-ops
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e .

export H3_OPS_H3C_SRC=/path/to/h3.c          # tree that contains h3_shaders.metal
export H3_OPS_MODEL_DIR=/path/to/MiniMax-H3   # must include FL2VA/
h3ctl doctor
h3ctl run --preset snap --prompt-file examples/smoke.prompt.txt -o out/snap.mp4 --profile
# or: smoke / draw / preview / deliver

Needs: Apple Silicon, a built h3.c, MiniMax-H3 with FL2VA/, and ffmpeg / ffprobe.
Without install: PYTHONPATH=src python3 -m h3_ops … or ./scripts/h3ctl ….

Typical loop:

h3ctl cir compile --brief "剑气削叶" -o shot.cir.json
h3ctl cir validate shot.cir.json
h3ctl run --preset preview --doc shot.cir.json -o out/preview.mp4
# factory / FL2VA:
# h3ctl run --preset draw --prompt-file shot.txt -o out.mp4 \
#   --first-frame start.png --no-ssd-streaming
h3ctl cir revise shot.cir.json --notes "剑气线不可读" -o shot.cir.json
h3ctl hd deliver --doc shot.cir.json --base out/preview.mp4 \
  --target upscale_1080 -o out/deliver_1080.mp4

Working now: doctor, presets, lock, run, cir *, hd ladder|deliver|stitch.
Demo ContextDoc: examples/leafcut.cir.json. Drop real clips under examples/renders/ (see README there).

Optional LLM (cir only)

export H3_OPS_LLM_BASE=http://127.0.0.1:11236/v1
export H3_OPS_LLM_MODEL=local
h3ctl cir compile --brief "..." --backend llm -o shot.cir.json
# never run LLM parallel with h3ctl run on the same GPU

Requirements

Need	Notes
Apple Silicon	arm64
Built h3.c	spawn must chdir to the tree that has h3_shaders.metal
MiniMax-H3 BF16	local path with FL2VA/ — not shipped here
ffmpeg / ffprobe	stitch / probe
Optional LLM	OpenAI-compatible for cir.compile
Optional API key	cloud CIR / Regenerate-2K adapters only

Presets & wall-clock anchors

Measured on M3 Ultra 96GB unless noted. 秒出 starts at snap, not deliver.

preset	canvas	frames	steps	knobs	~wall	use
snap	512²	22	4	layers40·reuse1·rw384·resident	cold ~35s / denoise ~秒级；warm 后接近 denoise	秒级试片
snap256	256²	22	4	layers40·reuse1·resident	fastest composition	构图闪看
smoke	512²	22	4	layers45·reuse1·resident	path check	冒烟
draw	480×832	56	6	layers45·reuse2·token-reduction	~1–2 min	vertical card
film_draft	832×480	56	4	layers45·reuse1·token-reduction	~1–2 min	16:9 电影卡
film_master	1248×704	124	8	layers45·resident	~22 min	16:9 成片
film_hero	1248×704	124	12	layers50	~25–45 min	开场/高潮
preview	480×832	124	8	layers45·reuse2·token-reduction	~3–5 min	≥5s review
deliver	480×832	124	24	layers50·reuse1·resident	7–14 min	hero
unsafe_hq	≥576×1024	124	≥20	resident	high	jetsam if mlx alive

Upstream: M5 Max denoise ≈ 3.5s @ 512²·22f·4step (h3.c).
冷启动瓶颈是 TE + DiT load，不是 denoise。 迭代请用 h3ctl warm --preset snap（interactive 常驻），不要每镜新进程 + --ssd-streaming。

Config

Env	Default idea
H3_OPS_H3C_SRC	path to h3.c checkout
H3_OPS_MODEL_DIR	MiniMax-H3 root (FL2VA/)
H3_OPS_LOCK	~/.cache/h3-ops/gpu.lock
H3_OPS_LLM_BASE	OpenAI-compatible base URL (cir only)
H3_OPS_LLM_MODEL	model id (default local)
MINIMAX_API_KEY	cloud adapters only

Non-goals

• Forking / reimplementing Metal DiT or redistributing weights
• Vendor drama / looksheet business
• Label local upscale as Regenerate-2K
• Claiming deliver-quality 5s clips in one second — 秒出 is the snap ladder; hero stays slow on purpose

Docs

• Why h3-opt（必要性参考）: docs/why-h3-opt.md
• Best practices: docs/best-practices.md · site §最佳实践
• Design SoT: DESIGN.md
• Landing: https://quantz8a.github.io/h3-ops/
• Release: https://github.com/quantz8a/h3-ops/releases/tag/v0.1.0
• Schema: docs/schemas/context_doc.v1.json
• Example docs: examples/leafcut.cir.json · examples/xuanhuan_film.prompt.txt
• Demos: docs/demo/snap.gif · docs/demo/xuanhuan_film.gif
• Discussions: https://github.com/quantz8a/h3-ops/discussions

License

MIT (same spirit as h3.c). Model cards apply to weights.