データ品質検査
データ品質検査は、MCAP 記録ごとの構造化レポートをルールに沿ってスキャンし、データセットの合否を判定して、その結論をデータセット上に集約表示します。ルールはプロジェクト単位とグローバル単位の 2 段階があり、判定は手動で上書きできます。結論はシステムタグおよびエクスポートのブロックと連動します。
データ品質検査の対象は ROS 記録データ（現状は主に MCAP）です。
前提条件
| 項目 | 内容 |
|---|---|
| メニュー入口 | データ → 品質検査 |
| ルート | ルール一覧 /qc/rules、実行ログ /qc/logs、データセット品質検査詳細 /qc/dataset/{id} |
| 必須権限 | 「品質検査を表示」 |
| 関連権限 | 「品質検査を実行」（品質検査実行の書き戻し）、「品質検査ルール管理」、「データ計算／前処理」（データセット側で品質検査を手動実行） |
| 依存 | データセットが MCAP であること。ルールで選択したアルゴリズムが登録済みで、空でない指標スキーマを宣言していること |
| 有効ルール | 管理者はモジュール権限の制限を受けません。その他のロールはロール既定テンプレートで有効になり、ユーザー単位の上書きがロール既定より優先されます |
モジュール権限の設定方法は モジュール権限 を参照してください。ロールごとのモジュール既定レベルは次のとおりです。
| ロール | 「品質検査を表示」 | 「品質検査を実行」 | 「品質検査ルール管理」 |
|---|---|---|---|
| プロジェクトマネージャー | 読み取り専用 | 読み書き | 読み書き |
| 収集者 | 読み取り専用 | 読み書き | 禁止 |
| アノテーター | 禁止 | 禁止 | 禁止 |
| レビュアー | 禁止 | 禁止 | 禁止 |
ルールと指標
ロールとルールの保守範囲
| 操作 | 管理者 | プロジェクトマネージャー | その他のロール |
|---|---|---|---|
| ルールと実行ログの表示 | 許可 | 許可（プロジェクトのデータ範囲に制限） | 「品質検査を表示」が必要 |
| プロジェクトルールの保守 | 許可 | 許可（所属プロジェクトに限定） | 禁止 |
| グローバルルールの保守 | 許可 | 禁止 | 禁止 |
| 実行結果の上書き | 許可 | 許可（所属プロジェクトのデータセットに限定） | 禁止 |
グローバルルールの作成、編集、削除、複製は管理者のみが実行できます。管理者以外は一覧でグローバルルールを確認できますが、変更はできません。
品質検査ルール
1 つのルールは、1 つの品質検査アルゴリズム、1 つのスコープ、1 組の断言を結び付けます。
| フィールド | タイプ | 必須 | 既定値 | 値の範囲 | 説明 |
|---|---|---|---|---|---|
| ルール名 | テキスト | はい | — | 最大 200 文字 | ルールの識別子 |
| ルール説明 | テキスト | いいえ | 空 | 最大 500 文字 | ルールの用途に関するメモ |
| スコープ | オプション | はい | プロジェクト | グローバル、プロジェクト | グローバルルールは全プラットフォームの MCAP に有効で、プロジェクトルールは選択したプロジェクトにのみ有効です |
| 名称一致 | テキスト | いいえ | * | glob（* と ? に対応） | データセット名に一致させます。空欄の場合はスコープ内のすべての名称が対象です |
| 品質検査アルゴリズム | オプション | はい | — | 登録済みで指標スキーマを宣言しているアルゴリズム | レポート指標の取得元を決めます |
| 有効化 | トグル | はい | 有効 | 有効、無効 | 無効にすると一致判定と自動投入の対象外になります |
| 優先度 | 整数 | はい | 100 | 整数。値が小さいほど優先 | 一覧と実行の並び順を決めます。該当したルールはそれぞれ独立に判定されます |
| 断言 | リスト | いいえ | 空 | — | 「断言」を参照してください |
プロジェクトに所属するデータセットは、グローバルルールと所属プロジェクトのルールの両方に一致し、2 段階のルールがそれぞれ独立した実行記録を生成します。
断言
断言はルール内の判定条件で、3 つのタイプがあります。
| タイプ | 判定対象 | 判定内容 |
|---|---|---|
| 数値しきい値 | レポート指標 | 比較演算子としきい値で判定します（例：frame_rate >= 20） |
| 必須 Topic | ファイル全体の Topic 一覧 | レポートに指定した Topic が存在する必要があります |
| 禁止 Topic | ファイル全体の Topic 一覧 | レポートに指定した Topic が存在してはなりません |
数値の断言は、比較演算子、しきい値、重大度、範囲を持ちます。
| 属性 | 値 | 説明 |
|---|---|---|
| 比較演算子 | <=、>=、<、>、==、!= | しきい値と比較します |
| 重大度 | 不合格（error）、警告（warning） | 不合格レベルの断言が 1 つでも失敗すると、その実行は不合格と判定されます。警告は記録のみです |
| 範囲 | 全部、Topic（グロブ）、スキーマ | グローバル指標は「全部」のみに対応します。Topic 別指標は「Topic（グロブ）」または「スキーマ」を選ぶ必要があります |
範囲は指標値の取得元を決めます。範囲が「全部」のときはファイル全体の指標を読み取ります。範囲が「Topic（グロブ）」または「スキーマ 」のときは、一致した Topic 明細の各行を個別に比較し、いずれかの行が失敗するとその断言は失敗します。スキーマでの比較の前に、メッセージタイプ名を小文字に正規化し、/msg/ を除去します。
グローバル指標と Topic 別指標では、値の範囲を相互に流用できません。誤った組み合わせはそのまま不合格となり、失敗明細に構成エラーであることが示されます。範囲「Topic（グロブ）」または「スキーマ」のパターンがいずれの Topic にも一致しない場合、その断言は不合格となります。
検出指標
品質検査は、アルゴリズムコンテナとプラットフォームの 2 層で実行します。コンテナは MCAP をスキャンして構造化レポートを出力し、プラットフォームはレポートのフィールドをルール内の断言に沿って 1 項目ずつ評価します。
グローバル指標
グローバル指標はレポートのファイル全体のスカラー値から取得します。数値の断言で使用する場合、範囲は「全部」である必要があります。
| 画面名称（単位） | 指標キー | 方向 | 検出目的 | 算出方法 | 既定の推奨値 |
|---|---|---|---|---|---|
| 記録時間（s） | record_duration_sec | 大きいほど良い | 有効な記録時間が短すぎる | ファイル全体で各 Topic の時間スパンの最大値から最小値を引いた値 | >= 3 |
| タイムスタンプ後退回数 | timestamp_monotonic_violations | 小さいほど良い | タイムスタンプが単調でない、または書き込みが乱順 | 各 Topic 内で t[i] < t[i-1] となる回数の合計 | <= 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 |
| 先頭の関節静止時間（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 明細から取得します。数値の断言で使用する場合、範囲は「Topic（グロブ）」または「スキーマ」である必要があります。
| 画面名称（単位） | 指標キー | 方向 | 検出目的 | 算出方法 | 既定の推奨値 |
|---|---|---|---|---|---|
| トピック毎のメッセージ頻度（Hz） | frequency_hz | 大きいほど良い | 指定チャネルの配信頻度が不足 | メッセージ数を先頭から末尾までの時間スパンで割った値。メッセージが 1 件以下またはスパンが 0 のときは 0 | >= 10 |
| トピック毎の最大フレーム間隔（ms） | topic_frame_gap_max_ms | 小さいほど良い | 指定チャネルの単一最長配信間隔 | 隣接メッセージの時間差の最大値。メッセージが 2 件未満のときは 0 | <= 500 |
| トピック毎のメッセージ数 | message_count | 大きいほど良い | チャネルに有効なデータがない | その Topic のメッセージ総数 | >= 1 |
| トピック毎の時間スパン（s） | duration_sec | 大きいほど良い | チャネルが途中で途切れる、または有効ウィンドウが短すぎる | 最後と最初のメッセージ時刻の差 | >= 0.1 |
| トピック毎の最初の時刻（s） | first_ts_sec | タスク定義による | チャネルの起動時刻 | 最初のメッセージ時刻 | タスク定義による |
| トピック毎の最後の時刻（s） | last_ts_sec | タスク定義による | チャネルの終了時刻 | 最後のメッセージ時刻 | タスク定義による |
表中の既定の推奨値はプラットフォーム組み込みの指標プリセットに由来し、現場の収集構成に合わせて調整する必要があります。
実行と結果
実行方式
| トリガー方式 | トリガー時期 | 説明 |
|---|---|---|
| 自動実行 | MCAP データの前処理が成功した後 | 有効なルールに該当するデータセットを自動でキューに投入します。1 件ずつ手動で開始する必要はありません |
| 手動実行 | データセット品質検査詳細またはデータセット操作 | 現在のデータセットが該当するルールをキューに投入します。ルールのサブセットに限定できます。「データ計算／前処理」が必要です |
| ルール再投入 | ルールの新規作成または有効化の後 | 過去に該当したデータを非同期で再実行します。キュー待ちまたは実行中の記録があるデータセットは再投入しません |
| 全件再投入 | 管理者が開始 | 有効なすべてのルールを再実行します。実行できるのは管理者のみです。データ量が多い場合はタスクがキューで順次実行されます |
自動投入と再投入はいずれも MCAP データを対象とします。MCAP 以外のデータは品質検査キューに入りません。
結果の確認
実行ステータス
単一実行のステータス値は次のとおりです。
| ステータス | 意味 |
|---|---|
| 待機中 | キューに投入済みで、実行待ち |
| 実行中 | 実行中で、進捗率を含む |
| 完了 | 実行が完了し、すべての断言を満たす |
| 完了（不合格項目あり） | 実行が完了し、不合格レベルの断言が少なくとも 1 つ失敗している |
| 実行時異常 | 実行中にエラーが発生し、異常の説明を伴う |
| キャンセル済 | 実行が中断された |
| 未実行 | そのルールにはまだ実行記録がない |
確認できる場所
| 入口 | 内容 |
|---|---|
QC ログ /qc/logs | データセット、ルール、ステータス、有効判定、上書きの有無、期間で実行記録を検索します。単一実行の詳細を開けます |
QC 詳細 /qc/dataset/{id} | 該当ルールごとに有効判定、不合格項目、すべての指標、Topic 一覧、実行情報を表示し、単一ルールまたは全ルールの再実行に対応します |
| データセット一覧と詳細 | データセットが該当したルール数と、合格・不合格・実行中の集計を表示します |
集計の考え方
データセットの集計は該当ルールを数え、各ルールは最新の実行を、判定は有効 判定を用います。
| 項目 | 定義 |
|---|---|
| 該当ルール | 有効なルールに該当した件数 |
| 合格 | 有効判定が合格のルール数 |
| 不合格 | 有効判定が不合格のルール数 |
| 実行中 | 最新の実行が待機中または実行中のルール数 |
| 未開始 | 実行記録がまだないルール数 |
| 上書き済 | 手動オーバーライドがあるルール数 |
有効判定は effective_pass = override_pass ?? pass で、手動オーバーライドがある場合は上書き値を、ない場合は実行時の判定を用います。不合格のルールはシステムタグ qc:failed にも同時に書き込まれ、判定が変わるとこのタグも増減します。
手動オーバーライド
ルールの最新の実行に対して手動オーバーライドを行えます。値は合格、不合格、上書きを取消のいずれかです。上書き時には理由を入力します（最長 500 文字）。理由、上書きした人、上書き時刻は QC 詳細と実行履歴に表示されます。
上書きは集計件数、システムタグ qc:failed、エクスポートのブロック判定に即座に反映されます。上書きを取消すると実行時の判定に戻ります。
エクスポートとトレーニングとの関係
エクスポート前の品質ゲートは、システム設定の QC 不合格のデータセットのエクスポートを禁止するか で制御し、既定で有効です。
| スイッチ状態 | 動作 |
|---|---|
| 有効 | 品質検査ルールに該当し、有効判定が不合格のデータセットはエクスポート画面で選択できず、バックエンドもそのようなエクスポート要求を拒否します |
| 無効 | 合格・不合格にかかわらずデータセットをエクスポートできます |
実行が完了していないルール（待機中または実行中）は、単独ではエクスポートをブロックしません。エクスポートの流れは データエクスポート、トレーニングデータの準備は モデルトレーニング を参照してください。
制約と制限
| 項目 | 値 | 説明 |
|---|---|---|
| データ形式 | MCAP | MCAP 以外のデータは品質検査キューに入りません |
| グローバルルールの書き込み権限 | 管理者のみ | プロジェクトマネージャーはグローバルルールを作成、編集、削除できません |
| 上書き理由の長さ | 最長 500 文字 | 超過分は切り捨てられます |
| ルールの優先度 | 値が小さいほど優先 | 該当したルールはそれぞれ独立に判定され、相互に上書きしません |
| 再投入の重複排除 | キュー待ちまたは実行中の記録があるデータセットは再投入しない | ルールとデータセット単位で重複排除します |
| Topic 別指標の範囲 | 「Topic（グロブ）」または「スキーマ」 | 「全部」の範囲と組み合わせると不合格になります |
| 欠落した指標 | レポートにそのフィールドが存在しない | ルールが欠落指標を参照すると、実際の値が空になるため断言が不合格になります |
| 単一実行記録の結果 | 最新の実行のみを集計 | 履歴は QC ログに保持されます |
トラブルシューティング
| 現象 | 想定原因 | 対処 | 担当 |
|---|---|---|---|
| データセットが品質検査キューに入らない | データが MCAP でない、有効なルールに該当しない、または前処理が完了していない | データ形式とルールの名称一致を確認し、前処理の完了後に再試行します | プロジェクトマネージャー、収集者 |
| 実行ステータスが実行時異常 | データにダウンロード URL がない、コンテナの実行に失敗した、またはレポートが生成されていない | 実行詳細の異常説明を確認し、ファイルがダウンロード可能であることを確 かめて再実行します | プロジェクトマネージャー、管理者 |
| 断言が失敗し構成エラーが表示される | 指標と範囲の組み合わせが合っていない | 指標の種類に合わせて断言の範囲を調整します | プロジェクトマネージャー、管理者 |
| 断言が失敗し該当 Topic がないと表示される | 範囲パターンがいずれの Topic にも一致しない | Topic またはスキーマのパターンを修正するか、必須 Topic の断言に変更します | プロジェクトマネージャー、管理者 |
| ルールを保存できない | プロジェクトまたはアルゴリズムを選択していない、またはアルゴリズムが指標スキーマを宣言していない | プロジェクトと品質検査に使えるアルゴリズムを選択します | プロジェクトマネージャー、管理者 |
| グローバルルールを編集できない | 現在のアカウントが管理者ではない | 管理者がグローバルルールを保守します | 管理者 |
| エクスポートが拒否される | データセットの有効判定が不合格で、エクスポートのブロックが有効 | データを修正して品質検査を再実行するか、確認のうえ手動オーバーライドを行います | プロジェクトマネージャー、管理者 |
| ルール変更後に過去データの結論が出ない | 再投入がまだ完了していない | 再投入がキューで実行されるのを待つか、データセット品質検査詳細から再実行します | プロジェクトマネージャー、管理者 |
関連ページ
| ページ | 用途 |
|---|---|
| データ管理 | データセットの検索、プレビュー、一括操作 |
| データエクスポート | エクスポート前に品質検査ゲートを適用 |
| モデルトレーニング | 品質検査に合格したデータでトレーニング |
| モジュール権限 | 品質検査モジュール権限の設定方法 |
| システム設定 | 品質検査のエクスポートブロックなどシステムスイッチ |