JOKER141/BUNNY_H3_Conditioning_Bridge

🐇 BUNNY H3 Semantic Bridge V1

A semantic-conditioning bridge for MiniMax H3.
一个用于 MiniMax H3 的语义增强 Bridge。

Semantic Bridge V1 works on H3 conditioning and mainly improves complex subject–action–state relationships.
Semantic Bridge V1 作用于 H3 的 Conditioning，主要改善复杂场景中的 人物—动作—状态关系。

Its main goal is to help H3 better understand who is doing what, who is interacting with whom, which object belongs to whom, and how the scene state should continue.
它主要帮助 H3 更好地理解 谁在做什么、谁和谁发生交互、物体属于谁，以及场景状态应该如何继续。

Typical improvements include:
主要改善的问题包括：

• Character/action ownership errors
  人物与动作归属错误

• Attacker / target confusion
  攻击者与目标错位

• Weapon / object ownership errors
  武器与物体归属错误

• Spatial continuity errors after movement or position exchange
  移动、换位之后的空间连续性错误

• Identity/state errors after occlusion
  遮挡之后的人物与状态错误

• Prompt-following and environment continuity errors
  提示词遵循与环境连续性错误

• Issues that cannot be resolved through motion repair
  动作修复都无法解决的问题

---

📦 Installation

📦 安装

1. Install the custom node

1. 安装节点

GitHub:

https://github.com/aa335615543-ux/BUNNY_H3_Conditioning_Bridge

Put the node folder into:
把节点文件夹放到：

ComfyUI/custom_nodes/

---

2. Install the model

2. 安装模型

Download:
下载：

BUNNY_H3_ActionLogic_Bridge_V1.safetensors

Put it into:
放到：

ComfyUI/custom_nodes/BUNNY_H3_Conditioning_Bridge/models/

Restart ComfyUI.
然后重启 ComfyUI。

If installed through ComfyUI Manager, the folder name may appear as bunny-h3-semantic-bridge. This is normal.

如果通过 ComfyUI Manager 安装，节点文件夹名称可能会显示为 bunny-h3-semantic-bridge，这是正常的。

The node does not depend on a fixed folder name. Just place the Bridge model inside the models folder of the actual installed node directory.

节点并不依赖固定的文件夹名称，只需要把 Bridge 模型放进你实际安装的节点目录中的 models 文件夹即可。

例如：

ComfyUI/custom_nodes/BUNNY_H3_Conditioning_Bridge/models/

或者：

ComfyUI/custom_nodes/bunny-h3-semantic-bridge/models/

Both are valid. 两种都可以。

🔌 Connection

🔌 节点连接

Insert the Bridge into the existing H3 CONDITIONING path.
把 Bridge 插入现有 H3 的 CONDITIONING 线路中间。

H3 Conditioning
      │
      ▼
BUNNY H3 Conditioning Bridge
      │
      ▼
Original downstream node
原来的下游节点

The Bridge input and output are both CONDITIONING.
Bridge 的输入和输出都是 CONDITIONING。

---

🎛️ Recommended settings

🎛️ 推荐参数

adapter = BUNNY_H3_ActionLogic_Bridge_V1.safetensors

alpha = 0.10 ~ 0.15

magnitude_match = per_token

enabled = true

Higher alpha is not always better.
alpha 并不是越高越好。

---

🆙 What changed from the original project?

🆙 相比原项目做了什么改进？

BUNNY H3 Semantic Bridge V1 is based on the research direction opened by speach1sdef178 / MiniMax-H3-Semantic-Bridge.
BUNNY H3 Semantic Bridge V1 基于 speach1sdef178 / MiniMax-H3-Semantic-Bridge 开放的研究方向继续开发。

The original project explored broad semantic enhancement such as composition, spatial relationships, counting, materials, reflection, transparency and occlusion.
原项目主要探索构图、空间关系、数量、材质、反射、透明、遮挡等更广泛的语义增强。

BUNNY V1 shifts the focus toward high-dynamic action logic and complex multi-character scenes.
BUNNY V1 则进一步把重点转向 高动态动作逻辑和复杂多人场景。

Main changes

主要改进

1. Action-focused training and testing
1. 更专注动作语义

More emphasis was placed on character identity, action ownership, target relationships, position changes, state continuation and environment continuity.
训练与测试更强调人物身份、动作归属、目标关系、换位、状态继承和环境连续性。

