---
title: H3-FP4-5070
canonical_url: "https://www.modelscope.cn/models/Xanyiyan/H3-FP4-5070"
md_url: "https://www.modelscope.cn/models/Xanyiyan/H3-FP4-5070.md"
repository: Xanyiyan/H3-FP4-5070
chinese_name: "H3/H3-Image NVFP4 本地流式推理（RTX 5070 12GB 实测）"
last_updated: 2026-11-22
downloads: 0
stars: 1
---

# H3-FP4-5070

> H3-FP4-5070 - Xanyiyan 在 ModelScope 开源的模型。MiniMax H3 + H3-Image NVFP4 W4A4 local inference engine (RTX 50 series / 5070 tested)

- **Repository**: Xanyiyan/H3-FP4-5070
- **Downloads**: 0
- **Stars**: 1
- **Last updated**: 2026-11-22

Source: https://www.modelscope.cn/models/Xanyiyan/H3-FP4-5070

---

# MiniMax H3 / H3-Image NVFP4 (W4A4) 本地流式推理 —— 面向 RTX 50 系（实测 RTX 5070 12GB）

把 MiniMax-H3（视频，Ref2VA）与 MiniMax-H3-Image（图像）跑进 **12GB 消费级显卡**的自量化推理引擎：
**权重离线转 NVFP4（E2M1）+ 真 W4A4 FP4 张量核 + 逐层流式 + AdaLN 预计算 + 自动驻留**。

- 权重**事先离线全量化**：运行时不量化、不反量化权重；激活的 W4A4 在线量化是 FP4 计算的固有成本。
- BF16 原件保留不删；精度可逐层叠加"套娃"恢复（见下文精度表）。
- 目标硬件：**NVIDIA Blackwell（sm120，RTX 50 系）**。实测卡：**RTX 5070 12GB**。
  RTX 40 系及更早**不支持** NVFP4 张量核；AMD（gfx942/gfx1100）同样**无 FP4 硬件**，本仓库不适用。

> 本仓库**不包含模型权重**（图像/视频 FP4 各 37.48GB），只包含引擎、转换器、预计算脚本、使用手册与实测样片。
> 权重请从官方仓库获取后自行转换（步骤见 `docs/`）。

---

## 1. 能做什么

### 图像（H3-Image）
- 文生图（512 / 2048 / 4096 方形或自定义画布）
- **参考图生图、多参考图编辑**（有序多图，经服务端接口）
- 512² **≈15–17 秒/张**（BF16 同机 648s ⇒ **≈40×**）
- 4K 整图 **≈178–203 秒**，峰值显存 **≤9.5GB**，不溢 12GB

### 视频（H3 Ref2VA，视频+音频联合）
- **参考图生视频**：参考图即首帧条件，**首帧天然锁定**（Ref2VA 结构决定）
- turbo 8 步蒸馏 LoRA：124 帧 / 512² 一条 **≈203 秒**
- 标准 20 步：124 帧 / 512² **≈284 秒**；kernel 修复后单步实测 **11.88s**
- 空间分块（MultiDiffusion）可上 2K；4K 可跑但很重（VAE 解码 ~945s 是大头）

---

## 2. 目录

