训练报错不可怕，多数问题有固定解法。本篇按"症状 → 原因 → 处理"整理 AI Toolkit 最常见的几类错误，先查这里再折腾。
1. Dataset 为空 / 找不到
症状：New Job 里 Target Dataset 下拉为空，或创建任务时报"数据集为空"。
原因与处理：
- Datasets 页没上传成功 → 回到 Datasets 页看图片计数是否为 0；确认图片是 jpg/jpeg/png、caption 是同名 .txt
- JSONL 格式问题 → 检查数据集文件是否为受支持格式（图片+txt 文件夹模式最稳）
- 先建数据集、再回来 New Job，下拉才会出现条目
2. Hugging Face 下载错误（GatedRepoError / 401）
症状：下载模型时报 GatedRepoError 或 401 / 403。
原因：模型是 gated 门控模型（FLUX.1/FLUX.2、Krea 2 等），你没有授权或没配令牌。
处理（两步缺一不可）：
- 浏览器打开模型页（如
black-forest-labs/FLUX.2-dev），点"同意并接受许可协议" - 生成 Read 令牌并配置：
huggingface-cli login粘贴令牌，或在 Settings 里填入 HF Token
开源模型（Z-Image Turbo 等）不会遇到此问题；新手建议先用开源模型跑通。
3. CUDA 显存不足（OOM）
症状：CUDA out of memory，训练或采样时崩溃。
处理阶梯（按顺序试，先易后难）：
- 降 bucket/分辨率：1024 → 896 → 768；去掉高分辨率桶
- 降 rank：32 → 16 → 8
- 开 Low VRAM、更激进量化（qfloat8 → 6/4 bit）
- 降 batch size / 采样频率与采样尺寸（采样往往也是显存大头）
- 减少控制流/关掉非必要缓存；还不行就上云（RunComfy H100/H200）
4. 过拟合 / 泄漏
症状：训练后期"只会复读训练图"；或不触发 trigger 也生成训练主体。
处理：
- 过拟合：换更早的 checkpoint；降低 steps；降 rank；略增 weight decay
- 泄漏：开启 DOP（Differential Output Preservation），并准备正则数据集（caption 不含 trigger）
5. 训练几百上千步"没变化"
症状：采样图一直和基线差不多，LoRA 似乎没生效。
处理：
- 确认采样时真的加载了 LoRA（UI 或 CLI 的 sample 配置里）
- rank 太低（< 8）可以先到 16–32
- learning rate 确认是 1e-4 级别（不是被清成 1e-5 或 0）
- caption 太笼统 → 检查描述是否覆盖了要学的特征；风格 LoRA 别在 caption 里写风格词
6. LoRA "覆盖"了基础模型
症状：激活 LoRA 后基础模型原本的能力（多样性、其他风格）全没了。
处理：
- 开启 DOP（保留基础行为）
- 减少步数（如 800–1500）
- 降 rank（16）并微降 lr（如 0.000075）
7. 采样相关问题
| 症状 | 原因 | 处理 |
|---|---|---|
| 生成分辨率不对 | 分辨率按模型取整（如 16/32 倍数） | 生成时用训练分辨率范围，不必纠结个别像素 |
| 少步数模型 negative 无效 | turbo 类模型 CFG=1 时无条件通道被跳过 | 这是正常行为；用正 prompt 控制 |
| 采样很慢/爆显存 | 采样配置与训练配置差距大 | 减小采样宽高、降低采样频率 |
8. 环境与安装问题
| 症状 | 原因 | 处理 |
|---|---|---|
| torch/CUDA 版本报错 | PyTorch 与驱动/CUDA 不匹配 | 按官方 README 安装匹配版本（如 cu130 系列） |
| Windows 安装失败 | 依赖编译问题 | 用 AI-Toolkit-Easy-Install 一键脚本 |
| 8675 打不开 | UI 未启动 / 端口占用 | 确认 npm run build_and_start 跑完；换端口排查占用 |
| 远程访问被拦截 | 无访问令牌 | 设置 AI_TOOLKIT_AUTH |
9. 网络问题（HF 下载慢/失败）
- 设置镜像：
HF_ENDPOINT=https://hf-mirror.com - 或手动下载模型放到本地，配置里用本地路径
- push_to_hub 上传失败：确认已登录且目标仓库可写
占位图
演示图占位
此处放：一次典型报错（如 CUDA OOM）的日志截图
说明：红字部分即定位关键词，对照上文处理
下一步
入门教程到此结束。接下来进入具体模型配方：
- 低显存/新手首选 → 《AI Toolkit 训练 Z-Image Turbo LoRA》
- 旗舰级 → 《AI Toolkit 训练 FLUX.2 [dev] LoRA》