InsightFace Server REST API 使用手册：从人脸检测到 1:N 人员库搜索与 RTSP 实时监控的完整指南

本指南以 InsightFace Server 的 /v1 REST API 为核心，系统讲解每个公开接口的调用方式、参数含义、服务端执行过程、成功结果与常见错误，覆盖系统诊断、无状态人脸检测/比对/特征抽取、Collection 人员库管理、Person/FaceSample 注册与搜索、以及持久化的 RTSP 摄像头监控任务（Monitor）。读完本文，你将掌握如何用 curl 或任意 HTTP 客户端完成从「创建人员库 → 注册人员 → 相似度搜索 → 接入 RTSP 实时识别」的完整业务闭环，并理解相似度语义、阈值判定规则、分页游标与认证等底层约定，为生产环境集成提供可直接落地的 API 契约参考。

InsightFace Server 是基于 FastAPI 实现的自托管人脸识别服务，路由入口集中在 app.py，OpenAPI Schema 实时暴露在 /docs 与 /openapi.json。若容器与模型尚未启动，请先阅读分步用户指南；本文聚焦于「接口怎么用、结果代表什么」。实时 Schema 与本文不一致时，以实际部署实例的 Schema 为准。

通用约定：路径、内容类型、限流与认证

所有公开接口遵循以下统一约定：

• API 基础路径为 /v1，JSON 字段统一使用 snake_case。
• Collection 的创建/修改（PATCH）请求使用 application/json；图片上传与人脸注册使用 multipart/form-data；人脸裁剪图下载返回 image/jpeg；摄像头预览返回 MJPEG 流。
• 支持 JPEG、PNG 与 WebP 三种图片格式。默认压缩图片上限 10 MiB、解码像素上限 4000 万、整个请求上限 64 MiB；实际值以 GET /v1/system 返回的 safe_config 为准。
• 每个响应都带 x-request-id 响应头，JSON 响应体内还包含同一个 request_id。排错时记录这个 ID，但不要记录图片、embedding、API Key 或 RTSP 凭据。
• 分数语义：detection_score 和质量分数范围为 0.0..1.0；similarity 是原始 cosine 值，范围 [-1.0, 1.0]，不是概率。公开匹配阈值范围为 [0.0, 1.0]，判定规则为 similarity >= threshold，默认阈值 0.4。这一点在测试用例中也得到印证：同一张合成图比对时 similarity 约为 1.0 且 matched=true，而两张不同合成图可以返回负的原始 cosine（见 test_face_operations.py），说明服务不会对相似度做 affine 映射或截断到 [0,1]。
• 列表接口的 cursor 是不透明令牌，只能原样交回同一个接口、同一个 Collection、同一个 Person 和同一个筛选条件，不要解析或自行构造。

认证方式

随项目附带的 Compose 配置在隔离评估环境中默认关闭认证（auth_enabled=false）。GET /v1/health 始终公开；管理员启用认证后，其他接口必须发送：

Authorization: Bearer <api_key>

认证关闭时不要发送空的 Authorization 头，直接省略该字段。从源码看，认证中间件由 auth.py 的 ApiKeyAuthenticator 实现，API Key 只以 hash 形式保存在数据库中，后续启动同一数据卷时传入不同的 INSIGHTFACE_API_KEY 会主动轮换当前 Key。OpenAPI Schema 中除 /v1/health 外的所有 /v1/ 路径都会自动声明 bearerAuth 安全方案（见 app.py 的 custom_openapi）。

统一错误格式与状态码

所有 JSON 错误响应使用统一信封：

{
  "error": {
    "code": "face_not_found",
    "message": "No usable face was detected.",
    "details": {}
  },
  "request_id": "3ed21e89-4595-4eed-a699-1df42ca62032"
}

常用状态码：400 参数错误、401 未认证、404 资源不存在、409 状态或契约冲突、413 请求/图片过大、422 图片或人脸不符合处理要求、429 达到流数量限制、500 内部错误、503 超时或模型/索引不可用。401 响应还会附带 WWW-Authenticate: Bearer 头；所有响应统一带 X-Content-Type-Options: nosniff、X-Frame-Options: DENY 等安全头（见 app.py 的中间件实现）。

