企业官网建设流程全解析

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/uniface

UniFace 是一个统一的 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/ user@offline-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.py）：

from 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。

缓存管理实战：查询、清理与手动验算哈希

最后一行来自 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 完整的模型管理能力：缓存位置随你定、文件完整性自动守、离线部署四步走。

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