OpenMed 快速入门：从零搭建本地医疗 NER 与 PII 去标识化环境

OpenMed 快速入门：从零搭建本地医疗 NER 与 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

本指南基于 docs/getting-started.hi.md 的中文解读，带你从一台空白工作站出发，在几分钟内完成 OpenMed 的安装、首次analyze_text实体抽取、deidentify隐私去标识化、离线模型拉取与运行配置固定。OpenMed 是一个 Local-first（本地优先）医疗 AI SDK，主打临床命名实体识别（NER）与符合 HIPAA 的 PII 去标识化，可 100% 在设备端离线运行，患者数据不离开你的网络。读完本文，你将掌握一套可复现、可离线、可上生产的最小启动路径。

本文全部命令与代码均可直接复制运行，并以仓库中的 pyproject.toml、openmed/init.py、openmed/core/pii.py、openmed/cli/main.py 等源码为事实依据。

1. 环境准备：用 uv 创建干净的 Python 3.11 环境

OpenMed 使用 uv 作为依赖管理工具（任何 Python 3.11+ 环境均可工作，仓库requires-python声明为>=3.10，见 pyproject.toml）。推荐做法是为项目创建独立虚拟环境，避免污染系统 Python。

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh # 安装 uv（若已安装可跳过） uv venv --python 3.11 # 创建专用虚拟环境 source .venv/bin/activate # 或直接用 `uv python` 管理解释器 # 安装 OpenMed，包含 Hugging Face extras 与文档工具链 uv pip install ".[hf]"

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" uv venv --python 3.11 .venv\Scripts\Activate.ps1 # 安装 OpenMed，包含 Hugging Face extras 与文档工具链 uv pip install ".[hf]"

.[hf]中的hf是核心 extras，对应 pyproject.toml 中的依赖组合：transformers>=4.50、huggingface-hub>=0.30、accelerate>=0.29、tokenizers>=0.15。这些依赖支撑了从 Hugging Face Hub 拉取模型与运行 token 分类 pipeline 的全部能力。

按需选择 extras

根据你的使用场景，可以按需组合安装以下 extras：

uv pip install ".[hf,gliner]" # 加入 GLiNER 与 transformers（zero-shot 模型栈） uv pip install ".[dev]" # 开发工具：pytest、覆盖率与 linting

glinerextra 定义于 pyproject.toml，引入gliner[tokenizers]>=0.2.0与torch>=2.0，用于 zero-shot GLiNER 场景；devextra（pyproject.toml）则包含pytest、pytest-cov、ruff、mypy、pre-commit等开发依赖。

如果需要扫描图片与文档 OCR，安装多模态 extra 以及系统 Tesseract 二进制：

uv pip install ".[multimodal]" brew install tesseract # macOS sudo apt-get install tesseract-ocr # Debian/Ubuntu

多模态 extra 覆盖了 pyproject.toml 中的pdfplumber、python-docx、python-pptx、pytesseract、easyocr、pydicom、pikepdf等依赖，支撑 PDF、Office 文档、DICOM 影像的文本提取与 OCR。

PaddleOCR 作为更重型的可选 OCR 后端单独提供（它依赖 paddlepaddle，体积大且平台敏感，故不并入通用多模态 extra，见 pyproject.toml 注释）：

uv pip install ".[ocr-paddle]"

CDA/C-CDA XML 去标识化开箱即用

CDA/C-CDA XML 去标识化随主安装包提供，无需额外 extras。它会对结构化头部元素中的 PHI 做脱敏，检查 CDA 章节的叙述性文本，保持 XML 可解析，并且只处理形似 CDA 文档的.xml文件。其实现位于 openmed/interop/cda.py，通过数据驱动的PhiElementRule规则表（如对recordTarget/patientRole/id做hash、对地址做null_flavor处理，见 openmed/interop/cda.py）保证命名空间感知的精准脱敏：

from openmed.interop.cda import redact_cda redacted_xml = redact_cda("synthetic_ccda.xml", date_shift_days=30)

Apple Silicon：直接走 MLX 路径

在 Apple Silicon Mac 上，可以直接安装 MLX 后端并验证运行环境：

uv pip install ".[mlx]" # Python MLX 运行时及 tokenizer/artifact 依赖 uv run python -c "from openmed.core.backends import get_backend; print(type(get_backend()).__name__)"

mlxextra 定义于 pyproject.toml，包含mlx>=0.22、mlx-lm>=0.31、safetensors、tiktoken等依赖。get_backend()会按当前环境返回实际生效的后端类型，是验证安装是否成功的快速手段。

全量安装：组合 extras

如果希望在一台机器上拥有完整的启动面（Hugging Face 模型、MLX 运行时、文档构建），直接组合安装：

uv pip install ".[hf,mlx,docs]"

2. 运行analyze_text：第一次临床实体抽取

analyze_text是 OpenMed 顶层 API 之一（定义见 openmed/init.py），默认使用disease_detection_superclinical模型，走 token-classification pipeline。它支持output_format参数（"dict"默认、"json"、"html"、"csv"）、置信度阈值、句子检测、上下文断言（assert_context）等丰富选项。

from openmed import analyze_text text = "Metastatic breast cancer treated with paclitaxel and trastuzumab." resp = analyze_text(text, model_name="disease_detection_superclinical") print(resp.entities[0]) # 需要可嵌入的 HTML？选择 "html" 输出格式 html = analyze_text(text, model_name="disease_detection_superclinical", output_format="html") print(html) # 可直接用于仪表盘或文档

