我已发布了源代码。https://github.com/shure-dev/small_vlm_video_analysis…
机制很简单：
・提前详细定义正确的规程手册
・让VLM（4B）描述视频的每一帧
・基于描述内容按规则进行判断
同时包含一个可视化工具。

shure-dev/small_vlm_video_analysis

来源：https://github.com/shure-dev/small_vlm_video_analysis

small_vlm_video_analysis

判断操作视频是否符合声明式SOP（规程），仅使用本地小型VLM（Qwen3-VL，Apple Silicon）。不使用云端、不使用大型模型。

• 阶段0（确定正确答案）：实际观看视频，按照格式由人工确认正确的操作步骤。
• 阶段1（观察）：让VLM观看视频的每一帧，对预先设定的问题（例如：“手是否在触摸旋钮？”）回答 yes / no / unclear。同时记录回答的确定程度。
• 阶段2（判断）：将VLM的回答与预先设定的步骤规则（例如：“点火必须在指差确认之前”）进行机械比对，给出 PASS / FAIL。此处不使用VLM。

运行环境

• macOS（Apple Silicon）
• Python >= 3.10
• observe / run 命令需要 mlx-vlm (https://github.com/Blaizzy/mlx-vlm)

安装

pip install -r requirements.txt   # 如果只使用 judge 命令：pip install pyyaml

快速开始

python src/cli.py run \
  --sop examples/konro_inspection/sop.yaml \
  --video examples/konro_inspection/data/konro_inspection.mp4 \
  --model 4b \
  --out-dir out/

帧提取 → VLM观察 → 判断，一行命令执行。自带示例实际数据即可运行。

也可以不运行VLM，仅使用已观察的日志进行判断：

python src/cli.py judge \
  --sop examples/konro_inspection/sop.yaml \
  --answer-log examples/konro_inspection/sample_output/answer_log.json

CLI

结果回放查看器

观察和判断的结果可配合帧图片在浏览器中回放：

python tools/replay_viewer/build.py   # 生成 tools/replay_viewer/replay.html

输出为无依赖的单页面HTML（帧图片已嵌入），双击即可打开。在一个画面中即可确认“当前在第几帧”“VLM对每个问题的回答是什么”“检测到了哪些事件”“最终判断是PASS还是FAIL”。已从示例数据生成 tools/replay_viewer/replay.html，可以直接打开。

可通过 --sop / --answer-log / --frames-dir / --out 替换为其他运行结果。例如传入 --sop examples/konro_inspection/sop_wrong_order.yaml，可看到同一视频因顺序违规而FAIL的情况。

SOP 格式

在一个YAML文件中编写三个部分。它们的作用不同：

1. questions — 每帧向VLM提问的问题
2. events — 对某个问题的回答持续N帧以上，则视为“发生”
3. relations — 声明事件之间的前后、同时、禁止关系

顺序为 questions → events → relations。observe 回答的内容，由 judge 转换为检测条件，然后检查检测结果之间的关系。

sop:
  id: konro_inspection
  name: 燃气灶班前检查
  domain_hint: "这是从上方拍摄的燃气灶检查作业视频中的一帧"

questions:                           # 阶段1 — 从这里自动生成向VLM的提示
  - id: knob
    ask: "手是否在触摸灶台前面的旋钮"
    values: ["yes", "no"]            # 必须加引号。裸的 yes/no 会被YAML解析为布尔值

events:                              # 阶段2 — 检测什么
  ignite:
    evidence: "knob==yes"
    min_frames: 2                    # 持续动作可提高此值以获得抗噪性
  point1:
    evidence: "pointing==yes"
    occurrence: 1                    # 显式指定时间序列中的第N次（不依赖声明顺序，见后文）

relations:                           # 阶段2 — 事件之间的时间关系
  - ignite before point1
  - point2  overlaps battery         # 可以同时发生
  - not gloves_worn                  # 绝不能被检测到

对上述示例进行解读：knob（是否在触摸旋钮）每帧向VLM提问（question）→ 若 knob==yes 持续2帧以上，则视为事件 ignite（点火）发生（event）→ ignite 必须在 point1 之前发生（relation）。

relations 只有三种

• before — A 先发生，B 后发生
• overlaps — A 和 B 可以同时发生
• not — 该事件绝不能发生

occurrence（第几次） 同一个问题（例如：“是否在指差确认？”）在视频中会被多次提问，因此需要区分“第1次”“第2次”的编号。若不指定，则按照“YAML中写出的顺序”分配，改变编写顺序会导致结果变化（在 tests/test_judge.py::test_occurrence_is_order_independent 中已验证）。

仓库结构

small_vlm_video_analysis/
├── src/
│   ├── observe.py   # 阶段1：从 questions 生成提示 + 调用VLM + 提取置信度
│   ├── judge.py     # 阶段2：events/relations 规则引擎
│   ├── extract.py   # 视频 -> 帧（cv2）
│   ├── sop.py       # SOP YAML 的加载和验证
│   └── cli.py       # `run`/`observe`/`judge` 子命令
├── examples/konro_inspection/   # 实际视频、帧、观察日志、3种SOP
├── tools/replay_viewer/         # 在浏览器中回放结果的单页面HTML生成（已附带生成好的 replay.html）
└── tests/                       # 针对实际数据的回归测试（不需要VLM）

还构思了更高级的格式（时序匹配树、非视觉步骤、向 judge 模型升级），但本仓库仅实现了经过端到端验证的部分。

许可证

MIT — 参见 LICENSE 文件。