ScreenFilter 智能助手：低代码构建屏幕内容分析工作流

• 上方会显示画有红色检测框的结果图片。
• 下方会显示一个可折叠的文本框，里面就是完整的 JSON 结果。点击它可以查看详细内容，你会看到类似下面的结构：

{
  "model_path": "/root/ai-models/best.pt",
  "type": "image",
  "count": 2,
  "class_count": {"laptop": 1, "monitor": 1},
  "boxes": [
    {
      "frame": 0,
      "class_id": 0,
      "class_name": "laptop",
      "confidence": 0.92,
      "xyxy": [255, 120, 800, 700]
    }
  ]
}

恭喜！你已经成功完成了第一次 AI 视觉分析。JSON 里的 class_name 告诉你发现了什么（如'laptop'），confidence 告诉你 AI 有多确信（0.92 表示 92% 的把握），xyxy 则标出了它的具体位置。

进阶操作：分析一段视频

理解了图片检测，视频检测就是水到渠成。

1. 切换模式：点击顶部切换到 '视频检测' 选项卡。
2. 上传视频：上传一段短视频（建议先用 10-30 秒的短片测试，快速验证效果）。
3. 开始检测：点击 '开始视频检测' 按钮。视频检测需要逐帧处理，耗时比图片长，请耐心等待进度条完成。
4. 获取结果：处理完成后，右侧会提供结果视频的下载链接，以及一份更详细的 JSON 报告。视频报告里会多出 total_frames（总帧数）、processed_frames（已处理帧数）等全局字段。

一个贴心提示：为了保障服务稳定，视频处理默认限制在 60 秒以内。如果你的视频超长，系统只会处理前 60 秒。这对于大多数抽样分析和功能验证来说，已经足够了。

核心参数调优：像老师批卷一样调整 AI

用过几次后，你可能会想：有时候 AI'疑神疑鬼'（误检），把不是屏幕的东西也框出来；有时候又'粗心大意'（漏检），明明有个小手机屏幕却没发现。这时，就需要调整两个关键'旋钮'。

理解两个关键参数

• 置信度阈值 (Confidence Threshold)：你可以把它理解为 'AI 判断的及格分数线' 。分数高于这个阈值的目标，AI 才认为是有效的。默认是 0.25（25 分）。
  • 调低（如 0.15）：相当于降低及格线，更多'疑似目标'会被报告出来，减少漏检，但可能增加误检。
  • 调高（如 0.5）：相当于提高及格线，只有非常确定的目标才会被报告，减少误检，但可能增加漏检。
• NMS IOU 阈值 (IOU Threshold)：当同一个物体被预测出多个重叠的框时，这个参数决定 '如何取舍' 。IOU 衡量两个框的重叠程度。默认 0.45。
  • 调低：标准更严格，重叠较多的框才会被合并，可能保留更多框。
  • 调高：标准更宽松，更容易合并重叠框，使结果更干净。

如何调整：对症下药

记住以下口诀，轻松应对大多数情况：

1. 情况：画面中很多明显是屏幕的物体没被检测到（漏检多）。
   • 操作：适当调低'置信度阈值'，比如从 0.25 调到 0.2 甚至 0.15，让 AI 变得更'敏感'。
2. 情况：AI 把窗户、相框等不是屏幕的物体也框出来了（误检多）。
   • 操作：适当调高'置信度阈值'，比如调到 0.35 或 0.45，让 AI 变得更'谨慎'。
3. 情况：同一个物体周围出现了很多个重叠的框，看起来不整洁。
   • 操作：可以尝试微调'IOU 阈值'，比如从 0.45 调到 0.5，让框的合并更积极。

最佳实践是：从默认参数（0.25，0.45）开始测试，根据测试结果，每次只调整一个参数（置信度或 IOU），小幅度变化（0.05 步进），观察效果，找到最适合你当前场景的'甜点'。

结果解读与二次利用：让数据流动起来

这个工具最大的价值之一，是输出结构化的 JSON 数据。这意味着结果不是一张'死'的图片，而是可以被其他程序理解和处理的'活'数据。

JSON 字段详解

我们结合一个实例来解读核心字段：

{
  "model_path": "/root/ai-models/xlangai/VideoAgentTrek-ScreenFilter/best.pt",
  "type": "video",
  "count": 150,
  "class_count": {"monitor": 89, "cell phone": 42, "laptop": 19},
  "boxes": [
    {
      "frame": 30,
      "class_id": 1,
      "class_name": "cell phone",
      "confidence": 0.87,
      "xyxy": [100, 200, 180, 300]
    }
  ]
}

