Buffalo 框架并非 InsightFace 的 buffalo_l，而是 Go 生态中已进入维护模式的全栈 Web 框架；InsightFace 中的 buffalo_l 是预训练人脸模型包，含检测、识别、关键点等能力，需指定 name="buffalo_l"自动下载加载，不可误作路径或填错名称。
Buffalo 框架不是 InsightFace 里的 buffalo_l，也不是 Go 生态中那个已归档的 gobuffalo/buffalo（2023 年起官方不再维护）。你搜到的“Buffalo 框架”大概率是混淆了名称——当前主流、活跃、可直接用于项目开发的 Buffalo，**只存在于 Go 语言生态中**，且它是一个全栈 Web 框架（类似 Rails），但**已进入维护模式，不推荐新项目选用**。
如果你实际想问的是 InsightFace 中的 buffalo_l 模型（常被误称为 “Buffalo 框架”），那它根本不是框架，而是 InsightFace 提供的一个预训练人脸分析模型包，包含检测、识别、关键点等能力。下面按这个真实意图展开：
为什么初始化 FaceAnalysis 时要指定 name="buffalo_l"
因为 buffalo_l 是 InsightFace 官方发布的高性能模型集合名，不是路径也不是自定义标识。它会自动从 Hugging Face 或 InsightFace 的 CDN 下载对应权重（det_10g.onnx、w600k_r50.onnx 等），并加载全部子模块（RetinaFace + ArcFace + 68pt landmark）。不填或填错（如 "buffalo_s" 但没联网）会导致 app.prepare() 失败，报错：FileNotFoundError: model not found。
-
buffalo_l：精度高、速度适中，适合大多数桌面/服务端场景 -
buffalo_s：轻量，但关键点和识别精度下降明显，仅建议边缘设备临时测试 - 不能写成路径（如
"./models/buffalo_l"），除非你手动下载并用root参数指定本地目录
GPU / MPS 设备下 ctx_id 必须设为 0
InsightFace 的 ONNXRuntime 封装对 Apple Silicon（MPS）支持不完善：ctx_id=-1 在 MPS 下会静默失败，导致 app.get() 返回空列表，且无任何错误提示。CUDA 同理——即使你有多个 GPU，也必须设 ctx_id=0，否则检测器不工作。
- device="cuda" → providers=['CUDAExecutionProvider', 'CPUExecutionProvider']，
ctx_id=0 - device="mps" → providers=['CoreMLExecutionProvider', 'CPUExecutionProvider']，
ctx_id=0（不是 -1） - CPU 模式下
ctx_id才可设为 -1
det_size 不是图像分辨率，而是检测器输入缩放基准
det_size 控制 RetinaFace 前向时将原图等比缩放到该尺寸再送入网络（保持长边不超过该值）。它直接影响速度与小脸召回率：
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 设太小（如
(320, 320)）：快，但漏检侧脸、远距离人脸 - 设太大（如
(1280, 1280)）：显存暴涨，单帧耗时翻倍，对普通摄像头无意义 - 推荐值：
(640, 640)（平衡点），高清视频可试(768, 768) - 注意：它不影响后续 ArcFace 的输入尺寸（那是固定 112×112）
调用 app.get() 前必须确认图像格式和通道顺序
InsightFace 内部默认接收 BGR 格式的 numpy.ndarray（OpenCV 默认格式）。如果你用 PIL、cv2.imread() 以外的方式读图（比如 requests + BytesIO + PIL.Image.open），极大概率拿到的是 RGB，直接传入会导致检测框偏移、关键点错乱，且不报错。
- 安全做法：统一用
cv2.cvtColor(img, cv2.COLOR_RGB2BGR)转一次 - 检查维度：
img.shape必须是 (H, W, 3)，不能是 (H, W)（灰度）或 (1, H, W, 3)（batch 维度） - 类型必须是
np.uint8；float32 且值在 [0,1] 区间会直接崩溃
真正容易被忽略的，是 buffalo_l 的“全家桶”特性——你调一次 app.get()，它内部其实串行执行了检测 → 对齐 → 识别 → 关键点回归四步。如果只要检测框，却用了全套流程，就白白浪费 60%+ 时间。需要拆解时，得绕过 FaceAnalysis，直接加载 RetinaFace 单独模型。
