From a2bb565f5d099869bd7abc476d5691f63b816ffc Mon Sep 17 00:00:00 2001 From: ussoewwin <136552381+ussoewwin@users.noreply.github.com> Date: Wed, 10 Jun 2026 19:54:13 +0900 Subject: [PATCH] docs: add zhmd v2.4.6 release notes and update Chinese README --- zhmd/README.md | 8 +++- zhmd/v2.4.6.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+), 2 deletions(-) create mode 100644 zhmd/v2.4.6.md diff --git a/zhmd/README.md b/zhmd/README.md index 38eab08..ebbf965 100644 --- a/zhmd/README.md +++ b/zhmd/README.md @@ -13,7 +13,7 @@ **目前正在开发和测试中。正在大量输出调试日志。这不影响功能。** -> 最新版本: [v2.4.5 on GitHub Releases](https://github.com/ussoewwin/ComfyUI-QwenImageLoraLoader/releases/tag/v2.4.5) +> 最新版本: [v2.4.6 on GitHub Releases](https://github.com/ussoewwin/ComfyUI-QwenImageLoraLoader/releases/tag/v2.4.6) > ## 来源 @@ -224,7 +224,11 @@ ComfyUI\python_embeded\python.exe -m pip install --upgrade diffusers ## 更新日志 -### v2.4.5 (最新) +### v2.4.6 (最新) +- **已修复**: ComfyUI **0.24.x** 启动时 **ComfyUI-nunchaku** 导入 Qwen Image 节点失败的问题（`ImportError: cannot import name 'apply_rotary_emb' from 'comfy.ldm.qwen_image.model'`）。通过本自定义节点的早期 `prestartup_script.py` 垫片，将 `apply_rotary_emb` 别名为 ComfyUI 的 `apply_rope1`（无需修改 ComfyUI-nunchaku 文件）。 +- **技术详情**: 请参阅 [v2.4.6 发行说明](v2.4.6.md) 获取完整说明 + +### v2.4.5 - **已添加**: 在 `zhmd/` 目录下新增中文文档页面（README 与发行说明），并在英文与中文 README 及发行说明页面提供双语语言切换。 - **技术详情**: 请参阅 [v2.4.5 发行说明](v2.4.5.md) 获取完整说明 diff --git a/zhmd/v2.4.6.md b/zhmd/v2.4.6.md new file mode 100644 index 0000000..65c0666 --- /dev/null +++ b/zhmd/v2.4.6.md @@ -0,0 +1,112 @@ + + + + + +
EN中文
+ +## 概述 + +修复 ComfyUI **0.24.x** 启动时 **ComfyUI-nunchaku** 导入 Qwen Image 节点失败的问题（`ImportError: cannot import name 'apply_rotary_emb' from 'comfy.ldm.qwen_image.model'`）。通过本自定义节点的早期 `prestartup_script.py` 提供**条件性、对上游安全的兼容垫片**，将缺失的 `apply_rotary_emb` 别名为 ComfyUI 的 `apply_rope1`。**不修改 ComfyUI-nunchaku 源文件**；上游恢复符号或 nunchaku 停止导入后，垫片自动停用。 + +--- + +## 问题症状 + +ComfyUI 启动时，nunchaku 在加载 Qwen Image 节点时失败： + +```text +ImportError: cannot import name 'apply_rotary_emb' from 'comfy.ldm.qwen_image.model' +``` + +典型导入链： + +```text +ComfyUI-nunchaku/__init__.py + → nodes/models/qwenimage.py + → models/qwenimage.py + → from comfy.ldm.qwen_image.model import (..., apply_rotary_emb,) +``` + +--- + +## 根本原因 + +| 组件 | 情况 | +|------|------| +| ComfyUI 0.24.x | `comfy.ldm.qwen_image.model` 中已移除 `apply_rotary_emb`，改用 `comfy.ldm.flux.math.apply_rope1` | +| ComfyUI-nunchaku（受影响版本） | 仍从 `comfy.ldm.qwen_image.model` 导入 `apply_rotary_emb` | + +此外，自定义节点按目录名排序加载；在 Windows 上 **ComfyUI-nunchaku** 通常排在 **ComfyUI-QwenImageLoraLoader** 之前，因此仅靠 `__init__.py` 补丁为时已晚。`prestartup_script.py` 在 `init_custom_nodes()` 之前运行，可在 nunchaku 导入前注入符号。 + +--- + +## 本版本的修复方式 + +### 修改的文件 + +- `prestartup_script.py` — ComfyUI 启动早期加载 `patches/nunchaku_patch.py` 并调用兼容逻辑 +- `patches/nunchaku_patch.py` — 条件性注入 `apply_rotary_emb`（带 `_qwen_lora_loader_rotary_shim` 标记，避免重复覆盖） + +### 决策逻辑（摘要） + +| 条件 | 行为 | +|------|------| +| 环境变量 `QWENIMAGE_ROTARY_COMPAT` 为 `0` / `false` / `no` / `off` / `disable` / `disabled` | **跳过**（手动关闭） | +| 模块上已有本节点的标记垫片 | **跳过**（幂等） | +| ComfyUI 已提供**原生** `apply_rotary_emb`（非本垫片） | **跳过** — 不覆盖上游 | +| `ComfyUI-nunchaku/models/qwenimage.py` **不再**导入 `apply_rotary_emb` | **跳过** — nunchaku 已修复 | +| 符号仍缺失且 nunchaku 仍导入（或找不到 `qwenimage.py`） | **应用** — `apply_rotary_emb = apply_rope1` | + +### 成功时的日志示例 + +垫片生效时： + +```text +[INFO] Patched comfy.ldm.qwen_image.model.apply_rotary_emb -> apply_rope1 (ComfyUI-nunchaku Qwen Image compat) +[INFO] ComfyUI-QwenImageLoraLoader prestartup: apply_rotary_emb compat applied +``` + +上游已修复而自动跳过时： + +```text +[INFO] apply_rotary_emb compat skipped: ComfyUI already exports apply_rotary_emb +``` + +或 + +```text +[INFO] apply_rotary_emb compat skipped: ComfyUI-nunchaku no longer imports apply_rotary_emb +``` + +手动关闭时： + +```text +[INFO] apply_rotary_emb compat skipped (QWENIMAGE_ROTARY_COMPAT is disabled) +``` + +--- + +## 升级说明 + +1. 将 **ComfyUI-QwenImageLoraLoader** 更新至 **v2.4.6** 或更高版本（`git pull` 或 ComfyUI Manager）。 +2. **重启 ComfyUI**（`prestartup_script.py` 仅在启动时运行）。 +3. 若需禁用垫片，启动前设置：`QWENIMAGE_ROTARY_COMPAT=0`。 +4. **无需**编辑 `ComfyUI-nunchaku` 内任何文件。 + +--- + +## 完整技术说明 + +英文完整说明（含完整补丁代码与验证步骤）请参阅： + +- [md/QWEN_IMAGE_APPLY_ROTARY_EMB_COMPAT_FIX.md](../md/QWEN_IMAGE_APPLY_ROTARY_EMB_COMPAT_FIX.md) + +--- + +## 本版本包含的提交（相对 v2.4.5） + +| 提交 | 说明 | +|------|------| +| `b3539cf` | v2.4.6 — 条件性 `apply_rotary_emb` 兼容垫片（`prestartup_script.py` + `patches/nunchaku_patch.py`） | +| `1eb6798` | 英文技术文档 `md/QWEN_IMAGE_APPLY_ROTARY_EMB_COMPAT_FIX.md` 更新 |