OpenMed Agent 开发指南为 AI Agent 构建本地优先的临床 NER 与 HIPAA 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 的编码型 Agentcoding agent或 LLM Agent 应用系统讲解如何安全、正确地消费 OpenMed 的本地优先医疗 AI 能力临床/生物医学命名实体识别NER、PII 检测与脱敏以及模型发现、批量处理、MCP 工具与命令行等周边设施。读完本文你将掌握analyze_text/extract_pii/deidentify三条主调用路径的完整用法、8 条不可违背的隐私不变量、MCP 工具注册表的使用方式以及避免 PHI 泄漏的工程化最佳实践。仓库根目录的 AGENTS.md 介绍的是如何向 OpenMed 贡献代码而本文介绍的是如何作为消费方安全地构建应用。说明本文所有示例均使用合成数据synthetic values。模型推理在首次下载模型后完全于本地运行无需把患者文本上传到云端。安装按需选择扩展安装核心库与本地模型运行时使用hf扩展python -m pip install openmed[hf]只有当应用确实需要相应能力时才追加可选扩展面python -m pip install openmed[hf,mcp,service]hfHugging Face 模型拉取与本地推理运行时核心依赖mcp本地 stdio 模式的 MCP 服务器见下文 MCP 服务器与工具注册表service自托管 REST 服务入口为openmed.service.app:app。从源码结构看openmed/__init__.py对所有顶层导出采用**惰性导入lazy import**机制ModelLoader、OpenMedConfig、analyze_text、extract_pii、deidentify等均在首次访问时才按_LAZY_IMPORTS映射加载对应模块。这意味着即使安装的是精简环境只要不触碰未安装扩展对应的符号导入from openmed import ...也不会因缺少可选依赖而失败。三条主调用路径1. 临床文本分析NER使用analyze_text进行临床或生物医学命名实体识别from openmed import analyze_text result analyze_text( Synthetic assessment: type 2 diabetes treated with metformin., model_namedisease_detection_superclinical, confidence_threshold0.5, ) for entity in result.entities: print(entity.label, entity.text, entity.start, entity.end)返回结果是带类型的AnalyzeResult。其entities暴露了文本片段text、标签label、置信度confidence与字符偏移start/endresult.to_dict()生成 JSON-ready 的映射。从源码看openmed/core/results.pyAnalyzeResult本身是一个Mapping[str, Any]to_dict()有意保留了 REST 服务使用的历史PredictionResult载荷结构text、entities、model_name、timestamp、processing_time、metadata方便与 HTTP 端点的输出直接对齐。analyze_text的完整签名见 openmed/init.py还支持这些常用参数model_name/model_id注册表键、完整 Hugging Face 模型 ID 或本地模型路径二者只能传其一output_formatdict默认、json、html、csvaggregation_strategyHugging Face 聚合策略默认simple设为None可取原始 token 输出group_entities在格式化输出中合并相邻同标签实体sentence_detection默认开启、sentence_language、sentence_backendauto或实验性yasbd句子级分块推理长文本按每块最多 6 句 / 约 480 字符切分后推理再把偏移量映射回原文assert_context为每个实体附加确定性否定、不确定性、经历者与时间性标注写入metadata[clinical_context]cache_results进程内 LRU 结果缓存默认 128 条仅内存、绝不落盘。2. 提取 PII 而不改写文本当应用只需要标识符的跨度与偏移时使用extract_piifrom openmed import extract_pii synthetic_note ( Synthetic patient Taylor Example, record SYNTH-0007, called 212-555-0198. ) result extract_pii( synthetic_note, langen, confidence_threshold0.5, ) for entity in result.entities: print(entity.label, entity.start, entity.end, entity.confidence)关键约束真实记录中不要打印entity.text。原始文本表面raw surfaces应只保留在可信进程内部诊断与审计输出只使用标签、偏移、哈希与置信度。源码实现openmed/core/pii.py确认extract_pii默认参数为model_name取语言对应的默认 PII 模型非en语言会自动切换语言适配模型、confidence_threshold0.5、langen、use_smart_mergingTrue。所谓智能合并smart merging是指用正则模式识别日期、SSN、电话号码等语义单元把模型碎片化预测合并为完整实体并通过支配标签dominant label消除标签冲突此外还支持custom_recognizer、印度 ABDM 模式abdmTrue、印地语/英语代码混合文本code_mixedTrue、以及budget每请求资源与超时预算等进阶能力。3. 脱敏文本使用deidentify对检测到的标识符执行掩码、删除、替换、哈希或一致性日期平移from openmed import deidentify synthetic_note ( Synthetic patient Taylor Example can be reached at demo.patientexample.test. ) result deidentify( synthetic_note, methodmask, langen, confidence_threshold0.5, ) print(result.deidentified_text) print(result.num_entities_redacted)DeidentificationResult还携带检测到的实体、元数据、可选的审计报告audit report与可选的可逆映射reversible mapping。不要把original_text、实体表面文本或映射跨不可信边界输出或记录。源码中定义了完整的脱敏方法集合openmed/core/pii.py方法含义mask默认替换为[NAME]、[EMAIL]等占位符aadhaar_mask印度 Aadhaar 号码专用掩码remove直接删除标识符replace用生成代理值替换可配合surrogate_vault持久化hash使用键控哈希替换shift_dates一致性日期平移date_shift_days、date_shift_max_days、date_shift_secretformat_preserve保留格式的替换值得注意的实现细节deidentify的默认confidence_threshold0.7高于extract_pii的 0.5——源码注释明确这是为了安全而采用的更高阈值Higher threshold for safety且keep_mapping默认False只有当显式需要可逆脱敏时才打开并应配合加密与隔离存储。use_safety_sweepTrue还会在模型输出之外做一轮安全清扫。公开 API 全景图下表梳理了 Agent 构建应用时最常用的公开面详见 api-reference.md 的签名说明与 feature-map.md 的模块映射任务公开面结果或用途临床 NERopenmed.analyze_text带类型实体跨度的AnalyzeResultPII 检测openmed.extract_pii不改写文本的 PII 预测脱敏openmed.deidentifyDeidentificationResult与改写后的文本重识别openmed.reidentify仅能通过显式保留的映射恢复批量文本处理openmed.BatchProcessor、openmed.process_batch跨多条输入复用模型状态数据集脱敏openmed.redact_dataset独立的 CSV / JSONL / Parquet 输出加聚合摘要模型发现openmed.get_model_info、get_models_by_category、get_pii_models_by_language离线注册表元数据模型加载openmed.ModelLoader、openmed.load_model显式模型生命周期与缓存复用FHIR 导出openmed.clinical.exporters.fhir确定性的 FHIR R4 辅助工具评估openmed.eval召回、泄漏、校准与发布门禁Agent 工具openmed.mcp.tool_registry带类型的工具定义与校验本地服务openmed.service.app:app自托管 REST 端点命令行openmedanalyze、PII、dataset、model、benchmark 等命令隐私不变量Agent 必须遵守使用 OpenMed 构建应用的 Agent 必须维护以下规则推理保持在本地。首次运行可能下载模型产物稳态推理不得要求上传文本或开启遥测。在已批准的模型缓存后使用离线模式from openmed import OpenMedConfig, extract_pii config OpenMedConfig(local_onlyTrue) result extract_pii( Synthetic contact: sample.userexample.test., configconfig, )源码层面OpenMedConfig由 openmed/core/config.py 实现支持从~/.config/openmed/config.toml可用OPENMED_CONFIG环境变量覆盖路径加载并经过 Draft 2020-12 JSON Schema 校验local_onlyTrue时推理路径会进入network_blocked_if_offline守卫从机制上禁止任何网络外联。绝不把原始 PHI 放入日志、trace、缓存键、临时文件名、异常消息、分析统计或审计产物中。审计证据必须无 PHI存储偏移量、规范化标签、阈值、来源provenance、计数与键控哈希而不是标识符文本。示例与已提交的 fixture 一律使用合成数据。绝不提交受 DUA数据使用协议限制的语料或受限术语资源。验证直接标识符召回、关键泄漏critical leakage、跨度完整性与量化模型差异。聚合 F1 本身不能作为隐私门禁。把脱敏视为技术控制手段而非合规保证或自动化临床决策。可逆映射必须加密存储且与文本分离或者保持keep_mappingFalse。完整的控制机制可进一步阅读 No-Raw-PHI Logging、No-Telemetry Guarantee 与 Redactor Threat Model。MCP 服务器与工具注册表安装并启动本地 stdio 服务器python -m pip install openmed[mcp] openmed-mcp --transport stdio服务器暴露openmed_analyze_text、openmed_extract_pii、openmed_deidentify、模型发现与生命周期工具以及一个 PHI 安全的工作流执行器workflow runner。这些工具的输入/输出 schema 的权威来源是 openmed/mcp/tool_registry.py其latest_specs()返回带类型校验的ToolSpec元组server.py中每个工具实现都会经过validate_registered_tool_output(...)对输出做 schema 校验见 openmed/mcp/server.py。客户端配置与认证后的远程部署参见 MCP Client Guide。优先使用 stdio 或 loopback切勿把未认证的服务器绑定到公网接口。不需要启动 MCP 传输、只想直接获取工具定义的应用可以导入注册表本身from openmed.mcp.tool_registry import TOOL_REGISTRY for tool in TOOL_REGISTRY.latest_specs(): print(tool.name)命令行接口在不发送任何临床文本的前提下发现模型openmed models list openmed models info disease_detection_superclinicalopenmed models list默认只读离线注册表--include-remote才会查询 Hugging Face Hubopenmed models info返回模型键与推断的最大序列长度openmed/cli/typer_app.py。运行三条主路径openmed analyze \ --text Synthetic assessment: asthma treated with albuterol. openmed pii extract \ --text Synthetic contact: 212-555-0198. openmed pii deidentify \ --text Synthetic contact: demo.patientexample.test. \ --method maskopenmed analyze支持--text/-t与--input-file/-f两种输入方式、--model/-m默认disease_detection_superclinical与--format/-odict|json|html|csv且二者互斥校验未提供任何输入会报错。处理文件与数据集时优先使用--input-file、openmed deid或openmed redact-dataset以免敏感值被 shell 历史捕获。流式与聚合的 PHI 安全进度报告参见 Batch Processing。仓库内的可移植技能包仓库根目录的 skills/ 目录包含 Agent 可直接加载的可移植流程procedure技能每个技能都带一段合成数据的可运行示例并指向已入库的仓库示例。建议从以下任务配方开始skills/deidentify-a-dataset/SKILL.md数据集级脱敏流程skills/extract-clinical-entities-to-fhir/SKILL.md临床实体抽取并导出 FHIRskills/pick-a-pii-model/SKILL.md按语言与场景挑选 PII 模型skills/benchmark-pii-recall/SKILL.md以直接标识符召回为目标的基准评测。给 Agent 的落地清单把以上内容浓缩为构建阶段的自检清单用openmed[hf]起步按需追加mcp、service扩展优先走analyze_text/extract_pii/deidentify三条主路径其余能力按 API 全景表按需引入对长文本开启句子级分块默认开启并对齐confidence_threshold语义PII 检测 0.5、脱敏默认 0.7模型缓存就绪后一律使用OpenMedConfig(local_onlyTrue)日志、trace、异常与审计中只允许出现标签、偏移、哈希与计数需要可逆脱敏时使用加密隔离的 mapping否则保持keep_mappingFalse数据文件处理走--input-file/deid/redact-dataset避免命令行泄密需要工具化集成时优先 stdio/loopback MCP并从TOOL_REGISTRY.latest_specs()获取权威 schema。遵循上述路径Agent 可以在不把任何患者数据送出本地网络的前提下安全地获得临床 NER 与 HIPAA PII 脱敏能力——这正是 OpenMed local-first healthcare AI 的设计初衷。【免费下载链接】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），仅供参考
