OpenMed v2.2 到 v2.3 迁移指南Python API 兼容边界验证、npm 令牌偏移对齐与隐私安全升级实践【免费下载链接】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 官方迁移文档 docs/migration/2.2-to-2.3.md 为核心骨架结合仓库内api_surface_diff.py比对工具、openmed/源码实现与js/openmedkit-web前端契约系统讲解从v2.2.0升级到v2.3.0时你需要关注的兼容性结论、可复现的静态比对方法、八个升级检查项、多模态/Agent/训练三大新增契约以及 npm 端 token-classification 偏移对齐的破坏性细节与修复方案。读完本文你将能够独立复现官方 API 兼容性审计、正确迁移 npm 消费者代码并完成一次符合隐私边界的版本升级。OpenMed 2.3.0 是一个以纯增量、零破坏为设计目标的 SDK 版本Python 公开 API 从 37,735 个符号增长到 41,729 个新增 3,994 个公开符号没有移除或重命名任何公开符号、没有收窄任何已有可调用对象的签名、也没有任何既有符号被新标记为deprecated。但这并不意味着升级可以原地替换包版本了事——REST 契约、Swift、Kotlin/Android、JavaScript、CLI、配置、trace schema、证据记录、模型产物与部署契约都需要单独复核尤其是 npm 端 token-classification 的偏移对齐行为发生了实质变化。一、兼容性结论一次由静态 AST 审计背书的安全升级官方迁移文档给出的兼容性结论如下Python 静态 API 清单从37,735 增长到 41,729个符号新增3,994个公开符号0个公开符号被移除或重命名0个既有可调用对象签名被收窄0个既有符号被新标记为deprecatedREST 契约保持不变仍为19 个路径paths与 17 个组件 schemacomponent schemas。由于静态比对没有发现移除或弃用类变更因此官方没有提供任何before/after 替换片段。同时文档明确划定了审计边界Python AST 比对不检查Swift、Kotlin/Android、JavaScript、CLI、配置、trace schema、证据记录、模型产物与部署契约这些表面必须单独人工复核。从版本发布记录docs/release/v2.3.0.md可知v2.2.0..v2.3.0的审计分支区间包含 252 个提交、651 个变更文件提交主题关联 127 个 issue/PR 编号REST 表面保持 19 路径与 17 组件 schema 的结论与迁移文档一致属于官方公布的实现事实。二、复现比对api_surface_diff.py 的工作原理与运行方式迁移文档提供了在本地完整复现上述结论的命令运行于仓库根目录python scripts/release/api_surface_diff.py \ v2.2.0 HEAD \ --json api-surface-diff.json \ --check docs/migration/2.2-to-2.3.mdbefore_ref如v2.2.0为基线 Git 引用after_ref如HEAD为候选引用也支持WORKTREE哨兵值来直接比对当前工作区文件--json api-surface-diff.json输出机器可读的 diff使用-可输出到 stdout--check docs/migration/2.2-to-2.3.md将迁移文档作为完整性门禁若文档缺少某个 breaking 或 deprecated 符号命令以非零码退出并列出缺失符号。该工具的实现位于 scripts/release/api_surface_diff.py其设计有几个值得注意的特点1. 纯静态、零导入。提取器从 Gitgit archive打包指定 ref或当前工作区读取源码用 Python 标准库ast解析故意从不 import 被审计的包见文件头注释It deliberately never imports the package being inspected。这保证比对过程离线安全、无 import 期副作用。2. 符号指纹fingerprint。每个函数/类/属性都会基于ast.dump的规范化输出计算 SHA-256 指纹scripts/release/api_surface_diff.py用于识别重命名同一指纹的 removedadded 配对而非单纯删除。3. 破坏性分类精确。diff_surfaces()将变更归类为renamed、removed、deprecated、signature-narrowed、added五类签名收窄检查逐参数比对参数是否被移除、可选变必选、positional/keyword 种类转换、位置顺序变化等并允许positional_only - positional_or_keyword这类安全放宽。4. 迁移文档完整性门禁。missing_migration_symbols()用单词边界正则(?![A-Za-z0-9_.])symbol(?![A-Za-z0-9_.])扫描迁移文档是否提及每个 breaking/deprecated 符号缺一个就让--check失败把文档与代码事实同步变成发布流程的硬约束。除了上面的 CLI脚本还提供可编程入口extract_surface()、diff_surfaces()、compare_refs()与check_migration_document()适合接入 CI 脚本做常规的 API 漂移巡检。三、升级检查清单八个必须在发布前完成的动作迁移文档给出了八个升级检查项按执行顺序整理如下精确安装仅安装openmed2.3.0且只带应用实际用到的 optional extras避免引入无谓依赖与隐私面。重新执行隐私与安全测试在合成测试样本synthetic fixtures上对每个部署语言、脚本、文档格式和量化运行时重跑隐私privacy、直接标识符召回direct-identifier recall、关键泄漏critical-leakage、span 完整性span-integrity与确定性安全deterministic safety测试。重新认证多模态资产对应用自有的多模态资产 profile、manifest 限制、摘要digest策略、弃权abstention处理与文档解析验收测试做重新认证。刷新机器可读契约消费者在启用新契约前重新生成/升级 CLI、REST、schema、agent-outcome 与 trace 的消费者代码。保持数据边界PHI、凭据、受限数据集、授权词表licensed vocabularies、外部模型权重与第三方运行时不得进入包及证据记录。临床证据定位临床证据、SDOH 提取、记录过滤、术语映射与训练输出一律视为需合格人员复核的辅助证据不得自动触发诊断、治疗、计费或发布行为。真实平台演练对启用的桌面、浏览器、Android、Apple、TensorRT、WebGPU、搜索、批处理或集群适配器在实际部署平台上逐一演练。运维表面评审在推广新运维表面之前评审容器、Helm、Kubernetes operator、HPA、sidecar 与 remote-function 策略。第 5、6 条与 OpenMed 一贯的隐私边界一致核心本地处理不新增强制网络或遥测路径v2.3.0发布说明也再次强调模型下载与可选的远程集成是显式边界且遥测默认关闭、证据记录只保留哈希/计数/偏移/溯源而非原始标识符。四、多模态 intake 与溯源受限清单、流式摘要与失败关闭OpenMed 2.3 在多模态侧新增的能力包括有界资产清单bounded asset manifests、流式摘要streaming digests、媒体类型检测media-type detection、类型化弃权记录typed abstention records、确定性 manifest profile、扩展的 PDF 布局与保真工具、本地邮件处理以及更多文档格式的隐私安全提取与脱敏。这些 API 对畸形或无界输入一律失败关闭fail closed。4.1 隐私安全的资产清单AssetManifest模块openmed.multimodal.asset_manifest源码见 openmed/multimodal/asset_manifest.py配套文档 docs/multimodal/asset-manifests.md为 preflight 步骤提供一个刻意狭窄的清单只记录以下字段字段说明version清单版本asset_id资产标识media_type媒体类型sha256SHA-256 摘要byte_size字节数pages/width/height/frames/duration_seconds可选的有界计数验证器拒绝未知字段、路径、URL 与任何自由文本字段如描述或来源元数据校验失败的错误只点名失败字段或规则不回显提交的值。整数大小与计数分别使用显式的 64 位与 32 位上界duration 必须是有限、正数且与其他计数同界布尔值、标量子类、重复 JSON 字段与越界数值一律失败关闭。官方示例from openmed.multimodal.asset_manifest import AssetManifest manifest AssetManifest.from_dict( { asset_id: dicom-001, media_type: application/dicom, sha256: a * 64, byte_size: 4096, frames: 12, width: 512, height: 512, } ) payload manifest.to_json()to_dict()按稳定顺序输出字段并省略未设置的可选字段to_json()输出键排序的紧凑 JSON保证两个调用方能确定性比较清单负载。清单本身不读取资产、不执行 OCR/推理、不保留内嵌元数据也不定义模型相关的张量形状。4.2 有界流式摘要digest_assetopenmed.multimodal.digest的digest_asset源码见 openmed/multimodal/digest.py文档见 docs/multimodal/asset-digests.md在不把 PDF、图片、DICOM、音频等二进制资产整体载入内存的前提下计算 SHA-256from openmed.multimodal.digest import digest_asset with open(synthetic-scan.dcm, rb) as stream: result digest_asset(stream, max_bytes2 * 1024**3) print(result.sha256) print(result.byte_count)流从当前读取位置开始按不超过1 MiB的块读取可寻址流在成功或失败后都会恢复到原位置且 helper 从不关闭调用方拥有的流不可寻址流则被消耗直接传bytes则对内存中的值就地哈希max_bytes为可选硬限制helper 至多再多读 1 字节以检测溢出然后抛出DigestLimitExceededError错误信息只含digest_size_limit类别、maximum_bytes与bytes_read绝不包含路径、文件名或资产内容其他流故障抛出无值的DigestStreamError结果包含小写 64 字符 SHA-256 十六进制摘要与精确哈希字节数该函数不打开路径、不校验媒体、不查毒、不签名、不提供内容寻址存储。4.3 媒体类型检测、类型化弃权与 manifest profile配套的多模态能力在仓库中均有独立文档与实现可查媒体类型检测的失败关闭语义见 docs/multimodal/media-type-detection.mdInvalid declared types fail closed with a value-free error类型化弃权记录的实现位于 openmed/multimodal/abstention.py其设计要点是只接受 stage reason code 两个元数据字段没有自由文本字段因此调用方在说明为何停止处理时不可能顺带序列化出 OCR 文本、转写、DICOM 值、文件路径、URL 或模型提示词。弃权阶段与原因构成一个封闭组合矩阵阶段AbstentionStage允许的原因AbstentionReasonpreflightunsupported_media、resource_limit、provider_unavailabledecodemalformed_media、resource_limit、low_qualityinferenceresource_limit、low_quality、phi_uncertainty、speaker_uncertainty、temporal_instability、provider_unavailablepost_process同类封闭集合实现于 openmed/multimodal/abstention.py 起的常量表更多细节可继续阅读 docs/multimodal/abstention-reasons.md、docs/multimodal/asset-limits.md、docs/multimodal/manifest-profiles.md、docs/multimodal/pdf-redaction-fidelity.md 与 docs/multimodal/preflight.md。迁移文档给出的使用原则是保留调用方拥有的流语义、使用声明的 size 与 digest 限制、只保留复核所需的元数据/偏移/哈希/聚合证据——这正是有界输入 元数据化证据的落地方式。五、Agent、trace 与训练契约封闭词表与可复现记录5.1 Agent封闭的结局码与确定性摘要Agent 运行新增了封闭结局码closed outcome codes、确定性摘要、单调时间记录、consent 校验结果与 PHI 安全的失败原因。核心实现是openmed.agent.outcomes源码见 openmed/agent/outcomes.py配套文档 docs/agent/outcome-reasons.md其载荷只有三个字段schema_versionopenmed.agent.outcome.v1、outcome_class、reason_code不存储提示词、工具参数、工具输出、证据文本、路径或凭据。公开 API 区分以下五类结局且类/原因组合是封闭的outcome_class允许的 reason_codesuccesscompletedabstainedinsufficient_evidence、out_of_scope、low_confidencereview_requiredconflicting_evidence、safety_review、human_gatepolicy_deniedconsent_required、purpose_mismatch、phi_policyfailedtool_error、timeout、invalid_input未知类、未知原因码、类/原因不匹配、多余字段与自由文本原因一律失败关闭异常消息只点名字段或稳定错误码不回显提交值。示例from openmed.agent import WorkflowOutcome outcome WorkflowOutcome.from_dict( { outcome_class: abstained, reason_code: insufficient_evidence, } ) payload outcome.to_json()to_dict()稳定排序输出、to_json()键排序紧凑序列化保证相同输入字节级一致——这与 run-summaries、timing-metadata 等契约共同构成可确定性复核的 Agent 证据链参见 docs/agent/run-summaries.md、docs/agent/timing-metadata.md、docs/agent/event-correlation.md 与 docs/agent/governance-identifiers.md。5.2 Trace本地发现、保 schema 脱敏与事务恢复trace 工具新增了本地发现local discovery、保 schema 脱敏schema-preserving redaction、流式与并行执行、事务恢复transactional recovery、保真校验fidelity checks与训练 schema 适配器。仓库内对应实现与文档包括事务式本地脱敏openmed/traces/transaction.py——源文件只读一次转换后的字节先写入并fsync到同级临时文件前缀.openmed-transaction-所有 pre-commit 检查通过后才替换目录项所有异常消息刻意无值敏感文本永远不会被复制进异常TransactionError的类注释明确说明这一点保真校验openmed/traces/fidelity.py 与 docs/reference/trace-fidelity.md流式执行openmed/traces/streaming.py 与 docs/guides/streaming-traces.mdschema 化 traceopenmed/traces/schemas/ 下的chat.py、columnar.py、preference.py与 docs/reference/chat-schema.md 等。5.3 训练教师集成清单、联邦轮次与可复现性训练侧新增教师集成清单teacher-ensemble manifests、确定性联邦轮次记录deterministic federated-round records与可复现性验证reproducibility verification。这些都是增量契约additive contracts但下游 schema 消费者应当先刷新快照并显式处理新的封闭词表再启用它们。一个可直接体验的示例是训练会话 schema 注册表 openmed/traces/schemas/registry.py文档见 docs/reference/training-schemas.md它内置识别messagesrole/content 消息列表、sharegptconversations[].value与preferenceprompt/chosen/rejected三类布局检测是结构化且确定性的不加载模型、不读数据集、不发网络请求from openmed.traces.schemas.registry import TrainingSchemaRegistry registry TrainingSchemaRegistry() record { messages: [ {role: user, content: Synthetic user value}, {role: assistant, content: Synthetic answer}, ] } schema registry.resolve(record) print(schema.name) # messages for path, text in registry.walk(record, schemaschema): print(path, text)自动检测在无 schema 匹配或多个 schema 同时匹配时失败关闭歧义记录必须显式指定schema才能重建副本。transform()始终返回副本并保留原始嵌套注册表错误从不包含记录值诊断中的 schema 标识以确定性schema_sha256_...标签代替调用方提供的名称。自定义 schema 可实现TrainingConversationSchema协议并通过registry.register(...)注册进程内注册无发现或网络副作用。六、集成与运行时可选适配器与显式信任边界v2.3 新增的集成适配器均为opt-in覆盖OpenSearch、Elasticsearch、Spark、Beam、Airflow、LlamaIndex、PostgreSQL、dbt、仓库远程函数warehouse remote functions、Kubernetes、浏览器扩展、Electron、Tauri、Android 加速器、TensorRT、GGUF 与 WebGPU。迁移文档明确提醒外部进程、集群、浏览器、数据库、模型文件与凭据都是显式信任边界适配器必须在真实目标平台上逐一演练对应检查项 7。关于 MedCAT 桥接迁移文档给出了三条明确事实它保持进程外out of process运行、不安装任何受限依赖并要求使用者显式确认其第三方许可证。核心本地处理不获得强制网络或遥测路径——这与 OpenMed local-first、默认无遥测 的整体设计一致。七、npm token-classification 兼容性偏移契约与修复路径这是 2.2→2.3 迁移中最容易被忽略、也最需要动手改代码的部分。官方结论npm 默认模型现在是OpenMed/OpenMed-PII-ClinicalE5-Small-33M-v1-onnx-android导出为DEFAULT_MODEL_ID-onnx-android仓库使用根目录 INT8 加载器。使用该默认路径需要安装可选的huggingface/transformerspeer 依赖或注入你自己的本地 pipeline模型下载与本地推理是分离的推理不把临床文本发给托管 API。7.1 类型契约既有数值偏移保留新增 Raw 输入类型既有TokenClassificationEntity、TokenClassificationPipeline与模型加载器的输出保留 v2.2 的数值start/end契约新增的RawTokenClassificationEntity、RawTokenClassificationPipeline与RawTransformersRuntime类型则接受可能省略偏移的运行时输入类型定义见 js/openmedkit-web/src/types.ts/** Unaligned runtime input; public aligned entities retain numeric offsets. */ export type RawTokenClassificationEntity OmitTokenClassificationEntity, start | end { start?: number; end?: number; };最终的OpenMedSpan偏移仍然必填且使用 JavaScript UTF-16 索引OPENMED_SPAN_SCHEMA_VERSION 1span 含start/end/text_hash/entity_type等字段。7.2 对齐机制alignTokenOffsets 与失败关闭调用alignTokenOffsets(text, tokens)可以把 raw token 转换成对齐实体模型加载器在返回 pipeline 输出之前会自动执行该转换见 js/openmedkit-web/src/model-loader.ts 中loadTokenClassificationPipeline对输出统一调用alignTokenOffsets的 Proxy 包装。对齐实现位于 js/openmedkit-web/src/offsets.ts关键行为大小写与变音符不敏感先做 Unicode 规范化NFD 剥离组合标记因此 BERT 式小写分词器仍能对齐容忍多种分词标记WordPiece##、SentencePiece▁、byte-level BPEĠ都会被剥离后参与匹配特殊 token[CLS]/[SEP]/s等被跳过顺序游标 有界回退搜索连续 token 只在游标附近 16 字符窗口内搜索被上游丢弃的 token如 ignored labels造成的 index 空洞会自动放宽为全串搜索对齐失败抛无内容错误new Error(Token offset alignment failed; provide source offsets.)——绝不静默省略脱敏 span显式偏移优先已带有限数值偏移的 token 原样保留并推进游标。7.3 extractPii 的 O-token 保留与错误语义extractPii()保留Otoken 以保证顺序对齐显式 pipeline 偏移被原样保留缺失偏移通过大小写/变音符与 token 标记归一化重建未知或无法对齐的 token 抛出无内容错误而不是静默省略脱敏 span。对自定义分词器或过滤输出迁移文档给出两条硬性规则提供精确的源偏移exact source offsets把对齐错误当作**一次失败的扫描a failed scan**处理永远不能当作文档不含 PII的证据——因为未对齐意味着可能存在漏掉的实体而不是没有实体。八、发布与模型证据SDK 发布不等于模型指针推进OpenMed 2.3.0 是SDK 发布本身不推进任何模型指针。模型转换、评估与发布是显式的地方维护者操作explicit local maintainer operations。未来若推进指针仍必须满足完整门槛真实的分阶段候选staged candidate、公开的 SHIELD 与 golden 证据、签名的抽取门禁signed extraction gates以及最终就绪判定恰好为READY。SDK 标签由以下证据独立限定qualify本文所讲的迁移指南机器可读的 API 比对结果api-surface-diff.json精确提交exact-commit的单元与平台门禁包产物检查artifact inspection保留的 last-green 模型证据。配套的 docs/release/v2.3.0.md 进一步明确了发布硬约束宿主检查必须指向精确发布提交早期 source head 上的成功任务不算数、镜像/包发布与注册表验证都是 tag 驱动的后续动作证据链层面docs/security/evidence-integrity.md 展示了报告/清单摘要使用sha256:64 位小写十六进制规范、invalid_manifest/hash_mismatch等稳定失败类别的落地形态。一个值得注意的上游依赖事实可选依赖树中的 NLTK 3.10.3 存在模型产物路径安全公告 CVE-2026-81726截至 2026-09-14 无已发布修复版本OpenMed 不调用受影响的模型文件 API服务镜像也不安装 NLTK。使用agents、llamaindex、quickumls、scrubadub等可选依赖的应用不得把 NLTK 模型导入/导出路径暴露给不可信输入且该豁免仅限此 CVE、nltk包与uv.lock目标到期时间为 2026-09-28——这是官方明示的已知上游限制而非NLTK 已修复的声明。九、迁移动作汇总把全文要点压缩成一张可直接执行的自检表#动作关键依据1运行api_surface_diff.py v2.2.0 HEAD --json ... --check ...复现兼容性结论scripts/release/api_surface_diff.py2pip install --upgrade openmed2.3.0或按需加[hf,fhir]/[mlx]等 extrasdocs/release/v2.3.0.md3在全部部署语言/格式/量化运行时重跑隐私与泄漏测试迁移文档检查项 24复核多模态 manifest/digest/abstention 相关实现与配置docs/multimodal/asset-manifests.md、docs/multimodal/asset-digests.md5刷新 Agent 结局码、trace、训练 schema 的消费者代码openmed/agent/outcomes.py、openmed/traces/schemas/registry.py6npm 侧确认默认模型、安装huggingface/transformers、检查偏移对齐js/openmedkit-web/src/model-loader.ts、js/openmedkit-web/src/offsets.ts7逐平台演练启用的集成/运行时适配器评审容器与 K8s 运维策略迁移文档检查项 7、88保持 PHI/凭据/受限数据在包与证据之外临床输出走合格复核迁移文档检查项 5、6升级到 OpenMed 2.3.0 的本质是在零 Python 破坏的前提下把多模态资产的隐私安全边界、Agent 结局的封闭词表、trace 的事务式脱敏、训练记录的可复现性以及 npm 端偏移对齐的正确性一次性引入你的部署栈。只要按本文的比对方法复现审计、按八项清单逐条执行、并在 npm 侧落实偏移契约与失败即扫描失败的错误语义这次升级就是一次低风险、可验证、可追溯的版本演进。【免费下载链接】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），仅供参考