第一次 API 调用：三分钟跑通「建库 → 注册 → 搜索」

假设服务已在本地 18097 端口运行（CPU 版；CUDA 版为 18098）：

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/collections" -H "${AUTH_HEADER}" \
  -H 'Content-Type: application/json' \
  -d '{"id":"employees","name":"员工库","threshold":0.4}'

curl -sS "${BASE_URL}/v1/collections/employees/persons" -H "${AUTH_HEADER}" \
  -F 'id=alice' -F 'name=Alice' -F 'review_mode=off' \
  -F 'images=@alice-enroll.jpg'

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

认证关闭时，从后三条命令中删除 -H "${AUTH_HEADER}"。若返回空 matches: []，这是无人脸匹配时的正常成功结果，不是错误。

系统接口：健康检查、运行时诊断与模型信息

GET /v1/health

用途： 容器健康检查和就绪探测，公开且无需认证。

参数： 无。

执行与结果： 检查启动状态和 SQLite quick_check。就绪时 HTTP 200：

{"status":"ready","auth_enabled":false,"request_id":"..."}

curl -sS "${BASE_URL}/v1/health"

常见错误： 模型、数据库或索引尚未就绪时返回 503 not_ready。从源码看，该接口还返回 version 字段，且 ready 判断同时依赖应用生命周期状态与数据库 quick_check 结果（见 app.py 的 health 路由）。

GET /v1/system

用途： 管理员查看安全的运行诊断。

参数： 无。

执行与结果： HTTP 200 返回 Server/OS/CPU/GPU、Compute Capability、Driver、CUDA、cuDNN、ORT、实际 Provider、模型与 License、数据库、挂载目录、Collection/Person/Face 数量、检索后端、安全配置（safe_config，含上述图片/请求大小上限、推理并发、RTSP 相关参数等）和最近错误（recent_errors，最多 10 条）。不会返回密钥、图片或特征。

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

常见错误： 401 unauthorized、503 request_timeout。

GET /v1/models

用途： 查看当前已验证的检测/识别模型、实际 Provider 和模型授权摘要。

参数： 无。

执行与结果： HTTP 200 返回 models（每个模型组件含 model_id、model_version、task、sha256、input_size、embedding_dimension 等字段）、execution_provider 和 license，不返回 ONNX 文件内容或签名私钥。

curl -sS "${BASE_URL}/v1/models" -H "${AUTH_HEADER}"

常见错误： 401 unauthorized。

无状态人脸接口：检测、比对与特征抽取

这三个接口不写数据库，适合做临时分析或与自有系统集成。

POST /v1/detect

用途： 检测一张图片中的所有可用人脸，不写数据库。

表单参数： image 必填；max_faces 可选，1～100；collection_id 可选，指定后使用该 Collection 的检测配置，否则使用系统配置。旧参数 min_score 不再支持——提交它会得到 400 request_detection_override_not_supported（检测阈值只能由系统或 Collection 配置决定，不允许请求级覆盖；测试用例 test_detect_respects_max_faces_and_rejects_request_threshold_override 验证了这一行为）。

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

执行与结果： 对配置中的每个输入尺寸分别检测（动态 SCRFD 多分辨率推理），把候选框映射回原图坐标后合并，做一次全局 NMS，按人脸面积降序返回。HTTP 200 包含 faces、processing_ms 和 request_id；每张脸包含像素/归一化框、五点关键点、检测分数和质量信息（清晰度、亮度、姿态等启发式质量，见 responses.py 的 FaceQuality）。无人脸是成功的 faces: []——测试 test_detect_sorts_faces_and_empty_image_is_success 验证了空图片返回 200 且空列表。

常见错误： 400 request_detection_override_not_supported、404 Collection、413、422 invalid_image、503 request_timeout。

POST /v1/compare

用途： 比对两张图片中按策略选中的单张脸，不持久化。

表单参数： source 和 target 必填；threshold 可选 0～1，默认 0.4；collection_id 可选，用于选择 Collection 检测配置。

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

