尧图网页设计 
OpenMed Python API 完全参考PII 提取、去标识化、可逆重标识与结构化错误体系【免费下载链接】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 官方 API 参考docs/api-reference.md为主线结合仓库源码openmed/core/pii.py、openmed/core/errors.py、openmed/init.py 等逐项解读顶层公开 API。你将掌握extract_pii、deidentify、reidentify三大 PII 核心函数及analyze_text、list_models、BatchProcessor等配套能力的完整签名、参数语义与实战用法理解从检测到脱敏、再到可审计重标识的全链路编程模型并学会用统一的OpenMedError错误树含 REST/MCP 映射安全地处理失败。所有结论均可回溯到当前仓库源码适用于在本地构建 HIPAA 合规的临床文本处理管线。1. 快速上手与公共 API 表面OpenMed 的顶层包openmed采用**惰性导入lazy import**机制openmed/init.py 中的__getattr__会在首次访问符号时才从对应子模块加载__dir__()则暴露全部可发现的顶层导出。这意味着import openmed本身开销极低且只有真正用到的能力才会被加载——对端侧部署与冷启动敏感场景友好。顶层 API 分组见 openmed/init.py 的__all__大致包括PII 检测与去标识化extract_pii、deidentify、reidentify、PIIEntity、DeidentificationResult通用 NER 分析analyze_text、AnalyzeResult模型发现list_models、get_model_info、get_models_by_category、search_models、get_default_pii_model等批处理与文档流BatchProcessor、process_batch、redact_dataset、deidentify_document_stream结构化错误OpenMedError及其十个子类、ERROR_CODES、redact_detailPDF 处理openmed.multimodal下的render_redacted_pdf、verify_redacted_pdf、verify_redacted_text_removed、measure_pdf_layout_fidelity可观测性openmed.core.telemetry.PipelineTelemetry、StageTelemetry。一个最简的端到端示例与源码 docstring 中reidentify的用法一致import openmed # 1) 检测 result openmed.extract_pii( Patient Casey Example called from 555-0100 on 01/15/1970., confidence_threshold0.5, ) # 2) 脱敏mask 策略默认即保留映射以支持逆向 d openmed.deidentify( Patient Casey Example called from 555-0100 on 01/15/1970., methodmask, keep_mappingTrue, ) print(d.deidentified_text) # 形如 Patient [NAME] called from [PHONE] on [DATE] # 3) 依据映射恢复 restored openmed.reidentify(d.deidentified_text, d.mapping) print(restored) # 还原原始文本2.extract_pii检测临床文本中的 PII 实体定义位于 openmed/core/pii.py。它使用 token 分类模型检测姓名、邮箱、电话、地址及其他受 HIPAA 保护的标识符模块 docstring 声称支持 18 实体类型并通过**智能实体合并smart merging**把被模型切碎的片段如日期01与/15/1970依据正则语义单元重新合并为完整实体01/15/1970再以主导标签dominant label归类。2.1 函数签名extract_pii( text: str | bytes | bytearray | memoryview, model_name: str OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1, confidence_threshold: float 0.5, config: Optional[OpenMedConfig] None, use_smart_merging: bool True, lang: str en, cache_results: bool False, max_cache_entries: int 128, normalize_accents: Optional[bool] None, *, preserve_whitespace: bool False, locale: Optional[str] None, loader: Optional[ModelLoader] None, batch_size: Optional[int] None, num_workers: Optional[int] None, custom_recognizer: Any None, abdm: Optional[bool] None, code_mixed: bool False, token_language_tags: Optional[Sequence[Any]] None, lid_model: Optional[TokenLIDHook] None, transliterated_name_config: Any None, budget: Optional[RequestBudget] None, ) - PredictionResult2.2 核心参数语义参数默认值说明text—支持str及bytes/bytearray/memoryview入口先经validate_pii_input校验model_nameOpenMed/OpenMed-PII-SuperClinical-Small-44M-v1PII 模型标识注册表键、Hugging Face 仓库 ID 或本地路径当lang ! en时自动切换到对应语言的默认模型confidence_threshold0.5置信度下限0–1低于阈值的结果被过滤use_smart_mergingTrue是否启用基于正则的语义单元合并官方推荐保持开启langenISO 639-1 语言码en、fr、de、it、es、nl、hi、te、pt、ar、ja、tr 等控制默认模型、正则模式与替换假数据hi/te的拉丁/天城文、拉丁/泰卢固文混合文本会自动走脚本感知的印度临床路由normalize_accentsNone推理前是否去除变音符号None表示对_ACCENT_NORMALIZE_LANGS当前为西班牙语es自动开启。结果中的实体偏移始终指向原始带重音文本preserve_whitespaceFalse保留首尾空白使返回偏移精确对应输入串custom_recognizerNone自定义识别器CustomRecognizer实例或 JSON/YAML 配置路径deny-list 命中以custom:deny溯源加入allow-list 命中抑制任何检测器的重叠跨度abdmNone印度 ABDM 标识符包开关None对印地语/泰卢固语及印度 locale 自动开启False显式关闭code_mixedFalse显式英语/印地语混合路径需配合token_language_tagsen/hi/ne/univ/other标签流budgetNone每次请求的墙钟时间与输入字符预算超长输入在模型推理前即被拒绝cache_results/max_cache_entriesFalse/128进程内 LRU 结果缓存缓存可能含 PHI但永不落盘2.3 底层流程与返回结构从源码调用链看extract_pii依次完成输入校验与预算检查 → 缓存查找 → 构造_extract_pii_batch单元素批 →可选Unicode 归一化与变音去除、印度临床脚本窗口路由、隐私过滤模型分发 → 智能合并 → 确定性safety_sweep补充结构化标识符SSN/身份证等→ 实体跨度校验validate_entity_spans→ 返回PredictionResult。返回的PredictionResult含text、entities、model_name、timestamp每条实体为PIIEntity见第 3 节。若lang指定的语言没有捆绑模型会抛出带明确指引的ModelLoadError例如提示设置INDIC_NER_MODEL_ENV或显式传model_name。3. 核心数据结构PIIEntity与DeidentificationResult3.1PIIEntity定义于 openmed/core/pii.py继承自EntityPrediction除基础text/label/start/end/confidence外还包含 PII 专属字段entity_typePII 类别与label相同构造时自动回填redacted_text/original_text脱敏后替换文本与脱敏前原文hash_value用于实体关联的一致性哈希reversible_id可选的可逆假名化句柄canonical_label规范化类别标签用于跨模型的标签归一sources/evidence实体来源如ml、locale_rule、safety_sweep、custom:deny与证据action/surrogate脱敏动作与代理值。3.2DeidentificationResult定义于 openmed/core/pii.py字段包括original_text输入原文deidentified_text脱敏后文本pii_entities检测并脱敏的实体列表method所用脱敏方法timestamp执行时间mapping可选的可逆映射keep_mappingTrue时返回。当多个原文拼写映射到同一替换面时使用私有 occurrence key 区分使不同的源拼写在脱敏文本不变的前提下仍可逐条恢复audit_report审计报告auditTrue时附带。三个实用方法to_dict()序列化为字典含num_entities_redacted与audit_report_repr_html_()在 Jupyter/IPython 中自动渲染高亮 PII 跨度视图置信度默认隐藏避免隐式展示敏感置信信息to_dataframe()转为 pandas DataFrame每实体一行列含text、label、entity_type、start、end、confidence、action、result_id未安装 pandas 时抛MissingExtraError。4.deidentify七种脱敏策略与可逆映射定义位于 openmed/core/pii.py是 OpenMed 的脱敏主入口内部构造 openmed/core/pipeline.py 的Pipeline并执行完整管线。4.1 支持的脱敏方法method方法行为mask默认替换为占位符如[NAME]、[EMAIL]aadhaar_mask合法的印度 Aadhaar 号渲染为XXXX XXXX NNNN其余实体用普通占位符remove完全移除替换为空串replace替换为逼真的假数据基于 Faker 与语言 localehash替换为一致性哈希值用于实体关联如NAME_a1b2c3d4format_preserve保持结构标识符的形状与分隔符生成合成值不支持的标签回退为掩码shift_dates按随机偏移平移日期且保持日期区间关系兼容性shift_datesTrue是methodshift_dates的弃用别名若shift_datesFalse与methodshift_dates冲突、或date_shift_days/patient_key等日期参数在非日期方法下使用都会抛出带明确修复指引的InputError。4.2 关键参数参数默认值说明confidence_threshold0.7脱敏置信度下限默认高于extract_pii的0.5体现检测可宽、脱敏从严的安全设计keep_yearFalse日期脱敏时保留年份不变date_shift_daysNone未提供patient_key时的固定偏移天数提供patient_key时作为历史最大绝对偏移上限除非同时给出date_shift_max_dayspatient_keyNone稳定患者标识仅用于派生确定性 HMAC 日期偏移原始键不记录、不持久化、不返回date_shift_max_daysNone最大绝对偏移提供patient_key/seed且二者均未设置时默认365date_shift_secretNoneHMAC 密钥材料跨会话复用同一值可保持偏移稳定与patient_key成对使用keep_mappingFalse是否保留用于reidentify的映射consistentFalsereplace/format_preserve下生成稳定代理同输入→同输出跨调用内一致seedNone请求级整数种子实现替换与自动日期平移的跨运行可复现对替换方法隐含consistentTruelocaleNoneFaker locale 覆盖如pt_BR、en_GB未指定时由lang推导surrogate_vaultNone跨文档代理保险库只存储 HMAC 源哈希Indic 姓名以语音折叠的 HMAC 复用身份并按输入文字渲染折叠本身永不持久化或审计policyNone策略配置名控制仲裁、动作选择、强制安全扫描与可逆映射calibration_thresholds_pathNonethresholds.json工件路径提供后按标签的校准阈值过滤检测并进入审计输出use_safety_sweepTrue模型检测后、脱敏前执行确定性结构化标识符扫描auditFalseTrue时返回AuditReport而非DeidentificationResultbudgetNone请求级墙钟/字符预算其余参数config、use_smart_merging、lang、normalize_accents、loader、custom_recognizer、abdm、code_mixed、token_language_tags、lid_model、transliterated_name_config、cache_results语义与extract_pii一致。4.3 返回与审计默认返回DeidentificationResultauditTrue时返回确定性AuditReport由 openmed/core/audit.py 提供包含DetectorInfo列表每个检测器的来源、模型 ID、格式ml/rules、commit 等以及经_sanitize_audit_evidence清洗的证据——所有文本类键text、word、surface、replacement、original_text、deidentified_text等一律从审计证据中剔除确保 PHI 安全。5.reidentify基于映射的逆向恢复定义位于 openmed/core/pii.py。要求脱敏时使用了keep_mappingTrue。reidentify(deidentified_text: str, mapping: Mapping[str, str]) - str实现要点入参严格校验deidentified_text必须是strmapping必须是字符串键值映射否则抛InputError并给出修复指引支持occurrence-aware 映射当不同原文拼写碰撞到同一替换面时映射键以__openmed_occurrence_v1__:ordinal:surface形式记录reidentify先按出现顺序恢复这些条目再用普通映射做全局替换源码模块 docstring 给出简洁示例from openmed import reidentify reidentify( Patient [NAME] called [PHONE], {[NAME]: Casey Example, [PHONE]: 555-0100}, ) # Patient Casey Example called 555-0100生产环境注意源码 docstring 明确提示重标识需要适当的授权与审计日志属于高敏感操作。6.analyze_text通用临床 NER 分析定义于 openmed/init.py运行 token 分类模型并格式化预测结果。与extract_pii的差异在于它是通用 NER默认模型disease_detection_superclinical不绑定 PII 语义可用于疾病、症状等临床概念抽取。主要参数model_name/model_id注册表键、HF 模型 ID 或本地路径二者只能传其一aggregation_strategyHF 聚合策略默认simpleNone时返回原始 token 输出output_formatdict默认、json、html、csvinclude_confidence/confidence_threshold置信度输出与过滤group_entities格式化输出中合并相邻同标签实体sentence_detection默认True/sentence_language/sentence_backend句子级分块推理sentence_backend可为auto默认路由或yasbd实验特性需openmed[yasbd]extraassert_context为每个实体附加确定性否定、不确定性、体验者与时间性标签存于metadata[clinical_context]默认关闭cache_results/max_cache_entries进程内 LRU 缓存可能含 PHI不落盘。底层实现会先按句子分段sentence_utils.segment_text以「最多 6 个句子 /max(480, max_length*4)字符」为界构造推理分块随后将各块预测偏移回填到原文坐标并在硬换行与句界处切分跨度、跳过占位符片段。若OpenMedConfig.use_medical_tokenizerTrue还会把模型跨度重映射到医学友好 tokenopenmed/processing/tokenization.py 的remap_predictions_to_tokens。7.list_models与模型发现定义于 openmed/init.pylist_models(*, include_registry: bool True, include_remote: bool True, config: Optional[OpenMedConfig] None) - List[str]include_registry是否在提交的 manifest 之外并入捆绑注册表中的条目include_remote为兼容保留不会执行实时远程发现离线优先设计返回可用模型标识符列表。配套发现能力还包括get_model_info、get_models_by_category、get_default_pii_model、get_pii_models_by_language、search_modelsModelQuery以及 HF Hub 拉取助手prefetch_model、list_cached_models、clear_cached_model、resolve_repo_idopenmed/core/hf_hub.py。8.BatchProcessor批量处理BatchProcessor定义于 openmed/processing/batch.py配套数据结构包括BatchItem、BatchItemResult、BatchResult、BatchProgress、DatasetRedactionResult等顶层从 openmed/processing 导出。典型用法是把多条文本组装为BatchItem列表每项含文本与自定义元数据提交后逐条执行检测/脱敏结果通过BatchResult汇总并可在BatchProgress中观察进度。仓库还提供更高层的process_batch函数与redact_dataset数据集级脱敏返回DatasetRedactionResult/DatasetRedactionSummary以及流式能力deidentify_stream、deidentify_document_stream。异步变体见 openmed/aio.pyabatch、aextract_pii、adeidentify、aanalyze_text。9. 结构化错误体系一个根、十个叶OpenMed 在 Python、REST 与 MCP 三端暴露同一棵错误契约详见 docs/api/errors.md。所有期望内的公开失败都继承自OpenMedErroropenmed/core/errors.py并具备四个稳定能力code稳定的小写机器可读错误码ClassVarmessage可操作的、不含 PHI的人类可读信息details非敏感结构化上下文计数、偏移、标签、哈希等to_dict(include_detailsTrue)返回{code, message, details}JSON 就绪对象。9.1 错误类层级与传输映射Python 异常稳定 code兼容内建基类REST 状态MCP codeOpenMedErroropenmed_errorException500openmed_errorInputErrorinput_errorValueError,TypeError400input_errorConfigurationErrorconfiguration_errorValueError,TypeError,KeyError400configuration_errorCapabilityErrorcapability_errorImportError503capability_errorMissingExtraErrormissing_extraImportError503missing_extraModelLoadErrormodel_load_errorImportError,ValueError503model_load_errorPolicyErrorpolicy_errorValueError,TypeError400policy_errorBudgetExceededErrorbudget_exceededRuntimeError503budget_exceededInternalErrorinternal_errorRuntimeError500internal_errorInferenceErrorinference_errorRuntimeError500inference_error继承关系MissingExtraError与ModelLoadError继承自CapabilityErrorInferenceError继承自InternalError。兼容内建基类的设计让存量except ValueError/except ImportError/except RuntimeError处理器在迁移期间继续工作。共享输入校验还保留更细的稳定叶码text_required、text_type、invalid_encoding、empty_text、min_chars、max_chars、max_bytes、language_required、language_type、unsupported_language、suspicious_content这些仍是InputError实例。openmed.ERROR_CODES是类名→code 的机器可读注册表openmed/core/errors.pycode 永不复用变更或删除已发布 code 属于兼容性破坏。9.2 推荐捕获模式import openmed try: result openmed.deidentify(payload, methodmask) except openmed.InputError as error: # 修正请求按 code 分支而不是匹配 message 文本 print(error.code, error.details) except openmed.CapabilityError as error: # 先安装/配置所请求的本地能力再重试 print(error.code) except openmed.OpenMedError as error: # 其余可预期失败都扎根于此 print(error.code)9.3 PHI 安全的诊断redact_detail错误消息绝不包含临床原文、检测到的标识符表面、可逆映射、凭据或密钥材料。当需要在本地关联不可信文本时使用redact_detailopenmed/core/errors.pyfrom openmed import redact_detail descriptor redact_detail(untrusted_value) # redacted bytes... sha256...描述符只含 UTF-8 字节长度与完整 SHA-256 摘要不要把原始值塞进自定义错误消息或details。9.4 REST 与 MCP 行为REST 侧使用标准错误信封{error: {code: ..., message: ..., details: ...}}可纠正的输入/配置/策略失败返回 HTTP 400能力缺失与预算超限返回 503内部与推理失败返回 500服务端响应将details置为null以避免暴露内部上下文。MCP 工具在结构化内容中返回同样的 code 与 message并同时置协议错误标志与is_error: true。10. PDF 脱敏与保真验证openmed.multimodal提供四个面向 PDF 的公开函数可用于「渲染红action 版 PDF 验证脱敏完整性」的闭环render_redacted_pdf(...)openmed/multimodal/render_pdf.py依据检测/脱敏结果渲染红action涂黑版 PDFmeasure_pdf_layout_fidelity(...)openmed/multimodal/render_pdf.py度量红action 后版面保真度用于评估脱敏对布局的影响verify_redacted_pdf(...)openmed/multimodal/verify_pdf.py校验输出 PDF 的脱敏状态verify_redacted_text_removed(...)openmed/multimodal/verify_pdf.py验证指定文本确实已从 PDF 中移除。这些函数与仓库中 docs/multimodal/pdf-redaction-fidelity.md、docs/multimodal/pdf-reading-order.md 描述的能力对应适合构建先脱敏、再验证、后发布的文档管线。11. 可观测性PipelineTelemetry与StageTelemetry定义于 openmed/core/telemetry.pyPipelineTelemetry默认关闭opt-in的 OpenTelemetry spans 与指标记录器。可传入调用方自有的 tracer/meterOpenMed 本身从不配置 provider、从不创建 exporter 或任何网络出口因此启用遥测不会把数据发送到任何目的地。StageTelemetry单个管线阶段的 No-PHI 记录器由PipelineTelemetry.stage_span创建。setter 只接受聚合值全部 span 属性经safe_stage_attributes过滤。StageTelemetry提供的方法全部记录聚合值、绝不落实体原文set_span_count(count)/set_entity_count(count)本阶段产生的规范跨度数与实体数openmed.stage.span_count/openmed.stage.entity_countset_labels(labels)记录规范化类别标签集合永远不是实体文本set_input_length(length)/set_redacted_length(length)输入字符数与输出脱敏字符数set_offset_range(start, end)聚合输出边界openmed.stage.offset.start_min/end_max不存储检测表面mark_failed()标记失败阶段不记录异常或消息finish(duration_ms)结束阶段并记录时长与聚合直方图。环境变量OPENMED_TELEMETRY可控制默认开关见parse_telemetry_enabled/telemetry_enabled_from_env。该设计呼应 docs/operations/no-phi-telemetry.md 的 no-PHI 遥测原则。12. 组合实战一条合规的端到端管线把上述 API 串联成一个典型工作流import openmed note ( Ms. Casey Example, DOB 01/15/1970, SSN 123-45-6789, was seen at 555-0100 for asthma follow-up on 03/12/2026. ) # 1) 先提取观察检测结果阈值可放宽到 0.5 found openmed.extract_pii(note, confidence_threshold0.5) for entity in found.entities: print(entity.label, entity.text, round(entity.confidence, 2)) # 2) 生产脱敏更高阈值 replace 假名 保留映射 一致性代理 masked openmed.deidentify( note, methodreplace, # 或用 mask / hash / format_preserve confidence_threshold0.7, keep_mappingTrue, consistentTrue, use_safety_sweepTrue, # 覆盖 SSN 等结构化标识符 ) print(masked.deidentified_text) # 3) 受控场景下按映射还原需授权与审计 restored openmed.reidentify(masked.deidentified_text, masked.mapping) assert restored note如需错误处理在deidentify外围包裹第 9.2 节的try/except并可按需传入budgetRequestBudget防止超大请求拖垮本地推理。全部处理在本机完成患者数据不出网络边界。延伸阅读结构化错误契约全文docs/api/errors.mdPII 实体合并与语义单元openmed/core/pii_entity_merger.py脱敏器与假数据生成openmed/core/anonymizer预算控制openmed/core/budget.py批量处理与数据集脱敏openmed/processing/batch.pyREST 服务形态docs/rest-service.md 与 docs/api-reference.md 配套的 docs/api/openapi.json端到端示例脚本examples/first_five_minutes_redact_extract_fhir.py、examples/pii_batch_processing.py【免费下载链接】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），仅供参考 OpenMed Python API 完全参考：PII 提取、去标识化、可逆重标识与结构化错误体系
OpenMed Python API 完全参考PII 提取、去标识化、可逆重标识与结构化错误体系【免费下载链接】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 官方 API 参考docs/api-reference.md为主线结合仓库源码openmed/core/pii.py、openmed/core/errors.py、openmed/init.py 等逐项解读顶层公开 API。你将掌握extract_pii、deidentify、reidentify三大 PII 核心函数及analyze_text、list_models、BatchProcessor等配套能力的完整签名、参数语义与实战用法理解从检测到脱敏、再到可审计重标识的全链路编程模型并学会用统一的OpenMedError错误树含 REST/MCP 映射安全地处理失败。所有结论均可回溯到当前仓库源码适用于在本地构建 HIPAA 合规的临床文本处理管线。1. 快速上手与公共 API 表面OpenMed 的顶层包openmed采用**惰性导入lazy import**机制openmed/init.py 中的__getattr__会在首次访问符号时才从对应子模块加载__dir__()则暴露全部可发现的顶层导出。这意味着import openmed本身开销极低且只有真正用到的能力才会被加载——对端侧部署与冷启动敏感场景友好。顶层 API 分组见 openmed/init.py 的__all__大致包括PII 检测与去标识化extract_pii、deidentify、reidentify、PIIEntity、DeidentificationResult通用 NER 分析analyze_text、AnalyzeResult模型发现list_models、get_model_info、get_models_by_category、search_models、get_default_pii_model等批处理与文档流BatchProcessor、process_batch、redact_dataset、deidentify_document_stream结构化错误OpenMedError及其十个子类、ERROR_CODES、redact_detailPDF 处理openmed.multimodal下的render_redacted_pdf、verify_redacted_pdf、verify_redacted_text_removed、measure_pdf_layout_fidelity可观测性openmed.core.telemetry.PipelineTelemetry、StageTelemetry。一个最简的端到端示例与源码 docstring 中reidentify的用法一致import openmed # 1) 检测 result openmed.extract_pii( Patient Casey Example called from 555-0100 on 01/15/1970., confidence_threshold0.5, ) # 2) 脱敏mask 策略默认即保留映射以支持逆向 d openmed.deidentify( Patient Casey Example called from 555-0100 on 01/15/1970., methodmask, keep_mappingTrue, ) print(d.deidentified_text) # 形如 Patient [NAME] called from [PHONE] on [DATE] # 3) 依据映射恢复 restored openmed.reidentify(d.deidentified_text, d.mapping) print(restored) # 还原原始文本2.extract_pii检测临床文本中的 PII 实体定义位于 openmed/core/pii.py。它使用 token 分类模型检测姓名、邮箱、电话、地址及其他受 HIPAA 保护的标识符模块 docstring 声称支持 18 实体类型并通过**智能实体合并smart merging**把被模型切碎的片段如日期01与/15/1970依据正则语义单元重新合并为完整实体01/15/1970再以主导标签dominant label归类。2.1 函数签名extract_pii( text: str | bytes | bytearray | memoryview, model_name: str OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1, confidence_threshold: float 0.5, config: Optional[OpenMedConfig] None, use_smart_merging: bool True, lang: str en, cache_results: bool False, max_cache_entries: int 128, normalize_accents: Optional[bool] None, *, preserve_whitespace: bool False, locale: Optional[str] None, loader: Optional[ModelLoader] None, batch_size: Optional[int] None, num_workers: Optional[int] None, custom_recognizer: Any None, abdm: Optional[bool] None, code_mixed: bool False, token_language_tags: Optional[Sequence[Any]] None, lid_model: Optional[TokenLIDHook] None, transliterated_name_config: Any None, budget: Optional[RequestBudget] None, ) - PredictionResult2.2 核心参数语义参数默认值说明text—支持str及bytes/bytearray/memoryview入口先经validate_pii_input校验model_nameOpenMed/OpenMed-PII-SuperClinical-Small-44M-v1PII 模型标识注册表键、Hugging Face 仓库 ID 或本地路径当lang ! en时自动切换到对应语言的默认模型confidence_threshold0.5置信度下限0–1低于阈值的结果被过滤use_smart_mergingTrue是否启用基于正则的语义单元合并官方推荐保持开启langenISO 639-1 语言码en、fr、de、it、es、nl、hi、te、pt、ar、ja、tr 等控制默认模型、正则模式与替换假数据hi/te的拉丁/天城文、拉丁/泰卢固文混合文本会自动走脚本感知的印度临床路由normalize_accentsNone推理前是否去除变音符号None表示对_ACCENT_NORMALIZE_LANGS当前为西班牙语es自动开启。结果中的实体偏移始终指向原始带重音文本preserve_whitespaceFalse保留首尾空白使返回偏移精确对应输入串custom_recognizerNone自定义识别器CustomRecognizer实例或 JSON/YAML 配置路径deny-list 命中以custom:deny溯源加入allow-list 命中抑制任何检测器的重叠跨度abdmNone印度 ABDM 标识符包开关None对印地语/泰卢固语及印度 locale 自动开启False显式关闭code_mixedFalse显式英语/印地语混合路径需配合token_language_tagsen/hi/ne/univ/other标签流budgetNone每次请求的墙钟时间与输入字符预算超长输入在模型推理前即被拒绝cache_results/max_cache_entriesFalse/128进程内 LRU 结果缓存缓存可能含 PHI但永不落盘2.3 底层流程与返回结构从源码调用链看extract_pii依次完成输入校验与预算检查 → 缓存查找 → 构造_extract_pii_batch单元素批 →可选Unicode 归一化与变音去除、印度临床脚本窗口路由、隐私过滤模型分发 → 智能合并 → 确定性safety_sweep补充结构化标识符SSN/身份证等→ 实体跨度校验validate_entity_spans→ 返回PredictionResult。返回的PredictionResult含text、entities、model_name、timestamp每条实体为PIIEntity见第 3 节。若lang指定的语言没有捆绑模型会抛出带明确指引的ModelLoadError例如提示设置INDIC_NER_MODEL_ENV或显式传model_name。3. 核心数据结构PIIEntity与DeidentificationResult3.1PIIEntity定义于 openmed/core/pii.py继承自EntityPrediction除基础text/label/start/end/confidence外还包含 PII 专属字段entity_typePII 类别与label相同构造时自动回填redacted_text/original_text脱敏后替换文本与脱敏前原文hash_value用于实体关联的一致性哈希reversible_id可选的可逆假名化句柄canonical_label规范化类别标签用于跨模型的标签归一sources/evidence实体来源如ml、locale_rule、safety_sweep、custom:deny与证据action/surrogate脱敏动作与代理值。3.2DeidentificationResult定义于 openmed/core/pii.py字段包括original_text输入原文deidentified_text脱敏后文本pii_entities检测并脱敏的实体列表method所用脱敏方法timestamp执行时间mapping可选的可逆映射keep_mappingTrue时返回。当多个原文拼写映射到同一替换面时使用私有 occurrence key 区分使不同的源拼写在脱敏文本不变的前提下仍可逐条恢复audit_report审计报告auditTrue时附带。三个实用方法to_dict()序列化为字典含num_entities_redacted与audit_report_repr_html_()在 Jupyter/IPython 中自动渲染高亮 PII 跨度视图置信度默认隐藏避免隐式展示敏感置信信息to_dataframe()转为 pandas DataFrame每实体一行列含text、label、entity_type、start、end、confidence、action、result_id未安装 pandas 时抛MissingExtraError。4.deidentify七种脱敏策略与可逆映射定义位于 openmed/core/pii.py是 OpenMed 的脱敏主入口内部构造 openmed/core/pipeline.py 的Pipeline并执行完整管线。4.1 支持的脱敏方法method方法行为mask默认替换为占位符如[NAME]、[EMAIL]aadhaar_mask合法的印度 Aadhaar 号渲染为XXXX XXXX NNNN其余实体用普通占位符remove完全移除替换为空串replace替换为逼真的假数据基于 Faker 与语言 localehash替换为一致性哈希值用于实体关联如NAME_a1b2c3d4format_preserve保持结构标识符的形状与分隔符生成合成值不支持的标签回退为掩码shift_dates按随机偏移平移日期且保持日期区间关系兼容性shift_datesTrue是methodshift_dates的弃用别名若shift_datesFalse与methodshift_dates冲突、或date_shift_days/patient_key等日期参数在非日期方法下使用都会抛出带明确修复指引的InputError。4.2 关键参数参数默认值说明confidence_threshold0.7脱敏置信度下限默认高于extract_pii的0.5体现检测可宽、脱敏从严的安全设计keep_yearFalse日期脱敏时保留年份不变date_shift_daysNone未提供patient_key时的固定偏移天数提供patient_key时作为历史最大绝对偏移上限除非同时给出date_shift_max_dayspatient_keyNone稳定患者标识仅用于派生确定性 HMAC 日期偏移原始键不记录、不持久化、不返回date_shift_max_daysNone最大绝对偏移提供patient_key/seed且二者均未设置时默认365date_shift_secretNoneHMAC 密钥材料跨会话复用同一值可保持偏移稳定与patient_key成对使用keep_mappingFalse是否保留用于reidentify的映射consistentFalsereplace/format_preserve下生成稳定代理同输入→同输出跨调用内一致seedNone请求级整数种子实现替换与自动日期平移的跨运行可复现对替换方法隐含consistentTruelocaleNoneFaker locale 覆盖如pt_BR、en_GB未指定时由lang推导surrogate_vaultNone跨文档代理保险库只存储 HMAC 源哈希Indic 姓名以语音折叠的 HMAC 复用身份并按输入文字渲染折叠本身永不持久化或审计policyNone策略配置名控制仲裁、动作选择、强制安全扫描与可逆映射calibration_thresholds_pathNonethresholds.json工件路径提供后按标签的校准阈值过滤检测并进入审计输出use_safety_sweepTrue模型检测后、脱敏前执行确定性结构化标识符扫描auditFalseTrue时返回AuditReport而非DeidentificationResultbudgetNone请求级墙钟/字符预算其余参数config、use_smart_merging、lang、normalize_accents、loader、custom_recognizer、abdm、code_mixed、token_language_tags、lid_model、transliterated_name_config、cache_results语义与extract_pii一致。4.3 返回与审计默认返回DeidentificationResultauditTrue时返回确定性AuditReport由 openmed/core/audit.py 提供包含DetectorInfo列表每个检测器的来源、模型 ID、格式ml/rules、commit 等以及经_sanitize_audit_evidence清洗的证据——所有文本类键text、word、surface、replacement、original_text、deidentified_text等一律从审计证据中剔除确保 PHI 安全。5.reidentify基于映射的逆向恢复定义位于 openmed/core/pii.py。要求脱敏时使用了keep_mappingTrue。reidentify(deidentified_text: str, mapping: Mapping[str, str]) - str实现要点入参严格校验deidentified_text必须是strmapping必须是字符串键值映射否则抛InputError并给出修复指引支持occurrence-aware 映射当不同原文拼写碰撞到同一替换面时映射键以__openmed_occurrence_v1__:ordinal:surface形式记录reidentify先按出现顺序恢复这些条目再用普通映射做全局替换源码模块 docstring 给出简洁示例from openmed import reidentify reidentify( Patient [NAME] called [PHONE], {[NAME]: Casey Example, [PHONE]: 555-0100}, ) # Patient Casey Example called 555-0100生产环境注意源码 docstring 明确提示重标识需要适当的授权与审计日志属于高敏感操作。6.analyze_text通用临床 NER 分析定义于 openmed/init.py运行 token 分类模型并格式化预测结果。与extract_pii的差异在于它是通用 NER默认模型disease_detection_superclinical不绑定 PII 语义可用于疾病、症状等临床概念抽取。主要参数model_name/model_id注册表键、HF 模型 ID 或本地路径二者只能传其一aggregation_strategyHF 聚合策略默认simpleNone时返回原始 token 输出output_formatdict默认、json、html、csvinclude_confidence/confidence_threshold置信度输出与过滤group_entities格式化输出中合并相邻同标签实体sentence_detection默认True/sentence_language/sentence_backend句子级分块推理sentence_backend可为auto默认路由或yasbd实验特性需openmed[yasbd]extraassert_context为每个实体附加确定性否定、不确定性、体验者与时间性标签存于metadata[clinical_context]默认关闭cache_results/max_cache_entries进程内 LRU 缓存可能含 PHI不落盘。底层实现会先按句子分段sentence_utils.segment_text以「最多 6 个句子 /max(480, max_length*4)字符」为界构造推理分块随后将各块预测偏移回填到原文坐标并在硬换行与句界处切分跨度、跳过占位符片段。若OpenMedConfig.use_medical_tokenizerTrue还会把模型跨度重映射到医学友好 tokenopenmed/processing/tokenization.py 的remap_predictions_to_tokens。7.list_models与模型发现定义于 openmed/init.pylist_models(*, include_registry: bool True, include_remote: bool True, config: Optional[OpenMedConfig] None) - List[str]include_registry是否在提交的 manifest 之外并入捆绑注册表中的条目include_remote为兼容保留不会执行实时远程发现离线优先设计返回可用模型标识符列表。配套发现能力还包括get_model_info、get_models_by_category、get_default_pii_model、get_pii_models_by_language、search_modelsModelQuery以及 HF Hub 拉取助手prefetch_model、list_cached_models、clear_cached_model、resolve_repo_idopenmed/core/hf_hub.py。8.BatchProcessor批量处理BatchProcessor定义于 openmed/processing/batch.py配套数据结构包括BatchItem、BatchItemResult、BatchResult、BatchProgress、DatasetRedactionResult等顶层从 openmed/processing 导出。典型用法是把多条文本组装为BatchItem列表每项含文本与自定义元数据提交后逐条执行检测/脱敏结果通过BatchResult汇总并可在BatchProgress中观察进度。仓库还提供更高层的process_batch函数与redact_dataset数据集级脱敏返回DatasetRedactionResult/DatasetRedactionSummary以及流式能力deidentify_stream、deidentify_document_stream。异步变体见 openmed/aio.pyabatch、aextract_pii、adeidentify、aanalyze_text。9. 结构化错误体系一个根、十个叶OpenMed 在 Python、REST 与 MCP 三端暴露同一棵错误契约详见 docs/api/errors.md。所有期望内的公开失败都继承自OpenMedErroropenmed/core/errors.py并具备四个稳定能力code稳定的小写机器可读错误码ClassVarmessage可操作的、不含 PHI的人类可读信息details非敏感结构化上下文计数、偏移、标签、哈希等to_dict(include_detailsTrue)返回{code, message, details}JSON 就绪对象。9.1 错误类层级与传输映射Python 异常稳定 code兼容内建基类REST 状态MCP codeOpenMedErroropenmed_errorException500openmed_errorInputErrorinput_errorValueError,TypeError400input_errorConfigurationErrorconfiguration_errorValueError,TypeError,KeyError400configuration_errorCapabilityErrorcapability_errorImportError503capability_errorMissingExtraErrormissing_extraImportError503missing_extraModelLoadErrormodel_load_errorImportError,ValueError503model_load_errorPolicyErrorpolicy_errorValueError,TypeError400policy_errorBudgetExceededErrorbudget_exceededRuntimeError503budget_exceededInternalErrorinternal_errorRuntimeError500internal_errorInferenceErrorinference_errorRuntimeError500inference_error继承关系MissingExtraError与ModelLoadError继承自CapabilityErrorInferenceError继承自InternalError。兼容内建基类的设计让存量except ValueError/except ImportError/except RuntimeError处理器在迁移期间继续工作。共享输入校验还保留更细的稳定叶码text_required、text_type、invalid_encoding、empty_text、min_chars、max_chars、max_bytes、language_required、language_type、unsupported_language、suspicious_content这些仍是InputError实例。openmed.ERROR_CODES是类名→code 的机器可读注册表openmed/core/errors.pycode 永不复用变更或删除已发布 code 属于兼容性破坏。9.2 推荐捕获模式import openmed try: result openmed.deidentify(payload, methodmask) except openmed.InputError as error: # 修正请求按 code 分支而不是匹配 message 文本 print(error.code, error.details) except openmed.CapabilityError as error: # 先安装/配置所请求的本地能力再重试 print(error.code) except openmed.OpenMedError as error: # 其余可预期失败都扎根于此 print(error.code)9.3 PHI 安全的诊断redact_detail错误消息绝不包含临床原文、检测到的标识符表面、可逆映射、凭据或密钥材料。当需要在本地关联不可信文本时使用redact_detailopenmed/core/errors.pyfrom openmed import redact_detail descriptor redact_detail(untrusted_value) # redacted bytes... sha256...描述符只含 UTF-8 字节长度与完整 SHA-256 摘要不要把原始值塞进自定义错误消息或details。9.4 REST 与 MCP 行为REST 侧使用标准错误信封{error: {code: ..., message: ..., details: ...}}可纠正的输入/配置/策略失败返回 HTTP 400能力缺失与预算超限返回 503内部与推理失败返回 500服务端响应将details置为null以避免暴露内部上下文。MCP 工具在结构化内容中返回同样的 code 与 message并同时置协议错误标志与is_error: true。10. PDF 脱敏与保真验证openmed.multimodal提供四个面向 PDF 的公开函数可用于「渲染红action 版 PDF 验证脱敏完整性」的闭环render_redacted_pdf(...)openmed/multimodal/render_pdf.py依据检测/脱敏结果渲染红action涂黑版 PDFmeasure_pdf_layout_fidelity(...)openmed/multimodal/render_pdf.py度量红action 后版面保真度用于评估脱敏对布局的影响verify_redacted_pdf(...)openmed/multimodal/verify_pdf.py校验输出 PDF 的脱敏状态verify_redacted_text_removed(...)openmed/multimodal/verify_pdf.py验证指定文本确实已从 PDF 中移除。这些函数与仓库中 docs/multimodal/pdf-redaction-fidelity.md、docs/multimodal/pdf-reading-order.md 描述的能力对应适合构建先脱敏、再验证、后发布的文档管线。11. 可观测性PipelineTelemetry与StageTelemetry定义于 openmed/core/telemetry.pyPipelineTelemetry默认关闭opt-in的 OpenTelemetry spans 与指标记录器。可传入调用方自有的 tracer/meterOpenMed 本身从不配置 provider、从不创建 exporter 或任何网络出口因此启用遥测不会把数据发送到任何目的地。StageTelemetry单个管线阶段的 No-PHI 记录器由PipelineTelemetry.stage_span创建。setter 只接受聚合值全部 span 属性经safe_stage_attributes过滤。StageTelemetry提供的方法全部记录聚合值、绝不落实体原文set_span_count(count)/set_entity_count(count)本阶段产生的规范跨度数与实体数openmed.stage.span_count/openmed.stage.entity_countset_labels(labels)记录规范化类别标签集合永远不是实体文本set_input_length(length)/set_redacted_length(length)输入字符数与输出脱敏字符数set_offset_range(start, end)聚合输出边界openmed.stage.offset.start_min/end_max不存储检测表面mark_failed()标记失败阶段不记录异常或消息finish(duration_ms)结束阶段并记录时长与聚合直方图。环境变量OPENMED_TELEMETRY可控制默认开关见parse_telemetry_enabled/telemetry_enabled_from_env。该设计呼应 docs/operations/no-phi-telemetry.md 的 no-PHI 遥测原则。12. 组合实战一条合规的端到端管线把上述 API 串联成一个典型工作流import openmed note ( Ms. Casey Example, DOB 01/15/1970, SSN 123-45-6789, was seen at 555-0100 for asthma follow-up on 03/12/2026. ) # 1) 先提取观察检测结果阈值可放宽到 0.5 found openmed.extract_pii(note, confidence_threshold0.5) for entity in found.entities: print(entity.label, entity.text, round(entity.confidence, 2)) # 2) 生产脱敏更高阈值 replace 假名 保留映射 一致性代理 masked openmed.deidentify( note, methodreplace, # 或用 mask / hash / format_preserve confidence_threshold0.7, keep_mappingTrue, consistentTrue, use_safety_sweepTrue, # 覆盖 SSN 等结构化标识符 ) print(masked.deidentified_text) # 3) 受控场景下按映射还原需授权与审计 restored openmed.reidentify(masked.deidentified_text, masked.mapping) assert restored note如需错误处理在deidentify外围包裹第 9.2 节的try/except并可按需传入budgetRequestBudget防止超大请求拖垮本地推理。全部处理在本机完成患者数据不出网络边界。延伸阅读结构化错误契约全文docs/api/errors.mdPII 实体合并与语义单元openmed/core/pii_entity_merger.py脱敏器与假数据生成openmed/core/anonymizer预算控制openmed/core/budget.py批量处理与数据集脱敏openmed/processing/batch.pyREST 服务形态docs/rest-service.md 与 docs/api-reference.md 配套的 docs/api/openapi.json端到端示例脚本examples/first_five_minutes_redact_extract_fhir.py、examples/pii_batch_processing.py【免费下载链接】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），仅供参考