FaceTron MCP 服务器

FaceTron 是一个高性能、模块化的面部识别嵌入服务器，支持 ONNX 运行时，具有动态多模型加载功能，可以将模型离线，并设计用于在本地机器到可扩展云环境中的任何地方运行。 它还提供了一个与 MCP 兼容元数据的 OpenAPI 规范（OAS）端点，并集成了 OpenTelemetry。

为了测试目的，在 models/ 目录下添加了轻量级的 ONNX 模型。用实际的高分辨率面部模型如 1k3d68, 2d106det, arcface, buffalo, genderage, glintr100, 和 scrfd_10g_bnkps 替换或挂载此目录以实现全部功能。

---

🚀 特性

• 🔗 API：

  • GET /models：从注册表中获取所有已加载的模型。
  • POST /infer：从图像中获取嵌入。
  • POST /infer_visualize：获取带有面部检测标记的框图。
  • GET /download：下载带有面部检测标记的框图。
  • GET /openapi.json：获取用于 MCP 元数据的 OpenAPI v3.1.0 JSON 规范。

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

• 📦 动态多模型支持 通过 /models 加载多个 ONNX 模型（例如，ArcFace, SCRFD, Glint360K），采用即插即用架构。

• 🔍 面部检测与可视化 返回带有边界框和对齐的面部裁剪的原始图像，用于推理验证。

• 📚 OpenAPI 3.1 & Swagger UI 通过内置的交互式 API 文档轻松集成。

• 🏷️ 开箱即用的 OpenTelemetry 跟踪 集成支持 OpenTelemetry，兼容 OTLP 导出器（Jaeger）。在 main.py 中调用 setup_telemetry() 自动启用跟踪，或者通过设置环境变量 DISABLE_OTEL=true 来禁用。

• 🧩 面向未来的模块化设计 清晰的架构，包括 services/, routes/, 和 utils/ 层，准备进行：

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

• 🧠 MCP 元数据支持 在 OpenAPI 规范中暴露模型信息，符合 Model Connector Protocol (MCP) 代理的要求。

---

🧱 技术栈

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

---

🗂 项目结构

facetron/
├── main.py                     # FastAPI 应用入口
├── routes.py                   # API 路由定义
├── services/                   # 核心面部检测与嵌入逻辑
│   ├── face_detection_service.py
│   ├── face_embedding_service.py
│   └── model_registry_service.py
├── utils/                      # 工具帮助程序
│   └── image_utils.py
├── models/                     # 预训练的 ONNX 模型（包含测试模型）
│   ├── 1k3d68.onnx
│   ├── 2d106det.onnx
│   ├── arcface.onnx
│   ├── buffalo.onnx
│   ├── genderage.onnx
│   ├── glintr100.onnx
│   └── scrfd_10g_bnkps.onnx
├── tester/                     # 客户端脚本用于本地测试
│   └── local_tester_client.py
├── temp/                       # 临时存储传入的图像文件
├── resources/                  # API 和架构的视觉资产
│   └── *.png, *.jpg
├── requirements.txt
├── docker-compose.yml
├── Dockerfile
├── .env
├── readme.md
├── telemetry_utils.py # 设置遥测配置
└── license

---

⚙️ 设置

1. 克隆并导航

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

2. 将您的 ONNX 模型添加到 /models

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

---

3. 添加/移除 OpenTelemetry 配置

服务器内置了 OpenTelemetry，如果在 main.py 中调用了 setup_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:     将监视这些目录中的更改：['/facetron']
INFO:     Uvicorn 正在运行于 http://0.0.0.0:8000 (按 CTRL+C 退出)
INFO:     已启动重新加载进程 [11385] 使用 StatReload
INFO:     已启动服务器进程 [11388]
INFO:     等待应用程序启动。
INFO:     应用程序启动完成。
(日志继续...)
# 运行测试脚本
python local_tester_client.py

...
200
{'message': '图像保存成功', 'saved_image_path': '/facetron/temp/temp_276ce9b8.jpg'}
200
{'message': '图像保存成功', 'saved_image_path': '/facetron/temp/temp_47179b1b.jpg'}
200
{'message': '图像保存成功', 'saved_image_path': '/facetron/temp/temp_feb98d6b.jpg'}
200
{'message': '图像保存成功', 'saved_image_path': '/facetron/temp/temp_5e4a77e5.jpg'}
...

---

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

---

Swagger 查看所有 API

---

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

---

推理 API：返回带有检测到的嵌入的 face_ids 映射

---

推理 API 可视化：返回带有边界的图像

OpenTelemetry 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 许可证发布 - 详情见 许可证 文件。

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

本项目依赖于各种开源模型和库，每个都有自己的许可条款。用户有责任理解并遵守他们选择使用的所有开源组件的具体许可。请咨询各自模型和库提供商提供的个别许可。