AI导哈

人脸识别嵌入服务器

FaceTron是一个高性能、模块化的人脸识别嵌入服务器，支持ONNX Runtime，具有动态多模型加载功能，可在本地机器到可扩展的云环境中运行，并提供OpenAPI规范和OpenTelemetry集成。

  • by 13shivam
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 13shivam/facetron

使用说明

FaceTron MCP服务器

FaceTron是一款高性能、模块化的人脸（识别）嵌入服务器，支持ONNX Runtime，具有动态多模型加载功能，使您的模型离线，可在任何地方运行，从本地机器到可扩展的云环境。 它还提供了一个具有MCP兼容元数据和OpenTetry集成的OpenAPI规范（OAS）端点。

出于测试目的，在models/目录下添加了轻量级ONNX模型。用实际的高分辨率人脸模型替换或装载此目录，例如 1k3d68、2d106det、弧形脸、水牛、性别、glintr100和scrfd_10g_bnkps 为了实现完整的功能。

🚀 特性

  • 🔗 API：

    • GET/models：从注册表中获取所有加载的模型。
    • POST/推断：从图像中获取嵌入。
    • POST/infect_visualize：获取带有面部检测标记的盒装图像。
    • GET/download:下载带有面部检测标记的盒装图像。
    • GET/openapi.json：获取MCP元数据的openapi v3.1.0 json规范。

  • 🧠 人脸嵌入推理
    接受人脸图像，检测人脸，并返回干净、标准化的向量嵌入。

  • 📦 动态多模型支持
    通过以下方式加载多个ONNX型号（例如ArcFace、SCRFD、Glint360K） /models 采用即插即用架构。

  • 🔍 人脸检测与可视化
    返回带有边界框和对齐的人脸裁剪的原始图像，以进行推理验证。

  • 📚 OpenAPI 3.1 和 Swagger 用户界面
    通过内置交互式API文档轻松集成。

  • 🏷️ 开箱即用的OpenTetry跟踪 与OTLP导出器集成支持OpenTetry（兼容Jaeger）。 使用main.py中的setup_telemetry（）自动启用跟踪，或通过disable_OTEL=true环境变量禁用

  • 🧩 面向未来的模块化设计
    干净的建筑 services/, routes/，以及 utils/ 图层--准备用于：

    • TensorFlow，PyTorch运行时扩展
    • 部署到模型编排管道中

  • 🧠 MCP元数据支持
    在OpenAPI规范中公开模型信息，以符合模型连接器协议（MCP）代理。

🧱 技术栈

  • FastAPI（异步web服务器）
  • ONNX运行时（模型执行）
  • Python 3.9+
  • Docker化和DevOps就绪

🗂 项目结构

facetron/
├── main.py                     # FastAPI app entrypoint
├── routes.py                   # API route definitions
├── services/                   # Core face detection & embedding logic
│   ├── face_detection_service.py
│   ├── face_embedding_service.py
│   └── model_registry_service.py
├── utils/                      # Utility helpers
│   └── image_utils.py
├── models/                     # Pretrained ONNX models (test models included)
│   ├── 1k3d68.onnx
│   ├── 2d106det.onnx
│   ├── arcface.onnx
│   ├── buffalo.onnx
│   ├── genderage.onnx
│   ├── glintr100.onnx
│   └── scrfd_10g_bnkps.onnx
├── tester/                     # Client script for local testing
│   └── local_tester_client.py
├── temp/                       # Temp storage for incoming image files
├── resources/                  # Visual assets for API & architecture
│   └── *.png, *.jpg
├── requirements.txt
├── docker-compose.yml
├── Dockerfile
├── .env
├── readme.md
├── telemetry_utils.py # setup telemetry configs
└── license

⚙️ 设置

1.克隆和导航

git clone https://github.com/13shivam/facetron.git
cd facetron

2.将ONNX型号添加到 /models

确保你的模型实现了 .get_embedding(np.ndarray) -> np.ndarray 通过包装器连接。

3.添加/删除OpenTetry配置

服务器包括内置的OpenTetry，如果在main.py中调用setup_Telemetry（），则在启动时启用Telemetry。

禁用遥测：在启动服务器之前设置环境变量Disable_OTEL=true，并跳过调用setup_Telemetry（）。

使用docker compose/pip运行

创建 .env

MODEL_DIR=models
LOG_LEVEL=info
OTEL_EXPORTER_OTLP_ENDPOINT=http://host.docker.internal:4317
DISABLE_OTEL=false

选项1：使用docker启动服务器

docker-compose up -d

通过Swagger访问API

http://127.0.0.1:8000/docs#/

访问Jaeger API探索跟踪

http://localhost:16686/search

选项2：使用pip启动服务器

pip install -r requirements.txt
python main.py
...
INFO:     Will watch for changes in these directories: ['/facetron']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [11385] using StatReload
INFO:     Started server process [11388]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
(logs contd...)

#run tester script
python local_tester_client.py

...
200
{'message': 'Image saved successfully', 'saved_image_path': '/facetron/temp/temp_276ce9b8.jpg'}
200
{'message': 'Image saved successfully', 'saved_image_path': '/facetron/temp/temp_47179b1b.jpg'}
200
{'message': 'Image saved successfully', 'saved_image_path': '/facetron/temp/temp_feb98d6b.jpg'}
200
{'message': 'Image saved successfully', 'saved_image_path': '/facetron/temp/temp_5e4a77e5.jpg'}
...

序列图测试顺序中的所有API

Swagger查看所有API

获取API：获取所有已加载的模型

推断API：返回检测到嵌入的face_id的映射

推断API可视化：返回盒装图像

Jaeger轨迹可视化

样本图像

🧪 推理示例

curl --location 'http://localhost:8000/infer' --header 'Content-Type: application/json' --form 'model_name="buffalo"' --form 'image_format="jpg"' --form 'file=@"/path/to/your/image.jpg"'

示例响应：

{
    "faces": [
        {
            "face_id": "15f9b282-ea6f-43f5-a60f-0e1a3b422fcd",
            "bbox": [403, 46, 465, 108],
            "embedding": [0, 0, 3434, -343...]
        }
    ]
}

性能报告

📝 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

关于开源依赖关系的重要通知：

该项目依赖于各种开源模型和库，每个模型和库都有自己的许可条款。用户有责任了解并遵守他们选择使用的所有开源组件的特定许可证。请咨询相应型号和库提供商提供的各个许可证。

相关 MCP