AI Guard 扩展说明

AI Guard 是 FLYOS-FAST v1.4.0 测试版镜像预置的 Klipper 图像检测扩展，可定时读取摄像头画面并尝试识别炒面和拉丝等打印异常。

测试功能，极高打印失败风险

AI Guard 会持续获取摄像头图片并执行本地 AI 推理，明显增加 CPU、内存和存储负载。一旦系统负载过高，极大概率造成 Klipper 调度异常、MCU 通信中断或打印任务直接失败。

• 不要在正式打印、长时间打印、无人值守打印或重要模型打印时启用。
• 仅可在能够随时停止的短时测试中使用，并持续观察系统负载和 Klipper 日志。
• AI 检测可能误报或漏报，不能替代人工监控，也不能作为打印机安全保护机制。

版本和默认状态

• 仅在 FLYOS-FAST v1.4.0 测试版镜像中确认。
• 系统预置 fly_ai_guard 扩展、模型文件和 fly-ai.cfg 示例。
• 默认 printer.cfg 没有加载 fly-ai.cfg，因此 AI Guard 默认不运行。

启用前准备

1. 先确认摄像头快照地址能够返回正常图片。
2. 确认打印机当前没有执行打印任务。
3. 备份 printer.cfg 和 fly-ai.cfg。
4. 使用 top 观察未启用 AI Guard 时的系统负载，作为对比基准。

参考配置

镜像中的示例文件位于：

/usr/share/printer_data/config/fly-ai.cfg

使用 GoCam 时可参考：

[fly_ai_guard]
camera: http://127.0.0.1:8080/snapshot
cpu_affinity: 0,1,2
spaghetti_threshold: 0.5
stringing_threshold: 0.5
interval_time: 10.0
discover_count: 1
print_only: True
pause_on_discover: False
discover_gcode:
    M118 AI检测触发

参数	v1.4.0 镜像默认值	说明
camera	http://127.0.0.1/webcam/?action=snapshot	AI Guard 读取的摄像头快照地址；使用 GoCam 时改为 http://127.0.0.1:8080/snapshot
cpu_affinity	0,1,2	允许 AI 工作进程使用的 CPU 核心编号
spaghetti_threshold	0.5	炒面检测置信度阈值
stringing_threshold	0.5	拉丝检测置信度阈值
interval_time	10.0	两次检测之间的间隔，单位为秒
discover_count	1	连续命中多少次后触发异常事件
print_only	True	为 True 时仅在打印状态进行检测
pause_on_discover	False	是否在达到触发次数后暂停打印
discover_gcode	M118 AI检测触发	达到触发条件后执行的 G-code

保持保守参数

• 初次测试保持 pause_on_discover: False，避免误识别直接暂停打印。
• 不要为了提高响应速度大幅缩短 interval_time，检测越频繁，系统负载越高。
• 不要仅凭一次测试就降低检测阈值或启用自动暂停。

启用扩展

在 printer.cfg 中添加：

[include fly-ai.cfg]

保存并重新启动 Klipper。首次测试不要开始打印，先通过 SSH 运行：

top

同时查看 Klipper 日志：

tail -f /usr/share/printer_data/logs/klippy.log

如果出现持续高负载、Klipper 调度异常、MCU 失联、摄像头取图失败或 AI worker 反复重启，应立即停用 AI Guard。

停用扩展

从 printer.cfg 中删除或注释：

[include fly-ai.cfg]

然后重新启动 Klipper。仅修改 pause_on_discover 并不能关闭 AI 推理；要停止资源占用，必须停止加载整个 [fly_ai_guard] 配置段。

已知限制

• 这是 v1.4.0 测试版功能，识别准确率和长期稳定性尚未完成验证。
• 推理负载会与 KlipperScreen、摄像头、延迟摄影、远程代理及其他插件叠加。
• 摄像头无信号、快照地址错误或网络取图超时会影响检测。
• 当前示例没有默认启用自动暂停，启用后仍可能因误报中断正常打印。
• 系统负载过高时，AI Guard 本身及打印控制都可能失效。