2. Additional Action Logic layer screening
2. 增加 Action Logic 层筛选

One BUNNY screening stage evaluated:

576 training pairs
144 validation pairs
30 SenseNova → H3 layer combinations

一次 BUNNY 筛选阶段测试了：

576 组训练 Pair
144 组验证 Pair
30 组 SenseNova → H3 层组合

This was used to find mappings that worked better for action relationships instead of directly using one fixed representation mapping.
这一步用于寻找更适合动作关系的映射，而不是直接固定使用一组表示层。

3. Practical ComfyUI runtime
3. 面向实际 ComfyUI 工作流

The final Bridge can be inserted directly into an existing H3 conditioning path and adjusted with a small residual strength.
最终 Bridge 可以直接插入现有 H3 Conditioning 线路，并通过小幅残差强度进行调整。

During training, SenseNova U1.5 was used as the external semantic teacher.
训练阶段使用 SenseNova U1.5 作为外部语义 Teacher。

Original project:
原项目：

https://huggingface.co/speach1sdef178/MiniMax-H3-Semantic-Bridge

---

🎬 Comparison Videos

🎬 对比视频

The following are merged A/B comparisons.
下面均为已经合并好的 A/B 对比视频。

---

🎬 01 — Character/action ownership & spatial continuity

🎬 01 —— 人物动作归属与空间连续性

This example shows correction of character/action ownership errors and spatial continuity errors.
这个案例主要展示人物动作归属错误与空间连续性错误的修复。

🎬 Showcase

---

🎬 02 — 1 vs 4 multi-character scene

🎬 02 —— 1 对 4 复杂多人场景

Five characters have different clothing features while continuously moving and interacting.
五个人物拥有不同服装特征，同时持续移动和发生交互。

The Bridge helps H3 keep character relationships and action ownership more stable in the crowded scene.
Bridge 可以帮助 H3 在复杂多人场景里更稳定地保持人物关系和动作归属。

🎬 Showcase

---

🎬 03 — Prompt following & environment stability

🎬 03 —— 提示词遵循与环境稳定性

This example focuses on prompt adherence and sudden environment errors during action.
这个案例主要展示动作过程中提示词遵循度和环境突然出错的问题。

The Bridge helps H3 preserve the intended scene logic instead of only improving the visible motion itself.
Bridge 更偏向帮助 H3 保持原本的场景逻辑，而不仅仅是改善表面的动作效果。

🎬 Showcase

---

🔍 Semantic Bridge vs Motion Continuity Repair

🔍 Semantic Bridge 和动作修复的区别

These two tools solve different problems.
这两个工具解决的是不同层面的问题。

Tool	Main purpose
Motion Continuity Repair	Smoother motion, clearer high-speed movement, better action continuity
Semantic Bridge V1	Character/action ownership, spatial logic, state continuity, prompt following and environment relationships

工具	主要作用
动作连续性修复	动作更流畅、高速动作更清楚、动作衔接更完整
Semantic Bridge V1	人物动作归属、空间逻辑、状态连续性、提示词遵循和环境关系

In simple terms:
简单来说：

Motion Continuity Repair
→ makes the action move better

动作连续性修复
→ 让动作本身动得更好

Semantic Bridge V1
→ helps H3 better understand who is doing what
→ and how the scene relationships should continue

Semantic Bridge V1
→ 帮助 H3 更好地理解谁在做什么
→ 以及场景关系应该如何继续

They can be used together.
两者可以一起使用。

---

📊 Current test results

📊 当前测试结果

In my current tests:
在目前的实际测试中：

• ~60% — different levels of repair or improvement
  约 60% —— 出现不同程度的修复或增益

• ~20% — no obvious difference
  约 20% —— 没有明显差别

• ~10% — new errors or regressions
  约 10% —— 出现新的错误或退化

These are approximate observations from my own tests, not a formal benchmark.
这些是实际测试中的近似观察，不是正式 Benchmark。

---

🙏 Credits

🙏 致谢

Special thanks to speach1sdef178 / MiniMax-H3-Semantic-Bridge for publicly sharing the original research direction, code, datasets and experiments.
特别感谢 speach1sdef178 / MiniMax-H3-Semantic-Bridge 公开原始研究方向、代码、数据集和实验过程。

Original project:
原项目：

https://huggingface.co/speach1sdef178/MiniMax-H3-Semantic-Bridge

---

FourBunny / JOKER141