```
code/
  h3image_engine_fp4.py      # 图像 FP4 引擎（NVFP4 算子 + 流式 + 自动驻留）
  h3_engine_fp4.py           # 视频 FP4 引擎（monkey-patch BF16 引擎；自动 AdaLN 缓存；--tile/--ov）
  h3image_engine.py          # 图像 BF16 基础引擎（依赖，随附）
  h3_engine.py               # 视频 BF16 基础引擎（依赖，随附）
  h3_engine_server.py        # 常驻 HTTP 服务：/v1/images/generations|edits、/v1/video/generations
  h3_video_job.py            # 视频任务驱动（turbo/steps/frames/size）
  h3image_fp4_convert.py     # 图像 BF16 → NVFP4 k1 转换器
  h3video_fp4_convert.py     # 视频 BF16 → NVFP4 k1 转换器
  h3image_adaln_precompute.py# 图像 AdaLN t 键预计算（26GB → 58MB）
  h3video_adaln_precompute.py# 视频 AdaLN t 键预计算（video shift12 / audio shift3）
  h3_encode.py               # Qwen3-VL 文本/参考图条件编码（生成 h3_cond_*.pt）
  fused_quant.cu             # 自研融合 NVFP4 量化 kernel（NVRTC 运行时编译，免 MSVC）
  技术成果与避坑总账.txt       # 全部实测数字与踩坑记录
docs/
  image.md                   # 图片：安装/权重/转换/文生图/参考图生图/多图编辑/性能/排错
  video.md                   # 视频：安装/权重/转换/参考图生视频/首帧锁/turbo8/分块/性能/排错
samples/
  h3image_fp4_512_kernel_42.png   # 512² 文生图样片
  h3_multi_edit_512.png           # 多参考图编辑样片
  turbo8_fp4_512.mp4              # turbo8 参考图生视频（124f/512²）
  h3video_fp4_20step.mp4          # 20 步参考图生视频
```

---

## 3. 环境（实测组合）

