TE keys missing

快速结论：这个报错通常出现在 Kohya SS v25 及以上版本默认把 LoRA 训练模式静默设为 UNet-only（不训练 Text Encoder）之后，导致保存的 safetensors 里完全没有 TE keys，表现为 SDXL 角色 LoRA 学不到身份特征、脸部变得通用、细节丢失。优先检查 LoRA 页的 Text Encoder learning rate 是否为 0。

适用环境：Kohya SS GUI（LoRA 标签页）；受影响的版本为 v25.0.0 及以后（v24.x 默认行为不同）；用户在 Linux、Windows 以及 Docker 中均复现过。Issue 未提供具体的 Python、CUDA、PyTorch、显卡型号或 sd-scripts 版本。

最快修复方案：把 LoRA 标签页中的 Text Encoder learning rate 从默认的 0 改为与 Unet learning rate 同量级的非零值（例如 0.0001），重新训练后检查 safetensors 中是否出现 TE keys。

注意事项：该处理来自 Issue triage 中对默认值变更的分析（对比 #3430），并非维护者已在代码中合入的修复；如果你确实想只训练 UNet，把 TE LR 设为 0 仍是有效的 UNet-only 入口。修改默认值后，仍需自行确认训练日志和输出文件，因为 Issue 指出训练过程中不会有报错提示。

问题场景

用户在 Kohya SS 中训练 SDXL LoRA。升级到新版后，新训练出来的 safetensors 突然完全不含 TE（Text Encoder）keys，而日志里没有任何关于 text encoder 的报错，看起来训练一切正常。用户对比了旧的、正常的 LoRA，旧的 LoRA 包含预期数量的 TE keys。该问题在 Linux、Windows 和 Docker 环境中都出现过，并且不止一个分支受影响，因此用户怀疑是某个依赖变化导致。

报错原文

TE keys missing

The safetensors-files suddenly completely lack any TE-keys, despite the fact that nothing in the logs indicates a problem with the text encoders.

No error is raised during training; the run appears to complete successfully.

原因分析

根据 Issue 的处理摘要，根因不在依赖，而在于 Kohya SS 版本间的默认值变更：

v24.x 中，LoRA 标签页的 Text Encoder learning rate 默认为 0.0001，与 Unet learning rate 同量级，默认同时训练 UNet 和 Text Encoder 两侧的 LoRA 模块。
v25.0.0+ 中，Text Encoder learning rate 默认变为 0，而 Unet learning rate 仍为 0.0001。
训练配置会据此推导：TE LR 为 0 且 Unet LR 非零时设置 network_train_unet_only；TE LR 非零且 Unet LR 为 0 时设置 network_train_text_encoder_only。
因此在全新默认配置下，每次 LoRA 训练都会变成 UNet-only，保存出的 safetensors 自然不含 TE keys，且不会有任何报错或警告。

用户报告的身份保持变差、脸部通用化、细节学习退化，正是 TE 训练被静默关闭后的结果。Issue 摘要也指出该根因与 #3430（“Huge difference in Lora training quality VS version 24.x”）相同：两者配置的唯一实质性差异就是 text_encoder_lr（可用的旧配置为 0.0001，出问题的配置为 0）。

需要说明的是，UNet-only 训练本身是合法模式，部分 SDXL 指导也会建议只训练 UNet 以规避双 Text Encoder 的副作用。这里的问题是模式切换是静默的、默认值在跨大版本时翻转，而界面没有给出明确提示。上述属于 Issue triage 的分析结论，尚无证据表明维护者已按“期望行为”全部实现。

环境排查

确认 Kohya SS 版本：是 v24.x 还是 v25.0.0 及以上。默认值翻转发生在 v25.0.0 之后。
检查 LoRA 标签页中 Text Encoder learning rate 的实际值：是 0 还是非零（v24 风格为 0.0001）。
检查 Unet learning rate 的值（默认 0.0001），以及是否存在主 learning rate 回退逻辑。
查看生成的训练配置中这些键的实际取值：network_train_unet_only、network_train_text_encoder_only、text_encoder_lr、unet_lr。
检查输出 safetensors 是否包含 TE keys，并与旧的可正常工作 LoRA 对比。
确认是否使用了 --network_train_unet_only，或模型特定的强制 UNet-only 标记（例如摘要中提到的 HunyuanImage UNet-only）。
Issue 未给出 Python、CUDA、PyTorch 或显卡版本，这些项目暂不作为排查依据。

解决步骤

打开 Kohya SS 的 LoRA 标签页，定位 Text Encoder learning rate 输入框。
如果该值为 0，将其改为非零值，与 Unet learning rate 保持一致（例如 0.0001）。这是恢复 v24 风格“同时训练 UNet 和 TE”的可优先尝试做法。
如果你确实只想要 UNet-only（部分 SDXL 工作流如此），保持 TE LR 为 0 即可，这是保留的 UNet-only 入口；但要清楚此时输出不会有 TE keys。
训练前检查将要写入 sd-scripts 的配置：TE LR 与 Unet LR 均非零时，不应设置 network_train_unet_only。
启动训练，确认日志中有明确的训练模式信息；Issue 期望增加训练模式与“UNet-only 意味着无 TE keys”的可见提示，但该 UX 改动是否已合入需以你拿到的版本为准。
训练完成后检查输出的 safetensors，确认包含 TE keys。

验证方法

用同一份 SDXL 角色数据集和与旧版本（可用配置的）等价的配置重新训练，其中 text_encoder_lr 为非零值。训练结束后检查 safetensors 是否出现 TE keys，且模型未落入 network_train_unet_only。若 TE keys 重新出现、身份保持与细节表现恢复到旧配置水平，则说明默认值问题已被绕过；Issue 中 #3430 的验证路径也与此一致。