数据质检
数据质检按规则扫描每条 MCAP 录制的结构化报告，对数据集给出通过或未通过的判定，并在数据集上汇总展示结论。规则分项目级与全局两级，判定可被人工覆盖，结论与系统标签、导出拦截联动。
数据质检的对象是 ROS 录制数据（当前以 MCAP 为主）。
使用前提
| 项 | 内容 |
|---|---|
| 菜单入口 | 数据 → 质检 |
| 路由 | 规则列表 /qc/rules；执行日志 /qc/logs；数据集质检详情 /qc/dataset/{id} |
| 必需权限 | 「查看质检」 |
| 相关权限 | 「执行质检」（质检执行回写）、「质检规则管理」、「数据计算/预处理」（在数据集侧手动触发质检） |
| 依赖 | 数据集为 MCAP；规则所选算法已注册且声明非空指标 schema |
| 生效规则 | 管理员不受模块权限限制；其他角色按角色默认模板生效，用户级覆盖优先于角色默认 |
模块权限的配置方式见 模块权限。各角色的模块默认级别：
| 角色 | 「查看质检 」 | 「执行质检」 | 「质检规则管理」 |
|---|---|---|---|
| 项目经理 | 只读 | 读写 | 读写 |
| 采集员 | 只读 | 读写 | 禁止 |
| 标注员 | 禁止 | 禁止 | 禁止 |
| 审核员 | 禁止 | 禁止 | 禁止 |
规则与指标
角色与规则维护范围
| 操作 | 管理员 | 项目经理 | 其他角色 |
|---|---|---|---|
| 查看规则与执行日志 | 允许 | 允许，受项目数据范围约束 | 需「查看质检」 |
| 维护项目规则 | 允许 | 允许，限所属项目 | 禁止 |
| 维护全局规则 | 允许 | 禁止 | 禁止 |
| 覆盖执行结果 | 允许 | 允许，限所属项目的数据集 | 禁止 |
全局规则的创建、编辑、删除、复制仅管理员可执行；非管理员在列表中可见全局规则，但不能修改。
质检规则
一条规则绑定一种质检算法、一个作用域与一组断言。
| 字段 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| 规则名 | 文本 | 是 | — | 最多 200 字 | 规则标识 |
| 规则说明 | 文本 | 否 | 空 | 最多 500 字 | 规则用途备注 |
| 作用域 | 选项 | 是 | 项目 | 全局、项目 | 全局规则对全平台 MCAP 生效；项目规则仅对所选项目生效 |
| 匹配数据名 | 文本 | 否 | * | glob，支持 * 与 ? | 对数据集名称匹配；留空表示作用域内全部数据名 |
| 质检算法 | 选项 | 是 | — | 已注册且声明指标 schema 的算法 | 决定报告指标的来源 |
| 启用 | 开关 | 是 | 启用 | 启用、停用 | 停用后不参与匹配与自动排队 |
| 优先级 | 整数 | 是 | 100 | 整数，越小越优先 | 决定列表与执行排序；命中规则各自独立判定 |
| 断言 | 列表 | 否 | 空 | — | 见「断言」 |
有项目归属的数据集同时匹配全局规则与所属项目规则，两级规则各自产生独立的执行记录。
断言
断言是规则内的判定条件，共三种类型。
| 类型 | 判定对象 | 判定规则 |
|---|---|---|
| 数值阈值 | 报告指标 | 按比较符与阈值判定，如 frame_rate >= 20 |
| 必需 Topic | 全文件 Topic 列表 | 报告中必须出现指定 Topic |
| 禁止 Topic | 全文件 Topic 列表 | 报告中不得出现指定 Topic |
数值断言带比较符、阈值、严重度与范围：
| 属性 | 取值 | 说明 |
|---|---|---|
| 比较符 | <=、>=、<、>、==、!= | 与阈值比较 |
| 严重度 | 不通过（error）、警告（warning） | 任一不通过级断言失败即判定本次未通过；警告仅记录 |
| 范围 | 全部、按 Topic、按 Schema | 全局指标仅支持「全部」；逐 Topic 指标须选「按 Topic」或「按 Schema」 |
范围决定指标的取值来源：范围为「全部」时读取全文件指标；范围为「按 Topic」或「按 Schema」时，对匹配到的每一行 Topic 明细独立比对，任一行失败则该断言失败。按 Schema 比对前会归一化消息类型名称（小写，移除 /msg/）。
全局指标与逐 Topic 指标的取值范围不通用。错误组合会直接 判定失败，失败明细标明配置错误。范围「按 Topic」或「按 Schema」的模式未匹配到任何 Topic 时，该断言判定失败。
检测指标
质检由算法容器与平台两层完成：容器扫描 MCAP 并输出结构化报告，平台依据规则中的断言对报告字段逐项评估。
全局指标
全局指标取自报告的全文件标量，配置数值断言时范围须为「全部」。
| 界面名称（单位） | 指标键 | 方向 | 检测目的 | 计算方法 | 默认建议值 |
|---|---|---|---|---|---|
| 录制时长（s） | record_duration_sec | 越大越好 | 有效录制时间过短 | 全文件所有 Topic 时间跨度的最大值减最小值 | >= 3 |
| 时间戳回退次数 | timestamp_monotonic_violations | 越小越好 | 时间戳非单调或写入乱序 | 按文件写入顺序，各 Topic 内记录时间（log_time）与消息 header.stamp 出现 t[i] < t[i-1] 的次数之和 | <= 0 |
| 输入数据异常数 | input_error_count | 越小越好 | 空消息、截断消息、非法时间戳 | 无法解码的消息数加非法时间戳消息数；大于 0 时无论规则配置如何都判不通过 | <= 0 |
| 无法解码的消息数 | undecodable_message_count | 越小越好 | 消息为空、被截断 或与 schema 不符 | 有解码器但解不开的消息条数 | <= 0 |
| 非法时间戳消息数 | invalid_header_stamp_count | 越小越好 | header.stamp 为 0、为负或纳秒溢出 | 为负、纳秒 ≥ 1e9，或在其他帧有有效时间戳的 Topic 上为 0 的消息条数 | <= 0 |
| 参考 topic 帧率（Hz） | frame_rate | 越大越好 | 主数据流平均发布频率偏低 | 参考 Topic 消息数除以文件时间跨度 | >= 20 |
| 帧间隔中位数（ms） | frame_gap_median_ms | 越小越好 | 主数据流基准间隔偏大 | 参考 Topic 相邻时间差序列的中位数 | <= 50 |
| 帧间隔 P95（ms） | frame_gap_p95_ms | 越小越好 | 间歇性发布延迟 | 同一序列的 95 分位 | <= 200 |
| 帧间隔 P99（ms） | frame_gap_p99_ms | 越小越好 | 偶发长间隔 | 同一序列的 99 分位 | <= 500 |
| 最大帧间隔（ms） | frame_gap_max_ms | 越小越好 | 单次最长发布间隔 | 同一序列的最大值 | <= 1000 |
| 丢帧次数 | drop_frame_count | 越小越好 | 相对正常节律的异常长间隔 | 参考 Topic 上相邻间隔大于 1.5 倍中位间隔的次数 | <= 0 |
| 跨 topic 同步 P95（ms） | cross_topic_sync_p95_ms | 越小越好 | 多通道时间对齐误差 | 各非参考 Topic 与参考 Topic 最近邻差 P95 的最大值 | <= 50 |
| 跨 topic 同步 P99（ms） | cross_topic_sync_p99_ms | 越小越好 | 多通道对齐误差尾部 | 全部采样最近邻差合并后的 99 分位 | <= 100 |
| 跨 topic 同步最大（ms） | cross_topic_sync_max_ms | 越小越好 | 单次最大对齐偏差 | 全部采样最近邻差的最大值 | <= 200 |
| 左腕相机相对头部滞后（ms） | sync_head_left_camera_max_ms | 越小越好 | 左腕彩色比头部彩色晚太多 | 按文件中的消息序号对齐，取左腕彩色比头部彩色更晚的最大毫秒数；更早记 0。只用彩色 | < 40 |
| 右腕相机相对头部滞后（ms） | sync_head_right_camera_max_ms | 越小越好 | 右腕彩色比头部彩色晚太多 | 按文件中的消息序号对齐，取右腕彩色比头部彩色更晚的最大毫秒数；更早记 0。只用彩色 | < 40 |
| 左臂相对三相机基准滞后（ms） | sync_cammax_left_arm_max_ms | 越小越好 | 左臂比三路相机里最晚的一帧还要晚 | 每一帧取头部、左腕、右腕彩色时间的最大值作为基准，再取左臂比该基准更晚的最大毫秒数 | < 50 |
| 右臂相对三相机基准滞后（ms） | sync_cammax_right_arm_max_ms | 越小越好 | 右臂比三路相机里最晚的一帧还要晚 | 每一帧取头部、左腕、右腕彩色时间的最大值作为基准，再取右臂比该基准更晚的最大毫秒数 | < 50 |
| 开头关节静止时长（s） | leading_joint_still_sec | 越小越好 | 录制开始后长时间未运动 | 文件起点到任一关节首次有效运动 | <= 3 |
| 结尾关节静止时长（s） | trailing_joint_still_sec | 越小越好 | 任务结束后长时间未停录 | 末次有效运动到文件终点 | <= 3 |
| 图像清晰度 P90 | blur_score_p90 | 越大越好 | 图像整体清晰度不足 | 采样帧拉普拉斯方差的 90 分位 | >= 40 |
| 曝光异常帧比例 | exposure_outlier_ratio | 越小越好 | 亮度异常帧占比过高 | 亮度偏离均值 2 倍标准差的帧数占采样帧数之比 | <= 0.05 |
参考 Topic：先排除名称含 /tf、/tf_static、/rosout、/parameter_events、/clock 的 Topic，再取剩余中消息条数最多者。帧率、帧间隔、丢帧与跨 Topic 同步均以该 Topic 为基准。图像与关节指标仅在报告中存在相应 Topic 时输出；缺失字段被规则引用时，断言因实际值为空而失败。
上面四项「滞后」和「跨 topic 同步」不是同一件事。跨 topic 同步对所有 topic 找时间上最近的一条消息；滞后只看头部、左腕、右腕彩色和左右臂，并且只统计更晚的一侧。相机和手臂按路径里的 head / left / right 识别，因此 camera_head 与 /camera/head/color、left_data 与 /arm/left/joint_states 都能对上。深度、camera_info 和腰关节不算。某一侧没有自己的关节 topic 时，用 /dual_arm/joint_state 补这一侧（joint_command 不用）；两侧都有单独 topic 时不用这条合成流。五路条数相同时按文件顺序逐帧对齐；条数不同时以头部彩色为时钟取最近邻。首帧与末帧都计入。条数不同时只比较各路都在录制的时间段：某一路晚开始或早结束时，头部多出来的那几帧没有可配的画面，不算滞后，报 告说明里会写明跳过了几帧；要约束某一路晚开始，可对该 Topic 的「单 topic 首条时间」（first_ts_sec）单独设规则。报告说明里会写明最近邻配对，以及改用合成关节流的原因。仍缺的角色只跳过依赖它的指标。同一角色对应超过 1 个 topic 时，这 4 项指标都省略。一个都匹配不到时不写说明。指标缺失时，数值断言会因实际值为空而失败。不通过时，失败说明会写出最差的帧号、两路的原始纳秒时间戳，以及超阈值的总帧数与前 20 个帧号；毫秒值默认显示 3 位小数，接近阈值时自动补位，不会把 40.0004 显示成 40。
输入数据异常：质检时会把每条消息完整解码一遍。空消息、被截断的消息、header.stamp 为 0（该 Topic 其他帧有有效时间戳时）、为负或纳秒溢出的消息都记为输入数据异常。只要出现一处，本次质检直接判为不通过，详情页单独列出异常所在的 Topic、帧号与记录时间，与规则里配置了哪些检查项无关。整条 Topic 的 header.stamp 都是 0 的视为该驱动不填时间戳，只在报告说明中提示。
逐 Topic 指标
逐 Topic 指标取自报告的每条 Topic 明细，配置数值断言时范围须为「按 Topic」或「按 Schema」。
| 界面名称（单位） | 指标键 | 方向 | 检测目的 | 计算方法 | 默认建议值 |
|---|---|---|---|---|---|
| 单 topic 消息频率（Hz） | frequency_hz | 越大越好 | 指定通道发布频率不足 | 消息数除以首末时间跨度；消息不超过 1 条或跨度为 0 时取 0 | >= 10 |
| 单 topic 最大帧间隔（ms） | topic_frame_gap_max_ms | 越小越好 | 指定通道单次最长发布间隔 | 相邻消息时间差的最大值；消息少于 2 条时为 0 | <= 500 |
| 单 topic 帧间隔超过 50ms 的次数 | topic_frame_gap_over_50ms_count | 越小越好 | 偶尔丢帧可接受，太多次才判不合格 | 相邻间隔严格大于 50ms 的次数；消息少于 2 条时为 0 | <= 5 |
| 单 topic 帧间隔超过 100ms 的次数 | topic_frame_gap_over_100ms_count | 越小越好 | 较长间隔出现太多次 | 相邻间隔严格大于 100ms 的次数；消息少于 2 条时为 0 | <= 5 |
| 单 topic 消息条数 | message_count | 越大越好 | 通道无有效数据 | 该 Topic 消息总数 | >= 1 |
| 单 topic 时间跨度（s） | duration_sec | 越大越好 | 通道中途断流或有效窗口过短 | 末条与首条时间之差 | >= 0.1 |
| 单 topic 首条时间（s） | first_ts_sec | 按任务定义 | 通道是否延后启动 | 相对录制起点（全文件最早消息为 0） | 建议 <= 1 |
| 单 topic 末条时间（s） | last_ts_sec | 按任务定义 | 通道结束时刻 | 相对录制起点的末条时刻 | 建议 <= 3600 |
表中的默认建议值来自平台内置的指标预设，须按现场采集配置调整。次数类指标适合配在图像等高频通道上（例如 Schema *CompressedImage*、允许 5 次）；10Hz 关节流的名义间隔已经是 100ms，套用「超过 50ms 的次数」几乎每帧都会计数。一条 200ms 间隔会同时计入 50ms 与 100ms 两条指标。
执行与结果
执行方式
| 触发方式 | 触发时机 | 说明 |
|---|---|---|
| 自动执行 | MCAP 数据预处理成功后 | 对命中已启用规则的数据集自动入队，无需逐条手动发起 |
| 手动执行 | 数据集质检详情或数据集操作 | 对当前数据集命中规则入队，可限定规则子集；需「数据计算/预处理」 |
| 规则回灌 | 规则新建或启用后 | 对历史命中数据异步补跑；已有排队中或执行中记录的数据集不重复入队 |
| 全量回灌 | 管理员发起 | 对全部启用规则补跑，仅管理员可执行；数据量较大时任务排队执行 |
自动入队与回灌均以 MCAP 数据为范围；非 MCAP 数据不进入质检队列。
结果查看
执行状态
单次执行的状态取值：
| 状态 | 含义 |
|---|---|
| 排队中 | 已入队，等待执行 |
| 进行中 | 执行中 ，含进度百分比 |
| 已完成 | 执行完成且断言全部满足 |
| 完成（含不通过项） | 执行完成且存在不通过级断言失败 |
| 运行异常 | 执行过程报错，附异常说明 |
| 已取消 | 执行被终止 |
| 未执行 | 该规则尚无执行记录 |
查看入口
| 入口 | 内容 |
|---|---|
质检日志 /qc/logs | 按数据集、规则、状态、有效判定、是否覆盖、时间区间检索执行记录；可打开单次执行详情 |
数据集质检详情 /qc/dataset/{id} | 按命中规则逐条展示有效判定、不通过项、全部指标、Topic 列表与执行信息，并支持重跑单条规则或全部规则 |
| 数据集列表与详情 | 显示数据集命中的规则数与通过、未通过、进行中的汇总 |
汇总口径
数据集的汇总按命中规则计数，每条规则取其最新一次执行，判定取有效判定：
| 计数 | 口径 |
|---|---|
| 命中规则 | 命中已启用规则的条数 |
| 通过 | 有效判定为通过的规则数 |
| 未通过 | 有效判定为未通过的规则数 |
| 进行中 | 最新执行处于排队中或进行中的规则数 |
| 未开始质检 | 尚无任何执行记录的规则数 |
| 已覆盖 | 存在人工覆盖的规则数 |
有效判定 effective_pass = override_pass ?? pass：存在人工覆盖时取覆盖值，否则取执行判定。未通过的规则会同步写入系统标签 qc:failed，判定变化时该标签随之增减。qc:failed 由质检生命周期自动维护，不可在数据标签处手动删除；若需消除「未通过」结论，请在质检详情或列表质检列中做人工覆盖。
数据管理高级搜索提供 质检状态 筛选（通过 / 不通过 / 未开始 / 进行中 / 运行异常 / 未命中规则），口径与列表「质检」列聚合一致，不依赖是否挂有 qc:failed 标签。
人工覆盖
对某条规则的最新一次执行可做人工覆盖，取值为通过、未通过或取消覆盖。覆盖时填写原因，最长 500 字；原因、覆盖人与覆盖时间在质检详情与执行历史中展示。
覆盖立即参与汇总计数、系统标签 qc:failed 与导出拦截的判定。取消覆盖后恢复执行判定。
与导出和训练的关系
导出前的质量门禁由系统设置中的 质检未通过的数据集是否禁止导出 控制，默认启用：
| 开关状态 | 行为 |
|---|---|
| 启用 | 命中质检规则且有效判定为未通过的数据集在导出界面不可勾选，后端拒绝此类导出请求 |
| 关闭 | 已通过或未通过的数据集均可导出 |
尚未执行完成的规则（排队中或进行中）不单独阻断导出。导出流程见 数据导出，训练数据准备见 模型训练。
约束与限制
| 项目 | 取值 | 说明 |
|---|---|---|
| 数据格式 | MCAP | 非 MCAP 数据不进入质检队列 |
| 全局规则写权限 | 仅管理员 | 项目经理不能创建、编辑、删除全局规则 |
| 覆盖原因长度 | 最多 500 字 | 超出部分截断 |
| 规则优先级 | 数值越小越优先 | 命中规则各自独立判定，不相互覆盖 |
| 回灌去重 | 已有排队中或执行中记录的数据集不重复入队 | 按规则与数据集去重 |
| 逐 Topic 指标范围 | 「按 Topic」或「按 Schema」 | 与「全部」范围组合会判定失败 |
| 缺失指标 | 报告中不存在该字段 | 规则引用缺失指标时断言因实际值为空而失败 |
| 单个执行记录的结果 | 最新一次执行参与汇总 | 历史记录保留在质检日志中 |
失败处理
| 现象 | 可能原因 | 处置 | 责任方 |
|---|---|---|---|
| 数据集未进入质检队列 | 数据非 MCAP、未命 中已启用规则、或预处理未完成 | 确认数据格式与规则匹配数据名；完成预处理后重试 | 项目经理、采集员 |
| 执行状态为运行异常 | 数据缺失下载地址、容器执行失败、或报告未生成 | 查看执行详情中的异常说明；确认文件可下载后重跑 | 项目经理、管理员 |
| 断言失败且提示配置错误 | 指标与范围组合不匹配 | 按指标类型调整断言范围 | 项目经理、管理员 |
| 断言失败且提示无匹配 Topic | 范围模式未匹配到任何 Topic | 校正 Topic 或 Schema 模式，或改为必需 Topic 断言 | 项目经理、管理员 |
| 规则无法保存 | 未选择项目或算法、算法未声明指标 schema | 选择项目与可用于质检的算法 | 项目经理、管理员 |
| 全局规则无法编辑 | 当前账号非管理员 | 由管理员维护全局规则 | 管理员 |
| 导出被拒绝 | 数据集有效判定为未通过，且导出拦截已启用 | 修正数据后重跑质检，或经核实后做人工覆盖 | 项目经理、管理员 |
| 规则变更后历史数据无结论 | 回灌尚未执行完成 | 等待回灌排队执行，或在数据集质检详情重跑 | 项目经理、管理员 |
相关页面
| 页面 | 用途 |
|---|---|
| 数据管理 | 数据集检索、预览与批量操作 |
| 数据导出 | 导出前应用质检门禁 |
| 模型训练 | 使用已通过质检的数据训练 |
| 模块权限 | 质检模块权限的配置方式 |
| 系统设置 | 质检导出拦截等系统开关 |