尧图网页设计 
InsightFace Server REST API 完全指南检测、注册、搜索与 RTSP 监控【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface本文是 InsightFace ServerInsightFace 人脸分析项目的自托管服务端公开 REST API 的完整使用指南覆盖/v1下全部公共路由的用途、输入参数、服务端工作流程、成功响应与错误语义。读完本文你将能够用 curl 完成「健康检查 → 创建 Collection → 注册 Person → 人脸搜索」的完整闭环掌握review_mode、embedding_mode、search.profile等关键配置的底层原理并上手 RTSP 实时识别 Monitor 的创建与事件消费。原文为西班牙语版 server/docs/api.es.md本文依据该文档并结合 server/docs/api.md英文权威版与仓库源码整理成中文安装与首次启动请参阅 server/docs/user-guide.zh-CN.md运行中的精确接口 schema 可通过/openapi.json或同源交互式查看器/docs获取。通用规则路由、编码与认证API 根路径为/v1JSON 字段采用snake_case图片以multipart/form-data形式上传支持 JPEG、PNG、WebP推理前会应用 EXIF 方向信息。仓库自带的 Compose 文件默认关闭认证以支持隔离评估。开启认证后INSIGHTFACE_AUTH_ENABLEDtrue除GET /v1/health外的所有端点都要求Authorization: Bearer api_key认证关闭时请完全省略该请求头不要发送空 header。认证实现见 server/backend/insightface_server/api/auth.pyApiKeyAuthenticator在启动时将INSIGHTFACE_API_KEY同步进存储sync_api_key若开启认证却没有任何 API key 会直接拒绝启动每次请求通过require()校验 Bearer 头并调用repository.verify_api_key()。所有响应都带x-request-idUUID 响应头JSON 响应体会在request_id字段重复它。成功的 DELETE 请求返回 204 且无响应体。分数与阈值语义confidence/quality/threshold的取值范围是0..1。其中similarity不是概率而是原始余弦相似度[-1, 1]识别阈值默认0.4且为闭区间判定similarity threshold即视为匹配。服务端的相似度计算实现见 server/backend/insightface_server/services/core.py即对两个 L2 归一化向量的内积做np.clip(..., -1.0, 1.0)。检测框同时返回像素坐标与归一化坐标两种形式{ pixels: {x: 120, y: 80, width: 240, height: 280}, normalized: {left: 0.12, top: 0.08, width: 0.24, height: 0.28} }默认的图片体积限制压缩图 10 MiB、解码后 4000 万像素、整个请求 64 MiB对应 server/backend/insightface_server/config.py 中的INSIGHTFACE_MAX_IMAGE_BYTES、INSIGHTFACE_MAX_IMAGE_PIXELS、INSIGHTFACE_MAX_REQUEST_BYTES。错误语义与分页错误使用标准 HTTP 状态码 统一信封{ 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 限流、503 超时/模型或索引不可用。中间件对请求体大小、请求超时与错误信封的统一处理见 server/backend/insightface_server/app.py。分页方面cursor是不透明令牌只能原样复用于同一端点、同一 Collection、同一 Person 及相同过滤条件客户端不得解析或构造它。服务端使用CursorCodec见 server/backend/insightface_server/storage/pagination.py对游标签名编码并将作用域如persons:{collection}:{search}绑定进游标因此跨作用域使用会返回400 invalid_cursor。第一个 API 工作流BASE_URLhttp://127.0.0.1:18097 AUTH_HEADERAuthorization: Bearer ${INSIGHTFACE_API_KEY} curl -fsS ${BASE_URL}/v1/health创建 Collection → 注册 Person → 用另一张图搜索curl -sS ${BASE_URL}/v1/collections -H ${AUTH_HEADER} \ -H Content-Type: application/json \ -d {id:employees,name:Employees,threshold:0.4} curl -sS ${BASE_URL}/v1/collections/employees/persons -H ${AUTH_HEADER} \ -F idalice -F nameAlice -F review_modeoff \ -F imagesalice-enroll.jpg curl -sS ${BASE_URL}/v1/collections/employees/search -H ${AUTH_HEADER} \ -F imagealice-query.jpg -F limit5客户端规则与重试安全客户端超时时间要大于服务端配置的请求超时时间默认 60 秒见INSIGHTFACE_REQUEST_TIMEOUT_SECONDS。把x-request-id当作关联 ID 记入日志但不要记录图片、embedding、RTSP 凭据和 API key。GET 可安全重试DELETE 重试前先确认当前状态网络不确定导致 Person/FaceSample 创建结果不明时不要盲目重试 POST先查询客户端提供的资源 ID。若 503 响应携带write_committed: true说明写入可能已提交同样应先读再重试见 server/backend/insightface_server/services/core.py 的_search_unavailable。仅429与瞬时503可用有上限的指数退避 jitter 重试4xx校验错误必须修改请求。内容类型敏感Collection/Person 的 PATCH 用 JSON图片操作与注册用 multipart已存人脸裁剪图返回 JPEGMJPEG 是流式响应。系统类端点GET /v1/health公开的 readiness 探活无参数、无需认证。服务完成启动且 SQLitequick_check通过时返回 200curl -sS ${BASE_URL}/v1/health{status:ready,auth_enabled:false,request_id:...}未就绪时返回503 not_ready模型、数据库或搜索索引未就绪。auth_enabled字段只暴露布尔值不会泄露密钥或其哈希。实现见 server/backend/insightface_server/app.py它同时检查进程ready标志与数据库quick_check结果。GET /v1/system运维诊断端点无参数需认证若开启。返回 200包含 OS/CPU/GPU 与 Compute Capability、NVIDIA 驱动、CUDA/cuDNN/ONNX Runtime、实际 Execution Provider、模型摘要、数据库与路径状态、聚合计数、API key 状态、安全配置与并发度、最近的结构化错误摘要永不返回密钥、图片、裁剪图或 embedding。具体字段见 server/backend/insightface_server/app.py。其中safe_config.detection报告不可变的系统检测配置safe_config.max_detected_faces报告安全上限safe_config.inference_max_concurrency报告进程级模型并发预算CPU 默认 4CUDA 默认 8见 server/backend/insightface_server/config.py。Detect、Compare、Embeddings、注册、搜索查询特征提取和 RTSP 识别共享这一预算。系统无运行时修改检测配置的端点Collection 创建时会复制该系统配置作为默认值可被请求覆盖Collection 配置持久化在 SQLite 中、可 PATCH且配置变更后不会自动重提已有 embedding。常见错误401、503 request_timeout。GET /v1/models读取已验证的模型包与实际 Provider无参数需认证。返回 200 与models、execution_provider、已核验的 license 摘要不返回模型字节或私钥。常见错误401。无状态人脸操作POST /v1/detect检测全部可用人脸但不落库。multipart 字段image必填max_faces可选1–100collection_id可选使用该 Collection 的检测配置而非系统配置。服务端流程动态 SCRFD 模型跑所有配置分辨率 → 把所有候选框映射回原图坐标 → 做一次全局 NMS → 按面积降序排序见 server/backend/insightface_server/services/core.py。无人脸是合法成功返回faces: []测试用例见 server/tests/api/test_face_operations.py。curl -sS http://localhost:18097/v1/detect \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -F imagegroup.jpg \ -F max_faces10 \ -F collection_idemployees成功返回 200 与faces、processing_ms、request_id每张人脸含像素/归一化检测框、5 个关键点、检测置信度与质量信号quality.score/sharpness/brightness/pose是文档化的本地质量信号而非 AWS 指标不返回也不持久化 embedding。常见错误400 request_detection_override_not_supported已废弃的min_score参数会触发见 server/backend/insightface_server/app.py、404未知 Collection、413、422 invalid_image、503 request_timeout。POST /v1/compare无持久化地比较两张图中各选出的一个人脸。multipart 字段source与target必填threshold可选0.0..1.0服务端默认0.4collection_id可选检测配置来源。活动配置的单脸策略从每张图选一个人脸任一张无人脸即返回422 face_not_found。实现见 server/backend/insightface_server/app.py通过selected_face()提取特征后调用similarity()计算余弦相似度matched score threshold。curl -sS http://localhost:18097/v1/compare \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -F sourcesource.jpg \ -F targettarget.jpg \ -F threshold0.4成功返回 200 与matched、原始余弦similarity、生效threshold、选中的 source/target 人脸摘要、processing_ms、request_id。常见错误404、413、422 invalid_image或face_not_found、503 request_timeout。POST /v1/embeddings为可信集成提取选中人脸的 embedding。multipart 字段image必填、collection_id可选。该需认证端点刻意不用于常规注册/搜索流程embedding 是敏感生物特征模板不会记入日志。已废弃的face_selection参数会返回400 request_detection_override_not_supported见 server/backend/insightface_server/app.py。curl -sS ${BASE_URL}/v1/embeddings -H ${AUTH_HEADER} \ -F imageportrait.jpg -F collection_idemployees成功返回 200faces中一项含 L2 归一化 embedding、model、processing_ms、request_id。常见错误400、404、413、422、503。CollectionsPOST /v1/collections创建隔离的身份数据库并固定其模型、检测与搜索契约。发送application/json{ id: employees, name: Company Employees, description: Employee face collection, threshold: 0.4, save_face_crops: false, detection: { input_sizes: [[96, 96], [512, 512]], threshold: 0.5, nms_threshold: 0.4, single_face_selection: largest }, search: { profile: fp32_v1, capacity_rows: 100000, max_faces_per_person: 20, load_policy: lazy }, metadata: {site: shanghai} }id为_default或 1–64 字符、以字母或数字开头、只能含字母/数字/./_/-name必填threshold省略时使用INSIGHTFACE_DEFAULT_THRESHOLD。search.profile只接受fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1五种没有隐式 rerank profile推荐的默认 INT8 尺度是 736Collection 整体默认仍是 FP32见 server/backend/insightface_server/config.py。其余默认值容量 100000 行、每 Person 20 个 FaceSample、lazy 加载_default在未指定加载策略时用 eager。解析后的值以search_profile、capacity_rows、max_faces_per_person、load_policy持久化并返回。后端支持矩阵CPU native 后端支持 FP32、BF16、INT8FP16 仅 CUDACUDA 后端支持全部五种 profile。持久化 profile 不被当前后端支持时会显式报错绝不静默转换CUDA BF16 还需 SM80 及以上设备。完整支持矩阵见 server/docs/user-guide.zh-CN.md。创建时绑定 model ID、版本、bundle digest、embedding 维度和预处理版本这些字段不可 PATCH每个 Collection 还会暴露稳定的不透明embedding_contract_id由上述固定字段派生使用可信外部注册时必须原样复制该 ID。detection可选可部分覆盖创建时复制的系统配置。single_face_selection接受largest与center_largest后者的像素空间评分公式为area - 2.0 * ((face_cx - image_cx)^2 (face_cy - image_cy)^2)检测置信度不参与该评分实现见 server/backend/insightface_server/services/core.py。响应返回解析后的detection对象与单调递增的detection_revision。save_face_crops默认取部署的INSIGHTFACE_SAVE_FACE_CROPS默认false解析后的布尔值持久化在 Collection 上不随之后的环境变量变化开启后被接受的 112×112 边界框裁剪图非原始上传图会编码为 JPEG 以 BLOB 存进 SQLite会显著增大数据库与备份体积。裁剪图编码逻辑见 server/backend/insightface_server/storage/crops.py。curl -sS ${BASE_URL}/v1/collections -H ${AUTH_HEADER} \ -H Content-Type: application/json \ -d {id:employees,name:Employees,threshold:0.4}成功返回 201 与解析后的collection含不可变模型绑定、检测配置、搜索设置、计数与时间戳。常见错误400 invalid_detection_profile/unsupported_search_profile/search_capacity_too_large、409 collection_exists、503 search_index_unavailable。GET /v1/collections列出 Collections。查询参数limit1–100默认 50、可选不透明cursor。成功返回 200 与collections、可空next_cursor。常见错误400 invalid_cursor、401。GET /v1/collections/{collection_id}读取单个 Collection返回collection、当前person_count、face_count与embedding_contract_id。在活动模型包不兼容时尝试模型绑定使用会返回409 collection_model_mismatch模型契约校验见 server/backend/insightface_server/services/core.py。常见错误404、409。PATCH /v1/collections/{collection_id}更新可变 Collection 策略。JSON body 可更新name、description、threshold、metadata、save_face_crops影响后续注册已有裁剪不回填也不删除在途注册可能按已读到的旧值完成嵌套search对象可更新capacity_rows、max_faces_per_person、load_policy不兼容的缩减会被拒绝search_profile因需重建索引而不可通过本端点修改嵌套detection对象可更新任意检测字段在途请求保持原不可变快照后续请求看到新版本且不重处理任何已有 FaceSample。未知字段与显式 null 都会被拒绝model_dump(exclude_unsetTrue)语义见 server/backend/insightface_server/app.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}}成功返回 200 与完整更新后的collection。常见错误400、404、409容量不兼容缩减或模型契约、503。DELETE /v1/collections/{collection_id}删除 Collection。查询参数force布尔默认false。空 Collection 直接删除非空返回409 collection_not_empty仅在确实要删除全部 Person 与 FaceSample 时才用forcetrue重试。curl -sS -X DELETE ${BASE_URL}/v1/collections/employees?forcetrue \ -H ${AUTH_HEADER}成功返回 204 无 body。常见错误404、409 collection_not_empty、503。此外注册超过capacity_rows返回409 collection_capacity_exceeded不提交多余 FaceSample超过max_faces_per_person返回409 person_face_limit_exceeded。Person 与 FaceSamplePOST /v1/collections/{collection_id}/persons一次请求创建 Person 并注册一个或多个 FaceSample。multipart 字段images必填、可重复默认最多 20 张见INSIGHTFACE_MAX_REGISTRATION_IMAGESid可选省略时生成 UUIDname、external_id可选metadata可选JSON 对象以 multipart 字符串编码默认{}review_modeoff/standard/strict默认offembedding_modeserver/external_trusted默认serverexternal_embeddings仅external_trusted必填JSON 数组每个images部分恰好一个特征向量embedding_contract_id仅external_trusted必填精确复制当前 Collection 的值。curl -sS http://localhost:18097/v1/collections/employees/persons \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -F idemployee-001 \ -F nameAlice \ -F external_idHR-1001 \ -F metadata{department:sales} \ -F review_modestandard \ -F imagesalice1.jpg \ -F imagesalice2.jpg三种 review 模式核心逻辑见 server/backend/insightface_server/services/core.pyoff使用 Collection 的单脸策略如最大人脸跳过可配置的质量阈值低摩擦注册standard要求恰好一张人脸并应用配置的最小人脸尺寸、检测得分、质量与姿态规则strict先执行standard全部规则再要求候选样本与本人已有样本的最大相似度严格大于与所有其他 Person 的最大相似度相似度用 Collection 固定的搜索 profile 评估平局即拒绝。首个无样本时的合格候选会引导bootstrap该 Person 并跳过相似度比较同一 multipart 请求中后续候选以先前已接受候选为类内参考类内/类外比较与写入在同一 Collection 锁下完成避免审查与提交之间类外最大值变化见_strict_registration_reviewserver/backend/insightface_server/services/core.py。两种 embedding 模式server服务端对齐每个被接受人脸、提取识别特征并做 L2 归一化external_trusted图片仍会解码、检测并走同样的 review 规则但不运行识别模型off模式下可信调用方需断言向量 i 属于图片部分 i 的最大人脸。没有自动回退到服务端提取图片与向量数量必须一致无效或被拒图片对应的向量不会入册。外部向量必须数值有限、非零、维度与 Collection 一致、embedding_contract_id匹配、L2 范数在1.0 ± 0.0002内超差按invalid_external_embedding拒绝该图不静默修复。通过校验的向量会在 FP32 转换后再次归一化以消除浮点漂移再提交 SQLite。strict审查使用该最终外部向量做类内/类外比较。可信调用方必须自己保证向量与配对图片出自声明管线服务端刻意不重新提取特征来证明关联校验实现见_trusted_embeddingserver/backend/insightface_server/services/core.py契约不匹配返回409 embedding_contract_mismatch见 server/backend/insightface_server/app.py。成功响应示例部分成功仍是 HTTP 201{ person: {id: employee-001, face_count: 1}, faces: [{id: a-face-uuid, quality: {score: 0.91}}], rejected_images: [ {index: 1, filename: alice2.jpg, reason: multiple_faces} ], request_id: a-uuid }当前拒绝原因包括invalid_image、image_too_large、face_not_found、multiple_faces、face_too_small、low_detection_score、low_quality、extreme_pose、invalid_embedding、identity_similarity_conflict。strict 相似度拒绝还会报告same_person_similarity、other_person_similarity、other_person_id、matched_face_id。若没有任何图片被接受返回422 registration_failed且不创建 Person。常见错误400非法 ID/metadata 或图片过多、404、409Person/external ID、embedding 契约、容量、每人限额冲突、413、422 registration_failed、503 search_index_unavailable若含write_committed: true勿盲目重试先读 Person。GET /v1/collections/{collection_id}/persons列出或过滤 Person。查询参数limit1–100默认 50、不透明cursor、可选search最长 200 字符匹配 Person ID、name 或 external ID。成功返回 200 与persons、可空next_cursor。常见错误400 invalid_cursor、404。GET /v1/collections/{collection_id}/persons/{person_id}读取单个 Person返回person与当前face_count及时间戳。常见错误404。PATCH /v1/collections/{collection_id}/persons/{person_id}更新 Person 显示数据。JSON body 接受name、external_id与对象metadata未知字段被拒绝metadata不能为 null。curl -sS -X PATCH ${BASE_URL}/v1/collections/employees/persons/alice \ -H ${AUTH_HEADER} -H Content-Type: application/json \ -d {name:Alice Chen,metadata:{department:sales}}成功返回 200 与完整更新后的person。常见错误400、404、409 external_id_exists。DELETE /v1/collections/{collection_id}/persons/{person_id}删除一个 Person 及其全部 FaceSample、embedding 与可选裁剪图。成功返回 204 无 body之后搜索不会返回该 Person。常见错误404、503 search_index_unavailable。POST /v1/collections/{collection_id}/persons/{person_id}/faces为已有 Person 添加 FaceSample。可重复 multipartimagesreview_mode取值/默认/注册规则/部分成功响应与创建 Person 完全一致embedding_mode、external_embeddings、embedding_contract_id语义也完全相同路由实现见 server/backend/insightface_server/app.py。curl -sS ${BASE_URL}/v1/collections/employees/persons/alice/faces \ -H ${AUTH_HEADER} -F review_modestandard \ -F imagesalice-2.jpg -F imagesalice-3.webp成功返回 201 与被接受的faces和rejected_images允许部分成功。常见错误与创建 Person 相同的注册/容量/契约/尺寸/质量/索引错误外加404Person。GET /v1/collections/{collection_id}/persons/{person_id}/faces分页读取 FaceSample 元数据。查询参数limit1–100默认 50、不透明cursor。不返回存储的 embedding 与裁剪图字节每项仅在有存储裁剪时has_crop: true。成功返回 200 与faces、可空next_cursor。常见错误400 invalid_cursor、404。GET /v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}/image下载可选的已存裁剪图用于管理。返回存储的 112×112 边界框裁剪图image/jpeg与普通 API 一样要求 Bearer 认证并带Cache-Control: no-store客户端不应把它当作原图。若 FaceSample 存在但没有存储裁剪返回 not-found 错误而不是合成图片。curl -sS http://localhost:18097/v1/collections/employees/persons/employee-001/faces/face-uuid/image \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -o face-crop.jpg成功返回 200 JPEG该响应无 JSONrequest_id请使用x-request-id响应头。常见错误404FaceSample 或face_image_not_found、401。DELETE /v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}删除一个 FaceSample、embedding 与可选裁剪图。成功返回 204且行在成功前已从活动索引移除。常见错误404、503 search_index_unavailable。人脸与 Person 的成功删除会同步更新活动搜索代generation同一进程内后续搜索不可能返回已删行。搜索POST /v1/collections/{collection_id}/search用查询图中选中的人脸搜索 Collection。multipart 字段image必填limit可选 1–100默认 5threshold可选0.0..1.0默认取 Collection 阈值。Collection profile 选择输入人脸与每个 FaceSample 比较每个 Person 取其最高 FaceSample 得分只返回达到阈值的 Person按得分降序排列。无匹配是matches: []查询图无人脸是422 face_not_found。服务端先检测提特征再调用搜索索引见FaceService.searchserver/backend/insightface_server/services/core.py。curl -sS http://localhost:18097/v1/collections/employees/search \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -F imageunknown.jpg \ -F limit5示例匹配{ person: { id: employee-001, name: Alice, external_id: HR-1001, metadata: {department: sales} }, similarity: 0.8642, matched_face_id: a-face-uuid }成功返回 200 与searched_face、有序matches、生效threshold、processing_ms、request_id。常见错误404、409 collection_model_mismatch、413、422、503 search_index_unavailable或request_timeout。RTSP MonitorsMonitor 是服务端持久化的 RTSP 识别任务配置存在 SQLite启用的 Monitor 在服务重启后自动恢复视频帧永不保存近期事件只存在于有限的内存环形缓冲重启即丢解码器只保留最新帧推理慢时降低实际帧率而不是堆积延迟帧队列。MonitorManager 的参数最大流数、预览 FPS、JPEG 质量、超时与重连延迟来自配置见 server/backend/insightface_server/config.py 与 server/backend/insightface_server/app.py。POST /v1/monitors创建并可选的启动一个持久 Monitor。application/jsonbody{ id: front-gate, name: Front gate, description: Main entrance, enabled: true, source: {type: rtsp, url: rtsp://viewer:secretcamera.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 }source.url只接受rtsp://或rtsps://凭据会在/data下以 AES-GCM 加密存储见 server/backend/insightface_server/storage/secrets.pyAPI 只返回打码后的 source。match_threshold: null表示继承 Collection 阈值event_buffer_size范围 10–10000。Web 预览默认关闭识别与事件收集不依赖任何观看者。curl -sS ${BASE_URL}/v1/monitors -H ${AUTH_HEADER} \ -H Content-Type: application/json -d monitor.json成功返回 201 与monitor、打码 source、生效默认值与运行摘要。常见错误400 invalid_request、404Collection、409 monitor_exists、429 monitor_limit_exceeded超过INSIGHTFACE_RTSP_MAX_STREAMS默认 4见 server/backend/insightface_server/app.py。GET /v1/monitors列出持久 Monitor 配置与紧凑运行摘要。查询limit1–100默认 50cursor是next_cursor返回的不透明值客户端不得解析或修改。成功返回 200 与有序monitors、可空next_cursor。常见错误400 invalid_cursor、401。GET /v1/monitors/{monitor_id}读取一个持久 Monitor 配置与最新运行摘要。返回的 RTSP URL 会省略用户信息与查询参数。成功返回 200 与monitor含event_policy、preview_enabled、时间戳、runtime。常见错误404 monitor_not_found、401。PATCH /v1/monitors/{monitor_id}部分更新 Monitor其id不可变。body 可提交创建时的任意可变字段event_policy本身也是部分更新轮换 RTSP URL 或凭据时才发送新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}}改变 source、Collection、频率、阈值或事件策略会重启该 Monitor 任务enabled设为false/true可停止/启动name、description、preview 与 buffer 大小的改动无需重启。成功返回 200 与完整更新后的monitor。常见错误400、404、429 monitor_limit_exceeded。DELETE /v1/monitors/{monitor_id}永久移除 Monitor 配置停止其解码与推理线程、释放 RTSP 连接、丢弃内存状态与事件不删除其 Collection。成功返回 204 无 body。常见错误404 monitor_not_found、401。GET /v1/monitors/{monitor_id}/state供无界面客户端或 Web UI 轮询实时状态。结果字段status、connected、源尺寸/FPS、配置与实际推理帧率、处理耗时、跳帧数、当前已识别与未知人脸、预览观看者数、重连计数与最近安全错误从不包含embedding 与源凭据。已禁用 Monitor 通常报告stopped。常见错误404、401。GET /v1/monitors/{monitor_id}/events无需长连接即可拉取最近的进入、离开、错误与恢复事件。查询limit1–1000默认 100下次轮询传入上次的next_cursor。游标是含内部流纪元与序号的不透明签名串。首次无游标调用返回最新的最多limit条事件后续调用返回更晚的事件。truncated: true表示客户端落后于有界环形缓冲stream_reset: true表示任务已重启、旧游标属于另一纪元。事件不持久进程重启即丢失。curl -sS ${BASE_URL}/v1/monitors/front-gate/events?limit100 \ -H ${AUTH_HEADER}成功返回 200 与events、next_cursor、has_more、truncated、stream_reset。常见错误400 invalid_cursor、404、401。GET /v1/monitors/{monitor_id}/preview.mjpeg打开可选的原始 MJPEG 预览。认证方式与其他 API 相同Bearer 头绝不要把 API key 放进 URL。端点返回未标注的multipart/x-mixed-replaceJPEG 帧流客户端用/state绘制框与标签。JPEG 编码只在preview_enabled为 true 且至少一个观看者连接时惰性执行关闭预览不会停止识别传输中断后客户端应以有界退避重连。curl -sS ${BASE_URL}/v1/monitors/front-gate/preview.mjpeg -H ${AUTH_HEADER}成功是 200 长连接二进制流非 JSON。常见错误409 preview_disabled、503 stream_unavailable、404 monitor_not_found、401。参考资源交互式 schema运行中的/openapi.json与/docs由 server/backend/insightface_server/app.py 的自定义 OpenAPI 生成自动为除 health 外的所有/v1路由注入 Bearer 安全方案。服务端入口与全部路由实现server/backend/insightface_server/app.py业务核心检测、注册审查、搜索、删除同步server/backend/insightface_server/services/core.py启动配置与全部INSIGHTFACE_*环境变量server/backend/insightface_server/config.py启动期 TOML 配置示例server/config/server.toml。API 契约测试server/tests/api/test_face_operations.py、server/tests/api/test_rtsp_streams.py、server/tests/api/test_external_trusted.py单元测试server/tests/unit/test_config_search.py、server/tests/unit/test_multires_scrfd.py。部署与使用server/docs/user-guide.zh-CN.md、server/README.zh-CN.md、server/deploy/compose.cpu.yml。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 InsightFace Server REST API 完全指南：检测、注册、搜索与 RTSP 监控
InsightFace Server REST API 完全指南检测、注册、搜索与 RTSP 监控【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface本文是 InsightFace ServerInsightFace 人脸分析项目的自托管服务端公开 REST API 的完整使用指南覆盖/v1下全部公共路由的用途、输入参数、服务端工作流程、成功响应与错误语义。读完本文你将能够用 curl 完成「健康检查 → 创建 Collection → 注册 Person → 人脸搜索」的完整闭环掌握review_mode、embedding_mode、search.profile等关键配置的底层原理并上手 RTSP 实时识别 Monitor 的创建与事件消费。原文为西班牙语版 server/docs/api.es.md本文依据该文档并结合 server/docs/api.md英文权威版与仓库源码整理成中文安装与首次启动请参阅 server/docs/user-guide.zh-CN.md运行中的精确接口 schema 可通过/openapi.json或同源交互式查看器/docs获取。通用规则路由、编码与认证API 根路径为/v1JSON 字段采用snake_case图片以multipart/form-data形式上传支持 JPEG、PNG、WebP推理前会应用 EXIF 方向信息。仓库自带的 Compose 文件默认关闭认证以支持隔离评估。开启认证后INSIGHTFACE_AUTH_ENABLEDtrue除GET /v1/health外的所有端点都要求Authorization: Bearer api_key认证关闭时请完全省略该请求头不要发送空 header。认证实现见 server/backend/insightface_server/api/auth.pyApiKeyAuthenticator在启动时将INSIGHTFACE_API_KEY同步进存储sync_api_key若开启认证却没有任何 API key 会直接拒绝启动每次请求通过require()校验 Bearer 头并调用repository.verify_api_key()。所有响应都带x-request-idUUID 响应头JSON 响应体会在request_id字段重复它。成功的 DELETE 请求返回 204 且无响应体。分数与阈值语义confidence/quality/threshold的取值范围是0..1。其中similarity不是概率而是原始余弦相似度[-1, 1]识别阈值默认0.4且为闭区间判定similarity threshold即视为匹配。服务端的相似度计算实现见 server/backend/insightface_server/services/core.py即对两个 L2 归一化向量的内积做np.clip(..., -1.0, 1.0)。检测框同时返回像素坐标与归一化坐标两种形式{ pixels: {x: 120, y: 80, width: 240, height: 280}, normalized: {left: 0.12, top: 0.08, width: 0.24, height: 0.28} }默认的图片体积限制压缩图 10 MiB、解码后 4000 万像素、整个请求 64 MiB对应 server/backend/insightface_server/config.py 中的INSIGHTFACE_MAX_IMAGE_BYTES、INSIGHTFACE_MAX_IMAGE_PIXELS、INSIGHTFACE_MAX_REQUEST_BYTES。错误语义与分页错误使用标准 HTTP 状态码 统一信封{ 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 限流、503 超时/模型或索引不可用。中间件对请求体大小、请求超时与错误信封的统一处理见 server/backend/insightface_server/app.py。分页方面cursor是不透明令牌只能原样复用于同一端点、同一 Collection、同一 Person 及相同过滤条件客户端不得解析或构造它。服务端使用CursorCodec见 server/backend/insightface_server/storage/pagination.py对游标签名编码并将作用域如persons:{collection}:{search}绑定进游标因此跨作用域使用会返回400 invalid_cursor。第一个 API 工作流BASE_URLhttp://127.0.0.1:18097 AUTH_HEADERAuthorization: Bearer ${INSIGHTFACE_API_KEY} curl -fsS ${BASE_URL}/v1/health创建 Collection → 注册 Person → 用另一张图搜索curl -sS ${BASE_URL}/v1/collections -H ${AUTH_HEADER} \ -H Content-Type: application/json \ -d {id:employees,name:Employees,threshold:0.4} curl -sS ${BASE_URL}/v1/collections/employees/persons -H ${AUTH_HEADER} \ -F idalice -F nameAlice -F review_modeoff \ -F imagesalice-enroll.jpg curl -sS ${BASE_URL}/v1/collections/employees/search -H ${AUTH_HEADER} \ -F imagealice-query.jpg -F limit5客户端规则与重试安全客户端超时时间要大于服务端配置的请求超时时间默认 60 秒见INSIGHTFACE_REQUEST_TIMEOUT_SECONDS。把x-request-id当作关联 ID 记入日志但不要记录图片、embedding、RTSP 凭据和 API key。GET 可安全重试DELETE 重试前先确认当前状态网络不确定导致 Person/FaceSample 创建结果不明时不要盲目重试 POST先查询客户端提供的资源 ID。若 503 响应携带write_committed: true说明写入可能已提交同样应先读再重试见 server/backend/insightface_server/services/core.py 的_search_unavailable。仅429与瞬时503可用有上限的指数退避 jitter 重试4xx校验错误必须修改请求。内容类型敏感Collection/Person 的 PATCH 用 JSON图片操作与注册用 multipart已存人脸裁剪图返回 JPEGMJPEG 是流式响应。系统类端点GET /v1/health公开的 readiness 探活无参数、无需认证。服务完成启动且 SQLitequick_check通过时返回 200curl -sS ${BASE_URL}/v1/health{status:ready,auth_enabled:false,request_id:...}未就绪时返回503 not_ready模型、数据库或搜索索引未就绪。auth_enabled字段只暴露布尔值不会泄露密钥或其哈希。实现见 server/backend/insightface_server/app.py它同时检查进程ready标志与数据库quick_check结果。GET /v1/system运维诊断端点无参数需认证若开启。返回 200包含 OS/CPU/GPU 与 Compute Capability、NVIDIA 驱动、CUDA/cuDNN/ONNX Runtime、实际 Execution Provider、模型摘要、数据库与路径状态、聚合计数、API key 状态、安全配置与并发度、最近的结构化错误摘要永不返回密钥、图片、裁剪图或 embedding。具体字段见 server/backend/insightface_server/app.py。其中safe_config.detection报告不可变的系统检测配置safe_config.max_detected_faces报告安全上限safe_config.inference_max_concurrency报告进程级模型并发预算CPU 默认 4CUDA 默认 8见 server/backend/insightface_server/config.py。Detect、Compare、Embeddings、注册、搜索查询特征提取和 RTSP 识别共享这一预算。系统无运行时修改检测配置的端点Collection 创建时会复制该系统配置作为默认值可被请求覆盖Collection 配置持久化在 SQLite 中、可 PATCH且配置变更后不会自动重提已有 embedding。常见错误401、503 request_timeout。GET /v1/models读取已验证的模型包与实际 Provider无参数需认证。返回 200 与models、execution_provider、已核验的 license 摘要不返回模型字节或私钥。常见错误401。无状态人脸操作POST /v1/detect检测全部可用人脸但不落库。multipart 字段image必填max_faces可选1–100collection_id可选使用该 Collection 的检测配置而非系统配置。服务端流程动态 SCRFD 模型跑所有配置分辨率 → 把所有候选框映射回原图坐标 → 做一次全局 NMS → 按面积降序排序见 server/backend/insightface_server/services/core.py。无人脸是合法成功返回faces: []测试用例见 server/tests/api/test_face_operations.py。curl -sS http://localhost:18097/v1/detect \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -F imagegroup.jpg \ -F max_faces10 \ -F collection_idemployees成功返回 200 与faces、processing_ms、request_id每张人脸含像素/归一化检测框、5 个关键点、检测置信度与质量信号quality.score/sharpness/brightness/pose是文档化的本地质量信号而非 AWS 指标不返回也不持久化 embedding。常见错误400 request_detection_override_not_supported已废弃的min_score参数会触发见 server/backend/insightface_server/app.py、404未知 Collection、413、422 invalid_image、503 request_timeout。POST /v1/compare无持久化地比较两张图中各选出的一个人脸。multipart 字段source与target必填threshold可选0.0..1.0服务端默认0.4collection_id可选检测配置来源。活动配置的单脸策略从每张图选一个人脸任一张无人脸即返回422 face_not_found。实现见 server/backend/insightface_server/app.py通过selected_face()提取特征后调用similarity()计算余弦相似度matched score threshold。curl -sS http://localhost:18097/v1/compare \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -F sourcesource.jpg \ -F targettarget.jpg \ -F threshold0.4成功返回 200 与matched、原始余弦similarity、生效threshold、选中的 source/target 人脸摘要、processing_ms、request_id。常见错误404、413、422 invalid_image或face_not_found、503 request_timeout。POST /v1/embeddings为可信集成提取选中人脸的 embedding。multipart 字段image必填、collection_id可选。该需认证端点刻意不用于常规注册/搜索流程embedding 是敏感生物特征模板不会记入日志。已废弃的face_selection参数会返回400 request_detection_override_not_supported见 server/backend/insightface_server/app.py。curl -sS ${BASE_URL}/v1/embeddings -H ${AUTH_HEADER} \ -F imageportrait.jpg -F collection_idemployees成功返回 200faces中一项含 L2 归一化 embedding、model、processing_ms、request_id。常见错误400、404、413、422、503。CollectionsPOST /v1/collections创建隔离的身份数据库并固定其模型、检测与搜索契约。发送application/json{ id: employees, name: Company Employees, description: Employee face collection, threshold: 0.4, save_face_crops: false, detection: { input_sizes: [[96, 96], [512, 512]], threshold: 0.5, nms_threshold: 0.4, single_face_selection: largest }, search: { profile: fp32_v1, capacity_rows: 100000, max_faces_per_person: 20, load_policy: lazy }, metadata: {site: shanghai} }id为_default或 1–64 字符、以字母或数字开头、只能含字母/数字/./_/-name必填threshold省略时使用INSIGHTFACE_DEFAULT_THRESHOLD。search.profile只接受fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1五种没有隐式 rerank profile推荐的默认 INT8 尺度是 736Collection 整体默认仍是 FP32见 server/backend/insightface_server/config.py。其余默认值容量 100000 行、每 Person 20 个 FaceSample、lazy 加载_default在未指定加载策略时用 eager。解析后的值以search_profile、capacity_rows、max_faces_per_person、load_policy持久化并返回。后端支持矩阵CPU native 后端支持 FP32、BF16、INT8FP16 仅 CUDACUDA 后端支持全部五种 profile。持久化 profile 不被当前后端支持时会显式报错绝不静默转换CUDA BF16 还需 SM80 及以上设备。完整支持矩阵见 server/docs/user-guide.zh-CN.md。创建时绑定 model ID、版本、bundle digest、embedding 维度和预处理版本这些字段不可 PATCH每个 Collection 还会暴露稳定的不透明embedding_contract_id由上述固定字段派生使用可信外部注册时必须原样复制该 ID。detection可选可部分覆盖创建时复制的系统配置。single_face_selection接受largest与center_largest后者的像素空间评分公式为area - 2.0 * ((face_cx - image_cx)^2 (face_cy - image_cy)^2)检测置信度不参与该评分实现见 server/backend/insightface_server/services/core.py。响应返回解析后的detection对象与单调递增的detection_revision。save_face_crops默认取部署的INSIGHTFACE_SAVE_FACE_CROPS默认false解析后的布尔值持久化在 Collection 上不随之后的环境变量变化开启后被接受的 112×112 边界框裁剪图非原始上传图会编码为 JPEG 以 BLOB 存进 SQLite会显著增大数据库与备份体积。裁剪图编码逻辑见 server/backend/insightface_server/storage/crops.py。curl -sS ${BASE_URL}/v1/collections -H ${AUTH_HEADER} \ -H Content-Type: application/json \ -d {id:employees,name:Employees,threshold:0.4}成功返回 201 与解析后的collection含不可变模型绑定、检测配置、搜索设置、计数与时间戳。常见错误400 invalid_detection_profile/unsupported_search_profile/search_capacity_too_large、409 collection_exists、503 search_index_unavailable。GET /v1/collections列出 Collections。查询参数limit1–100默认 50、可选不透明cursor。成功返回 200 与collections、可空next_cursor。常见错误400 invalid_cursor、401。GET /v1/collections/{collection_id}读取单个 Collection返回collection、当前person_count、face_count与embedding_contract_id。在活动模型包不兼容时尝试模型绑定使用会返回409 collection_model_mismatch模型契约校验见 server/backend/insightface_server/services/core.py。常见错误404、409。PATCH /v1/collections/{collection_id}更新可变 Collection 策略。JSON body 可更新name、description、threshold、metadata、save_face_crops影响后续注册已有裁剪不回填也不删除在途注册可能按已读到的旧值完成嵌套search对象可更新capacity_rows、max_faces_per_person、load_policy不兼容的缩减会被拒绝search_profile因需重建索引而不可通过本端点修改嵌套detection对象可更新任意检测字段在途请求保持原不可变快照后续请求看到新版本且不重处理任何已有 FaceSample。未知字段与显式 null 都会被拒绝model_dump(exclude_unsetTrue)语义见 server/backend/insightface_server/app.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}}成功返回 200 与完整更新后的collection。常见错误400、404、409容量不兼容缩减或模型契约、503。DELETE /v1/collections/{collection_id}删除 Collection。查询参数force布尔默认false。空 Collection 直接删除非空返回409 collection_not_empty仅在确实要删除全部 Person 与 FaceSample 时才用forcetrue重试。curl -sS -X DELETE ${BASE_URL}/v1/collections/employees?forcetrue \ -H ${AUTH_HEADER}成功返回 204 无 body。常见错误404、409 collection_not_empty、503。此外注册超过capacity_rows返回409 collection_capacity_exceeded不提交多余 FaceSample超过max_faces_per_person返回409 person_face_limit_exceeded。Person 与 FaceSamplePOST /v1/collections/{collection_id}/persons一次请求创建 Person 并注册一个或多个 FaceSample。multipart 字段images必填、可重复默认最多 20 张见INSIGHTFACE_MAX_REGISTRATION_IMAGESid可选省略时生成 UUIDname、external_id可选metadata可选JSON 对象以 multipart 字符串编码默认{}review_modeoff/standard/strict默认offembedding_modeserver/external_trusted默认serverexternal_embeddings仅external_trusted必填JSON 数组每个images部分恰好一个特征向量embedding_contract_id仅external_trusted必填精确复制当前 Collection 的值。curl -sS http://localhost:18097/v1/collections/employees/persons \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -F idemployee-001 \ -F nameAlice \ -F external_idHR-1001 \ -F metadata{department:sales} \ -F review_modestandard \ -F imagesalice1.jpg \ -F imagesalice2.jpg三种 review 模式核心逻辑见 server/backend/insightface_server/services/core.pyoff使用 Collection 的单脸策略如最大人脸跳过可配置的质量阈值低摩擦注册standard要求恰好一张人脸并应用配置的最小人脸尺寸、检测得分、质量与姿态规则strict先执行standard全部规则再要求候选样本与本人已有样本的最大相似度严格大于与所有其他 Person 的最大相似度相似度用 Collection 固定的搜索 profile 评估平局即拒绝。首个无样本时的合格候选会引导bootstrap该 Person 并跳过相似度比较同一 multipart 请求中后续候选以先前已接受候选为类内参考类内/类外比较与写入在同一 Collection 锁下完成避免审查与提交之间类外最大值变化见_strict_registration_reviewserver/backend/insightface_server/services/core.py。两种 embedding 模式server服务端对齐每个被接受人脸、提取识别特征并做 L2 归一化external_trusted图片仍会解码、检测并走同样的 review 规则但不运行识别模型off模式下可信调用方需断言向量 i 属于图片部分 i 的最大人脸。没有自动回退到服务端提取图片与向量数量必须一致无效或被拒图片对应的向量不会入册。外部向量必须数值有限、非零、维度与 Collection 一致、embedding_contract_id匹配、L2 范数在1.0 ± 0.0002内超差按invalid_external_embedding拒绝该图不静默修复。通过校验的向量会在 FP32 转换后再次归一化以消除浮点漂移再提交 SQLite。strict审查使用该最终外部向量做类内/类外比较。可信调用方必须自己保证向量与配对图片出自声明管线服务端刻意不重新提取特征来证明关联校验实现见_trusted_embeddingserver/backend/insightface_server/services/core.py契约不匹配返回409 embedding_contract_mismatch见 server/backend/insightface_server/app.py。成功响应示例部分成功仍是 HTTP 201{ person: {id: employee-001, face_count: 1}, faces: [{id: a-face-uuid, quality: {score: 0.91}}], rejected_images: [ {index: 1, filename: alice2.jpg, reason: multiple_faces} ], request_id: a-uuid }当前拒绝原因包括invalid_image、image_too_large、face_not_found、multiple_faces、face_too_small、low_detection_score、low_quality、extreme_pose、invalid_embedding、identity_similarity_conflict。strict 相似度拒绝还会报告same_person_similarity、other_person_similarity、other_person_id、matched_face_id。若没有任何图片被接受返回422 registration_failed且不创建 Person。常见错误400非法 ID/metadata 或图片过多、404、409Person/external ID、embedding 契约、容量、每人限额冲突、413、422 registration_failed、503 search_index_unavailable若含write_committed: true勿盲目重试先读 Person。GET /v1/collections/{collection_id}/persons列出或过滤 Person。查询参数limit1–100默认 50、不透明cursor、可选search最长 200 字符匹配 Person ID、name 或 external ID。成功返回 200 与persons、可空next_cursor。常见错误400 invalid_cursor、404。GET /v1/collections/{collection_id}/persons/{person_id}读取单个 Person返回person与当前face_count及时间戳。常见错误404。PATCH /v1/collections/{collection_id}/persons/{person_id}更新 Person 显示数据。JSON body 接受name、external_id与对象metadata未知字段被拒绝metadata不能为 null。curl -sS -X PATCH ${BASE_URL}/v1/collections/employees/persons/alice \ -H ${AUTH_HEADER} -H Content-Type: application/json \ -d {name:Alice Chen,metadata:{department:sales}}成功返回 200 与完整更新后的person。常见错误400、404、409 external_id_exists。DELETE /v1/collections/{collection_id}/persons/{person_id}删除一个 Person 及其全部 FaceSample、embedding 与可选裁剪图。成功返回 204 无 body之后搜索不会返回该 Person。常见错误404、503 search_index_unavailable。POST /v1/collections/{collection_id}/persons/{person_id}/faces为已有 Person 添加 FaceSample。可重复 multipartimagesreview_mode取值/默认/注册规则/部分成功响应与创建 Person 完全一致embedding_mode、external_embeddings、embedding_contract_id语义也完全相同路由实现见 server/backend/insightface_server/app.py。curl -sS ${BASE_URL}/v1/collections/employees/persons/alice/faces \ -H ${AUTH_HEADER} -F review_modestandard \ -F imagesalice-2.jpg -F imagesalice-3.webp成功返回 201 与被接受的faces和rejected_images允许部分成功。常见错误与创建 Person 相同的注册/容量/契约/尺寸/质量/索引错误外加404Person。GET /v1/collections/{collection_id}/persons/{person_id}/faces分页读取 FaceSample 元数据。查询参数limit1–100默认 50、不透明cursor。不返回存储的 embedding 与裁剪图字节每项仅在有存储裁剪时has_crop: true。成功返回 200 与faces、可空next_cursor。常见错误400 invalid_cursor、404。GET /v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}/image下载可选的已存裁剪图用于管理。返回存储的 112×112 边界框裁剪图image/jpeg与普通 API 一样要求 Bearer 认证并带Cache-Control: no-store客户端不应把它当作原图。若 FaceSample 存在但没有存储裁剪返回 not-found 错误而不是合成图片。curl -sS http://localhost:18097/v1/collections/employees/persons/employee-001/faces/face-uuid/image \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -o face-crop.jpg成功返回 200 JPEG该响应无 JSONrequest_id请使用x-request-id响应头。常见错误404FaceSample 或face_image_not_found、401。DELETE /v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}删除一个 FaceSample、embedding 与可选裁剪图。成功返回 204且行在成功前已从活动索引移除。常见错误404、503 search_index_unavailable。人脸与 Person 的成功删除会同步更新活动搜索代generation同一进程内后续搜索不可能返回已删行。搜索POST /v1/collections/{collection_id}/search用查询图中选中的人脸搜索 Collection。multipart 字段image必填limit可选 1–100默认 5threshold可选0.0..1.0默认取 Collection 阈值。Collection profile 选择输入人脸与每个 FaceSample 比较每个 Person 取其最高 FaceSample 得分只返回达到阈值的 Person按得分降序排列。无匹配是matches: []查询图无人脸是422 face_not_found。服务端先检测提特征再调用搜索索引见FaceService.searchserver/backend/insightface_server/services/core.py。curl -sS http://localhost:18097/v1/collections/employees/search \ -H Authorization: Bearer ${INSIGHTFACE_API_KEY} \ -F imageunknown.jpg \ -F limit5示例匹配{ person: { id: employee-001, name: Alice, external_id: HR-1001, metadata: {department: sales} }, similarity: 0.8642, matched_face_id: a-face-uuid }成功返回 200 与searched_face、有序matches、生效threshold、processing_ms、request_id。常见错误404、409 collection_model_mismatch、413、422、503 search_index_unavailable或request_timeout。RTSP MonitorsMonitor 是服务端持久化的 RTSP 识别任务配置存在 SQLite启用的 Monitor 在服务重启后自动恢复视频帧永不保存近期事件只存在于有限的内存环形缓冲重启即丢解码器只保留最新帧推理慢时降低实际帧率而不是堆积延迟帧队列。MonitorManager 的参数最大流数、预览 FPS、JPEG 质量、超时与重连延迟来自配置见 server/backend/insightface_server/config.py 与 server/backend/insightface_server/app.py。POST /v1/monitors创建并可选的启动一个持久 Monitor。application/jsonbody{ id: front-gate, name: Front gate, description: Main entrance, enabled: true, source: {type: rtsp, url: rtsp://viewer:secretcamera.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 }source.url只接受rtsp://或rtsps://凭据会在/data下以 AES-GCM 加密存储见 server/backend/insightface_server/storage/secrets.pyAPI 只返回打码后的 source。match_threshold: null表示继承 Collection 阈值event_buffer_size范围 10–10000。Web 预览默认关闭识别与事件收集不依赖任何观看者。curl -sS ${BASE_URL}/v1/monitors -H ${AUTH_HEADER} \ -H Content-Type: application/json -d monitor.json成功返回 201 与monitor、打码 source、生效默认值与运行摘要。常见错误400 invalid_request、404Collection、409 monitor_exists、429 monitor_limit_exceeded超过INSIGHTFACE_RTSP_MAX_STREAMS默认 4见 server/backend/insightface_server/app.py。GET /v1/monitors列出持久 Monitor 配置与紧凑运行摘要。查询limit1–100默认 50cursor是next_cursor返回的不透明值客户端不得解析或修改。成功返回 200 与有序monitors、可空next_cursor。常见错误400 invalid_cursor、401。GET /v1/monitors/{monitor_id}读取一个持久 Monitor 配置与最新运行摘要。返回的 RTSP URL 会省略用户信息与查询参数。成功返回 200 与monitor含event_policy、preview_enabled、时间戳、runtime。常见错误404 monitor_not_found、401。PATCH /v1/monitors/{monitor_id}部分更新 Monitor其id不可变。body 可提交创建时的任意可变字段event_policy本身也是部分更新轮换 RTSP URL 或凭据时才发送新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}}改变 source、Collection、频率、阈值或事件策略会重启该 Monitor 任务enabled设为false/true可停止/启动name、description、preview 与 buffer 大小的改动无需重启。成功返回 200 与完整更新后的monitor。常见错误400、404、429 monitor_limit_exceeded。DELETE /v1/monitors/{monitor_id}永久移除 Monitor 配置停止其解码与推理线程、释放 RTSP 连接、丢弃内存状态与事件不删除其 Collection。成功返回 204 无 body。常见错误404 monitor_not_found、401。GET /v1/monitors/{monitor_id}/state供无界面客户端或 Web UI 轮询实时状态。结果字段status、connected、源尺寸/FPS、配置与实际推理帧率、处理耗时、跳帧数、当前已识别与未知人脸、预览观看者数、重连计数与最近安全错误从不包含embedding 与源凭据。已禁用 Monitor 通常报告stopped。常见错误404、401。GET /v1/monitors/{monitor_id}/events无需长连接即可拉取最近的进入、离开、错误与恢复事件。查询limit1–1000默认 100下次轮询传入上次的next_cursor。游标是含内部流纪元与序号的不透明签名串。首次无游标调用返回最新的最多limit条事件后续调用返回更晚的事件。truncated: true表示客户端落后于有界环形缓冲stream_reset: true表示任务已重启、旧游标属于另一纪元。事件不持久进程重启即丢失。curl -sS ${BASE_URL}/v1/monitors/front-gate/events?limit100 \ -H ${AUTH_HEADER}成功返回 200 与events、next_cursor、has_more、truncated、stream_reset。常见错误400 invalid_cursor、404、401。GET /v1/monitors/{monitor_id}/preview.mjpeg打开可选的原始 MJPEG 预览。认证方式与其他 API 相同Bearer 头绝不要把 API key 放进 URL。端点返回未标注的multipart/x-mixed-replaceJPEG 帧流客户端用/state绘制框与标签。JPEG 编码只在preview_enabled为 true 且至少一个观看者连接时惰性执行关闭预览不会停止识别传输中断后客户端应以有界退避重连。curl -sS ${BASE_URL}/v1/monitors/front-gate/preview.mjpeg -H ${AUTH_HEADER}成功是 200 长连接二进制流非 JSON。常见错误409 preview_disabled、503 stream_unavailable、404 monitor_not_found、401。参考资源交互式 schema运行中的/openapi.json与/docs由 server/backend/insightface_server/app.py 的自定义 OpenAPI 生成自动为除 health 外的所有/v1路由注入 Bearer 安全方案。服务端入口与全部路由实现server/backend/insightface_server/app.py业务核心检测、注册审查、搜索、删除同步server/backend/insightface_server/services/core.py启动配置与全部INSIGHTFACE_*环境变量server/backend/insightface_server/config.py启动期 TOML 配置示例server/config/server.toml。API 契约测试server/tests/api/test_face_operations.py、server/tests/api/test_rtsp_streams.py、server/tests/api/test_external_trusted.py单元测试server/tests/unit/test_config_search.py、server/tests/unit/test_multires_scrfd.py。部署与使用server/docs/user-guide.zh-CN.md、server/README.zh-CN.md、server/deploy/compose.cpu.yml。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考