UniFace模型缓存与离线使用完全指南SHA-256校验与自定义缓存目录【免费下载链接】unifaceUniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.项目地址: https://gitcode.com/gh_mirrors/un/unifaceUniFace 是一个统一的 Python 人脸分析库在同一个 API 下覆盖人脸检测、关键点、识别、属性分析与防伪。本文带你搞懂 UniFace模型缓存与离线使用的两项核心能力SHA-256 完整性校验和自定义缓存目录——无论是部署在内网隔离机器上还是想把模型统一存到数据盘几分钟即可完成配置。UniFace模型缓存如何工作自动下载与双源回退UniFace 采用「首次使用即下载」的懒加载策略第一次实例化某个模型类时权重文件会被自动下载到本地缓存之后再加载同一模型则秒开因为直接命中本地缓存。from uniface.detection import RetinaFace detector RetinaFace() # 首次运行自动下载约 3.5 MB 权重 detector RetinaFace() # 后续运行直接从缓存加载无需联网下载流程有三个值得注意的设计源码见 uniface/model_store.py双源回退优先从主源下载失败后自动切换到备用镜像源单个源不可达不会中断加载原子落盘文件先写入临时文件校验通过后才原子替换到目标路径缓存目录永远不会留下半个损坏文件指数退避重试每次失败后按2^n秒递增等待默认每个源最多重试 3 次。定位模型缓存目录默认路径与缓存结构不配置任何参数时所有模型统一存放在~/.uniface/models/ ├── retinaface_mnet_v2.onnx ├── arcface_mnet.onnx ├── gaze_resnet34.onnx ├── parsing_resnet18.onnx └── ...文件名由「模型标识 扩展名」组成如retinaface_mnet_v2.onnx因此离线拷贝时可以只挑需要的文件不必整个目录照搬。想随时确认当前生效的缓存路径from uniface import get_cache_dir print(get_cache_dir()) # /home/user/.uniface/models三种方式设置UniFace自定义缓存目录当默认目录磁盘空间不足、或需要多用户共享同一份模型时可以改写缓存位置。以下三种方式底层都指向同一个UNIFACE_CACHE_DIR环境变量实现见 uniface/model_store.py。方式一调用 set_cache_dir()推荐在创建任何模型对象之前调用即可对进程内所有后续加载生效from uniface import set_cache_dir, get_cache_dir set_cache_dir(/data/models) print(get_cache_dir()) # /data/models方式二Python 内直接设置环境变量import os os.environ[UNIFACE_CACHE_DIR] /data/models方式三Shell 环境变量export UNIFACE_CACHE_DIR/data/models 小贴士set_cache_dir()必须在首次加载模型之前执行否则新目录不会作用于已经加载过的模型。SHA-256校验机制如何保证模型文件完整可信UniFace 内置了一个集中式模型注册表MODEL_REGISTRY位于 uniface/constants.py为每个模型登记了下载地址和期望的 SHA-256 哈希值。校验发生在两个关键节点1. 下载后立即校验。权重写入临时文件后verify_file_hash()会流式计算文件哈希每次读取 1 MiB 分块见 uniface/model_store.py与注册表中的期望值比对。无论文件来自哪个下载源校验规则完全一致——损坏或过期的镜像只会导致失败并切换到另一个源而不是被错误地缓存下来。2. 加载前再次校验。每次使用缓存前都会重新验算如果本地文件已被外部破坏例如拷贝中断、磁盘坏块UniFace 会打印警告并自动重新下载Cached weights for retinaface_mnet_v2 are corrupted; re-downloading.因此你可以放心地跨机器拷贝模型文件——即使某个文件拷坏了程序也不会加载出错误的权重而是提示并自愈。想查询某个模型的期望哈希from uniface.constants import MODEL_REGISTRY, RetinaFaceWeights expected MODEL_REGISTRY[RetinaFaceWeights.MNET_V2].sha256 print(f期望 SHA-256: {expected})UniFace离线部署完整教程离线环境4步走针对内网隔离 / 断网环境完整流程只有四步详见官方文档 docs/concepts/model-cache-offline.md第 1 步在联网机器上预下载模型from uniface import verify_model_weights from uniface.constants import RetinaFaceWeights, ArcFaceWeights # 逐个下载并自动完成 SHA-256 校验 verify_model_weights(RetinaFaceWeights.MNET_V2) verify_model_weights(ArcFaceWeights.MNET)第 2 步把缓存目录拷到目标机器# 整个目录拷贝或只挑需要的 .onnx 文件 scp -r ~/.uniface/models/ useroffline-machine:~/.uniface/models/第 3 步如果放在非默认位置指向缓存目录from uniface import set_cache_dir set_cache_dir(/path/to/copied/models) # 仅当不在 ~/.uniface/models/ 时需要第 4 步正常调用无需联网from uniface.detection import RetinaFace detector RetinaFace() # 直接读取本地缓存预下载模型缓存download_models 并发加速如果一次要用多个模型例如「检测 识别 年龄性别」三件套用并发下载比串行快得多。download_models()默认使用min(CPU核数, 8)个线程并行拉取见 uniface/model_store.pyfrom uniface import download_models from uniface.constants import RetinaFaceWeights, ArcFaceWeights, AgeGenderWeights paths download_models([ RetinaFaceWeights.MNET_V2, ArcFaceWeights.MNET, AgeGenderWeights.DEFAULT, ]) for model, path in paths.items(): print(f{model.value} - {path})任何模型失败都会聚合成一个RuntimeError一次性抛出方便你在部署流水线里做整体回滚。也可以不写代码直接用仓库自带的 CLI 工具# 下载全部模型或只下载某一类--model-type retinaface / arcface / ... python tools/download_model.py --model-type retinaface工具源码tools/download_model.py。缓存管理实战查询、清理与手动验算哈希需求做法查询当前缓存路径get_cache_dir()更换缓存位置set_cache_dir(/data/models)或设置UNIFACE_CACHE_DIR清理全部缓存删除~/.uniface/models/目录下次使用自动重新下载清理单个模型删除对应的.onnx文件即可手动验算文件哈希python tools/sha256_generate.py 文件路径最后一行来自 tools/sha256_generate.py适合运维场景下人工核对模型文件是否与注册表登记值一致$ python tools/sha256_generate.py ~/.uniface/models/retinaface_mnet_v2.onnx SHA256 hash for retinaface_mnet_v2.onnx: 3ca44c045651cabeed1193a1fae8946ad1f3a55da8fa74b341feab5a8319f757相关单元测试可参考 tests/test_model_store.py覆盖缓存目录切换、并发下载等场景。核心文件速查文件说明uniface/model_store.py缓存目录管理、下载重试、SHA-256 校验核心实现uniface/constants.pyMODEL_REGISTRY全部模型的下载地址与 SHA-256 登记tools/download_model.py命令行批量预下载工具tools/sha256_generate.py手动计算文件 SHA-256docs/concepts/model-cache-offline.md官方「模型缓存与离线使用」文档掌握以上方法你就拥有了 UniFace 完整的模型管理能力缓存位置随你定、文件完整性自动守、离线部署四步走。【免费下载链接】unifaceUniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.项目地址: https://gitcode.com/gh_mirrors/un/uniface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考