执行与结果： 按 largest 或 center_largest 策略分别选脸、对齐、抽取并 L2 归一化特征，计算原始 cosine。HTTP 200 返回 matched、similarity、实际 threshold、两张选中脸、processing_ms 和 request_id。matched = similarity >= threshold 在服务端直接比较得出（见 app.py 的 compare 路由）。任一图片没有可用脸时返回 422 face_not_found。

常见错误： 404 Collection、413、422 invalid_image 或 face_not_found、503 request_timeout。

POST /v1/embeddings

用途： 为可信集成方抽取一张选中脸的特征；普通注册/搜索不需要调用它。

表单参数： image 必填；collection_id 可选。旧 face_selection 请求参数不再支持。

curl -sS "${BASE_URL}/v1/embeddings" -H "${AUTH_HEADER}" \
  -F 'image=@portrait.jpg' -F 'collection_id=employees'

执行与结果： HTTP 200 返回一个 faces 项（含像素/归一化框、关键点、质量分）、L2 归一化 embedding、model、processing_ms 和 request_id。embedding 数值保留 8 位小数；embedding 属于敏感生物特征，服务不会记录其内容。

常见错误： 400 request_detection_override_not_supported、404、413、422 invalid_image 或 face_not_found、503。

Collection 接口：人员库的创建、查询、修改与删除

Collection 是独立的人员库，创建时固定绑定模型与搜索契约：会分配检索索引，并记录当时的模型 ID、版本、digest、512 维特征与预处理版本（见 app.py 的 create_collection 路由，这些值来自推理引擎的 summary）。

POST /v1/collections

用途： 创建独立人员库，并固定模型、检测和搜索契约。

JSON 参数： id、name 必填；description 默认空字符串；threshold 默认 0.4；metadata 默认 {}；save_face_crops 默认 false。可选 detection 包含 input_sizes、threshold、nms_threshold、single_face_selection；可选 search 包含 profile、capacity_rows、max_faces_per_person 和 load_policy。

ID 规则（在 schemas.py 的 validate_id 中以正则强制）：_default 或 1～64 位，首位是字母/数字，其余允许字母、数字、点、下划线和短横线。Schema 使用 extra="forbid" 严格模式，未知字段会被拒绝。

curl -sS "${BASE_URL}/v1/collections" -H "${AUTH_HEADER}" \
  -H 'Content-Type: application/json' \
  -d '{
    "id":"employees",
    "name":"公司员工",
    "threshold":0.4,
    "search":{"profile":"fp32_v1","capacity_rows":100000,"max_faces_per_person":20,"load_policy":"lazy"},
    "detection":{"input_sizes":[[96,96],[512,512]],"threshold":0.5,"nms_threshold":0.4,"single_face_selection":"largest"}
  }'

参数补充说明：

• detection.input_sizes：每个条目是 [width, height]，动态 SCRFD 会分别运行所有分辨率、把候选映射回原图后合并并做一次全局 NMS。系统级校验要求边长必须是 32 的倍数、范围 32～2048、最多 4 个尺寸、总像素不超过 4M（见 config.py 的 normalize_detector_input_sizes）。
• detection.single_face_selection：仅支持 largest 与 center_largest。largest 优先面积；center_largest 最大化 人脸面积 - 2.0 × 人脸框中心到图像中心的像素距离平方，检测置信度不参与该分数。
• search.profile：可选 fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1（详见下文「精确检索 Profile 与容量」）。
• search.load_policy：eager 或 lazy；_default Collection 在未指定时默认 eager，其他默认 lazy。

执行与结果： 分配索引并固定当前模型契约。HTTP 201 返回完整 collection、解析后的默认值、计数和时间戳（含 person_count、face_count、embedding_contract_id、detection_revision 等）。

常见错误： 400 invalid_detection_profile、unsupported_search_profile 或 search_capacity_too_large；409 collection_exists；503 search_index_unavailable。

GET /v1/collections

用途： 分页列出人员库。

查询参数： limit 1～100，默认 50；cursor 可选不透明令牌。

curl -sS "${BASE_URL}/v1/collections?limit=50" -H "${AUTH_HEADER}"

结果： HTTP 200 返回 collections 和可空 next_cursor。常见错误： 400 invalid_cursor、401 unauthorized。

