AWPortrait-Z WebUI日志体系：启动日志/生成日志/错误日志三级分类
AWPortrait-Z 基于Z-Image精心构建的人像美化LoRA 二次开发webui构建by科哥
AWPortrait-Z 基于Z-Image精心构建的人像美化LoRA 二次开发webui构建by科哥
在实际使用中，很多用户反馈“不知道模型到底卡在哪”“生成失败了但看不到原因”“重启后参数配置全丢了”，这些问题背后往往不是功能缺陷，而是日志信息缺失或组织混乱。AWPortrait-Z 的日志体系不是简单堆砌输出，而是围绕人像生成工作流，设计了一套清晰、可追溯、可调试的三级日志结构：启动日志记录环境就绪状态，生成日志沉淀每次创作过程，错误日志精准定位故障根因。这套体系让调试不再靠猜，复现不再靠试，优化不再靠蒙。
1. 日志体系设计原则：为真实使用而生
AWPortrait-Z 的日志不是工程师的自留地，而是给每一位使用者准备的“操作回放器”和“问题诊断仪”。它不追求技术炫技，只解决三类最常遇到的困惑：
- “我点下去了，它动没动？”→ 启动日志告诉你服务是否真正就绪
- “这张图是怎么出来的？”→ 生成日志完整还原提示词、参数、种子、耗时等关键事实
- “为什么这张图崩了？”→ 错误日志直接指出是显存不足、LoRA加载失败，还是提示词语法错误
所有日志均采用纯文本格式，按功能分离、按时间排序、按级别着色（终端中自动高亮），无需额外工具即可快速阅读。更重要的是，每条日志都自带上下文锚点——比如生成日志里会明确标注“本次生成对应历史记录第7项”，点击历史缩略图就能跳转查看原始参数，真正实现日志与界面的双向联动。
2. 启动日志：服务就绪的权威凭证
启动日志是整个WebUI的生命起点，它不只告诉你“程序跑起来了”，更告诉你“它是在什么条件下跑起来的”。当你执行./start_app.sh或python3 start_webui.py后，系统会在/root/AWPortrait-Z/logs/目录下生成webui_startup.log文件，并实时输出到控制台。
2.1 启动日志核心内容
启动日志严格按初始化顺序输出，共包含5个关键阶段，每阶段以分隔线和时间戳标识：
[2024-06-08 14:22:31] ──────────────────────────────── [2024-06-08 14:22:31] 环境检查阶段 [2024-06-08 14:22:31] • Python 版本: 3.10.12 ( 满足 ≥3.9) [2024-06-08 14:22:31] • CUDA 可用: True ( v12.1) [2024-06-08 14:22:31] • GPU 显存: 24.2 GB ( ≥12 GB 推荐) [2024-06-08 14:22:31] • 模型路径存在: /root/AWPortrait-Z/models/Z-Image-Turbo.safetensors () [2024-06-08 14:22:31] • LoRA 路径存在: /root/AWPortrait-Z/lora/AWPortrait-Z.safetensors ()[2024-06-08 14:22:45] ──────────────────────────────── [2024-06-08 14:22:45] ⚙ 模型加载阶段 [2024-06-08 14:22:45] • 加载基础模型: Z-Image-Turbo.safetensors (耗时 8.2s) [2024-06-08 14:22:47] • 加载 LoRA 权重: AWPortrait-Z.safetensors (强度 1.0) (耗时 2.1s) [2024-06-08 14:22:47] • LoRA 验证通过: 人像皮肤纹理层、光影增强层、发丝细节层全部激活 ()[2024-06-08 14:22:52] ──────────────────────────────── [2024-06-08 14:22:52] WebUI 初始化阶段 [2024-06-08 14:22:52] • Gradio 版本: 4.32.0 [2024-06-08 14:22:52] • 监听地址: http://0.0.0.0:7860 [2024-06-08 14:22:52] • 启动模式: --no-gradio-queue --enable-insecure-extension-access[2024-06-08 14:22:53] ──────────────────────────────── [2024-06-08 14:22:53] 预设加载阶段 [2024-06-08 14:22:53] • 写实人像预设: 已加载 (1024x1024, 8步, 引导0.0) [2024-06-08 14:22:53] • 动漫风格预设: 已加载 (1024x768, 12步, 引导3.5) [2024-06-08 14:22:53] • 油画风格预设: 已加载 (1024x1024, 15步, 引导5.0)[2024-06-08 14:22:54] ──────────────────────────────── [2024-06-08 14:22:54] 启动完成！ [2024-06-08 14:22:54] • WebUI 地址: http://localhost:7860 [2024-06-08 14:22:54] • 日志文件: /root/AWPortrait-Z/logs/webui_startup.log [2024-06-08 14:22:54] • 生成日志目录: /root/AWPortrait-Z/logs/generation/ [2024-06-08 14:22:54] • 错误日志目录: /root/AWPortrait-Z/logs/error/2.2 启动失败的典型日志与应对
当启动失败时，日志不会沉默，而是给出可执行的修复路径。例如：
[2024-06-08 14:18:22] LoRA 加载失败：/root/AWPortrait-Z/lora/AWPortrait-Z.safetensors 文件损坏 [2024-06-08 14:18:22] • 建议操作： 1. 进入 lora/ 目录，执行 md5sum AWPortrait-Z.safetensors 核对校验值 2. 若校验失败，请重新下载 LoRA 文件 3. 或临时禁用 LoRA：在 start_webui.py 中将 load_lora=True 改为 False再如显存不足提示：
[2024-06-08 14:15:11] GPU 显存不足：检测到 10.4 GB，低于推荐值 12 GB [2024-06-08 14:15:11] • 自动降级方案已启用： - 默认分辨率从 1024x1024 降至 768x768 - 批量生成上限从 8 张降至 2 张 - 启动时添加 --medvram 参数这些提示不是报错代码，而是带解决方案的操作指南，让非技术人员也能快速恢复服务。
3. 生成日志：每一次创作的数字档案
生成日志是AWPortrait-Z最具价值的日志类型。它不只记录“成功”或“失败”，而是把一次人像生成当作一个完整的创作事件来存档。每次点击“生成图像”按钮，系统都会在/root/AWPortrait-Z/logs/generation/下创建一个以时间戳命名的.jsonl文件（如20240608_143022.jsonl），其中每行是一次独立生成的完整快照。
3.1 生成日志结构解析
一条典型的生成日志（JSON Lines格式）如下所示，字段全部采用自然语言命名，无需解码即可理解：
{ "timestamp": "2024-06-08T14:30:22.184Z", "history_id": 7, "prompt": "a young woman, professional portrait photo, realistic, detailed, soft lighting, natural skin texture", "negative_prompt": "blurry, low quality, distorted, ugly, deformed", "width": 1024, "height": 1024, "steps": 8, "cfg_scale": 0.0, "seed": 123456789, "lora_strength": 1.0, "model_name": "Z-Image-Turbo.safetensors", "lora_name": "AWPortrait-Z.safetensors", "output_path": "/root/AWPortrait-Z/outputs/20240608/143022-0001.png", "elapsed_time_ms": 4280, "device": "cuda:0", "gpu_memory_used_gb": 18.3 }关键字段说明：
history_id：该记录在历史面板中的序号，点击历史缩略图即可反查此日志prompt/negative_prompt：原样保存输入内容，包括标点、空格、换行，确保复现零偏差elapsed_time_ms：精确到毫秒的端到端耗时，不含网络传输，是真实的GPU计算时间gpu_memory_used_gb：生成峰值显存占用，帮你判断是否可提升批量数量或分辨率
3.2 生成日志的实用场景
- 参数复现：复制
prompt、seed、lora_strength等字段，粘贴回WebUI对应输入框，100%复现结果 - 效果归因：对比两张相似但质量不同的图，发现
steps从8升到12后elapsed_time_ms增加1200ms，但皮肤纹理细节提升显著，从而确认“多花1.2秒换更好质感”值得 - 硬件评估：连续生成10次，取
gpu_memory_used_gb平均值，若稳定在20.1±0.3GB，说明当前GPU已接近满载，不宜再增加批量数 - 流程审计：导出所有
.jsonl文件，用Excel打开，按elapsed_time_ms排序，找出最耗时的5次生成，针对性优化其提示词（如删减冗余描述词）
小技巧：在终端中快速查看最新生成日志
tail -n 1 /root/AWPortrait-Z/logs/generation/*.jsonl | jq '.prompt, .elapsed_time_ms'
4. 错误日志：故障定位的精准地图
错误日志不是启动失败的副产品，而是运行时所有异常的集中收容站。它被设计为“最小必要信息”原则——不堆砌堆栈，只呈现用户能看懂、能操作、能验证的三要素：发生了什么、发生在哪、现在该怎么办。
4.1 错误日志的触发机制与分级
AWPortrait-Z 将错误分为三级，对应不同严重程度和处理方式：
| 级别 | 触发条件 | 日志位置 | 用户动作 |
|---|---|---|---|
| Warning（警告） | 可继续运行但效果可能打折（如LoRA加载成功但部分层未激活） | logs/error/warning.log | 查看提示，决定是否忽略或微调参数 |
| Error（错误） | 当前生成中断，但WebUI仍可用（如提示词含非法字符、输出路径无写入权限） | logs/error/generation_error.log | 根据提示修改输入或检查权限，重试即可 |
| Critical（严重） | WebUI崩溃或核心模块失效（如CUDA内核崩溃、模型权重读取失败） | logs/error/critical.log | 必须重启服务，按日志建议检查环境 |
4.2 典型错误日志案例与解读
案例1：提示词语法错误（Error级）
[2024-06-08 15:02:18] ❗ Error: 提示词解析失败 • 文件: /root/AWPortrait-Z/start_webui.py, 行: 217 • 错误: 提示词中包含未闭合的括号 '(' • 输入片段: "a woman (in red dress, professional portrait" • 建议: - 检查所有括号是否成对出现 - 或使用引号包裹含括号的短语："(in red dress)" - 临时移除括号重试案例2：LoRA风格冲突（Warning级）
[2024-06-08 15:11:44] Warning: LoRA 风格弱化 • 检测到负面提示词含 "realistic"，与 AWPortrait-Z 的"艺术化人像"风格倾向冲突 • 当前 LoRA 强度 1.0，实际生效强度估算为 0.6 • 建议: - 移除负面提示词中的 "realistic" - 或将 LoRA 强度提升至 1.3~1.5 - 或改用 "写实人像" 预设（已内置兼容配置）案例3：CUDA内存溢出（Critical级）
[2024-06-08 15:22:01] 💥 Critical: CUDA out of memory • 设备: cuda:0, 当前显存占用: 24.2 GB / 24.2 GB • 失败操作: 执行 torch.compile() 优化步骤 • 根本原因: Z-Image-Turbo 模型 + AWPortrait-Z LoRA + 1024x1024 分辨率超出显存容量 • 立即缓解: - 在WebUI中将分辨率改为 768x768 - 或在 start_webui.py 中添加 --lowvram 参数 • 长期方案: 升级至24GB以上显存GPU，或使用量化版模型你会发现，每条错误日志都像一位经验丰富的同事在你耳边提醒，而不是一串冰冷的Python traceback。
5. 日志协同工作流：从问题到解决的闭环
AWPortrait-Z 的三级日志不是孤立存在，而是构成一个高效的协同工作流。下面以一个真实用户场景为例，展示它们如何无缝配合：
用户问题：今天生成的3张图全都是模糊的，之前明明很清晰。
第一步：查生成日志定位共性
grep '"elapsed_time_ms":' /root/AWPortrait-Z/logs/generation/20240608_*.jsonl | sort -k4 -n发现这3次的elapsed_time_ms均为1850，远低于平时的4200+，说明生成过程被异常截断。
第二步：查错误日志找根源
tail -n 20 /root/AWPortrait-Z/logs/error/generation_error.log看到：
[2024-06-08 16:45:22] ❗ Error: 生成中断 —— 检测到输出目录 /root/AWPortrait-Z/outputs/ 已满（98%） • 当前磁盘使用: 99.2 GB / 100 GB • 建议: 清理 outputs/ 目录或挂载新存储第三步：查启动日志确认影响范围
grep "outputs/" /root/AWPortrait-Z/logs/webui_startup.log确认启动时确实使用了默认输出路径，且无自定义挂载。
第四步：执行解决并验证
# 清理旧输出（保留最近3天） find /root/AWPortrait-Z/outputs/ -type d -mtime +3 -exec rm -rf {} + # 重启服务 ./start_app.sh # 生成一张测试图，检查新生成日志的 elapsed_time_ms 是否回归正常整个过程不到5分钟，没有重启服务器，没有重装依赖，仅靠日志就完成了精准诊断与修复。这就是AWPortrait-Z日志体系的设计初心：让问题可见，让路径清晰，让解决简单。
6. 日志管理最佳实践
日志的价值不在于生成，而在于可持续使用。以下是科哥团队总结的日常管理建议：
- 定期归档：每周日执行
mv /root/AWPortrait-Z/logs/* /root/AWPortrait-Z/logs/archive/$(date +%Y%m%d)/，避免单目录文件过多影响性能 - 磁盘监控：在
start_app.sh开头加入检查逻辑，若/root/AWPortrait-Z/logs/占用超90%，则自动发送微信通知（需配置微信机器人） - 敏感信息过滤：所有日志自动过滤
prompt字段中的手机号、邮箱、身份证号等正则模式，保障用户隐私 - 日志压缩：每月1日自动将上月日志打包为
generation_202405.tar.gz并删除原始文件，节省85%空间 - 跨设备同步：在
outputs/目录下放置.sync_ignore文件，阻止Gradio将日志文件上传至浏览器缓存，保证本地日志唯一可信
重要提醒：不要手动编辑任何
.log或.jsonl文件。AWPortrait-Z 的日志是只写（write-only）的审计记录，修改会导致哈希校验失败，后续生成将被拒绝写入。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