| 项 | 版本 |
|---|---|
| GPU | NVIDIA RTX 5070 12GB（Blackwell sm120） |
| 系统 | Windows 11（Linux 同样可跑，仅路径常量需改） |
| PyTorch | 2.11 + CUDA 12.8（cu128） |
| cuDNN | 9.19 |
| Python | 3.12 |
| 额外 | `cuda-python`、`nvidia-cuda-nvrtc-cu12`（官方 pip，NVRTC 编译 `fused_quant.cu` 用，**不需要** nvcc/MSVC） |

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install numpy safetensors pillow cuda-python nvidia-cuda-nvrtc-cu12 "transformers>=4.57" accelerate
```

---

## 4. 快速开始

完整步骤在 `docs/image.md` 与 `docs/video.md`。最短路径：

1. **下载官方权重**
   - 图像：`MiniMaxAI/MiniMax-H3-Image`（HF）或 ModelScope 镜像 → 放到 `models/MiniMax-H3-Image`
   - 视频：`MiniMax-H3/Ref2VA` → 放到 `models/MiniMax-H3`
2. **转换 FP4**：`python h3image_fp4_convert.py` / `python h3video_fp4_convert.py`
   （66.28GB BF16 → 37.48GB，约 100–105 秒）
3. **预计算 AdaLN**：`python h3image_adaln_precompute.py` / `python h3video_adaln_precompute.py 20`
   （**缓存必须与运行时 steps 匹配**，错配会出 confetti 垃圾；视频引擎已做"按实际 steps 自动建/复用"）
4. **出图**：`python h3image_engine_fp4.py --run --size 512 --seed 42 --out out.png`
5. **出视频**：`python h3_video_job.py --ref ref.png --steps 8 --turbo 8 --frames 124 --size 512 --out out.mp4`

> 各脚本顶部有 `ROOT / FP4_DIR / COND` 路径常量，请改成你自己的路径（默认是作者机器的 `D:\ai\...`）。

---

## 5. 实测性能（RTX 5070 12GB，2026-11）

### 量化损失（往返 relL2；E2M1 的 1 位尾数是地板）

| 组件 | k1 | k2 套娃 | k3 套娃 |
|---|---|---|---|
| fc1/fc2/qkv/out/adaln | 9.4–9.6% | 0.86% | 0.078% |

- 图像 FP4 vs BF16：平均 L1 ≈9.7%，Pearson ≈0.84（结构对、细节漂移；作者目视认可）
- 视频：速度场与 BF16 逐位级接近（|v|std 1.30 / 相邻格相关 0.40）
- k2 套层（残差逐层细化）可把损失降到 0.86%，是追求画质时的推荐档

### 图像（H3-Image）

| 分辨率 | 时间 | 备注 |
|---|---|---|
| 512² | **15–17s/张** | BF16 648s ⇒ ≈40× |
| 2048² | 17.1s/单步 | 自动驻留 32 层 |
| 4096² | 30.6s/单步，整图 **178–203s** | 自动驻留 12 层，峰值 ≤9.5GB |

### 视频（Ref2VA，含音频）

| 配置 | 时间 | 备注 |
|---|---|---|
| 124f / 512²，turbo8 | **≈203s/条** | 首帧锁定，L1 0.037 |
| 124f / 512²，20 步 | ≈284s | kernel 修复后单步 11.88s（quant 10.5% / attn 60.3%） |
| 2K（2048²）22f，tile=1024 | ov0 单步 51s；ov256 单步 70s | 不分块 >240s；3 步 247s 出片 |
| 4K tile=1024 | ov0 单步 173s；ov256 单步 294s | 完整 1 步+解码 1239s（VAE 解码 ~945s） |

**12GB 卡结论：图片到 4K 可用；视频 512² 流畅，2K 是实用上限，4K 只适合离线慢跑。**

**驻留档位**：`--resident` 是上限，auto 只在其下按空闲显存算。12GB 用 32–36；**≥16GB 直接 `--resident 50`（50 层全驻留仅 10.7GB）**——实测 16GB 卡 512² 13.4s / 2048² 27.2s / 4K(自动 31 层) 132.7s，比 12GB 的 178s 快 35%；同卡 40 层时每步需流式重载 10 层，慢 11 倍（0.4→4.6s/步）。

---

## 6. 关键事实与坑（摘要，详见 `code/技术成果与避坑总账.txt`）

1. FP4 仅 Blackwell 有硬件；40 系 / AMD 跑不了（`torch._scaled_mm` 直接拒绝）。
2. 激活量化是 W4A4 固有在线成本；`fused_quant.cu` 用 NVRTC 编 sm120 cubin，实测 0.091ms vs Python 14.47ms（**160×**），失败自动回退。
3. AdaLN 缓存 steps 错配 = confetti 垃圾（调制错位），不是量化缺陷。
4. 驻留 sweet spot 32–36 层；40+ 会分配器 thrash 反而慢。
5. Windows `pin_memory` 额度约 7.5–8GB，32GB 内存机器**不要 pin** 11.5GB 权重。
6. 4K 激活估算：BF16 GEMM 输出 + 分块量化（CH=4096），否则 int64 bucketize 的临时张量会吃掉几 GB。
7. 视频参考图按自身分辨率编码，参考图糊 ⇒ 视频糊。
8. 测峰值须 GPU 空闲：游戏负载会把 FP4 峰值从 415 压到 ~179 TFLOPS。
9. `use_fast_accum=True` 对 FP4 不支持；trtllm-gen/DeepGEMM 在 sm120 不可用，只能 CUTLASS `_scaled_mm_v2` + 形状优化。
10. 4K 视频满帧 L≈114k，激活 >12GB 必溢；分块是唯一路（时序分块未做）。

---

## 7. 精度与开关（W4A4 之外的补救）

- **k 层套娃**：把残差按层细分、k 份存权重（非只计算），k2 已把往返损失压到 0.86%，k3 到 0.078%。
- 大矩阵可沿 N 合并成一次 GEMM（FP32 逐位等价、激活只量化一次）；但 H3 的 FFN 形状已饱和，收益有限。
- 目前不提供运行时权重反量化路径：权重必须**事先离线**转换。
- k2 的 FP4 注意力是研究级优化（需 NVRTC tcgen05 mma），未纳入本仓库主线。

---

## 8. 许可与免责

- 本仓库代码可自由使用/修改（请保留出处）；模型权重版权归 MiniMax，需遵守其官方许可。
- 本项目为个人研究工程，非官方实现；量化会带来画质漂移，商用前请自行评估。
- 作者实测环境为 Windows + RTX 5070；其他 Blackwell 卡（5080/5090）同理可用，显存越大驻留越高、速度越快。

---

## 9. 样片

`samples/` 下四件均为本引擎在 RTX 5070 12GB 上的真实产物（未做后期）：
- `h3image_fp4_512_kernel_42.png`：512² 文生图
- `h3_multi_edit_512.png`：多参考图编辑
- `turbo8_fp4_512.mp4`：turbo8 参考图生视频（首帧锁定）
- `h3video_fp4_20step.mp4`：20 步参考图生视频
