OpenMed OMOP 隊列導出校驗器零網(wǎng)絡的關系、詞匯與溯源不變量本地校驗實戰(zhàn)【免費下載鏈接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0項目地址: https://gitcode.com/GitHub_Trending/ope/openmedOpenMed 為臨床文本到 OMOP CDM 的本地隊列導出鏈路提供了一個確定性的、完全離線的結(jié)構(gòu)校驗器omop_cohort_check。本文以 docs/integrations/omop-cohort-check.md 為核心結(jié)合 實現(xiàn)源碼、OMOP 加載器 與 單元測試 展開讀完你可以掌握校驗器的輸入輸出形態(tài)、它驗證的三類不變量、16 種違規(guī)原因的完整語義、PHI-free 報告的讀取方式以及如何在加載-校驗-持久化管線中把它當作 fail-closed 的質(zhì)量門禁使用。一、為什么需要一個獨立的隊列導出校驗器OpenMed 的本地互操作鏈路會把“grounded clinical note spans”通過 Athena/Usagi 風格的詞匯路由轉(zhuǎn)換成 OMOP CDM 表完整流程見 FHIR 與 OMOP 互操作指南 中的grounded spans - ... - Athena/Usagi routing - OMOP CDM tables。在這一步之后隊列研究者通常需要把 CDM 表導出給下游消費方而此時任何一條破損的關系、錯誤的詞匯映射或斷裂的溯源鏈都會靜默污染后續(xù)的隊列分析、統(tǒng)計建?；蚝弦?guī)審計。openmed.interop.omop_cohort_check正是為此設計的本地校驗器它只操作內(nèi)存中的 OMOP 行從模塊 docstring 開始就明確聲明“intentionally has no network, database, or vocabulary-service dependency”。也就是說不發(fā)起任何網(wǎng)絡調(diào)用不訪問數(shù)據(jù)庫不依賴外部詞匯服務校驗行為完全確定deterministic對相同輸入無論映射的迭代順序如何產(chǎn)出完全相同校驗輸出的報告永遠不含源標識符、筆記文本或任何行值只含表名、列名、聚合計數(shù)與穩(wěn)定的行指紋。它要回答的問題非常聚焦這份即將導出的 OMOP 隊列在**關系relationships、詞匯vocabulary、溯源provenance**三個維度上是否自洽、是否可被下游安全消費。二、快速上手從加載器到校驗報告校驗器直接對接加載器返回的OmopCdmTables文檔給出的最小用法如下from openmed.interop.omop import load_grounded_notes from openmed.interop.omop_cohort_check import validate_omop_cohort_export tables load_grounded_notes(synthetic_notes) report validate_omop_cohort_export(tables) if not report.is_valid: print(report.to_dict())其中l(wèi)oad_grounded_notes(notes, *, vocabulary_versionNone, vocabulary_routerNone, modeappend)是 cdm_loader.py 提供的 OMOP CDM v5.4 內(nèi)存加載器接收帶start/end偏移與概念編碼的實體 span產(chǎn)出按主鍵排序的內(nèi)存 CDM 表校驗器拿到OmopCdmTables后即可直接校驗。三種可接受的輸入形態(tài)從validate_omop_cohort_export的簽名源碼 L397-L420可以看到除OmopCdmTables實例外它還接受兩種等價形態(tài)輸入形態(tài)說明OmopCdmTables加載器返回的內(nèi)存表容器tables字段 聚合summaryMapping[str, Iterable[Mapping[str, Any]]]表名 → 行可迭代對象的普通映射如{person: [{person_id: 1, ...}], ...}OmopCdmTables.to_dict()返回的嵌套映射含tables鍵的映射內(nèi)部會自動解包缺失的表按空表處理不影響其它表的校驗但傳入的表名若不在受支持的 11 張表清單內(nèi)會直接拋錯。為兼容不同調(diào)用習慣模塊還提供了check_omop_cohort_export與validate_cohort_export兩個等價的別名函數(shù)源碼 L438-L451以及報告類型的別名OmopCohortCheckReport/OmopCohortExportReport。一個完整的端到端示例結(jié)合測試中的合成數(shù)據(jù)形態(tài)test_omop_cohort_check.py L22-L83可以構(gòu)造一份可直接運行的最小導出并完成校驗from openmed.interop.omop_cohort_check import validate_omop_cohort_export export { concept: [ {concept_id: 0, vocabulary_id: UNMAPPED, standard_concept: }, {concept_id: 10, vocabulary_id: SYNTHETIC, standard_concept: S}, {concept_id: 20, vocabulary_id: SYNTHETIC, standard_concept: }, ], person: [{person_id: 1, person_source_value: synthetic-person}], visit_occurrence: [{visit_occurrence_id: 2, person_id: 1}], note: [ { note_id: 3, person_id: 1, visit_occurrence_id: 2, source_note_hash: a * 64, } ], note_nlp: [{note_nlp_id: 4, note_id: 3, note_nlp_event_id: 5}], condition_occurrence: [ { condition_occurrence_id: 5, person_id: 1, condition_concept_id: 10, condition_source_concept_id: 20, visit_occurrence_id: 2, note_id: 3, note_nlp_id: 4, source_note_hash: a * 64, } ], source_to_concept_map: [ { source_to_concept_map_id: 6, source_code: SYN-CODE, source_concept_id: 20, source_vocabulary_id: SYNTHETIC, target_concept_id: 10, target_vocabulary_id: SYNTHETIC, note_nlp_id: 4, source_note_hash: a * 64, } ], } report validate_omop_cohort_export(export) print(report.is_valid) # True print(report.row_counts[condition_occurrence]) # 1這段合成數(shù)據(jù)覆蓋了校驗器關心的核心鏈條note_nlp_event_id指向condition_occurrence的事件行、source_to_concept_map同時掛到note_nlp與溯源哈希、standard_conceptS的標準概念引用。對應測試test_validates_relationship_vocabulary_and_provenance_invariants斷言其is_valid is True且by_table/by_reason均為空。三、校驗范圍三類不變量校驗器驗證的不變量并非任意規(guī)則而是圍繞 OMOP CDM v5.4 表結(jié)構(gòu)加載器 DDL 中 11 張 loader-owned 表的_SQL_DDL設計的三組約束。1. 關系不變量主鍵唯一 外鍵可達 person/visit 一致受支持的 11 張表及主鍵源碼_PRIMARY_KEYS為表主鍵conceptconcept_idpersonperson_idvisit_occurrencevisit_occurrence_idnotenote_idnote_nlpnote_nlp_idcondition_occurrencecondition_occurrence_iddrug_exposuredrug_exposure_idmeasurementmeasurement_idprocedure_occurrenceprocedure_occurrence_idobservationobservation_idsource_to_concept_mapsource_to_concept_map_id校驗器先建立全表主鍵索引_build_primary_indexes再對以下外鍵關系做可達性檢查_validate_relationships必填外鍵visit_occurrence.person_id → person、note.person_id → person、note_nlp.note_id → note以及五個域表condition/drug/measurement/procedure/observation的person_id → person條件必填外鍵僅當該列出現(xiàn)在任何一行時啟用由_field_enabled判斷visit_occurrence.visit_concept_id → concept、note.visit_occurrence_id → visit_occurrence、域表與source_to_concept_map的note_id/note_nlp_id鏈接概念引用五個域表的*_concept_id與*_source_concept_id必須指向存在的concept行note、note_nlp、source_to_concept_map各自的*_concept_id列同理person/visit 一致性_validate_person_visit_consistencynote與五個域表如果同時給出visit_occurrence_id和person_id則該 visit 行所屬的 person 必須與行內(nèi) person 一致否則記為person_visit_mismatch。重復主鍵有一個關鍵語義被判定重復的主鍵全部計入違規(guī)且不會進入主鍵索引——即重復鍵所在行不能作為任何外鍵關系的目標。對應測試test_duplicate_primary_keys_are_all_flagged_and_not_referenceable驗證兩行person_id1的 person 記錄各記一次duplicate_primary_key而引用它的visit_occurrence行因目標不可達再記一次missing_reference。2. 標識符與主鍵的嚴格規(guī)則主鍵與關系標識符必須無損地落在有符號 64 位整數(shù)范圍內(nèi)_MIN_BIGINT -(2**63)到_MAX_BIGINT 2**63 - 1見 源碼_identifier。合法形態(tài)只有兩種原生整數(shù)或可無損解析的整數(shù)字符串解析前會 strip 空白。以下情況一律視為非法標識符缺失列不存在→missing_primary_keynull / 空字符串→ 按缺失處理浮點數(shù)如1.5→ 非法布爾值True/False會被特殊攔截避免與1/0混淆→ 非法超出 ±2^63 范圍如2**63→ 非法非數(shù)字字符串→ 非法。對應測試test_missing_and_lossy_primary_keys_are_rejected驗證None、1.5、2**63三種輸入分別產(chǎn)出missing_primary_key× 1 與invalid_primary_key× 2。3. 詞匯不變量標準概念、詞表一致性與映射唯一性詞匯校驗_validate_vocabulary圍繞concept.standard_concept、域表的概念引用與source_to_concept_map展開standard_concept枚舉允許值僅、C、N、S源碼_ALLOWED_STANDARD_CONCEPTS其它值記invalid_standard_concept標準概念引用約束域表行引用的 concept 若聲明了standard_concept只允許或S即標準概念引用CClassification或NNon-standard記nonstandard_concept_reference詞表一致性source_to_concept_map中聲明source_vocabulary_id/target_vocabulary_id時必須與 concept 行的vocabulary_id一致否則記vocabulary_mismatch目標概念必須標準target_concept_id ! 0時目標 concept 的standard_concept只能為或S否則記nonstandard_target_concept映射唯一性同一(source_vocabulary_id, source_code)對只允許映射到唯一目標概念多個不同目標記conflicting_vocabulary_mapping。4. 溯源不變量NOTE/NOTE_NLP 溯源鏈OpenMed 的 OMOP 導出帶有一條獨有的溯源鏈provenance chain每篇臨床筆記對應一個source_note_hash64 位小寫十六進制 SHA-256域表行與source_to_concept_map行通過note_id、note_nlp_id和source_note_hash回連到note/note_nlp。校驗器_validate_provenance會檢查哈希格式source_note_hash必須匹配[0-9a-f]{64}否則記invalid_provenance必填性當某表任一行的溯源字段啟用時所有行都必須補齊note_id/note_nlp_id/source_note_hash缺失記missing_provenance哈希一致性域表行的source_note_hash必須與所掛note行的哈希一致否則記provenance_mismatch事件鏈接note_nlp.note_nlp_event_id必須恰好解析到一個域表事件行——解析不到記unreachable_event解析到多個例如同一事件同時掛 condition 與 drug 行記ambiguous_event且該域表行的note_nlp_id必須與note_nlp行自身、以及note_nlp.note_id與域表行的note_id全部對齊。四、報告結(jié)構(gòu)只有計數(shù)、表名列名與行指紋校驗產(chǎn)物是OmopCohortValidationReport凍結(jié) dataclass其to_dict()輸出結(jié)構(gòu)源碼 L296-L305為{ count: 違規(guī)總行數(shù), row_counts: {concept: ..., person: ..., ...}, # 11 張表各自行數(shù) by_table: {condition_occurrence: 2, ...}, # 按表聚合的失敗數(shù) by_reason: {missing_reference: 2, ...}, # 按原因聚合的失敗數(shù) violations: [ { table: condition_occurrence, column: visit_occurrence_id, # 可能缺失 reason: missing_reference, count: 2, row_fingerprints: [sha256:..., ...], }, # ... ], }報告對象還暴露is_valid與兼容別名valid、violation_count與failure_count/failures同義、by_table、by_reason等只讀屬性。每條OmopCohortViolation是按 (表, 列, 原因) 分組聚合的count是精確的失敗行數(shù)row_fingerprints是被影響的行的去重指紋集合。行指紋確定性且可關聯(lián)omop_row_fingerprint(table, row)源碼 L365-L394對每行計算sha256:前綴的確定性指紋序列化載荷帶固定 schema 標記openmed.omop.cohort-check.v1與表名同名行在不同表不會共享指紋JSON 序列化使用sort_keysTrueseparators(,, :)因此行內(nèi)鍵順序不影響指紋——對應測試驗證{b: 2, a: 1}與{a: 1, b: 2}指紋相同規(guī)范化_canonicalize會區(qū)分類型1與1是不同的映射鍵非有限浮點數(shù)被轉(zhuǎn)換為{type: float, value: ...}形式集合類型排序后參與序列化。重要邊界由于指紋是內(nèi)容的確定性摘要內(nèi)容完全相同的兩行會得到相同指紋——指紋可被用來跨批次關聯(lián)同一行例如定位“上次也失敗的那條記錄”因此官方文檔明確要求把它當作診斷元數(shù)據(jù)diagnostic metadata而非匿名化數(shù)據(jù)對待不能因為“只見指紋不見原文”就視為已匿名。報告與異常中永不出現(xiàn)源標識符person_source_value之類、note_text筆記文本、lexical_variant原文片段或任何行值。對應測試test_reports_deterministic_counts_and_fingerprints_without_source_values斷言序列化后的報告不包含synthetic-note corpus value與synthetic-person。五、違規(guī)原因目錄16 種可枚舉的失敗類型源碼_VIOLATION_REASONSL97-L116將失敗原因收斂為封閉集合報告與異常中的reason只會取以下值原因所屬維度含義missing_primary_key標識符主鍵列缺失或為 nullinvalid_primary_key標識符主鍵非無損 64 位整數(shù)浮點/越界/布爾/非數(shù)字duplicate_primary_key標識符主鍵重復所有重復行均計入且不可作引用目標missing_reference關系必填外鍵缺失或指向不存在的目標invalid_reference關系外鍵值本身非法person_visit_mismatch關系行內(nèi) person 與其 visit 所屬 person 不一致invalid_standard_concept詞匯standard_concept取值不在/C/N/Snonstandard_concept_reference詞匯域表概念引用了非標準概念nonstandard_target_concept詞匯映射目標概念非標準vocabulary_mismatch詞匯聲明的詞表與 concept 行vocabulary_id不一致conflicting_vocabulary_mapping詞匯同一 (詞表, 源編碼) 映射到多個目標missing_provenance溯源溯源字段啟用但行內(nèi)缺失invalid_provenance溯源source_note_hash不是 64 位小寫 SHA-256provenance_mismatch溯源域表/映射行的哈希或事件鏈接與 note/note_nlp 不一致unreachable_event溯源note_nlp_event_id解析不到任何域表事件行ambiguous_event溯源note_nlp_event_id解析到多個域表事件行這條封閉枚舉既是契約也是安全機制OmopCohortViolation/OmopCohortValidationReport在__post_init__中會拒絕任何不在此集合內(nèi)的表名、列名或原因?qū)獪y試test_public_report_types_reject_untrusted_diagnostic_labels從類型層面杜絕任意字符串混入診斷輸出。六、Fail-closed斷言輔助函數(shù)與異常語義如果只想在導出管線中做“不合格即中止”的硬門禁用斷言輔助函數(shù)文檔示例from openmed.interop.omop_cohort_check import assert_valid_omop_cohort_export assert_valid_omop_cohort_export(tables)行為源碼 L454-L462校驗通過靜默返回OmopCohortValidationReport校驗失敗拋出OmopCohortExportValidationErrorValueError子類該異常攜帶完整聚合報告exc.report但異常消息只有一行聚合信息——OMOP cohort export validation failed with N row-level failure(s)其中N是失敗的行級不變量總數(shù)各違規(guī)count之和絕不內(nèi)嵌任何行值。對應測試test_row_fingerprints_are_canonical_and_validation_errors_are_phi_free驗證異常字符串中不包含任何合成數(shù)據(jù)值synthetic不出現(xiàn)且exc.report.is_valid is False。這種設計保證異?？梢园踩剡M入日志、監(jiān)控與 CI 輸出而不泄露 PHI。七、內(nèi)部實現(xiàn)管線四步確定式校驗從源碼_validate_omop_cohort_exportL423-L435可以看到完整管線_normalise_tables ── _build_primary_indexes ── _validate_relationships ── _validate_vocabulary ── _validate_provenance ── collector.report(row_counts)規(guī)范化_normalise_tables把OmopCdmTables/ 普通映射 /to_dict()輸出統(tǒng)一成{表名: (行, ...)}表名轉(zhuǎn)小寫并校驗合法性行必須是映射、列名必須是字符串非法表名、非法行、不可迭代行都會拋錯缺失表補為空元組。主鍵索引_build_primary_indexes逐表解析主鍵標識符把缺失/非法/重復三類問題直接送入_FailureCollector僅把“唯一且合法”的主鍵放入索引供后續(xù)外鍵查找。三組校驗按關系 → 詞匯 → 溯源的固定順序執(zhí)行所有失敗都經(jīng)由_FailureCollector.add(table, row, reason, column)聚合——它只保留(表, 列, 原因) → 指紋計數(shù)器三元組從源頭保證報告無行值。產(chǎn)出報告_FailureCollector.report()按表順序_TABLE_ORDER與 (表, 列, 原因) 字典序穩(wěn)定排序生成凍結(jié)的OmopCohortValidationReport。錯誤邊界面對敵意輸入也不泄漏校驗器對“無法安全處理”的輸入采取有界錯誤策略模塊 docstring 明確errors are bounded and never copy the source value無法迭代的行容器如__iter__直接拋異常的類→ 歸一化階段捕獲并轉(zhuǎn)為ValueError(cohort export table rows must be iterable)異常__cause__被清除原始異常消息不會透出test_hostile_row_iterators_fail_without_echoing_source_values斷言消息長度 100 字符循環(huán)引用行row[nested] row→ 指紋階段通過id()標記檢測環(huán)并拒絕_canonicalize的_active集合深度過深嵌套層級超過_MAX_CANONICAL_DEPTH 64→ 拒絕并報告有界錯誤__str__拋異常的敵意值、非有限浮點數(shù) → 規(guī)范化階段安全降級指紋計算整體被 try/except 包裹任何異常統(tǒng)一轉(zhuǎn)為ValueError(OMOP row cannot be fingerprinted safely)且指紋只是計算時的中間量從不回傳或嵌入異常。對應測試test_hostile_and_cyclic_rows_fail_without_echoing_source_values用RAW-SYNTHETIC-PATIENT哨兵值驗證循環(huán)行、65 層嵌套、拋異常的__str__值在異常消息中均不出現(xiàn)。八、與加載器及持久化組合完整質(zhì)量門禁校驗器不是孤立組件它可以與加載器/寫入器的其它質(zhì)量工具組合成完整鏈路加載load_grounded_notes(...)或load_grounded_jsonl(path, ...)產(chǎn)出OmopCdmTables加載器內(nèi)部還會拒絕缺失 offset、無效 offset、不支持域名的實體 span見 cdm_loader.py內(nèi)存校驗validate_omop_tables(tables)嚴格的行形狀 主鍵 概念引用 NOTE_NLPoffset 邊界 事件雙向可達性校驗或本文主角validate_omop_cohort_export(tables)持久化write_omop_duckdb/write_omop_sqlite/write_omop_parquet按主鍵冪等合并寫入modereplace_by_note時先刪除對應筆記哈希的歷史行庫級復核對已落庫的 DuckDB/SQLite 連接執(zhí)行validate_omop_database(con)或validate_omop_database_report(con)用同一套 PHI-free 違規(guī)形狀復核持久化結(jié)果源碼validate_omop_databaseL1261-L1285。推薦的 CI/批處理模式from openmed.interop.omop import ( load_grounded_jsonl, validate_omop_database_report, write_omop_duckdb, ) from openmed.interop.omop_cohort_check import assert_valid_omop_cohort_export tables load_grounded_jsonl(grounded_notes.jsonl) assert_valid_omop_cohort_export(tables) # fail-closed 內(nèi)存門禁 con write_omop_duckdb(tables, cohort.duckdb) report validate_omop_database_report(con) # 落庫后復核 assert report.is_valid, report.to_dict()OmopCdmTables.load_event()還能產(chǎn)出僅含哈希與計數(shù)的OmopLoadEvent供下游OmopDownstreamConsumer在持久化成功后安全訂閱事件里只有changed_note_hashes與row_counts永遠沒有筆記文本。九、定位與邊界結(jié)構(gòu)校驗 ≠ 合規(guī)認證最后必須明確校驗器的定位文檔結(jié)尾與模塊 docstring 反復強調(diào)它驗證的是結(jié)構(gòu)質(zhì)量structural quality主鍵、外鍵、詞匯標注、溯源鏈是否自洽它不是合規(guī)認證也不能替代臨床決策保障——OpenMed 不內(nèi)置 Athena、UMLS、SNOMED CT、CPT 等受限詞表內(nèi)容見 FHIR/OMOP 互操作指南概念編碼的臨床正確性由上游 grounded spans 與用戶自帶的詞匯路由負責報告中的指紋是診斷元數(shù)據(jù)而非匿名數(shù)據(jù)相同內(nèi)容行可被關聯(lián)處理時需按受控診斷信息對待校驗器只檢查當前內(nèi)存導出的自洽性跨批次增量合并append / replace_by_note的最終一致性由 加載器寫入邏輯 與庫級validate_omop_database_report共同兜底與 FHIR 側(cè)的關系可參考 FHIR-OMOP 互操作矩陣 了解雙向映射的覆蓋情況。在本地優(yōu)先local-first的 OpenMed 設計里omop_cohort_check的價值正在于它把“導出前最后一公里”的質(zhì)量檢查變成了一次無網(wǎng)絡、無依賴、無 PHI 泄漏的純函數(shù)調(diào)用——任何一個批處理作業(yè)、Airflow DAG 或 CI 管道都可以在幾行代碼內(nèi)把它變成一張確定性的、可審計的隊列質(zhì)量門禁。【免費下載鏈接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0項目地址: https://gitcode.com/GitHub_Trending/ope/openmed創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考