ESPectre 數(shù)據(jù)集質(zhì)量評審的檢測器無關(guān)化改造從 Classic 閾值回放到共享尺度不變特征證據(jù)【免費下載鏈接】espectreWi-Fi CSI motion sensing for ESP32. C SDK, ESPHome, Native, and Matter frontends, browser tools, and a CLI for the full device lifecycle. GPLv3 and commercial licensing.項目地址: https://gitcode.com/GitHub_Trending/es/espectre導(dǎo)讀本文圍繞 ESPectre 項目中的一份架構(gòu)決策記錄ADR展開詳細(xì)講解tools/validate_dataset_quality.py如何從依賴 Classic 檢測器回放、啟動校準(zhǔn)與閾值語言的評審機(jī)制演進(jìn)為**完全檢測器無關(guān)detector-agnostic**的評審機(jī)制。你將理解為什么低 RSSI 采集對會觸發(fā)檢測器告警但數(shù)據(jù)本身可分的偽劣信號評審指標(biāo)如何改用 8 個尺度不變的生產(chǎn)特征Cover / Sep / Tail / Exc / Burst / Drift / Score等評審指標(biāo)的精確含義與閾值以及如何運行驗證器、讀懂生成在data/auto_generated/DATASET_QUALITY_CHECK.md中的報告。讀完本文你可以直接上手校驗自己的數(shù)據(jù)集并能向他人解釋數(shù)據(jù)集評審與檢測器性能門禁為什么必須是兩套獨立的證據(jù)面。背景一份文檔曾經(jīng)同時承擔(dān)兩件不同的事在 2026-07-29 這份 ADR 之前tools/validate_dataset_quality.py已經(jīng)能很好地完成兩個任務(wù)阻止被污染或不可用的采集進(jìn)入 ML 訓(xùn)練在data/auto_generated/DATASET_QUALITY_CHECK.md中匯總已準(zhǔn)入語料供人工評審。問題出在 2026-07-17 的拆分Classic 已經(jīng)從數(shù)據(jù)集準(zhǔn)入流程中移除但評審表格仍然依賴ClassicDetector回放、啟動校準(zhǔn)startup calibration以及閾值相對的語言threshold-relative language。這就讓操作面殘留了一種循環(huán)論證一個校準(zhǔn)不良的檢測器即使共享的生產(chǎn)特征已經(jīng)把數(shù)據(jù)干凈地分開也可能讓某條采集看起來質(zhì)量差。這個缺陷在低 RSSI 配對low-RSSI pairs上尤其顯眼報告可能因為檢測器被激活而告警而數(shù)據(jù)內(nèi)在的 idle/motion 分離其實很強(qiáng)——這反映的是檢測器的局限而不是數(shù)據(jù)集損壞。報告因此需要直接描述數(shù)據(jù)本身而不是描述某一個檢測器的閾值落在哪里。ADR 同時強(qiáng)調(diào)必須保留單一事實來源one source of truth數(shù)據(jù)集準(zhǔn)入屬于驗證器檢測器晉升promotion屬于docs/performance/README.md把報告拆成第二份數(shù)據(jù)集質(zhì)量文檔會重復(fù)策略與指標(biāo)。決策保留一份報告但評審指標(biāo)檢測器無關(guān)ADR 的核心決策一句話即可概括仍然只生成一份數(shù)據(jù)集質(zhì)量報告但讓其中的評審指標(biāo)完全脫離任何檢測器回放。準(zhǔn)入admission邏輯保持不變?nèi)匀豢赡茏屨芜\行失敗完整性、連續(xù)性與信號質(zhì)量檢查integrity / continuity / signal-qualityempty與static_presence的可用性 / 重疊檢查availability / overlapML 就緒檢查ML readiness長錄制標(biāo)注與覆蓋檢查long-recording annotation and coverage被替換的只是僅用于評審的表格。它們現(xiàn)在來源于生產(chǎn)與訓(xùn)練中已經(jīng)在使用的共享尺度不變特征流水線shared scale-invariant feature pipeline。8 個核心證據(jù)特征全部增益不變評審的證據(jù)面是當(dāng)前生產(chǎn) High Accuracy 特征集按構(gòu)造全部增益不變gain-invariant。這 8 個特征定義在 tools/lib/csi_features.py 的PHASELESS8_FEATURES即DEFAULT_FEATURES中特征名語義方向FEATURE_EVIDENCE_DIRECTIONSturb_iqr_over_mean_aggr1.0越大越活躍turb_autocorr1.0turb_zcr-1.0過零率越高越安靜l1_delta_lag_ratio1.0chan_shape_spread_subband1.0默認(rèn)方向chan_shape_coherent_innovation_energy1.0默認(rèn)方向chan_shape_excess_path1.0默認(rèn)方向chan_shape_subband_kendall_lag_excess1.0默認(rèn)方向特征方向direction由特征語義固定而不是從檢測器回放中推斷。在 tools/lib/dataset_quality/severity.py 的FEATURE_EVIDENCE_DIRECTIONS中前 4 個特征顯式聲明了方向其余特征默認(rèn)取 1.0tools/lib/dataset_quality/metrics.py 的_feature_evidence_series會把每個窗口的多維特征矩陣按direction * (value - center) / scale歸一化并裁剪到 [-8, 8]再沿特征軸取均值折疊成一條共識特征證據(jù)序列consensus feature-evidence series。為什么這些特征能在弱鏈路 / 增益漂移下保持可比代碼里有一處非常典型的佐證l1_delta與l1_delta_std兩個特征曾在 2026-07-28 被移除——把一條強(qiáng)鏈路采集加入訓(xùn)練后一條弱鏈路配對的假陽性從 0% 跳到 100%因為其 idle 位移0.2653高于自身 motion0.1830、也高于新采集的 motion0.0587。這正是絕對能量類特征不可比的實證tools/lib/csi_features.py。配對行用證據(jù)覆蓋與秩 AUC 替代閾值診斷配對行Pair rows把閾值相對的 Classic 診斷替換為以下指標(biāo)Covermotion 窗口中有多少比例高于 idle 半段的自身 p95 證據(jù)share of motion windows above the idle halfs own p95 evidence。實現(xiàn)見 tools/lib/dataset_quality/pairing.pymotion_coverage ((motion_evidence idle_p95).mean())。Sepidle 與 motion 證據(jù)之間的基于秩的 AUCrank-based AUC。實現(xiàn)是 Mann-Whitney 統(tǒng)計量只讀兩條序列的相對次序因此與閾值位置及任何單調(diào)重標(biāo)度無關(guān)tools/lib/dataset_quality/metrics.py。Tailidle 側(cè) q95 高于該配對自身居中證據(jù)基線的量。Score0-100 的指示性排序由分離度、覆蓋度與 idle 潔凈度合成。配對行的最終Score還會被兩個方向的證據(jù)共同封頂min(pair_score, reference_cleanliness_score)后再被兩端采集的時域占用率occupancy封頂tools/lib/dataset_quality/pairing.py。這樣強(qiáng)分離無法掩蓋static 捕獲整體漂移或持續(xù)活躍的問題。Idle 行用自身基線替代自校準(zhǔn) Classic 基線Idle 行覆蓋 Presence / Empty / Long-recording 三張表把自校準(zhǔn) Classic 基線項替換為Exc在特征證據(jù)軸上超過median 3 MAD的窗口占比excursion share。BASELINE_EXCURSION_MADS 3.0tools/lib/dataset_quality/severity.py。Burst在塊級 idle 基線上測得的持續(xù)突發(fā)長度sustained burst length以 5 秒塊為單位BASELINE_BLOCK_SECONDS 5.0。Tailq95 高于該采集自身居中證據(jù)基線的量。Drift前半段與后半段的中位證據(jù)漂移half-to-half median evidence drift取絕對值tools/lib/dataset_quality/metrics.py。Score0-100 指示性排序由尾部潔凈度與突發(fā)長度合成agnostic_baseline_score權(quán)重 0.7 / 0.3見 tools/lib/dataset_quality/metrics.py。閾值相對的檢測器術(shù)語從生成報告中整體移除。Lightweight 仍然出現(xiàn)在檢測器晉升與性能面中但不再進(jìn)入數(shù)據(jù)集質(zhì)量評審docs/adr/2026-07-29-make-dataset-quality-review-detector-agnostic.md。演進(jìn)記錄日期方向決議2026-07-17將數(shù)據(jù)集準(zhǔn)入與 Classic 診斷分離但保留 Classic 評審表從準(zhǔn)入中移除檢測器行為2026-07-29讓剩余評審指標(biāo)檢測器無關(guān)作為唯一數(shù)據(jù)集質(zhì)量策略被接受驗證器如何運行命令、階段與報告命令入口入口腳本是 tools/validate_dataset_quality.py常用調(diào)用方式腳本自身 help 文本中的示例python tools/validate_dataset_quality.py # 完整校驗自動報告 元數(shù)據(jù)刷新 python tools/validate_dataset_quality.py --chip C6 # 只校驗 C6 python tools/validate_dataset_quality.py --data-dir data/untracked/example --preserve-pairs python tools/validate_dataset_quality.py --data-dir data/untracked/example --diagnostic-all-phy python tools/validate_dataset_quality.py --no-cache # 繞過持久化的驗證緩存 python tools/validate_dataset_quality.py --no-report # 跳過 Markdown 報告關(guān)鍵參數(shù)--chip按芯片類型過濾如 C6、S3、C3、ESP32--data-dir數(shù)據(jù)集根目錄默認(rèn)data/需包含dataset_info.json與標(biāo)簽?zāi)夸?-report-output報告輸出路徑默認(rèn)data-dir/auto_generated/DATASET_QUALITY_CHECK.md--preserve-pairs保留顯式配對而非按時間戳刷新--diagnostic-all-phy在仍報告違反受支持的 HT20 / HT-LTF 傳感契約的前提下評估所有顯式 PHY 行--no-cache單次運行繞過持久化的時間感知 ML 行緩存--check-current僅當(dāng)報告與當(dāng)前輸入一致時以 0 退出CI 場景很有用。校驗階段編排邏輯在 tools/lib/dataset_quality/runner.py 的run_validation中按階段執(zhí)行元數(shù)據(jù)完整性Phase 1域integrity要求每個新條目聲明environment與顯式dataset_role缺失角色視為exclude但校驗仍會失敗直到所有條目顯式聲明。NPZ 完整性 / 質(zhì)量Phase 2域integrity對每個文件做完整性、連續(xù)性stream loss、信號質(zhì)量檢查low_rssi采集的流缺失失敗閾值放寬到 5%普通錄制為 3%1% 以上開始告警。配對校驗Phase 3域feature_space基于共享特征矩陣評估static_presence ? motion配對產(chǎn)出 Pair Scores 行。配對由refresh_pair_metadata自動刷新同芯片、同子載波數(shù)、采集時間差在PAIR_MAX_DELTA_SECONDS 30 * 60秒內(nèi)、按時間差做最近 1:1 貪心配對tools/lib/dataset_quality/pairing.py。Empty / Presence 健全性Phase 4域label_sanity/feature_space產(chǎn)出 Empty Scores 與 Presence Scores 行并把empty_quality/*、presence_quality/*歸入特征空間域。Quiet-test 健全性Phase 5域long_recording/feature_space面向long_recording: true的安靜長錄制產(chǎn)出 Long-recording scores 行。ML 就緒Phase 6域ml。Excluded 診斷dataset_role: exclude的配對與 idle 采集仍會以信息性診斷形式出現(xiàn)在 Excluded 表中不參與校驗匯總——這正是 ADR被排除的配對可以保持可見但不重新引入檢測器偏差的落地方式。報告最終由 tools/lib/dataset_quality/report.py 的_generate_report原子寫入atomic_write_text頭部記錄數(shù)據(jù)修訂哈希、輸入修訂哈希、評估視圖與策略文檔指針。先決條件與適用前提按 docs/ML_DATA_COLLECTION.md 的說明校驗前必須完成至少 10 個樣本 / 標(biāo)簽建議 30-60 秒 / 樣本、每條dataset_info.json條目帶environment與顯式dataset_role、同一環(huán)境使用相同環(huán)境名。配對字段不要手工填寫驗證器會基于時間戳自動刷新均值有效槽占用率低于 85% 告警、低于 70% 準(zhǔn)入失敗并封頂所有相關(guān)評審分?jǐn)?shù)。時間質(zhì)量與 ML 就緒檢查需要可用的錄制包速率num_packetsduration_ms時序元數(shù)據(jù)不足會被判定為校驗失敗絕不會被解釋成 100 pps。完整流程見 docs/ML_DATA_COLLECTION.md 與 tools/README.md。報告中的評審指標(biāo)含義、閾值與實現(xiàn)依據(jù)報告在每個分?jǐn)?shù)表后都附有Reading these tables與Validation rule段落tools/lib/dataset_quality/report.py核心口徑如下。通用規(guī)則所有分?jǐn)?shù)都由共享尺度不變特征證據(jù)與時域占用率封頂共同構(gòu)成沒有任何一個分?jǐn)?shù)依賴檢測器閾值或概率面。配對行的Cover/Sep與外部靜態(tài)潔凈度RefExc/RefBurst保持獨立最終Score被兩者共同封頂因此強(qiáng)分離不能掩蓋漂移或持續(xù)活躍的靜態(tài)采集。Presence / Empty / Long-recording 行匯總采集內(nèi)部穩(wěn)定性因為使用采集自身的中心能暴露突發(fā)與漂移但無法暴露均勻的跨會話整體漂移Excluded Idle Diagnostics 針對已準(zhǔn)入的同芯片、同鏈路等級、同包速率等級參考提供這個缺失的跨會話視角同一環(huán)境至少有 3 個獨立采集時優(yōu)先。閾值一覽以報告生成邏輯為準(zhǔn)指標(biāo)告警 / 失敗規(guī)則Stream loss缺失stream_seq_num?? 1%? 3%普通? 5%low_rssi: trueOcc均值有效槽時域占用?? 85%? 70%失敗閾值是準(zhǔn)入門占用率同時是分?jǐn)?shù)封頂Covermotion 窗口高于 idle p95 占比?? 95%? 90%RefExc5 秒塊高于外部參考 p95 占比?? 25%? 50%RefBurst高于外部參考 p99 的最長連續(xù)塊?? 30s? 120sExc超過自身median 3 MAD的窗口占比?? 8%? 13%Tail自身 q95 與自身中位的差距?? 4.0? 6.0Sepidle/motion 證據(jù)秩 AUC?? 0.990? 0.970Burst最長持續(xù)突發(fā)秒數(shù)?? 30s? 120sScore0-100 評審排序信號不參與準(zhǔn)入準(zhǔn)入只取決于完整性、占用、連續(xù)性、元數(shù)據(jù)、重疊與 ML 就緒以上常數(shù)定義在 tools/lib/dataset_quality/severity.py 中如MAX_STREAM_SEQ_MISSING_WARN_RATIO、TEMPORAL_OCCUPANCY_WARN_RATIO、MIN_MOTION_COVERAGE_RATIO、REFERENCE_EXCURSION_WARN_RATIO、BASELINE_TAIL_WARN_LOGITS、SEPARATION_WARN_BELOW等并在 tools/lib/dataset_quality/report.py 中被引用進(jìn)報告文本——報告里看到的數(shù)字與判定代碼使用的是同一組常量。經(jīng)驗閾值peer-relative機(jī)制從源碼結(jié)構(gòu)看評審還在部分指標(biāo)上引入了同芯片經(jīng)驗閾值機(jī)制當(dāng)本次運行中通過采集足夠多時Burst/Drift等指標(biāo)會以通過樣本的經(jīng)驗分位數(shù)warn 為 90% 分位、fail 為 98% 分位替代固定閾值同芯片參考不足時回退到固定閾值tools/lib/dataset_quality/severity.py。值得注意的是Sep被刻意排除在經(jīng)驗閾值之外AUC 以 1.0 為上界且好配對緊貼天花板用底部分位數(shù)標(biāo)記會把近完美的錄制誤標(biāo)為離群因此配對分離度永遠(yuǎn)使用絕對下限tools/lib/dataset_quality/severity.py。外部參考潔凈度Ref 機(jī)制配對行與 Excluded Idle 行中的RefExc/RefBurst由 tools/lib/dataset_quality/references.py 實現(xiàn)從準(zhǔn)入的empty與static_presence排除長錄制中構(gòu)建 idle 參考塊按芯片 環(huán)境 鏈路/速率層stratum選擇參考——同環(huán)境參考 ≥3 條時優(yōu)先chipenvstratum否則退到chipstratum。目標(biāo)采集的 5 秒塊特征證據(jù)中超過參考 p95 的占比為RefExc超過參考 p99 的最長連續(xù)塊為RefBurst。這套機(jī)制正是 ADR 中弱鏈路與增益漂移采集保持可比的具體實現(xiàn)。后果收益、代價與取舍收益數(shù)據(jù)集質(zhì)量報告現(xiàn)在描述錄制本身而不是某個檢測器的啟動校準(zhǔn)弱鏈路與增益漂移采集保持可比因為核心指標(biāo)來自尺度不變共享特征被排除的配對可以保留為信息性診斷而不會重新引入檢測器偏差檢測器特有的問題仍然留在它們該在的地方性能與晉升門禁docs/performance/README.md。代價報告現(xiàn)在擁有一個小的特征證據(jù)層及其無閾值評分規(guī)則必須與共享特征語義保持對齊idle 采集的突發(fā)與漂移評審需要謹(jǐn)慎解讀它們概括的是特征空間行為而不是檢測器的二元告警。被否決的備選方案保留 Classic 評審、只刪掉標(biāo)記的閾值列否決。即使不標(biāo)出的回放表也會讓操作者錨定在某個檢測器的校準(zhǔn)路徑上把檢測器特有的失敗模式留在數(shù)據(jù)集質(zhì)量敘事中。在現(xiàn)有報告旁邊新建第二份 agnostic 報告否決。數(shù)據(jù)集質(zhì)量策略屬于一份生成文檔性能策略屬于docs/performance/README.md。直接用原始 RSSI 或絕對能量特征評分否決。這些量在增益變化或弱鏈路上不穩(wěn)健會重新引入本次變更要消除的可比性問題。如何在實踐中使用這份評審采集按 docs/ML_DATA_COLLECTION.md 的流程用./espectre collect --label empty|static_presence|motion --duration 60 --target ip采集并保持標(biāo)簽同質(zhì)。標(biāo)注元數(shù)據(jù)為data/dataset_info.json中每條新條目添加environment與顯式dataset_roletrain/selection/holdout/exclude。校驗運行python tools/validate_dataset_quality.py先解決準(zhǔn)入 FAIL評審分?jǐn)?shù)僅為診斷用途準(zhǔn)入失敗會阻斷工作流。讀報告查看data/auto_generated/DATASET_QUALITY_CHECK.md的 Pair / Presence / Empty / Long-recording / Excluded 各表關(guān)注Cover、Sep與RefExc/RefBurst配對表以及Exc、Burst、Tail、Driftidle 表Score只是緊湊的排序信號不是準(zhǔn)入依據(jù)。CI 化用--check-current讓報告與其輸入保持同步報告頭部同時記錄數(shù)據(jù)修訂與輸入修訂的 sha256。相關(guān)文檔數(shù)據(jù)采集與標(biāo)注見 docs/ML_DATA_COLLECTION.md訓(xùn)練與導(dǎo)出見 docs/ML_TRAINING.md特征定義見 docs/FEATURES.md檢測器晉升與性能門禁見 docs/performance/README.md訓(xùn)練/驗證加載器使用的 HT20 HT-LTF 64 子載波契約見 docs/CSI.md。【免費下載鏈接】espectreWi-Fi CSI motion sensing for ESP32. C SDK, ESPHome, Native, and Matter frontends, browser tools, and a CLI for the full device lifecycle. GPLv3 and commercial licensing.項目地址: https://gitcode.com/GitHub_Trending/es/espectre創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考