• type: 告诉你这是图片 (image) 还是视频 (video) 的分析结果。
• count: 总共检测到多少个目标实例。上例中，整个视频里所有框加起来有 150 个。
• class_count: 按类别统计的次数，这是非常有用的汇总信息。上例告诉我们，视频里'显示器'出现了 89 次，'手机'出现了 42 次，'笔记本电脑'出现了 19 次。你可以快速知道哪些屏幕设备是主角。
• boxes: 所有检测框的明细列表。每个框包含：
  • frame: 出现在第几帧（图片默认为 0）。这是做视频分析的关键，你可以定位到具体时间点。
  • class_name: 目标是什么。
  • confidence: 置信度，用于过滤低质量结果。
  • xyxy: 框的坐标 [左上角 x, 左上角 y, 右下角 x, 右下角 y]，可用于裁剪或精确定位。

构建你的自动化工作流

有了这些结构化数据，你可以轻松地将其融入自己的系统：

• 场景 2：会议室使用情况统计 分析会议室监控视频，统计每天'笔记本电脑'和'电视屏幕'被激活的时段和频率，生成使用率报告，优化会议室资源分配。
• 场景 3：内容安全过滤 对用户上传的视频截图进行检测，如果连续多帧出现'手机屏幕'或'电脑屏幕'，则触发人工审核流程，防止敏感信息泄露。

场景 1：在线教育视频分析

# 伪代码示例：分析教学视频中 PPT 出现的时段
import json

with open('detection_result.json', 'r') as f:
    data = json.load(f)

ppt_frames = [box['frame'] for box in data['boxes'] if box['class_name'] == 'monitor']
# 将帧号转换为时间戳（假设视频 30fps）
ppt_timestamps = [frame / 30 for frame in ppt_frames]
print(f"PPT 屏幕出现在以下时间点（秒）: {ppt_timestamps}")

这样就能自动生成视频的'屏幕内容'时间线，方便学生跳转复习。

常见问题与维护指南

即使工具再简单，在使用中也可能遇到一些小问题。这里汇总了最常见的几种情况及其解决方法。

Q1：打开网页显示错误或白屏怎么办？ A：这通常是背后的服务没有正常运行。可以通过 SSH 连接到服务器（如果你有权限），执行命令 supervisorctl status videoagent-screenfilter 查看状态。如果状态不是 RUNNING，尝试执行 supervisorctl restart videoagent-screenfilter 重启服务。服务重启后，刷新浏览器页面即可。

Q2：检测结果时好时坏，不稳定？ A：首先，确保你的测试图片或视频本身清晰、光线充足。然后，将参数固定为默认值（conf=0.25，iou=0.45）进行多次测试，排除参数随机性的影响。如果问题依旧，再按照第 4 章的方法，针对性地微调参数。

Q3：处理视频非常慢，正常吗？ A：这是正常的。视频检测本质上是将视频拆解成成百上千张图片，然后逐张进行 AI 推理，这是一个计算密集型任务。时长越长、分辨率越高的视频，处理时间就越久。建议：先用一段 10 秒左右的短视频验证流程和效果，再提交长视频进行正式处理。

Q4：如何确认服务正在使用 GPU 加速？ A：在服务器上执行 nvidia-smi 命令。如果看到有 python 进程占用了显存（GPU-Memory），就说明 GPU 正在工作，推理速度会远快于 CPU。

总结

通过以上步骤，你已经掌握了 ScreenFilter 这个低代码智能助手的全部核心用法。我们来回顾一下关键点：

1. 定位清晰：它是一个专注于检测屏幕内容（显示器、手机、笔记本等）的专用工具，开箱即用，无需编码。
2. 双模驱动：图片检测用于静态分析，视频检测用于动态追踪与统计，满足不同场景需求。
3. 操作极简：整个过程就像使用一个在线工具——上传文件、点击按钮、查看结果。复杂的模型推理和代码封装都已在后台完成。
4. 结果可用：提供可视化的带框图片/视频，更提供结构化的 JSON 数据，让你能轻松地将 AI 的'视力'集成到自己的自动化工作流中，进行二次分析和处理。
5. 参数可控：通过调整'置信度'和'IOU'两个通俗易懂的参数，你可以像指导助手一样，让 AI 的检测行为更符合你的具体需求。

无论你是想快速验证一个关于屏幕内容的想法，还是希望为现有系统增加一层智能视觉分析能力，ScreenFilter 都提供了一个近乎零门槛的起点。它降低了 AI 应用的门槛，让你可以更专注于业务逻辑和创新，而不是底层技术实现。

现在，就打开那个链接，上传你的第一张图片，开始构建你的智能屏幕分析工作流吧。