InsightFace ServerREST APIPython SDK人脸识别RTSP

集成 InsightFace Server REST API

通过 REST API 或 Python SDK 创建 Collection、注册身份、执行精确 1:N 搜索、处理重试并接入持久化 RTSP 监控。

2026-07-26•约 16 分钟

InsightFace Server Collections 页面，展示相互隔离的人脸身份库 — 每个 Collection 都会固定模型、检测、阈值和精确检索契约。

你将完成什么

InsightFace Server 是可自行部署的人脸分析与识别服务。Web UI、带版本的 /v1 REST API 和轻量 Python SDK 操作的是同一组 Collection、Person、FaceSample 与持久化摄像头 Monitor。

本指南从 API 边界出发，走通完整链路：确认认证和就绪状态，创建 Collection，注册 Person，检索该 Person，调用无状态 Detect 与 Compare，再接入 RTSP Monitor；同时说明隔离评估环境之外必须处理的重试、生物特征数据、模型授权和网络安全边界。

开始之前

已在 http://127.0.0.1:18097 运行 CPU Server；或已知 CUDA Server 地址（随附 CUDA 示例使用 18098 端口）。
经合法同意取得、包含清晰人脸的 JPEG、PNG 或 WebP 测试图片；默认压缩图片上限为 10 MiB。
若已启用认证，需要 API key；还需可运行 curl 的 shell，以及用于可选 SDK 流程的 Python 3。
已授权并验证的模型包。除非另有商业许可，InsightFace 公开预训练模型仅限非商业研究使用。

1. 确认认证状态与响应契约

先调用 GET /v1/health。该端点始终公开，并同时返回就绪状态和 auth_enabled。auth_enabled 为 true 时，其他所有端点都需要 Authorization: Bearer <api_key>。认证关闭时必须完全省略 Authorization header，不能发送空 header。第一段命令正是无认证写法；第二段用于已启用认证的部署。

API 使用 snake_case JSON，图片通过 multipart/form-data 上传。每个响应都带 x-request-id UUID header，JSON body 中还会以 request_id 重复返回。检测和质量信号范围为 0.0–1.0，但识别 similarity 是 [-1.0, 1.0] 的原始余弦值，不是概率。threshold 接受闭区间 [0.0, 1.0]，默认 0.4，similarity >= threshold 才算匹配。

成功的 DELETE 返回 HTTP 204，且没有 body。
Detect 未检测到人脸可以是正常空结果；Search 未命中则正常返回 matches: []。
OpenAPI 位于 /openapi.json，同源交互查看器位于 /docs。

认证关闭：完全省略 Authorization

BASE_URL=http://127.0.0.1:18097
curl -fsS "${BASE_URL}/v1/health"
curl -sS "${BASE_URL}/v1/system"

认证开启：发送 Bearer token

export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
BASE_URL=http://127.0.0.1:18097
AUTH_HEADER="Authorization: Bearer ${INSIGHTFACE_API_KEY}"

curl -fsS "${BASE_URL}/v1/health"
curl -sS "${BASE_URL}/v1/system" -H "${AUTH_HEADER}"

2. 创建 Collection 并固定识别契约

Collection 既是隔离的身份库，也是部署契约。创建时会绑定当前模型 ID、版本、bundle digest、embedding 维度、预处理版本、检测 profile 和精确检索 profile。返回的 embedding_contract_id 是不透明值：可信外部特征注册时原样复制，绝不能自行构造。

先从 threshold 0.4 开始，再用代表性验证集校准。Collection 响应会给出 detection_revision 和最终 search 设置。之后修改检测 profile 只影响新请求，不会重新提取已有 FaceSample。各 search profile 都是精确的平面穷举检索；低精度 profile 近似 FP32 余弦分数，但不是 ANN 索引。

总体默认 search profile 是 fp32_v1；fp16_v1 仅支持 CUDA，BF16 则取决于 CPU 能力或 SM80+ CUDA。
默认容量为 100,000 个活跃 row，max_faces_per_person 默认为 20；应按真实内存与保留预算设置。
人脸 crop 默认不保存。启用后仅存储 112×112 bounding-box JPEG crop，不保存原始上传或对齐后的识别输入。

创建 employees Collection

curl -sS "${BASE_URL}/v1/collections" -H "${AUTH_HEADER}" \
  -H 'Content-Type: application/json' \
  -d '{"id":"employees","name":"Employees","threshold":0.4}'

3. 注册 Person 并执行检索

