AI人脸识别配置：从零搭建可用的本地识别服务

想在服务器上跑一套能用的 AI 人脸识别服务，最省事的路线是用 Docker 部署一个开源的人脸识别引擎，再通过 HTTP 接口调用。
本文按零基础用户的操作顺序，讲清楚准备条件、配置步骤、验证方法和常见报错，环境以 Linux 服务器加 Docker 为准。

先确认服务器和依赖是否够用

人脸识别对 CPU 和内存有一定要求，尤其是首次加载模型时。
建议至少 2 核 CPU、4GB 内存，磁盘预留 10GB 以上。
如果服务器只有 1GB 内存，容器可能在启动阶段就被系统杀掉。

登录服务器后先检查基础环境：

uname -m
docker --version
docker compose version
free -h
df -h /

预期结果是能正常输出 Docker 版本号、内存和磁盘信息。
如果提示 docker: command not found，需要先安装 Docker。
以常见的 Debian/Ubuntu 系统为例：

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
docker run --rm hello-world

看到 Hello from Docker! 说明 Docker 可用。
如果服务器在国内且拉取镜像慢，可以在 /etc/docker/daemon.json 中配置镜像加速地址，然后执行 systemctl daemon-reload && systemctl restart docker。

用 Docker Compose 完成人脸识别服务配置

新建一个目录存放配置和模型数据，避免容器删除后数据丢失：

mkdir -p /opt/face-service/models
cd /opt/face-service

创建 docker-compose.yml，这里以提供 REST API 的人脸识别服务为例，关键配置如下：

services:
  face-api:
    image: your-face-api-image:latest
    container_name: face-api
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - ./models:/app/models
    environment:
      - MODEL_PATH=/app/models
      - DETECTION_THRESHOLD=0.6
      - LOG_LEVEL=info

几个配置项要留意：MODEL_PATH 指向容器内模型目录，
必须和挂载路径一致；DETECTION_THRESHOLD 是检测阈值，
值越高越严格，
误识别少但可能漏检；restart:
unless-stopped 让容器在服务器重启后自动拉起。

把模型文件放入 /opt/face-service/models，确认文件权限容器可读：

ls -lh /opt/face-service/models
chmod -R 755 /opt/face-service/models

然后启动：

docker compose up -d
docker compose ps
docker compose logs -f face-api

日志中出现模型加载完成、HTTP 服务监听 8000 端口的信息，说明配置生效。
如果日志反复报模型文件不存在，优先检查挂载路径和文件名大小写。

调用接口验证识别是否真正可用

服务起来不等于能识别。
先用健康检查接口确认进程存活：

curl -s http://127.0.0.1:8000/health

返回 {"status":"ok"} 或类似字段即可。
接着用一张清晰的正脸照片测试识别接口，具体字段名以你使用的服务文档为准，常见形式如下：

curl -X POST http://127.0.0.1:8000/detect \
  -F "image=@/tmp/test.jpg"

预期返回中包含人脸框坐标和置信度。
如果返回空数组，先换一张光线均匀、无遮挡的正脸照片再试，排除图片本身的问题。

需要从外网访问时，记得在云厂商安全组放行 8000 端口，并确认系统防火墙状态：

firewall-cmd --list-ports
# 或
ufw status

生产环境不建议直接把识别接口裸暴露到公网，至少加一层 Nginx 反向代理并配置访问鉴权。

容易踩坑的地方

内存不足导致容器反复重启。 用 docker inspect face-api --format '{{.State.OOMKilled}}' 查看是否被 OOM 杀掉，
返回 true 就要加内存或换更高配置的服务器。

模型路径写错。 容器内路径和宿主机挂载路径是两回事，MODEL_PATH 必须写容器内路径，不是 /opt/face-service/models。

端口冲突。 启动报 port is already allocated 时，
用 ss -lntp | grep 8000 找到占用进程，
改宿主机端口映射即可，
例如 "8001:
8000"。

图片编码问题。 上传接口要求 multipart 表单，直接用 JSON 传 base64 可能报 415 或 400，按接口文档选择正确的 Content-Type。

阈值调得太高或太低。 阈值不是固定值，需要根据你的场景用真实样本测试后微调，不要直接照搬别人的参数。

配置完成后怎么确认稳定

观察容器运行状态和资源占用：

docker stats --no-stream face-api
docker compose logs --tail=50 face-api

连续调用几次识别接口，确认响应时间在可接受范围、日志没有异常堆栈。
把 docker-compose.yml 和模型目录做好备份，后续迁移服务器时直接复制目录执行 docker compose up -d 即可恢复。

如果识别结果不稳定，优先排查图片质量、光照和阈值三个因素，再考虑更换模型。
AI人脸识别配置的核心不是把容器跑起来，而是让接口在真实图片上返回可用的结果，按上面的验证步骤走一遍，能少走很多弯路。