企业官网建设流程全解析

InsightFace-REST Docker Compose部署全指南：单GPU到多GPU方案

【免费下载链接】InsightFace-RESTInsightFace REST API for easy deployment of face recognition services with TensorRT in Docker.项目地址: https://gitcode.com/gh_mirrors/in/InsightFace-REST

InsightFace-REST 是一个生产级的人脸检测与人脸识别 REST API 服务，基于 FastAPI 构建，并针对 NVIDIA TensorRT 做了高性能推理优化。通过 Docker Compose，你可以在几分钟内完成部署——无论使用单张 GPU、多张 GPU，还是没有显卡的纯 CPU 环境。本文带你从环境准备到多 GPU 负载均衡，完整走通这套人脸服务的一键安装流程。

项目概览：它能为你的应用做什么？

InsightFace-REST 把 InsightFace 的完整识别流水线封装成了 HTTP 接口，核心能力包括：

• 🚀高性能推理：默认配置下 RTX 4090 可达 820 fps，换用更轻的模型还能更快
• 🐳容器化部署：官方提供 GPU 与 CPU 两套 Docker 镜像
• 🤖模型自动下载：SCRFD、YOLOv5-face 检测器 + ArcFace 系识别模型开箱即用
• 🔄批量推理：检测与识别模型均支持 batch 推理
• ⚙️多后端：GPU 用 TensorRT，CPU 用 ONNX Runtime

下图就是它处理万人合影的实测效果——每张脸都被框出并标注了置信度：

部署前准备：一键安装所需环境清单

在开始之前，请确认你的服务器已具备以下条件：

准备工作完成后，克隆仓库并进入部署目录：

git clone https://gitcode.com/gh_mirrors/in/InsightFace-REST cd InsightFace-REST/compose

所有部署方案都集中在compose/目录中，官方也提供了对应的说明文档compose/README.md，可对照本文查看。

单GPU部署：最快上手的路径

单 GPU 是最常见的场景，对应compose/docker-compose.yml。整个流程只有四步：

第 1 步：准备配置文件

cp example.env .env

.env文件集中管理所有参数（模型选择、worker 数量、推理精度等），示例配置在compose/example.env中有完整注释。

第 2 步：构建镜像

docker compose build

第 3 步：启动服务

docker compose up

第 4 步：访问 API 文档

打开浏览器访问http://localhost:18081/docs，你会看到 FastAPI 自动生成的交互式文档，支持直接在线调用/extract接口测试人脸识别效果：

💡 首次启动时容器会自动下载模型并编译 TensorRT 引擎，耗时取决于网络与显卡，请耐心等待 healthcheck 通过。

多GPU部署：双卡并行 + Nginx负载均衡

如果你的服务器有多张 GPU，可以用compose/docker-compose-multi-gpu.yml：它为每张卡启动一个服务容器（ifr-trt-gpu0、ifr-trt-gpu1），再挂一个 Nginx 容器做负载均衡。

如果偏好 Docker Compose v2 的 profiles 语法，compose/docker-compose-v2.yml用一条命令即可切换方案：

# 单GPU docker compose -f docker-compose-v2.yml --profile gpu up --build # 双GPU（Nginx负载均衡） docker compose -f docker-compose-v2.yml --profile mgpu up --build

⚠️多 GPU 部署有两个容易踩的坑：

1. 首次启动的竞态问题：多容器同时启动时会各自下载模型、编译 TRT 引擎。正确姿势是先用单 GPU 启动一次，等模型下载和引擎编译完成后再切回多 GPU 启动。
2. TRT 引擎与显卡型号绑定：如果机器上混用不同型号的 GPU，需要为不同 GPU 指定不同的模型目录，确保各自加载正确的.plan文件。

另一个细节：多 GPU 方案因为经过 Nginx 代理，对外端口从单卡模式的18081变为18080。Nginx 的配置位于misc/nginx_conf/conf.d/default.conf。

CPU部署：没有显卡也能跑

没有 GPU 也不怕。compose/docker-compose-cpu.yml使用 ONNX Runtime 后端，配合compose/cpu.env配置：

docker compose -f docker-compose-cpu.yml up

注意 CPU 模式下cpu.env已将INFERENCE_BACKEND设为onnx，批处理大小也会调低，适合验证流程或对延迟不敏感的轻量场景。

关键配置调优：.env 中最重要的几个参数

部署完成后，按需修改.env即可调优性能与效果：

官方建议以NUM_WORKERS为第一调优项：从小往大加，直到出现 CUDA Out of Memory 后回退一档。

验证部署：一张万人图测试极限

服务起来后，最直观的验证方式是处理大场景图片。项目内置了misc/test_images/lumia.jpg——一张包含数百张人脸的"世界最大自拍照"，常被用作检测性能的基准测试图：

通过 API 文档页或 Python 客户端库ifr_clients/发起请求，确认返回的faces数量与vec特征向量符合预期，即说明整条部署链路已打通。

常见问题快速排查

• 模型下载失败：默认从 Google Drive 拉取模型，网络受限地区可手动下载后放入models/目录
• CUDA Out of Memory：调小NUM_WORKERS或REC_BATCH_SIZE
• 端口访问不通：单卡用18081，多卡经 Nginx 用18080，注意别混
• Numba 缓存报错：仓库更新后可能出现模块缺失，清理__pycache__目录即可

写在最后

InsightFace-REST 把复杂的人脸识别推理栈压缩成了"克隆仓库 → 改配置 → docker compose up"三步，单卡、多卡、纯 CPU 三种形态开箱即用。对于需要在生产环境快速落地人脸识别能力的团队来说，这是一份相当省心的部署方案。

【免费下载链接】InsightFace-RESTInsightFace REST API for easy deployment of face recognition services with TensorRT in Docker.项目地址: https://gitcode.com/gh_mirrors/in/InsightFace-REST