
OpenMed Hugging Face 模型发布安全策略手动发布、令牌隔离与 CI 边界管控【免费下载链接】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/openmedOpenMed 作为 local-first 的医疗 AI 项目临床 NER 与 HIPAA PII 脱敏全部在端侧运行其模型工件发布遵循一套严格的手动发布策略模型转换与发布绝不发生在 GitHub Actions 托管流水线中仓库不得存储 Hugging Face 写令牌任何 workflow 不得接收HF_WRITE_TOKEN。本文以 docs/security/hf-token-policy.md 为骨架结合发布模块与边界测试源码完整讲解执行边界、令牌范围与存储、六步手动发布序列、90 天轮换机制与泄露应急流程帮助你理解并复刻这套fail-closed失败即关闭的模型发布安全模型。为什么模型发布必须手动OpenMed 的定位决定了模型发布的高安全要求模型工件包含 PII 识别与临床 NER 权重一旦被篡改可能直接影响医疗数据脱敏结果。因此发布策略的第一原则是模型发布的控制权必须掌握在维护者手中而不是自动化流水线手中。具体表现为三条硬性规则OpenMed 不从 GitHub Actions 转换或发布模型工件does not convert or publish model artifacts from GitHub Actions。仓库不得在 GitHub Actions secrets 中存储 Hugging Face 写令牌write token任何 workflow 不得接收HF_WRITE_TOKEN。模型发布是维护者在自行选定并控制的硬件上执行的显式本地操作explicit local operation。这一策略在测试层面被强制固化。仓库中 tests/unit/test_convert_workflow_hf_token.py 专门用于验证发布边界断言旧有的托管转换/发布工作流文件convert-models.yml、nightly-release.yml已从.github/workflows中删除扫描全部 workflow 文件禁止出现hf-publish、HF_WRITE_TOKEN、openmed.core.hf_publish、openmed.mlx.convert、openmed.coreml.convert、openmed.onnx.convert、scripts/release/dispatch_batch.py、scripts/release/orchestrate.py run等模型发布标记断言release-gates.yml仅支持workflow_dispatch与repository_dispatch显式触发且不含schedule/cron直接读取本策略文档校验其中必须包含 must not store、GitHub Actions、maintainer-controlled machine、explicit local command、Revoke、org-wide write access 等关键约束措辞——策略文档本身就是测试的输入与被验证对象确保策略与代码边界不漂移。执行边界什么能自动化什么不能策略定义了清晰的执行边界Execution Boundary区分了本地自主操作与严格禁止的操作允许维护者本地机器禁止在维护者控制的机器上构建、转换、评估并闸门gate候选模型且该机器具备足够的存储、内存与加速器支持添加 cron 定时触发、托管转换任务、托管发布任务发布前审查确切的源模型、目标模型仓库、工件目录、格式、闸门证据与目标仓库可见性任何携带 Hugging Face 写令牌的 CI 环境仅通过为该候选模型发起的显式本地命令发布将模型发布视为创建/修改/改变 Hugging Face Space 可见性的授权两条补充原则值得特别注意包发布与模型发布相互独立包发布凭据如 PyPI与模型发布令牌完全隔离互不复用、互不关联。模型发布绝不授权 Space 管理发布模型工件不代表获得创建、修改或变更 Hugging Face Space 可见性的权限——Space 权限需要单独、显式地授予。令牌范围与存储最小权限 一次性注入令牌类型分离策略明确区分三类凭据禁止混用写令牌HF_WRITE_TOKEN仅用于显式本地发布命令发布后立即从进程环境中清除运行时读令牌如HF_TOKEN用于模型下载/拉取详见下文运行时读令牌包发布凭据用于发布 Python 包与模型发布完全隔离。写令牌的最小权限要求使用细粒度fine-grained令牌仅授予 org-write 权限且仅限本次发布所需的 OpenMed 模型仓库org-write access limited to the OpenMed model repositories required for the release。不授予admin、billing、account-management、Space-management 等任何超范围权限。仅从**本地密钥管理器local secret manager**加载令牌仅用于那条显式的本地发布命令随后将其从进程环境中移除。令牌绝不出现在仓库文件、shell 历史、日志、workflow secrets、workflow artifacts、发布证据中。不重用个人开发令牌、读令牌或包发布令牌。策略用一句话量化了泄露后果将令牌暴露视为对 OpenMed 模型仓库的 org 级写访问泄露Treat exposure as org-wide write access to OpenMed model repositories。运行时读令牌另类但同样受保护发布策略与运行时读取是两套体系。日常运行时OpenMed 通过 openmed/core/hf_hub.py 的prefetch_model等便捷函数从 Hub 拉取模型读取凭据来自HF_TOKEN/HUGGING_FACE_HUB_TOKEN/HUGGINGFACE_HUB_TOKEN环境变量。这些读令牌同样受保护openmed/core/doctor.py 中的_check_hf_token诊断项只报告presenttrue/false布尔值绝不输出令牌内容tests/unit/cli/test_doctor_cli.py 通过三个用例验证设置HF_TOKENSUPER_SECRET_TOKEN_VALUE后run_diagnostics()的序列化结果中不包含该令牌值HUGGING_FACE_HUB_TOKEN等旧式变量同样只报存在性、不泄露内容。这与发布令牌策略一脉相承令牌值在任何输出面上都不应出现。手动发布序列六步全流程策略规定的六步发布序列如下每一步都可以在源码中找到对应实现第 1 步校验候选队列或配置不进行发布发布前的预检阶段只读取、校验配置不触碰网络。发布模块 openmed/core/hf_publish.py 在真正上传前会完成大量本地校验工件目录存在性检查publish_artifact中artifact_dir.exists()失败即抛HfPublishError、可复现性哈希计算、模型卡片一致性比对等。第 2 步本地构建工件并运行发布闸门在维护者控制的本地上运行发布闸门release gates。publish_artifact支持传入gate_report_path签名闸门报告与champion_gate_report_path冠军-挑战者闸门报告底层由 openmed/core/hf_publish.py 完成_load_verified_gate_report加载闸门报告用OPENMED_RELEASE_GATE_KEY环境变量中的可信密钥验证签名与可复现性哈希且要求决策必须为RELEASABLE否则抛错中止fail closed_require_champion_challenger_promotion若传入冠军-vN闸门报告则必须由compare_champion_challenger得出PROMOTE判定才允许发布判定记录可写入比较记录文件以便可复现审计。这些闸门逻辑位于 openmed/eval/release_gates.pyGateReport、RELEASABLE与 openmed/eval/champion_challenger.py。第 3 步检查工件清单、哈希、模型卡片与可见性发布模块为每个工件计算确定性 SHA-256 摘要artifact_sha256排除README.md与 datasheet 文件以保证哈希稳定并将摘要写入 manifest 行与可复现性哈希。同时若存在已验证的闸门报告_write_verified_model_card会构建带闸门证据的模型卡片并强制校验若工件目录中已存在README.md且与闸门报告生成的内容不一致直接报错拒绝发布stale model card disagrees with signed gate reportdatasheet 路径不得与README.md别名冲突目标仓库 ID 由target_repo_id按org/源模型名-vN-格式后缀规则推导如mlx、mlx-8bit、mlx-4bit、coreml、onnx、onnx-int8等也可通过--repo-id显式指定。第 4 步从本地密钥管理器注入HF_WRITE_TOKEN并执行显式发布命令令牌注入点位于 openmed/core/hf_publish.py 的read_hf_tokendef read_hf_token(env_var: str DEFAULT_TOKEN_ENV) - str: token os.environ.get(env_var) if not token: raise HfPublishError( f{env_var} is required to publish model artifacts. Configure it as a protected CI secret before enabling publish. ) return token默认环境变量名为HF_WRITE_TOKENDEFAULT_TOKEN_ENV与运行时的HF_TOKEN严格区分令牌缺失即抛错fail closed不会用匿名身份降级发布令牌仅在publish_artifact中被读取用于api.create_repo、api.upload_folder、api.upload_file等 Hub 调用不写入任何日志。发布模块可以模块形式直接运行python -m openmed.core.hf_publish其完整 CLI 参数见 openmed/core/hf_publish.py核心参数如下参数必填说明--model是源模型 ID如OpenMed-NER-xxx-434M--artifact-dir是转换后的工件目录--format是发布格式如mlx-fp、mlx-8bit、coreml、onnx--formats否逗号分隔的 manifest 格式单仓库多工件时--repo-id否显式指定目标仓库 ID--org否目标组织默认OpenMed--version否新仓库版本后缀默认1--manifest否JSONL manifest 路径默认models.jsonl--baseline否发布后更新的 last-green baseline JSON--gate-report否签名闸门报告用于构建并校验模型卡片--gate-signing-key-env否闸门 HMAC 密钥环境变量默认OPENMED_RELEASE_GATE_KEY--champion-gate-report否冠军-vN闸门报告设置后必须PROMOTE才允许发布--token-env否写令牌环境变量默认HF_WRITE_TOKEN--private否目标仓库不存在时以私有方式创建--overwrite-existing否允许覆盖已存在的目标仓库默认跳过发布动作的核心调用链openmed/core/hf_publish.py检查仓库是否存在_repo_exists404 视为不存在→ 按需api.create_repo→api.upload_folder上传整个工件目录 → 追加 manifest 行 → 更新 baseline 与状态产物benchmark 卡片、leaderboard、status 页。第 5 步核验已上传的 revision 并执行合成冒烟测试发布后需要验证上传的 revision 正确并执行合成synthetic冒烟测试。仓库在 scripts/release/smoke_test.py 中提供冒烟测试实现发布命令的--smoke-statusgreen/red与--smoke-failure-reason参数会把冒烟结果渲染进状态页。第 6 步清除令牌仅保留无 PHI 的证据发布完成后立即unset令牌只保留不含 PHI 的哈希、偏移量与闸门证据retain only PHI-free hashes, offsets, and gate evidence。这条与 OpenMed 全仓库的 no-PHI 原则一致——相关证据策略还可参考 docs/security/no-raw-phi-logging.md 与 docs/security/evidence-integrity.md。Fail-closed 的本地工具要求策略对本地发布工具提出三条强制要求令牌或必需证据缺失时必须失败关闭fail closed不得记录令牌值不得以上传文件的副作用更改仓库可见性——即上传操作不会隐式地把仓库从私有改成公开可见性必须在发布前作为独立决策显式确认。源码中这些要求均有对应read_hf_token缺失即抛错_load_verified_gate_report签名/哈希验证失败即拒绝--private是显式参数而非隐式行为。轮换与撤销90 天节奏与泄露应急常规轮换每 90 天轮换一次发布令牌维护者更替、可疑活动或意外泄露后立即轮换。轮换顺序有讲究先创建并验证新令牌再撤销旧令牌避免发布窗口真空。轮换日期与操作人记录在私有运维日志中但不复制令牌值本身。泄露应急流程若令牌已暴露按序执行立即撤销令牌停止所有正在使用该令牌的本地发布进程审计 OpenMed 模型仓库检查是否有意外的提交、文件、tag 或元数据变更从经过审查、哈希验证的本地证据中恢复受影响工件。这套流程与仓库中已有的审计/恢复机制相互呼应例如 docs/security/audit-key-rotation.md、docs/security/audit-retention.md 以及 docs/security/surrogate-audit.md。源码级验证策略如何被自动化守护除前文提到的 tests/unit/test_convert_workflow_hf_token.py 之外发布功能本身还有多组单元测试直接验证安全行为tests/unit/core/test_hf_publish_onnx.py 与 tests/unit/mlx/test_hf_publish.py验证target_repo_id的命名推导、manifest 行的可复现性哈希、artifact_sha256的确定性等发布核心逻辑tests/unit/core/test_hf_hub.py覆盖运行时读取路径——prefetch_model在离线模式下仅使用本地缓存local_files_onlyTrue、对远端文件名做路径穿越防护拒绝../secret、绝对路径、控制字符等、下载后校验 LFS 完整性元数据缺失即抛DownloadIntegrityErrortests/unit/onnx/test_android_batch_publish.py覆盖 Android 场景下批量发布的令牌处理tests/unit/release/test_retrain_trigger_workflow.py确保重训练触发工作流同样不越界。从源码结构可以推断发布相关脚本集中在 scripts/release/orchestrate.py、dispatch_batch.py、release.py、smoke_test.py、champion_challenger.py等而测试刻意将openmed.core.hf_publish、scripts/release/dispatch_batch.py、scripts/release/orchestrate.py run列为 workflow 中的禁用标记——这些脚本是本地运维工具不是 CI 步骤。小结OpenMed 的 Hugging Face 模型发布策略可以归纳为一句话发布是维护者控制下的显式本地操作令牌是注入即用、用完即弃的细粒度最小权限凭证CI 与自动化永远不触碰模型工件和写令牌。整套机制通过策略文档 边界测试 fail-closed 工具 90 天轮换四重防线落地边界测试把策略文本当作被测对象防止漂移发布工具在令牌缺失、闸门未过、卡片不一致、挑战者未胜时一律拒绝发布泄露时则按撤销 → 停止 → 审计 → 恢复四步处置。对于任何需要管理 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),仅供参考