OpenMed 本地医疗 AI 部署 FAQ 实战指南：离线推理、多语言 PII 去标识化与模型选型

OpenMed 本地医疗 AI 部署 FAQ 实战指南离线推理、多语言 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 官方 FAQ 为核心骨架系统解答团队在本地临床 NLP、PII 检测、去标识化与服务化部署中最常遇到的 9 类问题能否完全离线运行、该装哪个 pip extra、DeBERTa 模型的 attention 报错、如何选模型、支持哪些语言、去标识化是否可逆、为何各国证件号都归入ID_NUM、是否必须 GPU 以及如何控制内存。读完本文你将掌握从安装、配置、选型到隐私治理与性能调优的完整决策路径并看到每条结论背后对应的仓库源码与配置文件证据。遇到具体报错而非概念性问题时建议先查阅 Troubleshooting Common Errors 中的症状 → 原因 → 修复映射表覆盖缺失 extras、模型下载/离线问题、设备选择以及 REST/MCP 配置。安装与运行能否完全本地运行或在气隙air-gapped环境中运行可以。OpenMed 的核心设计就是 local-first临床文本无需发送到任何外部服务即可完成识别与去标识化。要严格离线使用只需三步预下载模型文件将model_name或model_id指向本地目录保持运行时使用devicecpu或环境内可用的其他设备。当标识符是一个已存在的本地路径时OpenMed 会要求底层加载器使用local_files_onlyTrue因此缺失的 tokenizer、config 或权重文件会在本地直接失败而不会触发从模型中心下载。这一行为在 analyze-text.md 的 Loading from a local path 一节有完整示例import os from openmed import OpenMedConfig, analyze_text local_path os.path.abspath(./models/OpenMed-NER-DiseaseDetect-SuperClinical-434M) config OpenMedConfig(devicecpu) result analyze_text( Patient presents with chronic myeloid leukemia and Type 2 diabetes., model_idlocal_path, configconfig, )从源码看local_files_onlyTrue贯穿了所有 Hub 加载路径例如 openmed/core/hf_hub.py 中的下载流程在离线模式下以local_files_onlyTrue运行若快照未缓存则直接抛出OfflineModeError而不是尝试网络抓取openmed/core/backends.py 中 ONNX 与 PyTorch privacy-filter 管线也都通过is_local_only(self._config)判断并注入local_files_only参数。在预热好配置的缓存之后设置OPENMED_OFFLINE1或使用OpenMedConfig(local_onlyTrue)即可进入严格离线模式。此时 OpenMed 会启用 Hugging Face 的 cache-only 标志HF_HUB_OFFLINE1、TRANSFORMERS_OFFLINE1、HF_DATASETS_OFFLINE1向 Hub 加载器传递local_files_onlyTrue在推理与去标识化期间阻止出站 socket 连接——任何被禁止的连接都会抛出OfflineModeError错误信息前缀为OPENMED_OFFLINE/local_onlyTrue blocks outbound network access after model loading.详见 configuration.md 的 Local-only offline mode 一节与 troubleshooting.md 的离线条目。正确流程是先联网预热缓存再启用离线模式# 1. 有网时下载一次填充 ~/.cache/openmed python -c from openmed.core import ModelLoader; ModelLoader().load_model(disease_detection_superclinical) # 2. 然后严格本地运行 export OPENMED_OFFLINE1对于机构内部使用 pip 镜像的场景HF_ENDPOINT、HTTP 代理、可断点续传的缓存预热、计量连接检查清单可参考 low-bandwidth-install.md低带宽安装指南。应该安装哪个包 extrasOpenMed 采用小而精的核心 按需选装的依赖策略重依赖与平台专属栈都声明在 pyproject.toml 的[project.optional-dependencies]中。选择与你的运行时匹配的最小 extra场景安装命令标准 Python 模型运行时pip install openmed[hf]需要 REST 服务FastAPI/uvicornpip install openmed[hf,service]Apple Silicon 上的 Python MLX 加速pip install openmed[mlx]文档/图像摄取与 Tesseract OCRpip install openmed[multimodal]更重的可选 PaddleOCR 后端pip install openmed[ocr-paddle]注意hfextra 只提供 Transformers/tokenizers/accelerate 栈不会替你选择 PyTorch 构建版本需要按平台单独安装 CPU、CUDA 或 MPS 版 PyTorch。Tesseract 是系统二进制pip不会安装它——multimodalextra 只提供pytesseract封装还需额外执行brew install tesseractmacOS或sudo apt-get install tesseract-ocrDebian/Ubuntu。如果漏装了某个功能对应的 extra调用会抛出ImportError/ModuleNotFoundError或MissingDependencyError后者是ImportError的子类错误信息会直接给出修复命令例如Optional dependency pdfplumber is required for this operation. Install with: pip install openmed[multimodal].所有 extras 均可叠加如pip install openmed[hf,service]。完整清单见 troubleshooting.md 的 extras 表格。新手建议先走 getting-started.md快速开始再阅读 configuration.md配置与校验 了解缓存路径、设备选择、profile 与环境变量覆盖。为什么 DeBERTa 模型提示 scaled dot-product attention 不受支持OpenMed 1.7.0 与 1.8.0 存在一个已知问题仅凭运行时可用性就选择 PyTorch 的 scaled dot-product attentionsdpa而忽略 Transformers 模型架构本身是否支持。这会影响 DeBERTa-v2 token-classification 模型在 NVIDIA、AMD 或 CPU 环境都可能出现。修复方式升级到 OpenMed 1.8.1 或更高版本这些版本中的自动 attention 选择已做到架构安全。若环境临时被钉在受影响版本上可在启动 Python 前选择通用的 eager 实现 Linux/macOSbash export OPENMED_TORCH_ATTENTION_BACKENDeager Windows PowerShellpowershell $env:OPENMED_TORCH_ATTENTION_BACKENDeager Windows Command Promptbat set OPENMED_TORCH_ATTENTION_BACKENDeager 在 1.8.1 及之后torch_attention_backendauto默认值会把后端选择完全交给 Transformers让其同时考虑 PyTorch 运行时与模型架构的支持情况。受支持的显式取值为auto、eager、sdpa、flash_attention_2eager是兼容性兜底sdpa与flash_attention_2除要求 PyTorch 与硬件兼容外还要求所选 Transformers 模型架构本身支持。API 配置方式与更多细节见 configuration.md 的 PyTorch attention backends 一节。模型与语言应该用哪个模型临床实体抽取场景下按实体族选择注册表别名即可如 disease疾病、drug药物、anatomy解剖、oncology肿瘤、gene基因或 PII。OpenMed 内置一个清单驱动的注册表openmed.core.model_registry.OPENMED_MODELS为每个官方 checkpoint 标注了类别、专业化方向、推荐置信度、Hugging Face ID、设备适配度与基准摘要——非常适合驱动 UI 下拉框、文本建议、模型大小提示与推荐置信阈值。核心查询函数来自 model-registry.mdfrom openmed.core.model_registry import ( get_all_models, list_model_categories, get_models_by_category, get_model_info, get_model_suggestions, ) print(list_model_categories()) oncology_models get_models_by_category(Oncology) info get_model_info(disease_detection_superclinical) print(info.description, info.entity_types) suggestions get_model_suggestions(Metastatic breast cancer on paclitaxel.)ModelInfo对象包含display_name、category、entity_types、size_category、size_mb、latency_ms、peak_ram_mb、recommended_tier、recommended_confidence等字段前几个帮助你判断模型是否适合纯 CPU 基础设施或目标设备档位entity_types可喂给前端筛选器recommended_confidence可作为 API 调用滑块的默认值或护栏传给analyze_text。此外get_pii_models_by_language会排除 tokenizer 被审计为对某语言脚本明确unsupported的模型底层 UNK、byte-fallback、tokens-per-grapheme 等测量数据仍可通过ModelInfo.script_coverage获取用于诊断与 UI 警告。对于 PII当保持默认模型参数时extract_pii(..., langcode)会自动为请求的语言选择默认模型。只有在你需要特定 checkpoint、本地目录或 privacy-filter 家族时才应覆盖model_name。仓库根目录的 models.jsonl 是注册表的清单源提交的发布通道状态family::tier::format槽位、SemVer 分配记录在 gates/registry_state.json模型清单与注册表的同步由脚本维护避免手工编辑注册表见 model-registry.md 的 Keeping the registry fresh 一节。支持哪些语言PII 提取与去标识化支持36 个官方 PII 语言码am、ar、as、bn、cs、da、de、el、en、es、fa、fr、he、hi、id、it、ja、ko、mr、nl、no、or、pt、ro、ru、sv、sw、ta、te、th、tr、uk、vi、xh、zh、zu几个细节需要说明**俄语ru**目前使用文档化的多语言默认模型占位符路由**孟加拉语bn、中文zh、泰米尔语ta**拥有专属注册表条目另有4 个可选的印度语码gu、kn、ml、pa通过用户配置的OPENMED_INDIC_NER_MODEL走 opt-in 路由阿萨姆语、孟加拉语、印地语、马拉地语、奥里亚语、泰米尔语、泰卢固语也可使用同一适配器。该适配器只加载OPENMED_INDIC_NER_MODEL显式给出的路径或仓库没有捆绑默认 checkpoint兼容矩阵见 indic-ner-checkpoints.md面向特定证件-only 语言波兰语、拉脱维亚语、斯洛伐克语、马来语、菲律宾语、芬兰语等的 validator 支撑的国家证件号覆盖面更广——这些代码不增加默认 PII 模型但证件号生成与格式校验仍可用。语言码的权威来源是openmed.core.pii_i18n.SUPPORTED_LANGUAGES见 anonymization.md 中的 privacy-filter 家族一节REST/API 层对非支持码会抛出ValueError: Unsupported language xx见 troubleshooting.md。临床 NER 的语言覆盖取决于所选注册表模型。每个模型的languages、entity_types与专业化方向都不同在把它放到 API 或批处理作业后面之前务必先在 model-registry.md模型注册表中核对。隐私与去标识化去标识化可逆吗取决于方法。deidentify()API 支持五种脱敏方法详见 anonymization.mdPII 匿名化方法输出何时使用mask[NAME]、[EMAIL]等占位符需要清晰的占位符remove删除不需要与原文的位置对齐如索引导出replace语言环境感知的合成假数据需要看起来真实的文本hashNAME_a1b2c3d4按实体类型加摘要需要跨文档一致地关联同一值shift_dates仅日期——偏移 N 天需要保留相对时间关系对应 FAQ 的回答是mask与remove不会在输出中保留原值replace输出语言环境感知的合成替身除非你自己的工作流在外部保存映射否则不可逆hash是单向的但对重复值确定性地一致可用于跨文档关联shift_dates只有知道偏移量的人才能还原。无论哪种方法发布数据前都应审查输出。PII 检测是辅助性控制手段不能替代隐私审查流程。若在授权工作流中确实需要还原可传keep_mappingTrue并用reidentify(result.deidentified_text, result.mapping)恢复——但 mapping 包含原始标识符必须按 PHI 保护。为什么许多国家证件号都归入ID_NUMOpenMed 会把不同检测器输出的标签规范化到50 个 canonical PII 标签源码见 openmed/core/labels.py 中的CANONICAL_LABELS集合与normalize_label辅助函数模块 docstring 明确说明这是统一的UPPER_SNAKE_CASE标签分类法。ID_NUM是通用标识符的规范桶涵盖病历号、国家证件号、CPF/CNPJ、NIR、Steuer-ID、Codice Fiscale、DNI/NIE、BSN、Aadhaar、NPI 等。同时labels.py保留了一套子类型元数据ID_SUBTYPE_MRN、ID_SUBTYPE_NPI、ID_SUBTYPE_NATIONAL_ID、ID_SUBTYPE_ABHA_NUMBER、ID_SUBTYPE_UPI_ID、ID_SUBTYPE_PASSPORT_MRZ、ID_SUBTYPE_PAN、ID_SUBTYPE_GSTIN等它们仍规范化到ID_NUM但保留细粒度语义。而拥有自己规范类别的标签如SSN、ACCOUNT_NUMBER、CREDIT_CARD当检测器明确输出时仍可保持独立。这套设计让多语言模型输出保持一致同时策略 profile 仍可将各类标识符按高风险直接标识符对待——例如印度 ABHA 号、UPI ID、ration card 等在国家层面被归入ID_NUM桶但LABEL_METADATA必须与CANONICAL_LABELS精确对齐源码中有对应的一致性运行时校验覆盖缺失/多余标签即抛错。应该用可逆还是不可逆的去标识化决策依据是下游工作流是否还需要原始值不可逆输出mask、remove或单向hash下游工作流不需要原始值replace临床医生、QA 审核员或演示需要看起来真实的合成文本shift_dates需要保留相对时间线且偏移量可以像敏感元数据一样被治理。replace在 v1.3.0 后升级为完整的 Faker 支撑混淆引擎见 anonymization.md 的 The new replace engine 一节langISO 639-1 码通过LANG_TO_LOCALE映射到 Faker locale如en→en_US、fr→fr_FR、pt→pt_PT巴西葡语需显式localept_BR并支持consistentTrue同文档内相同(canonical_label, original_value)对产出相同替身与seedint跨运行可复现便于快照测试。确定性基于hashlib.blake2b对(seed, canonical_label, original)计算不同原文必然得到不同替身。此外SurrogateVault可为跨文档的同标识符提供稳定假名临床 ID 替身会通过同款校验和验证器CPF、CNPJ、BSN、NIR、Codice Fiscale、NIE、Aadhaar、Steuer-ID、NPI、通用 MRN 等见 anonymization.md 的校验和表格。许可OpenMed 使用什么许可证OpenMed 包以Apache-2.0发布见仓库根目录的 LICENSE。模型 checkpoint 可能携带各自的元数据因此在再分发权重或将其打包进产品之前务必核对具体模型卡或注册表行的许可信息——不要假设所有权重都与主包同许可。性能OpenMed 需要 GPU 吗不需要。CPU 执行完全受支持并且是本地与 CI 环境的默认安全基线。GPU 加速可改善大负载下的延迟与吞吐CUDA 设备可用OpenMedConfig(devicecuda)选择或具体索引如cuda:1Apple Silicon 系统可在安装相应 extra 与模型产物后使用 MLX 后端批处理可提升重复抽取或去标识化作业的吞吐。设备选择的细节PyTorch 设备默认是autoOpenMed 依次探测MPS → CUDA → CPU再回退OPENMED_TORCH_DEVICE或旧别名OPENMED_DEVICE可显式覆盖gpu会被规范化为cuda见 configuration.md 的 cache/device 提示与 troubleshooting.md 的设备条目。MLX 是独立后端仅限 Apple Silicon需要pip install openmed[mlx]及对应模型产物详见 mlx-backend.mdMLX 后端。批处理方案见 batch-processing.md性能剖析见 profiling.md。如何让内存使用保持可预测核心建议复用ModelLoader或批处理器而不是为每篇文档新建 pipeline。每个 pipeline 都会在内存中驻留一个模型逐文档新建 pipeline 会成倍放大常驻内存。model-loader.mdModelLoader 与 Pipelines 的要点如下from openmed.core import ModelLoader, OpenMedConfig config OpenMedConfig(devicecuda, cache_dir~/.cache/openmed) loader ModelLoader(configconfig) pipeline loader.create_pipeline( disease_detection_superclinical, tasktoken-classification, aggregation_strategysimple, ) raw pipeline(Administered paclitaxel alongside trastuzumab.)token 按模型/配置组合缓存重复调用复用同一批 HF 对象长驻服务可用loader.unload_model(...)/loader.unload_all_models()释放缓存引用OpenMed 随后触发 Python GC 并清空可用的 torch CUDA/MPS 缓存冷启动慢时可在启动时预加载模型并把缓存目录放在 SSD/NVMe 上。在 REST 服务中用模型生命周期端点查看与卸载已缓存模型见 rest-service.mdREST 服务并通过OPENMED_SERVICE_PRELOAD_MODELS、OPENMED_SERVICE_MAX_RESIDENT_MODELSLRU 逐出、OPENMED_SERVICE_MODEL_MEMORY_BUDGET_BYTES、OPENMED_SERVICE_MAX_TEXT_LENGTH默认 1,000,000 字符超长请求被拒绝来约束工作集。analyze_text默认开启句子检测并将句子分组到有界的窗口中tokenizer 使用模型最大长度truncationTrue单条超长句子仍可能被截断必要时显式传max_length来约束单请求内存。综合决策速查最后把 FAQ 的核心结论浓缩成一张速查表方便团队在部署评审时快速对照问题结论能否离线运行能。预下载模型 本地路径 /OPENMED_OFFLINE1/local_onlyTrue装哪个 extra最小匹配hf、hf,service、mlx、multimodal、ocr-paddleDeBERTa sdpa 报错升级 ≥1.8.1临时用OPENMED_TORCH_ATTENTION_BACKENDeager用哪个模型临床 NER 按实体族选注册表别名PII 用extract_pii(lang...)默认模型支持哪些语言36 个官方 PII 语言码 4 个 opt-in Indic 路由去标识化可逆吗mask/remove/hash不可逆replace需外部映射shift_dates知偏移者可逆为何都归ID_NUM50 个 canonical 标签统一多语言输出子类型元数据仍保留细节需要 GPU 吗不需要。CPU 是默认基线CUDA/MLX 可选加速内存如何可控复用ModelLoader、批处理、REST 生命周期端点与内存预算变量如需进一步深入某个主题可继续阅读 getting-started.md快速开始、configuration.md配置与校验、troubleshooting.md错误排查与 anonymization.md匿名化全指南仓库中的 pyproject.tomlextras 声明、openmed/core/labels.pycanonical 标签分类法、openmed/core/backends.py离线/设备分派与 openmed/core/hf_hub.pyHub 下载与离线标志提供了上述所有行为的第一手源码依据。【免费下载链接】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），仅供参考