GET /v1/collections/{collection_id}

用途： 获取一个人员库。路径参数： collection_id。

curl -sS "${BASE_URL}/v1/collections/employees" -H "${AUTH_HEADER}"

结果： HTTP 200 返回 collection、实时 person_count、face_count 和 embedding_contract_id。常见错误： 404 resource_not_found。

PATCH /v1/collections/{collection_id}

用途： 修改 Collection 可变策略。路径参数： collection_id。

JSON 参数： 可提交 name、description、threshold、metadata、save_face_crops；search 只能修改 capacity_rows、max_faces_per_person、load_policy；detection 可修改检测配置（input_sizes、threshold、nms_threshold、single_face_selection）。模型绑定和 search.profile 不可修改，未知字段及显式 null 会被拒绝（reject_nulls 校验器，见 schemas.py）。检测修改从下一次请求生效，不重算已有特征。

curl -sS -X PATCH "${BASE_URL}/v1/collections/employees" \
  -H "${AUTH_HEADER}" -H 'Content-Type: application/json' \
  -d '{"threshold":0.45,"detection":{"single_face_selection":"center_largest"}}'

结果： HTTP 200 返回完整更新后的 collection。常见错误： 400、404、409 容量/模型契约冲突、503 索引更新失败。

DELETE /v1/collections/{collection_id}

用途： 删除人员库。路径参数： collection_id；查询参数： force 布尔值，默认 false。非空 Collection 必须明确 force=true。

curl -sS -X DELETE "${BASE_URL}/v1/collections/employees?force=true" \
  -H "${AUTH_HEADER}"

结果： HTTP 204，无响应体。常见错误： 404、409 collection_not_empty、503 search_index_unavailable。

Person 与 FaceSample 接口：注册、管理与增量入库

POST /v1/collections/{collection_id}/persons

用途： 一次创建 Person 并注册一张或多张 FaceSample。

路径参数： collection_id。表单参数： images 必填且可重复，默认最多 20 张（由 INSIGHTFACE_MAX_REGISTRATION_IMAGES 控制）；id 可选，省略后生成 UUID；name、external_id 可选（均限 200 字符）；metadata 是 JSON 对象字符串，默认 {}；review_mode 为 off|standard|strict，默认 off；embedding_mode 为 server|external_trusted，默认 server。外部模式还必须提交与图片一一对应的 external_embeddings JSON 数组（向量个数必须等于图片数，否则报 external_embedding_count_mismatch）以及 Collection 返回的 embedding_contract_id（不匹配返回 409 embedding_contract_mismatch）。外部 embedding 必须先完成 L2 归一化。

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.webp'

入库审查模式（review_mode）语义：

• off：按 Collection 策略选脸并允许多人脸；
• standard：要求恰好一张脸，并执行尺寸、检测分数、清晰度、亮度和姿态审查（对应配置项 INSIGHTFACE_REGISTRATION_MIN_SCORE 默认 0.6、INSIGHTFACE_REGISTRATION_MIN_QUALITY 默认 0.35、INSIGHTFACE_REGISTRATION_MIN_FACE_SIZE 默认 40，见 config.py）；
• strict：在 standard 基础上，还要求样本的最佳类内相似度严格大于最佳类外相似度（即入库样本必须比任何其他 Person 的样本更接近本人）。

执行与结果： HTTP 201 返回 person、成功 faces 和逐图片 rejected_images（含 index、filename、reason），允许部分成功。所有图片都失败时返回 422 registration_failed 且不创建 Person。

常见错误： 400 ID/metadata/图片数量；404 Collection；409 Person、外部 ID、embedding 契约、容量或每人样本上限冲突；413；422 registration_failed；503 search_index_unavailable。若 503 详情含 write_committed:true，说明写入可能已提交，先查询该 Person 再决定是否重试，不要盲目重复注册。

GET /v1/collections/{collection_id}/persons

用途： 分页列出或筛选人员。路径参数： collection_id。查询参数： limit 1～100，默认 50；cursor；search 可选，匹配 Person ID、姓名或外部 ID。

