From 5bf505ff2ed3b3a5fcb3a0ee3ef414f2a91415a5 Mon Sep 17 00:00:00 2001
From: tian <11429339@qq.com>
Date: Sun, 15 Mar 2026 21:37:53 +0800
Subject: [PATCH] Refresh detection parameter guide for current pipeline

---
 docs/design/detection_parameters_guide.md | 64 +++++++++++++++++++++--
 1 file changed, 59 insertions(+), 5 deletions(-)

diff --git a/docs/design/detection_parameters_guide.md b/docs/design/detection_parameters_guide.md
index 7e577f7..0d2eb46 100644
--- a/docs/design/detection_parameters_guide.md
+++ b/docs/design/detection_parameters_guide.md
@@ -1,10 +1,15 @@
-# 人脸检测参数配置指南
+# 检测参数配置指南
 
-本文档详细说明人脸检测节点（`ai_face_det`, `ai_scrfd`, `ai_scrfd_sliding`）中的核心后处理参数及其对检测结果的影响。
+本文档说明当前项目中与“检测效果”和“实时性”最相关的参数，覆盖：
+
+- 人脸检测
+- 人脸识别
+- 车间劳保鞋两阶段检测
+- 颜色判断与告警稳定性
 
 ---
 
-## 参数概览
+## 一、人脸检测参数概览
 
 | 参数名 | 类型 | 默认值 | 范围 | 说明 |
 |--------|------|--------|------|------|
@@ -258,6 +263,41 @@ const int out_n = std::min<int>(cfg.max_faces, static_cast<int>(keep.size()));
 
 ## 四、人脸识别参数 (`ai_face_recog`)
 
+人脸识别当前已经支持节流参数，适合车间这类“人比较稳定、不需要高频重复识别”的场景。
+
+### 1. 关键参数
+
+| 参数 | 当前建议 | 作用 |
+|------|----------|------|
+| `infer_fps` | `2` | 人脸识别频率 |
+| `infer_phase_ms` | `120` 左右 | 与其它 AI 节点错峰 |
+| `max_faces` | `50` | 单帧最多识别多少张脸 |
+| `threshold.accept` | `0.45` | 识别通过阈值 |
+| `threshold.margin` | `0.05` | Top1/Top2 相似度边界 |
+
+### 2. 调参原则
+
+- 完整流程 FPS 不够：优先降低 `infer_fps`
+- 识别太慢才出结果：适当提高 `infer_fps`
+- 误识别偏多：提高 `threshold.accept`
+- 经常识别成 unknown：适当降低 `threshold.accept`
+
+### 3. 典型配置示例
+
+```json
+{
+  "id": "face_recog",
+  "type": "ai_face_recog",
+  "infer_fps": 2,
+  "infer_phase_ms": 120,
+  "max_faces": 50,
+  "threshold": {
+    "accept": 0.45,
+    "margin": 0.05
+  }
+}
+```
+
 ---
 
 ## 五、车间劳保鞋检测参数（当前主线）
@@ -299,14 +339,15 @@ ai_yolo(person only)
 
 | 参数 | 当前建议 | 作用 |
 |------|----------|------|
-| `conf` | `0.15` | 鞋候选召回阈值 |
+| `conf` | `0.15 ~ 0.22` | 鞋候选召回阈值 |
 | `nms` | `0.45` | 鞋框去重 |
 | `infer_fps` | `2` | 鞋检频率 |
 | `dynamic_roi.max_rois` | `3` | 单帧最多处理多少人 |
 | `dynamic_roi.min_person_height` | `60` | 过滤太远的人 |
+| `dynamic_roi.max_box_area_ratio` | `0.60` | 过滤接近整块脚区的大误框 |
 | `x_offset/y_offset/width_scale/height_scale` | 见推荐配置 | 控制脚部 ROI 形状 |
 
-为什么 `shoe_det.conf` 只有 `0.15`？
+为什么 `shoe_det.conf` 会落在 `0.15 ~ 0.22`？
 
 - 当前场景是高机位、小目标、遮挡多
 - 如果把鞋阈值直接提到常规检测项目里的 `0.4~0.5`
@@ -359,6 +400,19 @@ ai_yolo(person only)
 3. 再调颜色判断黑白边界
 4. 最后再调告警节流
 
+### 六、实施人员速查
+
+如果只记一小部分参数，优先记下面这些：
+
+| 想解决的问题 | 先改哪个参数 |
+|--------------|--------------|
+| 人脸太吃性能 | `face_det.infer_fps`、`face_recog.infer_fps` |
+| 人框太紧、鞋 ROI 裁偏 | `person_det.bbox_expand.bottom` |
+| 鞋漏报 | `shoe_det.conf`、`shoe_assoc.min_shoe_score` |
+| 蓝框误报多 | `shoe_det.conf`、`dynamic_roi.max_box_area_ratio` |
+| 黑鞋被误报 | `dark_threshold` |
+| 告警太频繁 | `min_duration_ms`、`cooldown_ms` |
+
 不要一开始就只改 `alarm`，否则常常会把“检测问题”误判成“规则问题”。
 
 `ai_face_recog` 节点接收人脸检测结果，提取人脸特征向量并与特征库进行比对，完成人脸识别。