注册请求使用 multipart，可一次上传多张图片。review_mode=off 按 Collection 的选脸策略处理；standard 要求恰好一张可用人脸，并执行已配置的尺寸、置信度、质量和姿态检查；strict 还会比较类内与类外相似度。批次可能以 HTTP 201 部分成功，因此必须同时检查 faces 和 rejected_images。

Search 用 Collection profile 选出一张 query 人脸，与所有活跃 FaceSample 比较；每个 Person 取其所有样本中的最高分，只返回达到有效 threshold 的结果，并按 similarity 降序排列。验证流程时应使用不同于注册图片的查询图。

query 中没有可用人脸会返回 422 face_not_found；query 有效但无人达到阈值时返回 matches: []。
成功响应前，已接受样本会先写入 SQLite，再加入当前内存索引。
external_trusted 仍需配对图片和精确的 embedding_contract_id；向量必须有限、维度正确、非零，并在 1.0 ± 0.0002 范围内完成 L2 归一化。

用两张图片注册 Alice

curl -sS "${BASE_URL}/v1/collections/employees/persons" \
  -H "${AUTH_HEADER}" \
  -F 'id=employee-001' \
  -F 'name=Alice' \
  -F 'external_id=HR-1001' \
  -F 'metadata={"department":"sales"}' \
  -F 'review_mode=standard' \
  -F 'images=@alice1.jpg' \
  -F 'images=@alice2.jpg'

用另一张图片检索

curl -sS "${BASE_URL}/v1/collections/employees/search" \
  -H "${AUTH_HEADER}" \
  -F 'image=@alice-query.jpg' \
  -F 'limit=5'

4. 使用无状态 Detect 与 Compare

Detect 按面积降序返回全部可用人脸，包括像素与归一化框、五点关键点、检测置信度和本地质量信号；不会返回 embedding，也不会写入数据。若要使用某个 Collection 的检测 profile，而不是不可变的系统 profile，请传 collection_id。

Compare 分别从 source 和 target 选一张人脸，计算原始余弦 similarity，并按有效 threshold 返回 matched。相似度可以为负，绝不能显示为“置信度百分比”。任一图片没有可用人脸都会返回 422 face_not_found。

max_faces 接受 1–100。支持 JPEG、PNG、WebP，推理前会应用 EXIF orientation。
默认完整请求上限为 64 MiB，解码后图片上限为 4,000 万像素。
Detect、Compare、注册、Search、embedding 与 RTSP 识别共享进程级推理并发预算。

无持久化地检测人脸

curl -sS "${BASE_URL}/v1/detect" \
  -H "${AUTH_HEADER}" \
  -F 'image=@group.jpg' \
  -F 'max_faces=10' \
  -F 'collection_id=employees'

比对两张选定人脸

curl -sS "${BASE_URL}/v1/compare" \
  -H "${AUTH_HEADER}" \
  -F 'source=@source.jpg' \
  -F 'target=@target.jpg' \
  -F 'threshold=0.4'

5. 使用轻量 Python SDK

直接从当前 checkout 安装 client。它基于 httpx，不包含推理 runtime，可接收图片路径、bytes 或二进制 file-like object；默认等待 65 秒，略长于 Server 的 60 秒请求 deadline。

示例使用用户指南中的 CPU 地址 18097，并假定认证已开启。认证关闭时应构造 Client("http://localhost:18097")，完全省略 api_key，以免发送 Authorization header。同一 client 还提供 create_monitor、update_monitor、monitor_state 和基于 cursor 的 monitor_events。

除非应用有意更早失败，client timeout 应长于 Server 配置的请求 timeout。
Detect 或 Compare 需要 Collection 检测 profile 时传 collection=。
使用 context manager 或显式 close，确保释放连接池。

安装本地 Python SDK

python -m pip install ./server/sdk/python

用 Python 创建、注册、检测、比对与检索

from insightface_server import Client

# Authenticated deployment. When authentication is disabled, omit api_key:
# with Client("http://localhost:18097") as client:
with Client("http://localhost:18097", api_key="your-key") as client:
    client.create_collection(
        collection_id="employees",
        name="Employees",
        threshold=0.4,
    )
    client.add_person(
        "employees",
        person_id="employee-001",
        name="Alice",
        images=["alice1.jpg", "alice2.jpg"],
        review_mode="standard",
    )

    faces = client.detect("group.jpg", max_faces=10, collection="employees")
    comparison = client.compare(
        "source.jpg", "target.jpg", threshold=0.4, collection="employees"
    )
    matches = client.search("employees", "alice-query.jpg", limit=5)

    print(faces.faces)
    print(comparison.similarity, comparison.matched)
    print(matches.matches)

6. 正确处理错误与重试，避免重复写入生物特征数据

