OpenMedKit Android 本地端临床 NLP 与 PHI 脱敏库：架构、隐私边界与 Android 集成指南

OpenMedKit Android 本地端临床 NLP 与 PHI 脱敏库架构、隐私边界与 Android 集成指南【免费下载链接】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导读OpenMedKit Androidandroid/openmedkit/是 OpenMed 项目的 Kotlin Android 库模块为 Android 应用提供完全在设备端运行的临床命名实体识别clinical NER与 HIPAA PII 脱敏能力。本指南将围绕该模块的 Gradle 工程结构、平台基线、隐私安全设计、ICU 分词边界方案、公共 Kotlin API、内置策略配置与模型管理展开讲解并结合源码实现说明其底层原理。读完本文你将掌握如何通过 JitPack 将 OpenMedKit 集成到自己的 Android 应用、如何使用analyzeText/extractPii/deidentify等核心 API、如何理解六套内置脱敏策略的语义以及该库零网络、零遥测、零原始 PHI 日志的设计是如何在代码层面被保证的。模块概览一个专为本地优先设计的 Android 库android/openmedkit/是一个标准的 Gradlecom.android.library模块隶属于顶层android/构建工程使用 Android 命名空间org.openmed.openmedkit。它不是一个独立应用而是供医疗健康类 Android 应用消费的 AAR 库。公共应用通过 JitPack 消费不可变的v2.3.0版本发布安装方式详见 Android 安装指南。从目录结构看模块的职责划分非常清晰src/main/kotlin/com/openmed/openmedkit/当前公共 Kotlin API 的全部实现按功能分包onnx/ONNX Runtime 令牌分类推理、加速器会话与推理错误类型decode/令牌分类结果解码与聚合策略merge/标签归一化、PII 实体合并与校验器deid/脱敏引擎与脱敏方法policy/策略配置文件加载器segmentation/基于 Android 平台 ICU 的文本分词边界适配intake/文档摄入、偏移映射与 PDF 页面渲染ocr/OCR 适配层含 ML Kit 适配器与测试用假适配器catalog/模型目录download/可选模型下载器与缓存util/PHI 安全的日志边界SafeLog。src/main/AndroidManifest.xml刻意保持最简的库清单。src/main/assets/policies/六套内置脱敏策略 JSON 配置。src/test/kotlin/com/openmed/openmedkit/本地 JVM 单元测试使用 JUnit 与 Robolectric 运行覆盖推理、解码、合并、脱敏、下载、OCR 偏移、分段、无网络推理、无 PHI 日志、API 奇偶校验等主题。平台基线minSdk 26 与 SDK 33 的取舍模块设置minSdk为 26即 Android 8.0。官方文档给出的理由是对于设备端临床工具库Android 8.0 是兼顾覆盖面与现代性的实用基线——既保持了广泛设备支持又允许后续工作依赖现代平台的安全、存储与运行时行为。模块当前针对 Android API 33 编译与仓库的 Java 11 本地开发基线保持一致见 android/README.md。本地构建环境需要 JDK 11 与 Android SDK Platform 33然后执行cd android ./gradlew testAndroid CI 门禁还会构建 release AAR并测量离线库初始化耗时打包目录加载 下载器/缓存初始化cd android ./gradlew :openmedkit:verifyAndroidBudgets --continue可审查的预算上限声明在 gradle/budgets.properties测量结果写入openmedkit/build/reports/budgets/并发布到 CI 任务摘要。依赖解析被限制在 Google Maven、Maven Central 与 JitPack 上 scoped 的 OpenMed 组依赖与插件版本统一声明在 gradle/libs.versions.toml避免在模块构建文件中硬编码版本号。隐私与安全零网络、零遥测、零原始 PHI 日志OpenMedKit Android 的核心设计定位是本地优先local-first、设备端on-device处理。库代码默认不得向网络服务发送受保护健康信息PHI、不得要求遥测、不得将原始 PHI 写入日志、缓存、临时文件、分析事件或审计产物。推理路径不开网络analyzeText、extractPii、deidentify三条推理路径只操作调用方提供的设备端模型资产不打开 socket 也不发起 HTTP 调用。可选的模型下载器是独立的、显式的推理前操作永远不会被推理逻辑调用。这一承诺在清单层面得到落实src/main/AndroidManifest.xml 整个文件只有一行且不请求android.permission.INTERNET权限。测试层对此有专门的验证NoNetworkInferenceTest.kt 用于在测试中确认推理路径无网络访问行为。SafeLog类型化的 PHI 安全日志边界内部推理诊断默认关闭。库代码只能通过类型化的SafeLog边界发出诊断信息该边界只接受标签、Unicode 偏移量与 SHA-256 跨度哈希——不允许任意消息或检测出的原始表面文本。相关实现见 SafeLog.ktSafeLogOperation枚举定义了四种推理操作ANALYZE_TEXT、EXTRACT_PII、EXTRACT_PII_CHUNKED、DEIDENTIFYSafeLogSpan只包含label、start、end和textSha256四个字段构造时对 label 施加正则校验[A-Za-z0-9_.:-]{1,128}、对 start/end 施加边界校验、对textSha256施加 64 位小写十六进制 SHA-256 校验SafeLog的默认 sink 为null因此除非内部宿主集成显式安装 sink库默认不产生任何日志或遥测实体在到达日志边界前会先通过toSafeLogSpan()转换将原始文本替换为sha256Hex(text)从而保证有溯源、无原文。脱敏动作记录同样只留元数据脱敏动作记录保留溯源与替换元数据但不保留原始标识符。在 DeidentifyEngine.kt 中每个作用跨度最终都会带上canonicalLabel、textHashHMAC-SHA256 摘要、action与replacement原始表面文本只作为处理过程的中间量参与计算不会进入结果记录。明确的边界声明该模块仅限设备端使用。它不是医疗器械不提供诊断、治疗决策或紧急临床指导。任何未来的临床工作流集成都必须在脚手架之外保留人工审查与适当的监管评估。ICU 边界分词复用平台 ICU不捆绑运行时生产环境的词边界与字素grapheme边界使用 Android 平台自带的android.icu.text.BreakIterator因此 AAR 中不需要捆绑任何词典或额外运行时。本地 JVM 奇偶校验测试则使用com.ibm.icu:icu4j:78.3作为仅测试用依赖验证 JVM 结果与 Android 平台 ICU 一致。实现细节见 TextSegmentationAdapter.ktTextSegmentationAdapter接口定义了graphemeBoundaries(text, locale)与wordBoundaries(text, locale)两个方法AndroidIcuTextSegmentationAdapter是生产实现直接包装BreakIterator.getCharacterInstance(locale)与BreakIterator.getWordInstance(locale)适配器边界内部使用 UTF-16Android ICU 与 ICU4J 都暴露原生 JVM 索引但IcuTextSegmenter会把所有公共结果转换到共享的 Unicode 标量偏移契约针对中文HAN、印地语Devanagari、泰米尔语Tamil等无空白脚本路径fallbackWordSegments提供确定性兜底若平台词迭代器无法切分无空白文本则退化为完整字素簇作为最后手段全程不依赖应用捆绑词典代码还针对九种印度文字脚本的 virama joiner 组合做了窄幅调整isIndicConjunctBoundary以满足 OpenMed 共享字素契约在 fixture 脚本上的要求。ICU4J 采用宽松的 Unicode Data Files and Software LicenseUnicode-3.0又称 ICU/Unicode License。该依赖仅用于验证 JVM 结果与 Android 平台 ICU 一致不是运行时依赖也不会在设备外处理文本。对应的 JVM 测试适配实现见 Icu4jTextSegmentationAdapter.kt 与 IcuSegmentationFallbackTest.kt。公共 Kotlin API从本地模型目录到脱敏结果OpenMedKit见 OpenMedKit.kt是公共 Kotlin 门面facade组合了四个核心组件OnnxTokenClassifierONNX 令牌分类器、TokenClassificationDecoder解码器、PiiEntityMerger实体合并器与DeidentifyEngine脱敏引擎。从目录加载模型OpenMedKit.fromDirectory(modelDirectory, variant)是加载 OpenMed 导出的 ONNX 模型目录的入口其中variant决定加载哪个模型文件variant文件名int8默认model_int8.onnxfp32model.onnxfp16model_fp16.onnx传入其他值会抛出IllegalArgumentException(variant must be int8, fp32, or fp16)。公共常量OpenMedKit.VERSION 2.3.0与文档中的发布版本保持一致。此外还支持带显式 Android 执行提供方选项的构造函数AcceleratorConfig用于在支持的环境下启用 GPU/NNAPI 等加速执行提供方相关加速会话实现见 AcceleratorSession.kt。analyzeText令牌分类 置信度过滤suspend fun analyzeText( text: String, confidenceThreshold: Float 0.5f, ): ListEntityPrediction流程classifier.predict(text)得到令牌级预测 →decoder.decode(predictions, text)解码为实体 → 按confidence confidenceThreshold过滤阈值必须落在0.0f..1.0f否则抛异常→ 按偏移排序 → 记录 PHI 安全日志。extractPii跨度修复 智能合并suspend fun extractPii( text: String, confidenceThreshold: Float 0.5f, useSmartMerging: Boolean true, ): ListEntityPrediction在analyzeText的基础上先执行SpanRepair.repair修复跨度边界再按需用PiiEntityMerger.merge进行智能合并。合并逻辑涉及标签归一化与去重详见 LabelNormalizer.kt 与 PiiEntityMerger.kt。extractPiiChunked长文本分窗推理suspend fun extractPiiChunked( text: String, confidenceThreshold: Float 0.5f, chunkTokenLimit: Int 256, tokenOverlap: Int 32, useSmartMerging: Boolean true, ): ListEntityPrediction用于超出模型窗口长度的长文本。其内部makeTokenChunks按令牌边界切分窗口默认每窗 256 令牌、窗间重叠 32 令牌每个分窗独立做extractPii再通过UnicodeOffsetContract.utf16ToScalarOffset将各窗结果映射回原始完整输入文本的标量偏移最后合并、去重deduplicateOverlappingEntities依据重叠比例 ≥0.5 判定重复候选并择优保留。所有返回偏移始终引用原始全文这是与 Swift 端共享的偏移契约见 UnicodeOffsetContract.kt。deidentify按策略执行脱敏suspend fun deidentify( text: String, policy: String PolicyProfiles.DEFAULT_PROFILE, // hipaa_safe_harbor confidenceThreshold: Float 0.5f, useSmartMerging: Boolean true, ): PolicyDeidentificationResult未指定策略时OpenMedKit 使用文档化的hipaa_safe_harbor默认策略。流程为PolicyProfiles.load(policy)加载内置策略 →extractPii(...)提取实体 →deidentifyEngine.deidentify(text, entities, profile)执行脱敏。与 Swift 对齐的公共面同一文件还提供了与 Swift OpenMedKit 对齐的OpenMed入口类、OpenMedMLXModelCacheStatemissing/partial/ready枚举与OpenMedModelStore对象保证跨平台 API 形态一致。跨平台奇偶性由 ApiParityTest.kt、OffsetContractParityTest.kt 与 SpanEquivalenceTest.kt 等测试守护。ONNX 推理层令牌分类器的运行时细节OnnxTokenClassifier.kt 封装了 ONNX Runtimeai.onnxruntime的令牌分类推理输入张量input_ids、attention_mask若模型存在token_type_ids输入名则自动补零张量元素类型支持INT64默认与INT32输出logits要求批次维度为 1、序列长度与偏移数一致解码对每个令牌取 logits 最大值对应的 label id并用 softmax含数值稳定的 max 平移计算置信度分数intraOpThreadCount默认 1必须大于 0id2label从 JSON 对象文件加载键必须是整数且映射不能为空特殊令牌如[CLS]、[SEP]通过TokenOffset.isSpecialToken跳过不参与实体解码run使用withContext(Dispatchers.Default)保证推理在后台调度器执行并协作式响应协程取消ensureActive。资源释放方面close()会依次关闭 session 与自持有的环境任何关闭失败都会被聚合抛出。加速器回退行为由 AcceleratorFallbackTest.kt 覆盖。脱敏引擎从右到左的替换与重叠解决DeidentifyEngine.kt 是脱敏重写的核心。其设计要点从右到左应用替换引擎接受原始文本偏移并按 span 排序后逆序执行StringBuilder.replace这样即使前面 span 的替换导致输出变长或变短每个 span 仍能在原始偏移处被正确替换重叠解决resolveOverlaps按 start 升序、end 降序、score 降序排序重叠区间内按置信度分数、长度、起始位置依次裁决标签四种脱敏方法见 DeidentifyMethod.kt方法行为示例输出MASK替换为带标签的方括号令牌[PERSON]、[PERSON_2]REMOVE删除原文REPLACE替换为代理令牌PERSON_SURROGATE、PERSON_SURROGATE_2HASH替换为 HMAC-SHA256 摘要hmac-sha256:64位hex确定性令牌分配ReplacementState对相同 (方法, 标签, 表面文本) 组合复用同一替换令牌同时按标签维护计数器生成_2、_3后缀可配置盐构造函数接受hashSalt默认openmed-android-deidentify-v1HMAC 载荷为label\0surface输出带hmac-sha256:前缀。策略系统六套内置 OM-031a 脱敏策略PolicyProfiles.kt 负责加载src/main/assets/policies/下的六套策略 JSON策略文件用途hipaa_safe_harbor.jsonHIPAA 安全港Safe Harbor脱敏默认策略hipaa_expert_review_assist.jsonHIPAA 专家评审辅助gdpr_pseudonymization.jsonGDPR 假名化支持别名gdprresearch_limited_dataset.json研究用受限数据集strict_no_leak.json严格无泄漏strict_no_leak: true时任何 KEEP 动作都被强制提升为 MASKclinical_minimal_redaction.json临床最小脱敏策略 JSON 使用schema_version: 1核心字段包括posture策略姿态标识如hipaa_safe_harbor_deidentificationthreshold_profile与arbitration_mode置信度阈值配置与仲裁模式default_action与default_action_bias默认动作及偏置keep/redact/replace/mask/remove/hash见PolicyAction枚举strict_no_leak、safety_sweep_mandatory、keep_mapping、reversible_id泄漏防护、安全清扫、映射保留与可逆 ID 开关forced_cascade_tiers强制级联层级如[R0, R1, R2]policy_label_actions针对三大策略标签DIRECT_IDENTIFIER/QUASI_IDENTIFIER/CLINICAL_CONCEPT的动作actions针对具体规范标签如PERSON、SSN、CREDIT_CARD、DATE_OF_BIRTH的动作映射。动作解析顺序为actions[canonicalLabel]→policyLabelActions[policyLabel]→defaultAction。标签归一化支持 B/I/E/S 前缀剥离、别名映射如name→PERSON、dob→DATE_OF_BIRTH、mrn/id→ID_NUM、ssn→SSN以及直接标识符/准标识符/临床概念三大类的分类。以默认的hipaa_safe_harbor.json为例配置文件default_action为masksafety_sweep_mandatory为truepolicy_label_actions与全部actions均为mask——即默认把所有检测到的 PHI 跨度统一替换为[LABEL]形式的遮蔽令牌符合安全港彻底移除 18 类标识符的精神。可选模型下载器显式的推理前操作ModelDownloader.kt 是可选的 Hugging Face 模型资产下载器与推理路径完全解耦下载前先核对可复现性哈希ModelIntegrity.reproducibilityHash对 repo_id、revision sha、released 日期与排序后的 siblings 文件列表做 SHA-256与模型目录条目中声明的哈希不一致则抛出ModelIntegrityException只下载 Android 可运行文件ONNX/TFLite 权重.onnx、.ort、.onnx_data、.tflite与必要的 sidecar 文件tokenizer.json、vocab.json、config.json等跳过.gitattributes、readme.md与 license 文件下载后校验文件大小与 SHA-256 校验和写入前先落 staging 目录全部验证通过后才storeReadyModel提交为 ready 状态失败则清理 staging 目录路径解析做了穿越防护拒绝.、..、反斜杠且要求解析后的 canonical 路径必须位于缓存根目录内默认缓存预算见ModelCache.DEFAULT_CACHE_BUDGET_BYTES支持缓存命中直接返回。同样重要的是下载器默认使用ModelDownloadLogger.NONE即不产生日志而推理本身永远不调用该下载器。这与文档可选模型下载器是独立、显式的推理前操作的表述完全一致。R8 / ProGuard 与发布OpenMedKit AAR 内置了针对 ONNX Runtime 与 DJL 原生绑定、服务加载的 tokenizer provider 以及模型目录边界的 consumer rules见 consumer-rules.pro。消费应用启用压缩或混淆时R8 与 ProGuard 会自动应用这些规则无需额外添加 OpenMedKit keep 规则。发布打包检查会验证每条规则都出现在打包后的proguard.txt中cd android ./gradlew :openmedkit:verifyReleaseConsumerRulesJitPack 是文档化的公共安装路径解析不可变的v2.3.0标签并发布openmedkitAndroid release 组件为 AAR公共消费者无需 GitHub 凭据另有可选的 Maven Central 发布路径仅在配置了签名与 Sonatype 凭据ANDROID_SIGNING_KEY、ANDROID_SIGNING_KEY_PASSWORD、SONATYPE_USERNAME、SONATYPE_PASSWORD时上传签名 bundle。安装与消费在消费应用的settings.gradle.kts中添加 JitPack 仓库限定 OpenMed 组dependencyResolutionManagement { repositories { google() mavenCentral() maven { url uri(https://jitpack.io) content { includeGroup(com.github.maziyarpanahi) } } } }然后添加v2.3.0坐标dependencies { implementation(com.github.maziyarpanahi:openmed:v2.3.0) }仅当有意测试未发布构建时才使用 commit 坐标。配套 Demo 与延伸阅读OpenMedScanDemo演示 CameraX 采集、设备端 OCR 与高亮标识符脱敏OCR 适配层见 MlKitOcrAdapter.ktOpenMedMapleDemo离线 Maple 临床工作室覆盖 PII 脱敏、实体抽取、关系抽取与溯源推理/对话支持无权重合成预览模式与固定校验和的 ONNX Runtime Mobile bundleandroid/README.md安装、本地构建、预算门禁与发布说明。本文描述的所有行为均可在当前仓库源码与测试中验证无网络推理由 NoNetworkInferenceTest.kt 守护无 PHI 日志由 NoPhiLoggingTest.kt 守护脱敏引擎行为由 DeidentifyEngineTest.kt 覆盖。OpenMedKit Android 的意义在于将临床 NLP 与 PHI 脱敏能力完整下沉到设备端让患者数据在网络边界之内完成处理。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考