curl -sS "${BASE_URL}/v1/collections/employees/persons?limit=50&search=alice" \
  -H "${AUTH_HEADER}"

结果： HTTP 200 返回 persons 和 next_cursor。常见错误： 400 invalid_cursor、404 Collection。

GET /v1/collections/{collection_id}/persons/{person_id}

用途： 获取一个 Person。路径参数： collection_id、person_id。

curl -sS "${BASE_URL}/v1/collections/employees/persons/employee-001" \
  -H "${AUTH_HEADER}"

结果： HTTP 200 返回 person、当前 face_count 和时间戳。常见错误： 404。

PATCH /v1/collections/{collection_id}/persons/{person_id}

用途： 修改 Person 展示信息。路径参数： collection_id、person_id。JSON 参数： name、external_id、对象 metadata；未知字段拒绝，metadata 不可为 null。

curl -sS -X PATCH "${BASE_URL}/v1/collections/employees/persons/employee-001" \
  -H "${AUTH_HEADER}" -H 'Content-Type: application/json' \
  -d '{"name":"Alice Chen","metadata":{"department":"sales"}}'

结果： HTTP 200 返回完整 person。常见错误： 400、404、409 external_id_exists。

DELETE /v1/collections/{collection_id}/persons/{person_id}

用途： 删除 Person 及其全部 FaceSample、embedding 和可选裁剪图。

curl -sS -X DELETE "${BASE_URL}/v1/collections/employees/persons/employee-001" \
  -H "${AUTH_HEADER}"

结果： HTTP 204，无响应体；成功后搜索不会再返回该 Person。常见错误： 404、503 search_index_unavailable。

POST /v1/collections/{collection_id}/persons/{person_id}/faces

用途： 给已有 Person 增量加入 FaceSample。

路径参数： collection_id、person_id。表单参数： 可重复 images、review_mode、embedding_mode、external_embeddings、embedding_contract_id，含义与创建 Person 完全相同。

curl -sS "${BASE_URL}/v1/collections/employees/persons/employee-001/faces" \
  -H "${AUTH_HEADER}" -F 'review_mode=standard' \
  -F 'images=@alice3.jpg' -F 'images=@alice4.png'

结果： HTTP 201 返回成功 faces 和逐图片 rejected_images，允许部分成功。常见错误： 与注册 Person 相同，另有 404 Person。

GET /v1/collections/{collection_id}/persons/{person_id}/faces

用途： 分页列出 FaceSample 元数据，不返回 embedding 或图片字节。

路径参数： collection_id、person_id；查询参数： limit 1～100，默认 50；cursor 可选。has_crop 表示是否存在已保存裁剪图。每个 FaceSample 还含 bounding_box、landmarks、detection_score、quality、model_id、embedding_source（server|external_trusted）等元数据（见 responses.py 的 FaceSample）。

curl -sS "${BASE_URL}/v1/collections/employees/persons/employee-001/faces?limit=50" \
  -H "${AUTH_HEADER}"

结果： HTTP 200 返回 faces 和 next_cursor。常见错误： 400 invalid_cursor、404 Collection 或 Person。

GET /v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}/image

用途： 下载启用保存后存在的 112×112 管理用人脸裁剪图。注意：它不是原始上传图片，也不是识别模型使用的对齐输入。

路径参数： collection_id、person_id、face_id。

curl -sS "${BASE_URL}/v1/collections/employees/persons/employee-001/faces/FACE_ID/image" \
  -H "${AUTH_HEADER}" -o face-crop.jpg

结果： HTTP 200 image/jpeg，带 Cache-Control: no-store。非 JSON 响应的请求 ID 只在 x-request-id 头中。常见错误： 401、404 FaceSample 或 face_image_not_found。

DELETE /v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}

用途： 删除一个 FaceSample、embedding 和可选裁剪图。

curl -sS -X DELETE "${BASE_URL}/v1/collections/employees/persons/employee-001/faces/FACE_ID" \
  -H "${AUTH_HEADER}"

结果： HTTP 204，无响应体；返回成功前同步从活动索引移除。常见错误： 404、503 search_index_unavailable。

