InsightFace-REST核心端点详解/extract人脸特征提取完全教程【免费下载链接】InsightFace-RESTInsightFace REST API for easy deployment of face recognition services with TensorRT in Docker.项目地址: https://gitcode.com/gh_mirrors/in/InsightFace-RESTInsightFace-REST是一个基于 FastAPI TensorRT 的生产级人脸识别 REST API 服务支持 Docker 一键部署与 GPU/CPU 双后端。本文带你完整掌握其最核心的/extract 人脸特征提取端点请求参数逐个讲透、响应字段逐层拆解并附上官方客户端调用方式帮助新手快速把手忙脚乱的模型调通成稳定的人脸识别 API 服务。 它是什么为什么值得关注InsightFace-REST 把开源人脸库 InsightFace 的检测 识别模型封装成了标准 HTTP 接口高性能RTX4090 上默认配置可达 820 fpsDocker 化部署自动下载模型开箱即用批量推理检测与识别模型均支持批处理⚙️多后端TensorRTGPU/ ONNX RuntimeCPU核心能力集中在 4 个端点上实现位于if_rest/api/routes/v1/recognition.py与if_rest/api/routes/v1/service.py端点方法用途/infoGET查询服务版本、模型与默认参数配置/healthGET用内置测试图执行一次完整提取验证服务健康/extractPOST核心端点人脸检测 特征向量embedding提取/draw_detectionsPOST返回画好检测框、关键点、置信度的标注图PNG/multipart/draw_detectionsPOST以 multipart 表单上传图片并返回标注图JPG⚡ 最快启动方式Docker 三步跑通克隆仓库并进入compose目录git clone https://gitcode.com/gh_mirrors/in/InsightFace-REST cd InsightFace-REST/compose复制并修改环境变量文件模型、批大小、FP16 等都在这里配置cp example.env .env构建并启动然后访问http://localhost:18081/docs打开 Swagger 交互文档可直接在线调试 /extract 接口docker compose build docker compose up配置文件compose/example.env与compose/docker-compose.yml是部署时的主要入口。 /extract 端点详解人脸特征提取完全指南下面是 API 文档页中 /extract 的官方说明截图参数含义与本文表格一一对应请求体参数一览请求体定义见if_rest/schemas.py中的BodyExtract模型支持一次传入多张图片data与urls二选一参数默认值作用images.data/images.urls必填图片列表base64 字符串 或 可访问的 URLthreshold0.6检测置信度阈值越高越严格、漏检越多extract_embeddingtrue是否提取 512 维特征向量设为 false 则只做人脸检测速度更快embed_onlyfalse输入即为 112×112 人脸裁剪图跳过检测步骤return_face_datafalse返回对齐后人脸裁剪图base64return_landmarksfalse返回 5 点面部关键点坐标extract_gafalse附带性别/年龄估计需服务端配置 genderage 模型detect_masksfalse附带口罩佩戴检测需服务端配置 mask 模型limit_faces0每张图最多处理的人脸数0 为不限min_face_size0过滤小于指定宽度的小脸0 为不过滤msgpackfalse用 MessagePack 序列化响应体积减小约一半verbose_timingsfalse返回各阶段耗时便于排查性能瓶颈请求示例URL 与 base64 两种传图方式方式一URL服务端可访问的地址或容器内路径{ images: { urls: [test_images/lumia.jpg] }, threshold: 0.6, extract_embedding: true }方式二base64客户端本地图片最常用{ images: { data: [/9j/4AAQSkZJRg... ] }, limit_faces: 10 }处理流程if_rest/core/face_model.py中的FaceAnalysis.embed读图 → 缩放到max_size默认 640×640→ 检测器出框 → 仿射对齐裁剪 → 识别模型算 embedding → L2 归一化。响应结构逐层读懂返回结果顶层包含总耗时took与每张图片一个条目的data列表结构见ifr_clients/schemas.py字段层级说明data[].status图片ok/failed下载失败等data[].took_ms图片该图处理耗时毫秒faces[].bbox人脸[x1, y1, x2, y2]检测框原图坐标faces[].prob人脸检测置信度0~1faces[].size人脸人脸宽度像素faces[].vec人脸512 维归一化特征向量人脸比对的核心产物faces[].norm人脸原始向量 L2 范数faces[].landmarks人脸5 关键点return_landmarkstrue时faces[].facedata人脸对齐后人脸图 base64return_face_datatrue时faces[].gender/age/mask人脸需服务端配置对应模型并开启参数典型用法对两张图分别调用 /extract取faces[0].vec用余弦相似度向量已归一化直接点积即可判断是否同一人相似度 0.35~0.4 通常认为是同一人阈值视业务调整。 三种实用参数组合只检测不识别最省算力extract_embeddingfalse跳过裁剪与识别推理适合单纯做图里有没有人的校验此时响应仅含bbox、prob等轻量字段。极速 embedding跳过检测embed_onlytrue输入必须是 112×112 人脸裁剪图直接进入识别模型适合已有人脸框的下游流水线。大流量传输优化msgpacktrue或请求头Accept: application/x-msgpackembedding 体积约为 JSON 的 1/2高并发场景推荐官方客户端ifr_clients/ifr_client.py默认就启用了它。 用官方客户端 5 行代码调用仓库内置了ifr_clients客户端库同步 异步两个版本核心方法IFRClient.extract()封装了 msgpack 序列化与人脸图解码from ifr_clients.ifr_client import IFRClient client IFRClient(hosthttp://localhost, port18081) client.server_info() # 打印后端/模型/批大小 res client.extract(data[...], modedata) # 传本地图片二进制IFRClient支持modepathsURL 列表与modedata本地二进制两种传图模式返回结构可直接取res[data][0][faces][0][vec]。批量处理目录示例可参考examples/process_dir_async.py压测脚本见benchmark.py。 常见问题与调优建议问题建议大合照漏检人群密集图可参考内置的 lumia.jpg 测试图1600×898数百人脸调低threshold至 0.5或提高服务端max_size小脸干扰比对设置min_face_size如 60过滤远景小脸只想要前 N 张脸limit_faces按面积优先保留最大的 N 张脸响应太慢查看verbose_timingstrue返回的read_imgs_ms/embed_all_ms区分瓶颈在读图还是推理GPU 环境在.env开启force_fp16首次启动报模型缺失容器会自动从 Google Drive 拉取模型部分地区受限可预先下载放入models/目录并挂载✅ 小结/extract 是 InsightFace-REST 的核心一次请求完成读图 → 检测 → 对齐 → embedding全链路记住三个关键开关extract_embedding要不要向量、embed_only要不要检测、msgpack传输提速部署认准compose/example.envdocker compose up调试认准http://localhost:18081/docs比对同一人直接对vec做点积即可归一化已帮你做好。掌握了 /extract再配合 /draw_detections 的可视化验证与 /health 的健康检查你就已经能独立交付一套完整的人脸识别 API 服务了 【免费下载链接】InsightFace-RESTInsightFace REST API for easy deployment of face recognition services with TensorRT in Docker.项目地址: https://gitcode.com/gh_mirrors/in/InsightFace-REST创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 InsightFace-REST核心端点详解：/extract人脸特征提取完全教程
InsightFace-REST核心端点详解/extract人脸特征提取完全教程【免费下载链接】InsightFace-RESTInsightFace REST API for easy deployment of face recognition services with TensorRT in Docker.项目地址: https://gitcode.com/gh_mirrors/in/InsightFace-RESTInsightFace-REST是一个基于 FastAPI TensorRT 的生产级人脸识别 REST API 服务支持 Docker 一键部署与 GPU/CPU 双后端。本文带你完整掌握其最核心的/extract 人脸特征提取端点请求参数逐个讲透、响应字段逐层拆解并附上官方客户端调用方式帮助新手快速把手忙脚乱的模型调通成稳定的人脸识别 API 服务。 它是什么为什么值得关注InsightFace-REST 把开源人脸库 InsightFace 的检测 识别模型封装成了标准 HTTP 接口高性能RTX4090 上默认配置可达 820 fpsDocker 化部署自动下载模型开箱即用批量推理检测与识别模型均支持批处理⚙️多后端TensorRTGPU/ ONNX RuntimeCPU核心能力集中在 4 个端点上实现位于if_rest/api/routes/v1/recognition.py与if_rest/api/routes/v1/service.py端点方法用途/infoGET查询服务版本、模型与默认参数配置/healthGET用内置测试图执行一次完整提取验证服务健康/extractPOST核心端点人脸检测 特征向量embedding提取/draw_detectionsPOST返回画好检测框、关键点、置信度的标注图PNG/multipart/draw_detectionsPOST以 multipart 表单上传图片并返回标注图JPG⚡ 最快启动方式Docker 三步跑通克隆仓库并进入compose目录git clone https://gitcode.com/gh_mirrors/in/InsightFace-REST cd InsightFace-REST/compose复制并修改环境变量文件模型、批大小、FP16 等都在这里配置cp example.env .env构建并启动然后访问http://localhost:18081/docs打开 Swagger 交互文档可直接在线调试 /extract 接口docker compose build docker compose up配置文件compose/example.env与compose/docker-compose.yml是部署时的主要入口。 /extract 端点详解人脸特征提取完全指南下面是 API 文档页中 /extract 的官方说明截图参数含义与本文表格一一对应请求体参数一览请求体定义见if_rest/schemas.py中的BodyExtract模型支持一次传入多张图片data与urls二选一参数默认值作用images.data/images.urls必填图片列表base64 字符串 或 可访问的 URLthreshold0.6检测置信度阈值越高越严格、漏检越多extract_embeddingtrue是否提取 512 维特征向量设为 false 则只做人脸检测速度更快embed_onlyfalse输入即为 112×112 人脸裁剪图跳过检测步骤return_face_datafalse返回对齐后人脸裁剪图base64return_landmarksfalse返回 5 点面部关键点坐标extract_gafalse附带性别/年龄估计需服务端配置 genderage 模型detect_masksfalse附带口罩佩戴检测需服务端配置 mask 模型limit_faces0每张图最多处理的人脸数0 为不限min_face_size0过滤小于指定宽度的小脸0 为不过滤msgpackfalse用 MessagePack 序列化响应体积减小约一半verbose_timingsfalse返回各阶段耗时便于排查性能瓶颈请求示例URL 与 base64 两种传图方式方式一URL服务端可访问的地址或容器内路径{ images: { urls: [test_images/lumia.jpg] }, threshold: 0.6, extract_embedding: true }方式二base64客户端本地图片最常用{ images: { data: [/9j/4AAQSkZJRg... ] }, limit_faces: 10 }处理流程if_rest/core/face_model.py中的FaceAnalysis.embed读图 → 缩放到max_size默认 640×640→ 检测器出框 → 仿射对齐裁剪 → 识别模型算 embedding → L2 归一化。响应结构逐层读懂返回结果顶层包含总耗时took与每张图片一个条目的data列表结构见ifr_clients/schemas.py字段层级说明data[].status图片ok/failed下载失败等data[].took_ms图片该图处理耗时毫秒faces[].bbox人脸[x1, y1, x2, y2]检测框原图坐标faces[].prob人脸检测置信度0~1faces[].size人脸人脸宽度像素faces[].vec人脸512 维归一化特征向量人脸比对的核心产物faces[].norm人脸原始向量 L2 范数faces[].landmarks人脸5 关键点return_landmarkstrue时faces[].facedata人脸对齐后人脸图 base64return_face_datatrue时faces[].gender/age/mask人脸需服务端配置对应模型并开启参数典型用法对两张图分别调用 /extract取faces[0].vec用余弦相似度向量已归一化直接点积即可判断是否同一人相似度 0.35~0.4 通常认为是同一人阈值视业务调整。 三种实用参数组合只检测不识别最省算力extract_embeddingfalse跳过裁剪与识别推理适合单纯做图里有没有人的校验此时响应仅含bbox、prob等轻量字段。极速 embedding跳过检测embed_onlytrue输入必须是 112×112 人脸裁剪图直接进入识别模型适合已有人脸框的下游流水线。大流量传输优化msgpacktrue或请求头Accept: application/x-msgpackembedding 体积约为 JSON 的 1/2高并发场景推荐官方客户端ifr_clients/ifr_client.py默认就启用了它。 用官方客户端 5 行代码调用仓库内置了ifr_clients客户端库同步 异步两个版本核心方法IFRClient.extract()封装了 msgpack 序列化与人脸图解码from ifr_clients.ifr_client import IFRClient client IFRClient(hosthttp://localhost, port18081) client.server_info() # 打印后端/模型/批大小 res client.extract(data[...], modedata) # 传本地图片二进制IFRClient支持modepathsURL 列表与modedata本地二进制两种传图模式返回结构可直接取res[data][0][faces][0][vec]。批量处理目录示例可参考examples/process_dir_async.py压测脚本见benchmark.py。 常见问题与调优建议问题建议大合照漏检人群密集图可参考内置的 lumia.jpg 测试图1600×898数百人脸调低threshold至 0.5或提高服务端max_size小脸干扰比对设置min_face_size如 60过滤远景小脸只想要前 N 张脸limit_faces按面积优先保留最大的 N 张脸响应太慢查看verbose_timingstrue返回的read_imgs_ms/embed_all_ms区分瓶颈在读图还是推理GPU 环境在.env开启force_fp16首次启动报模型缺失容器会自动从 Google Drive 拉取模型部分地区受限可预先下载放入models/目录并挂载✅ 小结/extract 是 InsightFace-REST 的核心一次请求完成读图 → 检测 → 对齐 → embedding全链路记住三个关键开关extract_embedding要不要向量、embed_only要不要检测、msgpack传输提速部署认准compose/example.envdocker compose up调试认准http://localhost:18081/docs比对同一人直接对vec做点积即可归一化已帮你做好。掌握了 /extract再配合 /draw_detections 的可视化验证与 /health 的健康检查你就已经能独立交付一套完整的人脸识别 API 服务了 【免费下载链接】InsightFace-RESTInsightFace REST API for easy deployment of face recognition services with TensorRT in Docker.项目地址: https://gitcode.com/gh_mirrors/in/InsightFace-REST创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考