docs: add zhmd v2.4.6 release notes and update Chinese README
This commit is contained in:
ussoewwin
+6
-2
@@ -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) 获取完整说明
|
||||
|
||||
|
||||
+112
@@ -0,0 +1,112 @@
|
||||
<table align="center">
|
||||
<tr>
|
||||
<td align="center" bgcolor="#e5e7eb" width="88" height="36"><a href="https://github.com/ussoewwin/ComfyUI-QwenImageLoraLoader/blob/main/md/QWEN_IMAGE_APPLY_ROTARY_EMB_COMPAT_FIX.md"><font color="#4b5563"><b>EN</b></font></a></td>
|
||||
<td align="center" bgcolor="#d4465e" width="88" height="36"><font color="#ffffff"><b>中文</b></font></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 概述
|
||||
|
||||
修复 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` 更新 |
|
||||
Reference in New Issue
Block a user