OpenMed 示例与复制即用配方指南从 Notebook 到生产流水线的全量实操手册【免费下载链接】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 仓库中Examples Copy/Paste Recipes示例与复制即用配方这一核心文档展开系统梳理仓库内可直接运行的 Notebook、脚本与工具从快速脱敏、批量处理、FHIR 导出、离线评测四大入门 Notebook到 20 个覆盖多语言脱敏、策略审计、结构化风险、多模态互操作与仓库数据变换的生产级示例脚本再到 Jupyter 富文本高亮组件show()/render_spans_html()的源码级原理与可直接搬进 CI 的自动化流水线。读完本文你将能按图索骥地运行仓库中全部官方示例并理解其背后的调用链与设计约束。一、示例库整体布局文档的定位与导航OpenMed 的示例体系遵循按目标找脚本、按脚本学原理的组织方式。核心入口文档 docs/examples.md 本身是一张索引地图它只承担策展职能把散落在仓库各处的可运行样例聚合成四类资源策展 Notebook 画廊docs/examples/notebook-gallery.md端到端引导式教程覆盖从快速脱敏到 FHIR 导出、再到离线评测的完整旅程全部运行在合成数据之上无需任何网络调用且由持续集成逐格验证examples/notebooks/目录下的 Notebook按主题分册的 Jupyter 教程examples/目录下的 Python 脚本可复制的命令行工具docs/下散落的复制即用配方REST、LangChain 包装器、MLX 后端、Swift OpenMedKit、Transformers.js 导出等。如果你已经明确想要什么结果可以跳过这份索引直接使用任务导向的 docs/cookbook.md——它以目标 → 起点 → 演示内容三列表格把 40 个脚本和 Notebook 按隐私脱敏、临床抽取与互操作、模型与 Agent 本地流水线、策略与发布证据四大类组织起来是本文档的姊妹篇。二、零安装演示浏览器隐私游乐场若你不想安装任何依赖可以打开 docs/demo/privacy-playground/ 下的浏览器游乐场目录内包含index.html与app.js。它的内置规则会在当前浏览器标签页内对有界的合成文本进行脱敏并暴露聚合计数与当前浏览器的网络边界信息。这套演示的价值在于直观展示 OpenMed 的边界心智模型脱敏只作用于内存中的有界文本聚合统计而非原始内容被输出关于如何证明浏览器端无网络外泄可进一步阅读 docs/demo/browser-egress.mdBrowser Network-Egress Proof浏览器网络外泄证明。三、四大入门 Notebook从脱敏到离线评测examples/notebooks/目录下现包含 15 个 Notebook 与 1 个 Python 伴侣脚本clinical_extraction_dataframe_api.py。其中 01–04 四个编号 Notebook 构成官方推荐的学习主线均100% 离线运行在合成 fixtures 之上无网络调用、无强制模型权重下载Notebook亮点examples/notebooks/01_quickstart_redaction.ipynb快速脱敏掩码masking、可逆替换reversible replacement与密码学哈希cryptographic hashingexamples/notebooks/02_batch_dataset.ipynb基于BatchProcessor的批处理与目录处理examples/notebooks/03_fhir_export.ipynb临床文本脱敏、医学实体抽取、组装确定性 FHIR R4 Bundleexamples/notebooks/04_eval_walkthrough.ipynb基于捆绑的多语言合成 golden fixtures 的离线评测其余 Notebook 覆盖更专精的主题getting_started.ipynb复刻快速开始指南安装、注册表探索、首次调用analyze_textSentence_Detection_Batching.ipynb演示基于 pySBD 的句子切分与批处理、以及如何把预测结果对齐回原始段落ZeroShot_NER_Tour.ipynb走查 GLiNER 索引、领域默认值与把 span 转换为 BIO/BILOU 方案的适配器Chinese_Hindi_Deid_Tour.ipynb则用虚构的中文、印地语与 Hinglish 笔记跑通确定性脱敏、结构化实体审查、UTF-8 输出文件与零泄漏断言。运行方式统一# 所有 Notebook 依赖同一基线依赖集 uv pip install .[hf]然后使用 VS Code、Jupyter 或 Google Colab 打开即可。注意这些 Notebook 的输出会随.ipynb文件一起存储请仅使用授权或合成文本分享前务必清空输出。3.1 富文本高亮组件show()与render_spans_html()openmed.processing.show()会在活跃的 Jupyter/IPython shell 中直接渲染 displaCy 风格的彩色 span 高亮——带每标签图例与置信度分数。由于类型化结果对象如AnalyzeResult、DeidentificationResult暴露了_repr_html_把求值结果作为单元格最后一行即可自动触发渲染from openmed import deidentify # 仅使用合成文本。结果通过 _repr_html_ 在 Jupyter 内联渲染。 deidentify(Patient John Doe called from 555-123-4567., methodmask)如需显式控制可调用show()在活跃 IPython shell 中内联渲染并返回None其他环境返回 HTML 字符串或render_spans_html()始终返回 HTML 字符串from openmed.processing import render_spans_html, show text Contact Jane Roe at jane.roeexample.com. spans [ {start: 8, end: 16, label: PERSON, score: 0.98}, {start: 20, end: 40, label: EMAIL, score: 0.95}, ] show(text, spans) # 活跃 IPython内联显示并返回 None否则返回 HTML html render_spans_html(text, spans) # 原始 HTML 同样可用源码级原理openmed/processing/display.py从实现看display.py L322-L413render_spans_html()的完整链路为_resolve_text_and_spans()归一化输入——接受(text, spans)二元组或直接传入结果对象AnalyzeResult、DeidentificationResult、PredictionResult以及带text/entities的映射对每个 span 调用_span_from_object()兼容四种形态普通dict含start/end偏移与标签字段、EntityPrediction/PIIEntity对象、OpenMedSpan记录_clamp_spans()将越界偏移钳制到文本长度内_span_layers()把重叠标注放到确定性分层上保证每个输入 span 始终是完整高亮图例按标签首次出现顺序生成保证颜色稳定渲染时用语义化的pre/mark元素包裹文本带data-start/data-end/data-label/data-layer属性与悬停 tooltip源文本始终经 HTML 转义——临床笔记里的方括号与 号不会破坏视图。show()display.py L416-L439则在此基础上做了一层shell 感知活跃 IPython shell 中通过IPython.display.display内联展示并返回None避免单元格二次输出原始字符串非 IPython 环境或未安装 IPython 时静默返回 HTML 字符串。这意味着IPython 是可选、懒加载依赖渲染 HTML 字符串永不要求它仅仅安装了 IPython 也不会在非活跃 shell 外触发展示生成的 HTML 片段无脚本、无网络请求当严格的内容安全策略CSP屏蔽了内联样式时语义化的pre/mark元素仍能保证文本可读自动富文本表示默认抑制置信度分数若不想把分数持久化进 Notebook 输出请传show_confidenceFalse。Deidentification_Cookbook.ipynb中的 Recipe 5 对该组件做了端到端演示。四、脚本与工具20 个复制即用入口examples/目录集中了仓库最完整的可运行脚本。下表与源码逐一对应路径功能examples/deid_chinese_clinical_note.py对虚构简体中文临床笔记脱敏打印结构化实体断言所有内嵌合成标识符均已移除并保存脱敏文本examples/deid_hindi_hinglish_note.py使用随附的紧凑印地语 checkpoint对虚构印地语与代码混合 Hinglish 笔记运行同样的 fail-closed 流程examples/pii_model_comparison.py在共享样本文本上比较多个 PII 模型汇总抽取质量examples/pii_batch_processing.py基于BatchProcessor(operation...)的批量 PII 抽取与脱敏examples/sms_deid_helpdesk_logs.py用short_text预设脱敏 RapidPro 风格 JSON 或通用 CSV 客服导出含联系人假名化、时间戳粗化与有界批次examples/pii_multilingual_new_languages.py演练荷兰语、印地语、泰卢固语、葡萄牙语、阿拉伯语、日语、土耳其语注册表条目、locale 正则匹配与可选实时抽取examples/gradio_deid_app.py交互式 Gradio UI粘贴合成文本、选择mask/replace/hash方法查看脱敏输出与检测实体可选pip install gradioexamples/v16_policy_audit_release_gates.py演示 v1.6 策略画像、规范化 span、签名审计报告、审查包、脱敏预览、泄漏热力图与 k-匿名指标无需下载模型examples/structured_release_risk.py对合成结构化发布执行建议性准标识符发现、显式患者级 k/l/t 策略审查、匿名化、物化输出验证与聚合专家审查证据examples/structured_population_risk.py基于患者级联合 QI 画像度量精确离线 k-map、精确链接风险与 delta-presenceexamples/v17_multimodal_browser_interop.py演示 v1.7 多模态与互操作面AsciiDoc 偏移投影、OCR 契约、chat JSONL、CSV 清单、FHIR、HL7 v2 与 Transformers.js 浏览器包检查examples/chw_form_deid.py脱敏本地 ODK、CommCare 或 KoBoToolbox JSON/CSV 表单导出并输出无值字段策略清单examples/privacy_gateway_quickstart.py展示外部模型调用前的脱敏与受保护边界后的安全再标识examples/dbt-deidentify/演示 v1.8 仓库数据变换包表级脱敏宏与脱敏 staging 模型examples/warehouse-remote-function/部署 BigQuery 远程函数批处理 handler无原始 PHI 日志、容器入口与注册 DDLexamples/spark-streaming/演示针对合成记录的 Spark 结构化流脱敏examples/first_five_minutes_redact_extract_fhir.py走查合成脱敏、确定性临床抽取与 FHIR Bundle 组装examples/interop_fhir_export.py通过公开to_fhir()门面导出合成 grounded spans、冒烟检查事务 Bundle 并打印 JSONexamples/datasets_walkthrough.py加载一个捆绑合成 golden fixture以离线优先的模型处理运行公开extract_pii/deidentifyAPIscripts/smoke_gliner.py在发布前运行一组有界的 GLiNER 模型/文本确认 zero-shot 依赖已安装tests/run-tests.sh便捷运行器拼接单元、集成与冒烟测试可扩展以纳入文档构建与 API 冒烟检查4.1 运行发布示例与结构化风险示例v1.6/v1.7 发布示例全部基于合成数据可在发布评审期间安全运行uv run python examples/v16_policy_audit_release_gates.py uv run python examples/v17_multimodal_browser_interop.py结构化发布风险与参考人群示例同样使用合成数据uv run python examples/structured_release_risk.py uv run python examples/structured_population_risk.py对应的 CLI/Python 工作流、精确纵向画像语义、签名专家交接、工件处理与局限说明见 docs/reidentification-risk.md。4.2 多语言脱敏 walkthrough源码级拆解中文与印地语/Hinglish 两个脚本是fail-closed失败即关闭流程的样板uv run python examples/deid_chinese_clinical_note.py uv run python examples/deid_hindi_hinglish_note.py两者均使用虚构笔记、打印 JSON 可序列化实体详情、写出 UTF-8 脱敏文本并在任一已知合成标识符残留时以断言失败终止。中文示例examples/deid_chinese_clinical_note.py的关键设计模型显式指定注册表键MODEL_KEY pii_superclinical_small——注释明确说明这是为了让通用英文 checkpoint 作为显式回退而不是被zh占位默认值悄悄替换调用前先用openmed.core.pii_i18n.validate_chinese_resident_identity_card()校验虚构身份证号110108198503150018的格式与校验位CHINESE_CUSTOM_RECOGNIZER提供zh路由——langzh、localezh_CN负责中文规范化与内置模式自定义 deny 词典则保证教程虚构值姓名、病历号、日期、身份证、电话、邮箱、地址可重复识别策略选用policychina_pipl并开启use_safety_sweepTrue、consistentTrue、seed708——合成标识符在assert_synthetic_identifiers_removed()中逐条比对泄漏即抛AssertionError脱敏后的文本以 UTF-8 写入chinese_clinical_note_redacted.txt。印地语示例examples/deid_hindi_hinglish_note.py的设计要点模型为随附的紧凑 checkpointOpenMed/OpenMed-PII-Hindi-SuperClinical-Small-44M-v1同时处理纯印地语与代码混合 Hinglish 两条笔记用validate_aadhaar()校验虚构 Aadhaar2467 7832 5484policyindia_dpdp_act启用 ABDM recognizer 识别 Aadhaar 与 ABHA本地 deny 词典只让虚构姓名、病历号与带空格的电话显示形式保持确定性邮箱由安全扫描独立兜底输出按hindi/hinglish分别写入hindi_hinglish_redacted/目录下的 UTF-8 文件。两者共用的structured_entities()展示了实体的 JSON 化视图字段canonical_label/entity_type/label三级标签回退、text、start/end偏移、置信度、redacted_text替换值与sources溯源列表——这与 docs/output-formatting.md 中的 span 过滤与转换约定一致。4.3 模型比较与批量处理脚本examples/pii_model_comparison.py 展示了 OpenMed PII 模型集合的分层结构——脚本注释明确列出 33 个专门模型按体积分为 Tiny33MB快速推理、Small44–82MB均衡、Medium109–210MB通用、Large278–434MB高精度与 XLarge560–600MB最大覆盖。核心用法from openmed import deidentify, extract_pii from openmed.core.model_registry import get_model_info, get_models_by_category result extract_pii( sample_text, model_namemodel_key, # 如 pii_clinical_e5_small use_smart_mergingTrue, confidence_threshold0.3, )同时演示四种脱敏方法mask占位符替换、remove完全移除、hash密码学哈希与shift_dates按date_shift_days180平移日期。注意模型比较部分需要下载权重脚本默认只打印注册表概览与推荐比较与脱敏演示被注释掉取消注释前请先安装pip install openmed[hf]。examples/pii_batch_processing.py 是BatchProcessor的最小用法from openmed import BatchProcessor processor BatchProcessor( operationextract_pii, # 或 deidentify model_namepii_detection, batch_size8, confidence_threshold0.5, use_smart_mergingTrue, # 脱敏场景还可追加 # methodreplace, consistentTrue, seed42, ) result processor.process_texts(TEXTS, ids[note-1, note-2, note-3])每个条目的结果都带success/error字段便于失败隔离与下游写入process_directory()变体可流式处理整个目录的文本文件见 examples/notebooks/02_batch_dataset.ipynb。4.4 其他实用脚本速览examples/sms_deid_helpdesk_logs.py命令行入口redact_sms_export(input, output, batch_size512, contact_hash_key...)脱敏 RapidPro 风格 JSON/CSV联系人哈希键通过OPENMED_SMS_CONTACT_HASH_KEY环境变量注入默认批次上限 512 条examples/gradio_deid_app.pygradio是示例局部可选依赖模型访问发生在首次调用时而非导入时保持模块可被测试安全导入UI 提供输入文本框、mask/replace/hash单选、脱敏文本输出与Label/Text/Start/End/Confidence实体表格examples/datasets_walkthrough.py默认FIXTURE_ID golden-multilingual-en-ssn从openmed/eval/golden/fixtures/multilingual.json加载合成 fixture除非显式设置OPENMED_EXAMPLE_ALLOW_DOWNLOAD1否则通过临时注入HF_HUB_OFFLINE1与TRANSFORMERS_OFFLINE1强制离线——模型不可用时打印可操作的提示而非报错。五、v1.7多模态、互操作与浏览器配方v1.7 示例围绕三个新公开面分组多模态文本契约ExtractedDocument、SourceSpan、OCR 结果投影、Markdown/AsciiDoc 抽取以及元数据安全的源映射结构化健康数据FHIR$de-identify、FHIR Bulk NDJSON、确定性 FHIR Bundle、OperationOutcome、HL7 v2 字段脱敏、CSV/TSV PHI 列清单浏览器部署面向 Transformers.js 打包的 ONNX/WebGPU 工件发布前检查预期的transformersjs/文件布局。完整的 v1.6–v1.7 覆盖面地图见 docs/release/v1.6-v1.7-feature-coverage.md。FHIR/OMOP 互操作语境见 docs/guides/fhir-omop-interoperability.md。六、v1.8运行时、部署与仓库数据变换配方v1.8 示例聚焦跨平台运行时与生产部署路径Android/Kotlin 与 Swift-Kotlin 对齐docs/android-parity.mdAndroid Span Parity、docs/export-onnx-android.mdAndroid ONNX 导出、docs/swift-kotlin-parity.mdSwift-Kotlin API 对齐浏览器与移动端 JavaScriptdocs/demo/browser-egress.md、docs/runtimes/onnxruntime-web.mdONNX Runtime Web 加载器、docs/export-transformersjs.mdTransformers.js 导出以及js/openmedkit-react-native/下的 React Native 桥服务运维docs/serving/authentication.mdREST 认证、docs/serving/grpc.mdgRPC 服务、docs/serving/async-jobs.md异步 REST 任务与 Webhooks、docs/serving/resilience.md服务韧性、docs/serving/tracing.mdREST 追踪结构化数据任务docs/integrations/columnar-redactor.md列式脱敏器、docs/integrations/lakehouse-redaction.md湖仓表脱敏、docs/integrations/dask.mdDask DataFrame 脱敏、docs/duckdb-deidentification.mdDuckDB 脱敏 UDF以及examples/dbt-deidentify/。数据集 walkthrough 只使用捆绑的、合成的、可再分发 fixtures——这些记录不要求数据使用协议DUA示例也不下载数据。想换用其他 fixture把脚本中的FIXTURE_ID改成openmed/eval/golden/fixtures/multilingual.json中的其他 ID 即可模型下载默认关闭只有当你确实想加载模型时才设置OPENMED_EXAMPLE_ALLOW_DOWNLOAD1python examples/datasets_walkthrough.py七、Apple Silicon 与 Swift 配方OpenMed2.3.0版本包含发布关键级的 Apple、Android、浏览器与服务入口点docs/mlx-backend.mdApple Silicon Mac 上的 Python MLX 后端含 Privacy Filter、OpenMed 多语言隐私过滤器与实验性 GLiNER 家族工件docs/swift-openmedkit.md面向 macOS、iOS、iPadOS 应用的 OpenMedKitSwift Packagedocs/export-onnx-android.md 与 docs/android-parity.mdKotlin OpenMedKit 面的 Android ONNX 导出与 span 对齐docs/export-transformersjs.md通过 ONNX/WebGPU 工件做浏览器 token 分类。Python MLX 快速检查uv pip install .[mlx] uv run python -c from openmed.core.backends import get_backend; print(type(get_backend()).__name__)Swift MLX 快速检查import OpenMedKit let modelDirectory try await OpenMedModelStore.downloadMLXModel( repoID: OpenMed/OpenMed-PII-LiteClinical-Small-66M-v1-mlx ) let openmed try OpenMed(backend: .mlx(modelDirectoryURL: modelDirectory)) let entities try openmed.extractPII(Patient John Doe, DOB 1990-05-15)浏览器包冒烟检查uv run python -m openmed.onnx.transformersjs \ --onnx-export-dir dist/example-onnx八、复制即用的文档内配方以下配方直接位于docs/下按需跳转docs/analyze-text.md — 带元数据的 dict/JSON/HTML/CSV 输出docs/rest-service.md — FastAPI 端点与 Docker runbookdocs/integrations-langchain.md — 模型调用前的 RAG 上下文脱敏包装器docs/mlx-backend.md — Apple Silicon Python 运行时与工件打包docs/swift-openmedkit.md — macOS/iOS/iPadOS 原生应用运行时docs/export-transformersjs.md — 浏览器/WebGPU token 分类打包docs/model-loader.md — 缓存、token 辅助与多模型配置docs/output-formatting.md — span 过滤与格式转换docs/zero-shot-ner.md — 索引、标签默认值与推理 API。九、示例自动化流水线直接搬进 CI原文档提供了一个可直接复制进 CI 的样本流水线——它同时守护模型、文档与 zero-shot 流程的健康状态#!/usr/bin/env bash set -euo pipefail uv pip install .[hf,docs] python examples/pii_model_comparison.py artifacts/result.txt uv run python examples/v16_policy_audit_release_gates.py artifacts/v16.json uv run python examples/v17_multimodal_browser_interop.py artifacts/v17.json uv run mkdocs build --strict python scripts/smoke_gliner.py --limit 1 --threshold 0.5每个阶段各有侧重.[hf,docs]统一安装模型推理与文档构建依赖pii_model_comparison.py验证注册表可枚举与模型元数据完整两个uv run发布示例覆盖策略审计与多模态互操作面mkdocs build --strict把文档内失效链接升级为构建失败smoke_gliner.py --limit 1 --threshold 0.5有界地确认 zero-shot 依赖可用。十、使用边界与安全须知最后汇总本文档隐含的几条硬性约束它们同样是事实准确的一部分数据边界仓库内所有示例默认使用合成输入在真实数据上复刻工作流前请先审查任何可选模型下载或外部服务边界见 docs/security/no-raw-phi-logging.md 与 docs/security/no-telemetry.mdNotebook 输出富文本组件会渲染源文本.ipynb内会持久化输出——分享前清空输出需要抑制置信度时传show_confidenceFalse下载开关模型权重默认不下载OPENMED_EXAMPLE_ALLOW_DOWNLOAD1仅在明确需要时使用数据集 fixtures 全部捆绑于仓库无需 DUA离线保证Notebook 画廊的 CI 保证是无网络调用、无强制权重下载依赖离线优先的模型处理路径HF_HUB_OFFLINE/TRANSFORMERS_OFFLINE注入可参考tests/run-tests.sh与scripts/check_notebooks.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），仅供参考
