tomas-gajarsky/facetorch

解决的问题

构建人脸分析流水线通常需要处理模型源代码、依赖项和可复现性问题。Facetorch 通过精选开源人脸分析模型，将其打包为可移植的 torch.export 格式（.pt2），并提供统一的 Python 工具包来解决此问题，使您无需在推理时使用模型源代码即可运行检测和分析。

工作原理

Facetorch 以 FaceAnalyzer 类为核心，该类协调多个可插拔组件：一个读取器，处理来自本地路径、张量、NumPy 数组、PIL 图像或字节的图像；一个检测器（神经网络包装器），用于查找人脸；一个统一器，用于规范化人脸大小和像素范围；一组预测器（用于嵌入、验证、表情等任务的神经网络包装器）；以及实用工具（例如绘制边界框）。配置通过 Hydra/OmegaConf 管理，允许您选择 CPU 或 GPU 配置文件并覆盖设置。模型使用 torch.export 序列化，因此推理不需要原始代码。该库的默认行为是确定性的：默认情况下它会强制转换输入，并且仅当您显式配置有界 URLReader 时才获取远程图像。模型在首次使用时延迟加载并缓存，该库支持对单张图像中检测到的人脸进行动态批处理。

适用人群

需要在 Python 中灵活、可复现地运行人脸检测和分析（例如验证身份、读取面部表情）的开发者和研究人员，尤其是那些希望避免直接管理模型内部细节的人。它需要 Python 3.11–3.12 和 PyTorch 2.6–2.13，官方平台为 Linux x86-64（Windows/macOS/ARM 为实验性支持）。

亮点

• 便携式 .pt2 格式模型——推理时无需模型源代码；支持动态批处理和 torch.compile
• 受控的可扩展性：自定义组件必须通过验证，包括不可变清单、来源和模型权利审查
• 确定性输入流水线：接受本地路径、张量、NumPy 数组、PIL 图像或字节；仅通过显式、有界的 URLReader 进行远程输入
• 通过 uv、conda-lock 和 Docker 实现可复现环境；缓存目录可通过环境变量控制
• 检测器/预测器模型的延迟加载和缓存；内置预测器将人脸批大小上限设为 64