OpenMed 低带宽环境安装指南：pip 镜像、Hugging Face 镜像、HTTP 代理与强制离线模式

OpenMed 低带宽环境安装指南pip 镜像、Hugging Face 镜像、HTTP 代理与强制离线模式【免费下载链接】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 工具包其模型与依赖下载完全依赖 Hugging Face Hub 和 PyPI。在带宽受限的医院内网、数据不出域要求严格的机构网络或计量计费链路上直接安装往往不可行。本文以 docs/low-bandwidth-install.md 为主体结合仓库源码openmed/core/hf_hub.py、openmed/core/offline.py、openmed/core/doctor.py等讲解如何在不改动任何应用代码的前提下通过机构 PyPI 镜像、Hugging Face 镜像、HTTP 代理完成安装维护单一模型缓存并在廉价带宽窗口预取模型后切换到 OpenMed 的强制离线模式。读完本文你将掌握一套可复制的在线预取—离线运行安装流程以及配套的诊断排错手段。总体思路一条缓存两个阶段OpenMed 的低带宽安装策略可以概括为选定并固定一个 Hugging Face 缓存目录HF_HOME/HF_HUB_CACHE在线预取与离线运行必须看到同一个缓存在带宽廉价的时段如夜间、机构内网、按量计费之外的 Wi-Fi通过镜像或代理完成依赖安装与模型预取预取成功后启用强制离线模式OPENMED_OFFLINE1让运行期任何网络缺失都变成明确报错而不是悄悄消耗计量流量。从源码结构看这一策略与 OpenMed 的 local-first 设计约束完全一致openmed/core/hf_hub.py的模块文档明确写道No telemetry and no mandatory network access. Downloads are explicit; whenOPENMED_OFFLINEis active every helper stays cache-only即下载是显式行为离线模式下所有辅助函数只允许走缓存。把下载收敛到同一个缓存在下载任何模型之前先决定缓存位置。huggingface_hub会按以下优先级解析缓存目录见openmed/core/doctor.py中_hf_cache_location()的实现HF_HUB_CACHE显式指定最终 Hub 缓存目录HF_HOME此时实际缓存为$HF_HOME/hubXDG_CACHE_HOME此时实际缓存为$XDG_CACHE_HOME/huggingface/hub默认~/.cache/huggingface/hub推荐做法是在 shell 配置中固定HF_HOME并确保在线预取步骤与离线运行进程使用同一份环境变量export HF_HOME${HF_HOME:-$HOME/.cache/huggingface} mkdir -p $HF_HOME/hubHF_HUB_CACHE可以覆盖最终 Hub 缓存目录适用于需要把模型放在独立磁盘分区的场景。设置完成后运行openmed doctor确认当前生效的缓存路径——诊断报告中的hf_cache字段会给出解析结果及其来源HF_HUB_CACHE/HF_HOME/XDG_CACHE_HOME/default。通过 pip 镜像安装依赖OpenMed 的可选依赖通过[hf]extra 引入huggingface_hub是惰性导入的未安装时调用相关辅助函数会抛出带安装提示的ImportError见 openmed/core/hf_hub.py。在内网环境中可以设置PIP_INDEX_URL指向机构或区域镜像的/simple端点export PIP_INDEX_URL${PIP_INDEX_URL:-https://pypi.org/simple} python -m pip install \ --index-url $PIP_INDEX_URL \ --retries 20 \ --timeout 120 \ openmed[hf]几个要点--retries 20与--timeout 120针对脆弱链路调高了容错与超时--retries对 pip 而言是重试次数上限在低带宽下建议保持较大值命令行--index-url只对本次调用生效设置PIP_INDEX_URL环境变量则对该环境后续所有 pip 命令生效不要为了绕过证书校验而加--trusted-host。TLS 校验的缺失会让镜像流量暴露在中间人风险之下正确做法是向网络管理员索取机构 CA 证书并配置到 pip 的信任链中。选择 Hugging Face 镜像OpenMed 的prefetch_model()把下载委托给huggingface_hub后者会读取HF_ENDPOINT环境变量。OpenMed不会替换或自动探测该值hf_hub.py的模块文档明确说明 Mirror aware.HF_HOME/HF_HUB_CACHEandHF_ENDPOINTare honoured byhuggingface_hubitself; these helpers never override them。因此必须在启动 Python 或hfCLI 之前设置镜像export HF_ENDPOINT${HF_ENDPOINT:-https://huggingface.co} export HF_HUB_ETAG_TIMEOUT${HF_HUB_ETAG_TIMEOUT:-60} export HF_HUB_DOWNLOAD_TIMEOUT${HF_HUB_DOWNLOAD_TIMEOUT:-300}注意事项HF_ENDPOINT必须是机构批准的确切 HTTPS 端点公共 Hub 只是兜底回退镜像必须实现与 Hub 兼容的 repository-info 与文件下载路由通用缓存型 Web 代理并不自动等价于 Hub 镜像Hub 客户端可能向自定义端点隐式发送探测到的 Hugging Face token匿名镜像应设置HF_HUB_DISABLE_IMPLICIT_TOKEN1需鉴权的镜像只应使用镜像专用凭据绝不要把权限更广的 Hub 凭据发给不受信任的镜像两个超时变量ETag 校验超时与下载超时在低带宽/高延迟链路上建议显式调大默认值 60 秒与 300 秒是文档给出的保守起点。配置 HTTP 代理Python、pip 与huggingface_hub都遵循常规代理环境变量。大小写两种拼写都很常见如果宿主应用同时设置了两种小写值优先openmed/core/doctor.py的_environment_value()就复刻了 urllib 的代理选择逻辑先查小写再查大写。ALL_PROXY用于让单个代理处理所有 schemeexport HTTP_PROXYhttp://proxy.example.org:8080 export HTTPS_PROXYhttp://proxy.example.org:8080 export NO_PROXYlocalhost,127.0.0.1,.example.org将示例主机与端口替换为网络管理员提供的实际值。只有镜像与内网主机直连可达时才把它们加入NO_PROXY。不要在生产脚本或支持日志中内嵌代理密码——openmed doctor输出代理设置时会脱敏 URL 凭据源码中_redact_url_credentials()会把用户名密码渲染为***并移除查询串与 fragment但日志环境本身仍应避免出现明文凭据。让模型下载可断点续传Hugging Face 缓存会记录已完成 blob与未完成传输。中断后重跑同一条命令已缓存文件被复用服务器支持 HTTP range 请求时部分下载会续传。在脆弱链路上单 worker 更慢但更可靠export MODEL_IDOpenMed/OpenMed-NER-DiseaseDetect-TinyMed-135M hf download \ $MODEL_ID \ --cache-dir $HF_HOME/hub \ --max-workers 1 \ --no-force-downloadOpenMed 的 Python 辅助函数可以预热同一个缓存并解析注册表别名aliasexport OPENMED_MODEL_ALIASdisease_detection_tiny python - PY import os from openmed import prefetch_model print(prefetch_model(os.environ[OPENMED_MODEL_ALIAS])) PYprefetch_model()的实现openmed/core/hf_hub.py提供了比裸hf download更多的保障别名解析resolve_repo_id()会先查模型注册表openmed/core/model_registry.py把disease_detection_tiny这类键解析为完整 repo id含/的字符串原样返回裸名则补上OpenMed/前缀重试策略默认 5 次重试retries: int DEFAULT_RETRIES采用指数退避 抖动_BACKOFF_BASE_SECONDS1.0上限 30 秒仅对瞬时错误重试——408/429/5xx 状态码以及连接/超时/代理类异常会被判为瞬时错误而 401、404 等永久错误绝不重试完整性校验下载后按 Hub 返回的 sha256或 git-sha1与文件大小逐文件校验失败则删除损坏文件强制重取一次仍失败抛DownloadIntegrityError带宽限速max_bandwidth参数可设置整次拉取的总带宽上限字节/秒由_BandwidthLimiter进程内节流离线感知离线模式下内部以local_files_onlyTrue调用snapshot_download缓存缺失时抛出OfflineModeError而不是回退到网络错误信息会提示先关掉离线模式预取一次或把HF_HOME指向已包含该模型的缓存。关键纪律在预取成功之前不要设置OPENMED_OFFLINE1。离线模式对缓存未命中是拒绝而不是回退联网这是防止意外计费的护栏。计量链路操作清单三步走低带宽/按量计费场景下官方文档给出了一份三步检查清单第 1 步下载前先看体积估算openmed models size disease_detection_tiny该命令默认只读本地元数据来自models.jsonl/ manifest 的估算除非显式加--remote才发起网络请求。build_models_size_report()openmed/cli/main.py会合并三方面数据manifest 估算、list_cached_models()扫描到的本地缓存已缓存的模型显示cached — 0 MB to download并把disk_mb替换为真实占用、以及--remote时的 Hub 元数据通过get_remote_model_size_mb()它只在离线未激活时才允许联网。报告还给出peak_ram_mb远端体积的 1.25 倍估算下限 256 MB与可选的budget_mb预算筛选。第 2 步廉价带宽窗口内预取在便宜的 Wi-Fi 或计划内的网络窗口中先清掉任何残留的离线标志再执行预取。该块可以安全地重复运行缓存命中即复用unset OPENMED_OFFLINE HF_HUB_OFFLINE TRANSFORMERS_OFFLINE HF_DATASETS_OFFLINE export OPENMED_MODEL_ALIASdisease_detection_tiny python - PY import os from openmed import prefetch_model print(prefetch_model(os.environ[OPENMED_MODEL_ALIAS])) PY第 3 步断网、开启强制离线、验证断开网络连接启用强制离线模式先验证缓存快照与诊断再启动应用export OPENMED_OFFLINE1 export OPENMED_MODEL_ALIASdisease_detection_tiny python - PY import os from openmed import prefetch_model print(prefetch_model(os.environ[OPENMED_MODEL_ALIAS])) PY openmed doctor预取成功之后体积检查、缓存验证与 doctor 诊断都是纯本地操作。正式启动真实工作负载时保持OPENMED_OFFLINE1这样任何缺失文件都会明确失败OfflineModeError而不是触发联网下载消耗计量流量。离线模式的底层机制OPENMED_OFFLINE并不只是给 Hugging Face 传一个标志。openmed/core/offline.py提供了双层保障依赖侧 cache-only 标志configure_offline_mode()/enable_hf_offline_flags()会同时设置HF_HUB_OFFLINE、TRANSFORMERS_OFFLINE、HF_DATASETS_OFFLINE让 Transformers、datasets 与 hub 全部走缓存进程级 socket 护栏network_blocked_if_offline()在离线激活时用socket.socket.connect/connect_ex/socket.create_connection的进程级补丁物理阻断出站连接任何越过依赖缓存的网络尝试都会抛OfflineModeErrorOPENMED_OFFLINE/local_onlyTrue blocks outbound network access after model loading…。补丁支持嵌套作用域多个并发作用域共享一次进程级补丁只有最后一个作用域退出时才恢复原始 socket 函数。这也解释了为什么openmed doctor的输出能区分OpenMed 的 socket 护栏与依赖自带的 cache-only 标志offline_mode_assertion()返回的asserted字段要求二者同时成立才算完整离线姿态。用openmed doctor诊断活动环境openmed doctor openmed doctor --json诊断报告openmed/core/doctor.py 的run_diagnostics()包含以下字段hf_endpoint当前生效的 Hub 端点及其来源HF_ENDPOINT或default并校验是否为 HTTPShttp_proxy/https_proxy/all_proxy/no_proxy四个代理变量各自的取值与来源PROXY_ENV_VARSURL 凭据被脱敏hf_cache实际解析出的缓存路径及来源openmed_offline离线模式开关状态OPENMED_OFFLINE的原始值与解析结果/0/false/no/off均视为关闭见env_flag_enabled()另有python_version、python_arch、low_resource_memory含 cgroup 内存上限识别与 4 GiB 低资源信封建议、可选依赖探测mlx/coreml/onnx/hf/multimodal、hf_token是否存在、manifest 是否存在与行数等检查项。该命令不发起任何网络请求也绝不打印 Hugging Face tokenURL 中的凭据、查询串与 fragment 都会从诊断输出中剔除。--json变体输出结构化 JSON便于接入自动化巡检。如果在线预取仍然失败把这些字段与机构的网络配置逐项比对端点、代理、NO_PROXY、缓存路径。如果离线状态下缓存未命中只在获批的网络窗口内临时关闭离线模式重跑同一条预取命令然后立刻恢复OPENMED_OFFLINE1。完全离线机构的补充路径airgap 安装包对于完全不允许出网的机构OpenMed 还提供了openmed airgap命令族openmed/cli/airgap.py在联网构建机上把 Python wheel、模型缓存与完整性清单打包成一个离线安装包含bundle-manifest.json默认打包限额约 900 MB拷入离线机器后运行./install.sh即可完成安装随后同样要设置OPENMED_OFFLINE1并用openmed doctor加一次合成脱敏检查确认环境可用。这与本文的低带宽流程互为补充前者解决带宽贵后者解决完全没网。常见排错速查症状检查项pip 安装超时/失败PIP_INDEX_URL是否正确、--retries/--timeout是否足够、机构 CA 是否已配置勿用--trusted-host绕过预取一直走公共 HubHF_ENDPOINT是否在启动 Python 前设置、镜像是否实现了 Hub 兼容的 repo-info 与下载路由镜像拒绝/泄露凭据匿名镜像设HF_HUB_DISABLE_IMPLICIT_TOKEN1鉴权镜像只用镜像专用 token代理不生效确认大小写变量一致小写优先、ALL_PROXY是否需要、内网主机是否误入NO_PROXY断点续传不工作确认服务器支持 HTTP rangehf download去掉--force-download或--no-force-download离线运行报缓存缺失缓存目录是否与预取时一致openmed doctor看hf_cache、预取是否真的成功、OPENMED_OFFLINE是否在预取后才设置需要复验下载完整性prefetch_model()内置逐文件哈希校验失败时清掉该模型缓存重试clear_cached_model()小结OpenMed 的低带宽安装不要求任何应用层改动PIP_INDEX_URL解决依赖源HF_ENDPOINT解决模型源HTTP(S)_PROXY/NO_PROXY解决出口网络HF_HOME/HF_HUB_CACHE统一缓存OPENMED_OFFLINE在预取完成后把运行期彻底锁在本地。配合prefetch_model()的重试、限速与完整性校验以及openmed doctor的零网络诊断这套流程可以在计量链路、医院内网与完全隔离网络三类场景下稳定落地。相关源码可在 openmed/core/hf_hub.py、openmed/core/offline.py、openmed/core/doctor.py 与 openmed/cli/airgap.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），仅供参考