OpenMed 2.1 到 2.2 迁移指南API 兼容边界、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本篇指南面向正在使用或计划升级 OpenMed 的开发者完整解析从v2.1.0到v2.2.0的公开兼容边界如何用仓库内置的静态 API 对比工具复现兼容性结论、逐条执行升级检查清单、理解SnapshotManifest与VocabularySnapshotManifest等保留名称的语义变化以及 Maple、Compass、FHIR/OMOP 交换、结构化隐私等新增能力的采用前提。读完本文你将掌握一次零破坏版本升级的完整验证路径并知道哪些新增 API 是 opt-in、需要额外模型工件或受信任边界。兼容性结论从何而来静态 API 面比对迁移指南的核心依据不是人工核对而是仓库内置的静态比对脚本 scripts/release/api_surface_diff.py。该脚本用 Python 标准库ast解析openmed/包源码刻意不导入被检查的包从而避免 import 时的副作用使发布检查保持离线安全见脚本 docstring 与 compare_refs 实现。对比对象可以是任意两个 Git 引用也可以用WORKTREE哨兵值指代当前工作区文件。在仓库根目录本地复现官方对比python scripts/release/api_surface_diff.py \ v2.1.0 HEAD \ --json api-surface-diff.json \ --check docs/migration/2.1-to-2.2.md参数含义见 build_parserbefore_ref/after_ref基线 Git 引用如v2.1.0与候选引用如HEAD或WORKTREE--repo-rootGit 仓库根目录默认当前目录--package待检查的包目录默认openmed--json PATH输出机器可读的 diff-表示 stdout--check MIGRATION_DOC迁移文档完整性门禁——若 diff 中存在破坏性变更或弃用符号而迁移文档未提及命令以退出码 1 失败并列出缺失符号见 missing_migration_symbols。该脚本生成的 JSON 遵循schema_version: 1包含before_ref、after_ref、summary前后符号数、新增/弃用/破坏性变更计数以及分类明细见 ApiSurfaceDiff.to_dict。Symbol记录还带有基于ast.dump的 SHA-256fingerprint可用于识别跨模块重命名见 _fingerprint。官方结论纯增量无破坏按上述工具静态对比 v2.1.0 与 HEAD公开 Python API 清单从 31,619 个符号增长到 37,735 个新增 6,116 个公开符号没有任何公开符号被删除或重命名没有任何已有可调用对象的签名被收窄无参数删除、无必填参数新增、无位置参数顺序变化——这些正是_narrowing_reasons逐项检查的破坏性模式见 scripts/release/api_surface_diff.py#L845-L892没有任何已有符号被新标记deprecated。因此迁移文档末尾无需提供删除/弃用符号的替换片段——静态比对发现这两类变更均为零。REST 契约同样保持加法式演进从 17 个路径、15 个组件 schema 增至 19 个路径、17 个组件 schema。新增的POST /ground与POST /pii/deidentify/stream不替换任何既有路由。后者可以在 openmed/service/app.py 的流式路由注册处找到对应实现。需要明确的是Python AST 比对不覆盖 JavaScript、CLI、配置、模型清单与证据契约这些契约需要单独审查。升级检查清单逐条执行官方为升级到2.2.0给出了 9 条检查项这里逐条展开并补充可操作的细节精确安装依赖pip install openmed2.2.0只带应用实际使用的 optional extras详见下文可选依赖与集成一节不要整包拉入全部适配器。回归测试矩阵对每个部署的语言、脚本、文档格式与量化运行时在合成 fixture上重跑隐私、直接标识符召回、关键泄漏、span 完整性、确定性安全测试。v2.2 的合成一致性矩阵见 docs/release/v2.2-standards-matrix.md其泄漏边界要求参考测试中合成直接标识符在 review JSON、grounding 审计输出、序列化 FHIR、脱敏 OMOP 报告、错误与日志、生成证据及临时工件路径中出现次数严格为零。刷新 MCP schema 与生成式 REST 客户端在采用 grounding 或流式脱敏路由之前完成避免客户端与服务端契约错位。重新认定应用侧资产应用自有的术语快照、FHIR profile、OMOP 映射、结构化数据策略与临床抽取验收测试在启用新工作流前需重新合格化。保持敏感物在包外有许可的词汇表、受限语料、PHI、凭据与模型文件一律不进包新的 loader 与 bridge 都是调用方自供caller-supplied、opt-in。Android 诊断审计审查所有插值EntityPrediction值的诊断路径仅允许text字段出现在本地 UI 边界严禁进入日志、遥测、崩溃报告或远程诊断详见下文专节。FHIR 校验验证 Bundle 引用与 OperationOutcome 报告恢复交换工作流时仅保留 digest-only 的 Bulk Data checkpoint。辅助证据定位结构化发布建议与临床映射只作为辅助证据需合格人员复核不得自动触发诊断、治疗、计费或数据发布。Maple / Compass 采纳前提固定并校验外部模型工件在部署设备上重跑任务级与图像级验收测试模型输出与其他临床抽取结果一样停留在同一个人工复核边界内。保留的公开名称两次包重组中的显式兼容绑定本次发布审计中有两处包重组为此建立了显式兼容绑定确保既有 import 保持 v2.1 语义openmed.clinical.grounding.SnapshotManifest继续指代 v2.1 的快照缓存清单实现位于 openmed/clinical/grounding/snapshot_cache.py 的SnapshotManifest类配套MANIFEST_FILENAME、SNAPSHOT_SCHEMA_VERSION、MAX_ARTIFACT_BYTES等约束。新增的词汇清单则以新名字导出VocabularySnapshotManifest——它是对openmed/clinical/grounding/vocab.py中词汇快照清单的显式别名在 openmed/clinical/grounding/init.py 通过SnapshotManifest as VocabularySnapshotManifest完成绑定并同时出现在__all__第 350 行。迁移含义处理术语词汇清单的新代码应显式使用VocabularySnapshotManifest沿用旧 import 的存量代码继续获得 v2.1 语义无需改动。openmed.clinical.exporters.omop.ConceptResolver在 OMOP 导出器从模块重组为包之后仍是公开类型别名。当前定义见 openmed/clinical/exporters/omop/init.py即Mapping[tuple[str, str], int]词汇表 → concept_id 映射与Callable[[GroundedSpan, Candidate | None], int | None]解析回调的联合类型并被to_omop的concept_resolver/resolver参数及各表导出函数消费。Android 诊断描述默认 PHI 安全这是本次版本中最值得注意的隐私加固点EntityPrediction.description不再包含检测到的源文本。以 Kotlin 实现为例EntityPrediction.kt 的toString()现在输出[label] sha256digest (start:end) conf0.xxlabel经过phiSafeLabel处理sha256后是文本的 SHA-256 摘要sha256Hex(text)(start:end)是Unicode 标量码点半开区间偏移不是 Kotlin UTF-16 索引conf使用半偶银行家舍入保留两位小数与 SwiftString(format: %.2f, ...)完全一致非有限值不参与舍入以免抛异常。这是对诊断输出的有意加固而非对预测字段或 span 契约的改动label、text、confidence、start、end五个字段及entityType、utf16SpanIn、snappedToGraphemeBoundaries等成员契约保持不变。迁移动作应用仍可在获得批准的本地 UI 边界内渲染显式text字段但不得把description当作源文本传输通道也不得把text加入诊断或遥测路径。Maple 与 Compass 运行时新增但模型工件在包外Python 侧新增MapleClinicalAssistant任务 API实现位于 openmed/mlx/maple.py。构造函数只记录model_name与config惰性加载 5GB 模型首次使用时才实例化运行器见 _model。complete_task以temp0.0运行结构化抽取并把结果解析为经过校验的MapleTaskResult——由于 Maple 是推理模型可能在隐藏的think块中消耗数百 token因此默认max_tokens1024需为隐藏推理预留余量chat则只返回可见答案、剥离隐藏推理visible_maple_response。MLX Maple 导出/运行辅助函数。openmed.mlxCompass 视觉-语言运行时OpenMedMLXVisionLanguageModel位于 openmed/mlx/vlm.py提供generate与generate_with_metadataCompass 模型结构视觉 patch embedding/merger、attention、MLP、RMSNorm 等见 openmed/mlx/models/cohere_compass.py。OpenMedKitSwift侧新增OpenMedMaple*的 request、response、解析与 MLX 运行时类型以及OpenMedVisionLanguageModel的加载与生成能力Swift 包还将 MLX Swift LM 固定到经评审的 revision 用于多模态生成。重要边界这些是加法式 API但模型工件保持外部。未启用这些运行时的部署不会获得隐式的网络或模型下载路径——这点可通过MapleClinicalAssistant的惰性构造直接印证。临床交换与 grounding本地优先术语工作台v2.2 在临床交换与 grounding 方向集中落地了一批能力本地优先术语工作台与固定版本pinned词汇快照排序式 grounding 与校准ranked grounding and calibration调用方自供的 Athena 与 crosswalk 支持FHIR R4 患者摘要与临床文档组装、显式 R4/R5 边界、本地 profile 校验、SDC 隐私投影Bulk Data 恢复resume支持FHIR → OMOP CDM 5.4 桥。这些能力的源码落点包括grounding 编排入口 openmed/clinical/grounding/api.py 的ground_payload、快照缓存 openmed/clinical/grounding/snapshot_cache.py 中的TerminologySnapshotCache/SnapshotCache、OMOP 导出包 openmed/clinical/exporters/omop/init.py 与 openmed/interop/fhir_omop 相关模块。合规底线不捆绑任何有许可的术语。词汇权利、快照完整性、版本固定、弃权abstention策略、映射复核与下游临床校验均由调用方负责。v2.2 的合成一致性矩阵对此有明确记录——例如 FHIR R4/IPS 一行只覆盖Document Bundle 含 Composition、伪名化 Patient 与 grounded Condition不声称通用 R5 转换或全资源校验见 docs/release/v2.2-standards-matrix.md。文档摄入与结构化隐私文档摄入在 v2.2 扩展为确定性的表单与键/值抽取跨格式 offset 投影PDF 表格重建XLSX、PPTX、ODT 处理HL7 v2 叙述文本抽取X12 837 脱敏fail-closed 的 MIME 隔离quarantine——无法判定类型的输入默认拒绝而非放行。结构化隐私新增k-anonymity、l-diversity、t-closeness、成员推断自测、仅聚合的差分隐私以及面向发布决策的复核证据review evidence。注意定位这些工具报告风险与策略证据不保证数据集已匿名或适合发布。矩阵中structured-privacy-negative一行即演示了单条唯一合成记录被零容忍成员推断阈值拒绝的负向边界见 docs/release/v2.2-standards-matrix.md。可选依赖与集成按需安装v2.2 新增fhir、dagster、sqlalchemy三个聚焦 extras并扩展multimodal与serviceextras定义见 pyproject.toml 及 multimodal/service 段。只安装部署实际需要的适配器例如pip install openmed[fhir]2.2.0 pip install openmed[dagster]2.2.0 pip install openmed[sqlalchemy]2.2.0此外新增一批 opt-in 适配器Arrow Flight、PostgreSQL PL/Python、可执行 UDF、分布式 SQL、Dataflow、Dagster、Ray、pandas-on-Spark、search ingest 与流处理器。外部数据库、服务、凭据与运行时构成显式信任边界核心本地处理不依赖它们。发布与模型证据SDK 发布不提升模型指针v2.2.0 是 SDK 发布不提升任何模型指针提交的PII/latest与PII/last_green均保持OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1-mlxPII/canary保持未设置。未来若要进行模型提升仍需满足完整流程真实的分阶段候选、公开的 SHIELD 与 golden 基准证据、签名的抽取门禁、以及最终决策恰好为READY。缺少候选工件会使模型提升调度失败——不会为指针未变的 SDK tag 伪造候选。v2.2 tag 的合格性由以下证据共同支撑保留的 last-green 模型证据、v2.2 合成一致性矩阵、本迁移指南、机器可读的 API 对比api-surface-diff.json以及精确提交exact-commit的包与平台门禁。升级路径总结关注面v2.1 → v2.2 结论迁移动作Python 公开 API6,116 符号零删除/重命名/收窄/新弃用直接升级用api_surface_diff.py自证REST 契约17→19 路径、15→17 schema纯增量刷新客户端与 MCP schema术语清单SnapshotManifest保留新代码用VocabularySnapshotManifest新代码显式使用新名OMOP 导出ConceptResolver别名保留无改动Android 诊断description默认 PHI 安全只用本地 UI 渲染textMaple/Compass加法式 API模型工件外部固定校验工件设备端验收依赖新增 fhir/dagster/sqlalchemy extras按需安装模型指针未提升无一句话概括本次升级的性质v2.1 → v2.2 是经过静态验证的零破坏 SDK 升级——所有变化都是加法式的真正的迁移工作不在于改写代码而在于按清单重新合格化应用侧的测试、诊断路径与外部工件边界。【免费下载链接】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），仅供参考