从源码看，analyze_text内部会依次执行输入校验、模型名校验、pipeline 创建、句子切分（sentence_detection=True默认开启）、按句子分块推理、跨块偏移还原、置信度过滤与格式化输出（见 openmed/init.py），最终返回包含实体列表的AnalyzeResult或指定格式的渲染结果。

喜欢一行脚本的快速验证？直接运行仓库自带的 smoke 脚本：

uv run python examples/pii_model_comparison.py

3. PII 去标识化：deidentify的五种脱敏方法

deidentify()是面向 HIPAA 合规的顶层接口（定义见 openmed/core/pii.py），支持mask、remove、replace、hash、shift_dates五种核心方法，另有aadhaar_mask、format_preserve等扩展方法：

from openmed import deidentify result = deidentify("Patient John Doe, DOB 01/15/1970", method="mask") print(result.deidentified_text) # Patient [first_name] [last_name], DOB [date]

五种核心方法的行为（依据 openmed/core/pii.py 的 docstring）：

方法	行为	典型用途
mask	替换为占位符，如[NAME]、[EMAIL]、[DATE]	默认方法，最直观的脱敏展示
remove	完全删除 PII 文本（替换为空串）	追求最大程度的信息移除
replace	替换为伪造但逼真的数据	保留文本可读性的仿真场景
hash	替换为一致的哈希值	实体链接（同一实体多次出现得到相同值）
shift_dates	日期按随机偏移量平移，同时保持时间间隔	保留时间语义的临床研究

此外，deidentify还内置了智能合并（smart merging）逻辑：用正则把被切碎的实体重新拼合（例如把拆成'01'和'/15/1970'的日期合并成完整的'01/15/1970'），并默认开启 safety sweep 提高召回安全性。每种方法的可运行示例以及如何用reidentify()恢复结果，见 匿名化快速入门。

4. 离线使用：可靠地拉取模型

在开始离线工作前，先用模型拉取命令预热 Hugging Face cache。该命令支持断点续传（中断后自动恢复）、对临时网络故障自动重试，并会针对 Hub 元数据逐一校验每个文件的完整性：

openmed models pull disease_detection_superclinical

在按流量计费或不稳定的网络环境下，可以固定 revision、限制传输速度并显式设置重试次数：

openmed models pull disease_detection_superclinical \ --revision main \ --max-bandwidth 524288 \ --retries 5

这些参数在 openmed/cli/main.py 中定义：

• --revision：可选的分支、tag 或 commit，用于固定模型版本；
• --max-bandwidth：以字节/秒为单位的聚合下载带宽上限（--max-bandwidth 524288即约 512 KiB/s）；
• --retries：临时网络失败的重试次数，默认 5 次。

底层实现是prefetch_model（见 openmed/core/hf_hub.py），它会校验max_bandwidth必须为正整数，超过retries上限或带宽非法时抛出ValueError；下载完成后还会对照 Hub 报告的 commit hash、文件大小与 ETag 做完整性验证，任一不匹配即抛DownloadIntegrityError。

进度输出只包含 repository 文件名与字节/文件总数（不含内容，避免敏感信息泄露）。Pull 完成后设置OPENMED_OFFLINE=1，再次运行同一命令将只做 cache 查找、绝不尝试网络连接：

export OPENMED_OFFLINE=1

若你的目标场景是间歇性网络、离线诊所、OpenMRS 或 DHIS2 集成，可进一步参考 非洲开发者上手指南（低带宽模型配置、纯本地推理、隐私 profile 指南与 FHIR 集成配方）；若需要为 metered/离线部署准备安装包，或身处机构 proxy / package mirror 之后，参见 低带宽、镜像与 proxy 安装指南，其中包含 pip、HF_ENDPOINT、共享模型 cache 与诊断的完整配置。

5. 从文档复制代码片段

本文档的所有代码块均带 Material for MkDocs 的复制按钮。也可以打开命令面板（/或cmd/ctrl + K），搜索 "GLiNER"、"OpenMedConfig" 或 "token classification"，在预览中直接复制对应片段。若你使用 AI 编程助手，可将已发布文档的 URL 交给它，让助手读取这份结构化 Markdown 后给出有依据的回答。

6. 可选：固定配置（OpenMedConfig + ModelLoader）

对于需要长期复用同一模型管线、或在服务中管理多个模型的场景，推荐显式构造OpenMedConfig与ModelLoader：

from openmed.core import OpenMedConfig, ModelLoader config = OpenMedConfig.from_env_fallback( cache_dir="~/.cache/openmed", device="cuda", default_org="OpenMed", ) loader = ModelLoader(config=config) ner = loader.create_pipeline("disease_detection_superclinical") entities = ner("Hydroxyurea dose reduced after platelet drop.")

from_env_fallback支持从环境变量读取配置并回退到显式参数，非常适合在开发、CI 与生产之间复用同一套配置逻辑。ModelLoader则是模型注册、加载与 pipeline 构建的统一入口（openmed顶层包中的analyze_text、list_models、get_model_max_length等都依赖它按需解析，见 openmed/init.py）。

完整的 YAML/ENV 配置 schema、PHI 感知的校验辅助工具与日志设置，参见仓库中的 配置文档。

小结：一条通往离线生产的启动路径

从本文你可以得到一条清晰的路径：用 uv 创建 Python 3.11 环境并安装.[hf]（必要时叠加gliner、multimodal、mlx等 extras）→ 用analyze_text验证临床实体抽取 → 用deidentify的五种方法完成 PII 脱敏 → 用openmed models pull预热离线缓存并设置OPENMED_OFFLINE=1→ 用OpenMedConfig与ModelLoader固定生产配置。每一步都有对应的仓库源码实现可查证，整条链路完全本地化运行，适合在数据不出网的合规要求下快速落地。

【免费下载链接】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