错误统一使用 JSON envelope，包含 error.code、error.message、可选 details 和 request_id。常见映射包括：400 参数无效、401 key 缺失或错误、404 资源不存在、409 状态或模型冲突、413 超出大小限制、422 图片无效或无人脸可用、500 未预期错误、503 超时或 runtime/index 不可用。

GET 可安全重试。429 和暂时性 503 可采用带 jitter、次数和上限受控的指数退避；校验类 4xx 必须先修改请求。网络故障后，Person 或 FaceSample 的创建结果可能不明确：应先读取 client 提供的资源 ID。如果注册 503 的 details 含 write_committed: true，SQLite 已经写入，绝不能盲目重试；先读取 Person 再决定后续动作。

记录 x-request-id、endpoint、status 和安全的耗时信息；不要记录图片、embedding、API key 或 RTSP 凭据。
DELETE 只有在读取当前状态后才能重试。
分页与事件 cursor 是不透明值，只能在相同 endpoint 和 filter 下原样复用，不能解析或自行生成。

7. 接入持久化 RTSP Monitor

InsightFace Server 摄像头监控页面，展示持久化 RTSP 识别任务 — 持久化 RTSP Monitor 在浏览器关闭后仍会在服务端运行。

Monitor 是服务端 RTSP 识别任务，配置保存在 SQLite。enabled 任务会在 Server 重启后恢复，即使浏览器关闭也继续运行。decoder 只保留最新 frame，因此推理变慢只会降低实际频率，不会堆积延迟帧。match_threshold: null 表示继承 Collection threshold。

preview 特意默认关闭，识别无需预览即可运行。启用后，/preview.mjpeg 传输未经标注的原始 JPEG frame，client 使用 /state 绘制框。绝不能把 API key 放入预览 URL。用不透明 cursor 轮询 /events 获取 enter、exit、error 和 recovery 事件，并显式处理 truncated 与 stream_reset。

RTSP 凭据在 /data 下以 AES-GCM 加密，API 只返回脱敏地址。
视频帧永不保存；近期事件仅存在有界内存 ring 中，进程重启后丢失。
仅允许可信 operator 管理 Monitor；第一阶段只有一把不区分权限的 API key，不提供租户级授权。

monitor.json

{
  "id": "front-gate",
  "name": "Front gate",
  "description": "Main entrance",
  "enabled": true,
  "source": {
    "type": "rtsp",
    "url": "rtsp://viewer:secret@camera.example/live"
  },
  "collection_id": "employees",
  "inference_fps": 2.0,
  "match_threshold": null,
  "event_buffer_size": 1000,
  "event_policy": {
    "confirm_frames": 3,
    "absence_timeout_seconds": 3.0,
    "cooldown_seconds": 10.0,
    "emit_unknown": true
  },
  "preview_enabled": false
}

创建 Monitor 并轮询状态与事件

curl -sS "${BASE_URL}/v1/monitors" -H "${AUTH_HEADER}" \
  -H 'Content-Type: application/json' \
  -d @monitor.json

curl -sS "${BASE_URL}/v1/monitors/front-gate/state" \
  -H "${AUTH_HEADER}"

curl -sS "${BASE_URL}/v1/monitors/front-gate/events?limit=100" \
  -H "${AUTH_HEADER}"

8. 保护数据、网络、备份与模型权利

持久化 /data，以只读方式挂载 /models；停止写入后，或用 SQLite-safe snapshot，同步备份 SQLite 与已配置的 crop storage。数据卷和所有备份都应按生物特征数据保护。由可信 reverse proxy 终止 HTTPS，只允许必要的 CORS origin，并在边缘增加 rate/body/time limit；绝不能把关闭认证的评估部署暴露到网络。

Server source 与 Python SDK 采用 MIT 许可；模型明确不在该许可范围内。容器镜像不包含模型。安装器会展示模型许可，verify 会校验 package identity、签名 license、有效期和当前授权。包括 buffalo_l 在内的 InsightFace 公开模型包，除非另有商业许可，通常仅限非商业学术研究。代码可获取或模型下载成功都不等于获得商业部署许可。

API key 以 hash 保存；后续启动时更换 INSIGHTFACE_API_KEY 会有意轮换该数据卷的 active key。
使用 docker compose down 时不要加 -v；-v 会永久删除 named data volume。
处理生产身份前，明确 consent、retention、deletion、incident response 和 authorized-use policy。

安装并验证已授权模型包

docker compose -f server/deploy/compose.cpu.yml \
  run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cpu.yml \
  run --rm models verify buffalo_l

需要生产部署支持？

联系 InsightFace，获取模型授权、运行时优化和目标硬件部署支持。

提交企业询盘