写入一致性说明： 新 FaceSample 会先提交到 SQLite，再加入内存索引，然后才返回成功；删除同时更新两处。重启时从 SQLite 重建索引，SQLite 始终是权威数据源（详见 user-guide.zh-CN.md 第 5 节及搜索索引同步模块 synchronization.py）。

搜索接口：1:N Person 搜索

POST /v1/collections/{collection_id}/search

用途： 用一张查询图片在指定人员库中执行 1:N Person 搜索。

路径参数： collection_id。表单参数： image 必填；limit 1～100，默认 5；threshold 可选 0～1，省略后使用 Collection 阈值。旧 face_selection 参数不再支持（提交会得到 400 request_detection_override_not_supported）。

curl -sS "${BASE_URL}/v1/collections/employees/search" -H "${AUTH_HEADER}" \
  -F 'image=@unknown.webp' -F 'limit=5' -F 'threshold=0.4'

执行与结果： 按 Collection 配置选择查询脸，扫描所有有效 FaceSample，每个 Person 取最高 FaceSample 相似度，按相似度降序且只返回达到阈值的结果。HTTP 200 返回 searched_face、matches（每个匹配含 person、similarity、matched_face_id）、实际 threshold、processing_ms 和 request_id。无匹配是成功的 matches: []。

常见错误： 404 Collection、409 collection_model_mismatch、413、422 invalid_image 或 face_not_found、503 search_index_unavailable 或超时。

底层实现： 搜索是Flat 精确全量搜索（grouped Flat-IP），不是 ANN 索引。以参考实现 reference.py 为例：查询向量先做 L2 归一化校验（范数与 1 的偏差须在 2e-4 以内），再按 Profile 编码（FP32/FP16/BF16/INT8），对每个存活行计算点积分数、按 Person 分组取最高分、排序取前 limit，最终把相似度 clip 到 [-1, 1] 返回。INT8 Profile 的量化 scale 分别为 736 与 1000，点积使用 INT32 累加后除以 scale² 还原为近似 cosine。

RTSP Monitor 监控任务：持久化的服务端实时识别

Monitor 是持久化的服务端 RTSP 识别任务：配置保存在 SQLite 中，处于启用状态的 Monitor 会在 Server 重启后自动恢复。系统不保存视频帧；事件只存在于有容量上限的内存环形缓冲区，进程重启后丢失。解码器只保留最新帧，因此推理变慢时会降低实际执行频率，而不会积压已经过时的视频帧（跳帧而非排队）。

POST /v1/monitors

用途： 创建并可选择立即启动一个 Monitor。请求体： 使用 JSON；source.url 只允许 rtsp:// 或 rtsps://（校验逻辑见 schemas.py 的 MonitorSource：必须含 host、不允许 fragment、端口必须合法）。凭据使用 AES-GCM 加密保存在 /data，API 只返回脱敏地址（不包含用户名、密码和查询值）。

