InsightFace Server 的精确搜索 profile（fp32_v1、int8_x736_v1 等）怎么选？

InsightFace Server 的精确搜索 profile（fp32_v1、int8_x736_v1 等）怎么选？

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface

在 InsightFace Server 里创建 Collection 时，search.profile必须指定精确搜索的向量存储与计算方式：fp32_v1、fp16_v1、bf16_v1、int8_x736_v1或int8_x1000_v1。这个选择在创建时就固定下来，之后不能通过PATCH /v1/collections/{collection_id}修改（search_profile在该端点不可变，改动它需要重建索引），所以选错了基本等于要重建这个库。本文基于 server/README.md、server/docs/user-guide.md 和 server/docs/api.md，给出五个 profile 的可用范围、选型依据，以及创建、验证的完整操作路径。

五个 profile 与硬件可用范围

几个直接影响选型的边界：

• FP16 是 CUDA 专属，CPU 部署不能选fp16_v1；CUDA BF16 额外要求 SM80 或更新架构的设备。
• 后端不支持的 profile 在创建/加载 Collection 时会被显式拒绝，不会静默转换为其他 profile 或其他执行 provider。
• 所有 profile 都是 flat 精确搜索：对每个存活的 FaceSample 全量打分，不做 ANN 候选筛选。“精确”描述的是候选覆盖，低精度 profile 的分数是对 FP32 的近似。
• INT8 的打分内部用 INT32 累加，int8_x736_v1与int8_x1000_v1的区别是编码 scale S 为 736 或 1000（编码在 profile 名里）。对外返回的相似度与阈值始终是原始 cosine（0.0..1.0，默认0.4）。

先确认当前环境支持哪些 profile

System 响应只公布当前 CPU/GPU 上实际可用的 profile，这是选型的第一步：

curl -fsS http://127.0.0.1:18097/v1/health

CPU 镜像用18097端口，CUDA 12 镜像用18098；开启认证时按 API 文档带上认证头。也可以打开 Web UI 的System页面查看。以这里公布的能力为准，而不是直接抄上表的“典型可用范围”——上表是文档给出的典型值，实际以本机能力掩码为准。

怎么选：容量、速度与精度三个依据

精度代价。项目用 ICCV21-MFR 的多种族（MR）测试集，在 FAR1e-6的 MR-ALL 全对 1:1 协议下评测了各 profile。所有 profile 使用同一批通过 Server API 提取的 L2 归一化 512 维buffalo_l特征，只改变存储向量与搜索计算表示：

按挑战常用的两位小数报告精度，FP32 和 INT8 都是91.25% MR-ALL，未取整差异仅 0.0011 个百分点。也就是说 INT8 在这个基准上没有实质精度损失。注意这个对比测的是向量存储/搜索精度，不是 INT8 模型推理。

容量与速度。在单张 NVIDIA GeForce RTX 5090（32,607 MiB）上，原生 CUDA 精确 flat 索引的实测上限（GPU 独占测量，Driver 580.105.08，CUDA 12.9）：

INT8 相对 FP32 是 3.73 倍容量、3.35 倍 10M Top-5 吞吐。速度测试口径是恰好 10M 图像向量、GPU 常驻全量 Top-5、单查询在飞、10 次预热、100 次测量。

内存预算。512 维向量每行纯向量字节数：FP32 2,048 字节，FP16/BF16 1,024 字节，INT8 512 字节；ID、工作区、分配器开销另算。capacity_rows默认100000，部署护栏上限默认10000000；它既是初始预留也是该 Collection 的存活行上限，文档明确要求“按真实内存预算设置 capacity”。

据此，文档支撑的选择路径是：

• GPU 上追求最大容量和最低延迟：选int8_x736_v1（官方标注 recommended INT8）。
• 需要 FP16 的存储/计算表示且跑 CUDA：fp16_v1，容量和吞吐与 BF16 同级，但不支持 CPU。
• CPU 部署或需要最高精度基线：fp32_v1（也是整体默认）；支持的 CPU 上还有bf16_v1。
• int8_x1000_v1文档只标注为 compatibility contract，没有给出独立的性能或精度数据；除非有既有兼容需求，新库没有理由选它替代int8_x736_v1。

创建 Collection 时指定 profile

Web UI 路径：打开Collections→New collection，在 “a search profile supported by the current host” 一项里选择 profile，同时设置阈值（默认0.4）、capacity 与max_faces_per_person（默认 20）。

API 路径，POST /v1/collections：

curl -sS "${BASE_URL}/v1/collections" -H "${AUTH_HEADER}" \ -H 'Content-Type: application/json' \ -d '{ "id": "employees", "name": "Employees", "threshold": 0.4, "search": { "profile": "int8_x736_v1", "capacity_rows": 100000, "max_faces_per_person": 20, "load_policy": "lazy" } }'

• BASE_URL是服务地址（CPU 为http://127.0.0.1:18097，CUDA 为http://127.0.0.1:18098）；AUTH_HEADER在开启认证时按 server/docs/api.md 的要求填写，未开启认证时可省略。
• profile只能是五个合法值之一；capacity 超过部署上限会得到400 search_capacity_too_large，profile 不被当前后端支持会得到400 unsupported_search_profile，库已存在是409 collection_exists，索引不可用是503 search_index_unavailable。
• load_policy缺省为 lazy；_default这个特殊 Collection 在未提供 load policy 时用 eager。

Python SDK 等价调用：

from insightface_server import Client client = Client("http://localhost:18097", api_key="your-key") client.create_collection( collection_id="employees", name="Employees", threshold=0.4, search_profile="int8_x736_v1", )

验证选择是否生效

1. 创建成功返回 HTTP 201，响应里的collection包含解析后的search_profile、capacity_rows、max_faces_per_person和load_policy——这四个字段是持久化值，与请求一致即说明 profile 已固定。
2. GET /v1/collections/{collection_id}同样返回完整collection，可随时核对search_profile没被意外改动。
3. 走一遍搜索验证功能：注册至少一张清晰人脸照片的 Person，用该 Person 的另一张照片在Search（或 SDK 的client.search(collection, query, limit=5)）中检索，按相似度排序、Person 得分取其所有 FaceSamples 的最高分；查无结果是空列表，属于成功而不是故障。

限制与注意事项

• 换 profile 只能新建 Collection：search_profile通过 PATCH 端点不可改，文档说明改动它需要 index rebuild。
• 上表的容量/QPS 数据是同一张 RTX 5090 的 GPU 独占测量，未加载 ONNX 模型和 Server 负载；README 明确提示生产部署还要为模型、请求、并发、索引重建和分配器余量预留显存。
• INT8 是“无实质精度损失”的结论仅指上述 MR-ALL 基准，量化仍会使分数相对 FP32 变化；低精度 profile 也可能产生与 FP32 不同的排序。
• 持久化的 profile 与后端不匹配时（例如把fp16_v1的库搬到 CPU 后端）会显式失败，不会被静默转换。

INT8 能力相关的迁移文件可作进一步参考：0002_native_search.sql、0003_int8_x736.sql。

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface