Rangers/algo-cv-pipeline-face-buffalo-l

Buffalo L ONNX 模型包（人脸检测/关键点/识别/年龄性别）

本仓库包含一套用于人脸分析的 ONNX 模型文件集合，可用于人脸检测、关键点对齐、年龄与性别估计，以及人脸特征向量提取（识别/检索）。模型文件位于 buffalo_l/ 目录下，适合在 Python 环境中直接加载进行推理。

文件结构

• buffalo_l/1k3d68.onnx：三维/姿态相关辅助模型（常用于提升对齐鲁棒性）
• buffalo_l/2d106det.onnx：人脸关键点检测（106 点）
• buffalo_l/det_10g.onnx：人脸检测模型（多尺度、轻量级）
• buffalo_l/genderage.onnx：年龄与性别估计
• buffalo_l/w600k_r50.onnx：人脸识别/特征提取（ResNet50 backbone，600K 训练集）

注：具体模型来源与训练细节请参考你使用的上游项目与模型文档；这些文件通常成套使用以完成完整的人脸分析流水线。

适用场景

• 人脸检测与对齐（获取稳定的人脸区域与关键点）
• 人脸特征提取与相似度计算（识别、去重、检索）
• 基础属性估计（年龄与性别）

环境与依赖

• Python 3.9+（建议）
• onnxruntime 或对应加速后端（如 onnxruntime-gpu）
• 如需从 Hugging Face Hub 自动下载模型：huggingface_hub

安装示例：

pip install onnxruntime huggingface_hub
# 如果需要 GPU 版本：
# pip install onnxruntime-gpu

快速开始（本地加载）

from pathlib import Path
import onnxruntime as ort

MODEL_DIR = Path(__file__).resolve().parent / "buffalo_l"

# 加载人脸检测模型
session_det = ort.InferenceSession(str(MODEL_DIR / "det_10g.onnx"), providers=["CPUExecutionProvider"])  # 或 GPU 提供者

# 加载关键点模型
session_kps = ort.InferenceSession(str(MODEL_DIR / "2d106det.onnx"), providers=["CPUExecutionProvider"])  

# 加载识别模型
session_rec = ort.InferenceSession(str(MODEL_DIR / "w600k_r50.onnx"), providers=["CPUExecutionProvider"])  

# 加载年龄性别模型
session_attr = ort.InferenceSession(str(MODEL_DIR / "genderage.onnx"), providers=["CPUExecutionProvider"])  

# TODO: 根据你的前后处理逻辑，准备输入张量并进行推理

从 Hugging Face Hub 下载（推荐在部署时使用）

如果你将本模型包推送到 Hugging Face Hub（例如仓库 ID 为 <你的用户名>/algo-cv-pipeline-face-buffalo-l），可以在运行时自动下载：

from pathlib import Path
from huggingface_hub import hf_hub_download

REPO_ID = "Rangers/algo-cv-pipeline-face-buffalo-l"
LOCAL_DIR = Path("models") / "buffalo_l"
LOCAL_DIR.mkdir(parents=True, exist_ok=True)

for fname in [
    "1k3d68.onnx",
    "2d106det.onnx",
    "det_10g.onnx",
    "genderage.onnx",
    "w600k_r50.onnx",
]:
    hf_hub_download(repo_id=REPO_ID, filename=fname, repo_type="model", local_dir=str(LOCAL_DIR))

• 若仓库为私有，需要先执行 hf auth login 或在环境中设置 HUGGINGFACE_HUB_TOKEN。

性能与注意事项

• 推理速度与精度取决于硬件和后端（CPU/GPU、onnxruntime 提供者、线程数等）。
• 不同模型的输入大小、预处理（归一化、BGR/RGB、对齐等）与输出解释不同，请参考你在代码中实现的前处理/后处理。
• 年龄与性别估计存在统计误差与偏差，不适用于需要严格准确性的场景。

许可与来源

• 这些 ONNX 文件可能来自开源人脸分析项目（例如 InsightFace 生态中的模型）。
• 请根据上游模型的许可协议进行使用与分发；若你确定许可类型，可在此处补充具体许可（如 Apache-2.0/MIT 等）。
• 如果你将本模型卡上传到 Hugging Face，请在仓库设置中补充 License 与 Dataset/Training 信息。

引用

如在研究或产品中使用本模型，请引用相应的上游项目与论文；示例：

• InsightFace 项目：https://github.com/deepinsight/insightface
• ONNX Runtime：https://onnxruntime.ai/

维护者

• 维护者：Rangers
• 联系方式：[email protected]

---

如需我将仓库 ID 与你的用户名替换为实际值，或添加更详细的使用示例（包括你现有的 code/face_model.py、face_model_cpu.py 的加载逻辑对接），告诉我具体信息即可。