{
  "id": "front-gate",
  "name": "公司前门",
  "description": "主入口",
  "enabled": true,
  "source": {"type": "rtsp", "url": "rtsp://viewer:[e-mail]/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
}

参数说明： match_threshold: null 表示继承 Collection 阈值；event_buffer_size 范围 10～10000；inference_fps 范围 0.1～30.0（默认 2.0）；事件策略默认值：confirm_frames=3（连续多少帧后确认）、absence_timeout_seconds=3.0（离开超时）、cooldown_seconds=10.0（重复事件冷却）、emit_unknown=true（是否产生陌生人脸事件）。Web 预览默认关闭，不打开预览也会持续识别并产生事件。

结果： HTTP 201 返回完整 monitor、脱敏源、实际默认值和运行摘要（含 runtime 状态）。常见错误： 400 invalid_request、404 Collection、409 monitor_exists、429 monitor_limit_exceeded（同时运行的 Monitor 数量达到 INSIGHTFACE_RTSP_MAX_STREAMS 上限，默认 4）。

GET /v1/monitors

用途： 分页列出持久化 Monitor 配置和简要运行状态。查询参数： limit 范围 1～100，默认 50；cursor 必须原样使用上次响应中的 next_cursor，客户端不应解析。

curl -sS "${BASE_URL}/v1/monitors?limit=50" -H "${AUTH_HEADER}"

结果： HTTP 200 返回有序 monitors 和可空 next_cursor。常见错误： 400 invalid_cursor（令牌无效、被修改或作用域不匹配）；启用认证时也可能返回 401。

GET /v1/monitors/{monitor_id}

用途： 读取一个 Monitor 的持久化配置和最新运行摘要。路径参数： monitor_id 是创建时由调用方指定的 ID；响应中的 RTSP 地址不包含用户名、密码和查询值。

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

结果： HTTP 200 返回 monitor，包括事件策略、预览开关、时间戳和 runtime（含 status、connected、stream_epoch、preview_viewers 等）。常见错误： 404 monitor_not_found、401 unauthorized。

PATCH /v1/monitors/{monitor_id}

用途： 局部修改 Monitor，id 不可修改。请求体： 至少提供一个创建接口中的可变字段；event_policy 也支持局部字段。只有更换 RTSP 地址或凭据时才发送 source；将 match_threshold 设为 null 可恢复继承 Collection 阈值。

curl -sS -X PATCH "${BASE_URL}/v1/monitors/front-gate" \
  -H "${AUTH_HEADER}" -H 'Content-Type: application/json' \
  -d '{"inference_fps":1.5,"event_policy":{"confirm_frames":5}}'

行为说明： 修改源、Collection、执行频率、阈值或事件策略会重启该任务；enabled 控制启停。名称、描述、预览和缓冲容量可以在线生效。

结果： HTTP 200 返回更新后的完整 monitor。常见错误： 400 invalid_request、404 Monitor 或 Collection、429 monitor_limit_exceeded。

DELETE /v1/monitors/{monitor_id}

用途： 永久删除一个 Monitor 配置。路径参数： monitor_id。操作会停止解码与推理线程、释放 RTSP 连接并丢弃内存状态和事件，但不会删除其 Collection。

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

结果： HTTP 204，无响应体。常见错误： 404 monitor_not_found、401 unauthorized。

GET /v1/monitors/{monitor_id}/state

用途： 供无界面客户端或 Web UI 轮询当前运行状态。返回字段： 包含连接状态、源分辨率/FPS、配置与实际推理频率、耗时、跳帧（dropped_frames）、当前已识别与陌生人脸、预览查看者、重连次数和安全的最近错误；不会包含 embedding 或源凭据。

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

结果： HTTP 200 返回 state（字段结构见 responses.py 的 MonitorState，含 inference 子对象与 faces 列表），停用的 Monitor 通常为 stopped。常见错误： 404 monitor_not_found、401 unauthorized。

GET /v1/monitors/{monitor_id}/events

用途： 通过短轮询获取最近的进入、离开、错误和恢复事件，无需保持长连接。查询参数： limit 范围 1～1000，默认 100；下一次请求原样携带上次的 next_cursor。cursor 是包含内部任务 epoch 和序号的签名不透明字符串。

第一次不带 cursor 时返回最新的若干事件；后续只返回更新事件。truncated: true 表示客户端落后于环形缓冲区，stream_reset: true 表示任务已重启，旧 cursor 属于上一个 epoch。事件不落盘，Server 进程重启后会丢失。

结果： HTTP 200 返回 events、next_cursor、has_more、truncated 和 stream_reset。每个事件含 id、sequence、type（enter/leave/error/recovery 等）、stream_epoch、occurred_at，以及可选的 track_id、person、similarity、threshold、face、error（见 responses.py 的 MonitorEvent）。常见错误： 400 invalid_cursor、404 monitor_not_found、401 unauthorized。

GET /v1/monitors/{monitor_id}/preview.mjpeg

用途： 打开可选的原始 MJPEG 预览。认证： 与其他 API 一样使用 Bearer 请求头，不要把 API Key 放进 URL。接口返回未画框的 multipart/x-mixed-replace JPEG 流，客户端结合 /state 自行绘制人脸框、ID 和相似度（Web UI 的标注约定是：绿框=已入库人员，橙框=检测到但未入库的人脸）。

只有 preview_enabled=true 且至少有一个查看者时才进行 JPEG 编码；关闭预览不会停止识别，传输中断后客户端应采用有上限的退避方式重连。预览相关可调参数包括 INSIGHTFACE_RTSP_PREVIEW_FPS（默认 5.0）与 INSIGHTFACE_RTSP_JPEG_QUALITY（默认 82）。

结果： HTTP 200 长连接二进制流，不是 JSON。常见错误： 409 preview_disabled、503 stream_unavailable、404 monitor_not_found、401。

生产客户端检查表

面向生产集成的健壮性建议：

• 先调用 /v1/health，再读取 /v1/system 确认 Provider、模型和阈值配置（CUDA 部署必须显示 CUDAExecutionProvider，不会静默回退到 CPU）。
• GET 可以安全重试；DELETE 重试前先读取资源状态。创建 Person/FaceSample 遇到网络结果不确定时，先按调用方指定 ID 查询，不要直接重复注册。
• 429 和临时 503 可使用带抖动的有界指数退避；其他 4xx 应修正请求而不是重试。
• 升级前保存当前镜像 digest、模型 ID/digest、数据库备份和 API 版本。不要让两个 Server 进程同时写同一个 /data 目录（服务启动时会获取进程级数据库锁，见 app.py 的 database.acquire_process_lock()）。

附：启动前提与仅启动时生效的配置

• 通用配置文件为 server.toml，Compose 将其只读挂载到 /etc/insightface/server.toml，修改后必须重启容器。默认值包括：[inference] max_concurrency = "auto"（CPU 解析为 4、CUDA 为 8，上限 256）；[detection] input_sizes = [[96,96],[512,512]]、threshold = 0.50、nms_threshold = 0.40、single_face_selection = "largest"、max_detected_faces = 100；[web] disabled = false（设为 true 则只启动 API，/v1 与 /openapi.json 仍可用，但不会注册 /、/docs、帮助文档和前端静态资源）。这些字段的校验逻辑见 config.py 的 load_server_config 与 DetectionProfile.from_mapping。
• 大量部署参数通过环境变量注入（见 compose.cpu.yml），包括 INSIGHTFACE_AUTH_ENABLED、INSIGHTFACE_API_KEY、INSIGHTFACE_SAVE_FACE_CROPS、INSIGHTFACE_DEFAULT_THRESHOLD、INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILE（默认 fp32_v1）、INSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS（默认 100000）、INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS（默认 10000000）、INSIGHTFACE_COLLECTION_DEFAULT_MAX_FACES_PER_PERSON（默认 20）、INSIGHTFACE_COLLECTION_DEFAULT_LOAD_POLICY（默认 lazy）等。
• 系统配置只在启动时读取，不提供运行时修改 API。新 Collection 会复制系统检测配置，之后可独立修改并从下一次请求生效；无状态 Detect 和 Embeddings 使用系统配置；Compare 可使用系统配置或指定 Collection；注册与 Search 始终使用 Collection 配置。

附：精确检索 Profile 与容量

系统接口只公布当前 CPU/GPU 真正可用的 Profile。Collection 在创建时固定 Profile，不能在单次 Search 请求中临时切换。

Profile	存储类型	常见可用环境
fp32_v1	FP32	CPU 与 CUDA
fp16_v1	FP16	CUDA
bf16_v1	BF16	支持的 CPU 或 SM80+ CUDA
int8_x736_v1	INT8，scale 736	CPU 与 CUDA；推荐 INT8
int8_x1000_v1	INT8，scale 1000	兼容已有 Collection

这些实现都会遍历全部有效 FaceSample，属于 Flat 精确全量搜索，不是 ANN 索引。低精度 Profile 会近似 FP32 分数；INT8 点积使用 INT32 累加。对外相似度和阈值始终是原始 cosine。

capacity_rows 预留该 Collection 的最大有效行数，避免常规扩容停顿。512 维向量的大致纯特征占用为：FP32 每行 2,048 字节，FP16/BF16 每行 1,024 字节，INT8 每行 512 字节，还需额外计算 ID 与工作区。默认容量 100000，部署级上限默认 10000000。max_faces_per_person 默认 20，限制单人样本数，不限制 Person 数量。