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 facetron2.将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
My Local Image
______________________________________________________________________
Swagger查看所有API
My Local Image
______________________________________________________________________
获取API：获取所有已加载的模型
get_all_models_configured.png
______________________________________________________________________
推断API：返回检测到嵌入的face_id的映射
infer_api.png
______________________________________________________________________
推断API可视化：返回盒装图像
infer_visualize.png
Jaeger轨迹可视化
opentelemetry_jaegar.jpg
______________________________________________________________________
样本图像
temp_1cc1baa9.jpg temp_f16f0348.jpg
🧪 推理示例
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...]
}
]
}______________________________________________________________________
性能报告
console_log.jpg
📝 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
关于开源依赖关系的重要通知：
该项目依赖于各种开源模型和库，每个模型和库都有自己的许可条款。用户有责任了解并遵守他们选择使用的所有开源组件的特定许可证。请咨询相应型号和库提供商提供的各个许可证。