tao-analyze-gaps-vlm-bcq

VLM 二元分类差距分析

读取 VLM 预测 JSON，将每个模型响应与真实值进行比较，并将 FP/FN 失败案例写入 JSONL 文件，同时生成摘要报告。

用途

在 VLM 完成二元是/否评估任务后，需要将预测结果与真实值进行比较，以识别失败案例。此技能会生成结构化的 FP（假阳性）和 FN（假阴性）样本列表，供下游 RCCA 阶段（例如 cosmos 生成、根因分析）使用，以驱动一次 DEFT 迭代。

用法

在 TAO Toolkit 数据服务容器中，使用 Hydra 风格的 key=value 覆盖参数调用 vlm_bcq 操作：

gap_analysis vlm_bcq \
  predictions_json=/path/to/results.json \
  results_dir=/path/to/output/gaps

如果预测中的 video_id 值是相对路径，请包含 videos_dir：

gap_analysis vlm_bcq \
  predictions_json=/path/to/results.json \
  results_dir=/path/to/output/gaps \
  videos_dir=/path/to/videos/root

运行后，从 kpi_gaps_report.txt 中提取 FP/FN 数量，并将 kpi_gaps.jsonl 提供给下游阶段。

输入

• predictions_json：预测 JSON 文件的路径。必须是一个 JSON 数组，每个条目都包含 video_id、response 和 gt 字段。解析 response 和 gt 时使用单词边界匹配——字符串中任意位置出现 'yes' 或 'no' 都会被识别。如果两者同时出现或均未出现，则跳过该样本并发出警告。
• videos_dir（可选）：用于解析相对 video_id 路径的基目录。若省略，则将 video_id 值视为绝对路径。

预测 JSON 格式：

[
  {
    "video_id": "/path/to/video.mp4",
    "response": "Yes, there is a collision.",
    "gt": "B. No",
    "question": "Is there a collision?"
  }
]

输出

• kpi_gaps.jsonl：每个 FP/FN 案例各占一行的 JSON 对象。字段：video_id（绝对路径）、error_type（FP 或 FN）、question、ground_truth、response。
• kpi_gaps_report.txt：包含 FP/FN 总数的易读表格。

如果未发现差距，则不会写入任何文件，并会记录一条消息。

关键参数

参数	必需	描述
predictions_json	是	预测 JSON 文件的路径
results_dir	是	输出目录；如果不存在则会创建
videos_dir	否	用于解析相对 video_id 路径的基目录

错误模式

错误	原因	解决方法
FileNotFoundError	predictions_json 不存在	检查路径
ValueError: must be a JSON array	预测文件不是列表	将预测内容包装在 [...] 中
ValueError: missing 'gt'/'response'/'video_id'	预测条目缺少必需字段	检查并修复预测 JSON
样本被静默跳过	response 或 gt 中同时包含或均不包含 'yes'/'no'	查看日志中的警告；检查这些样本