init

backend/algorithm_subprocesses/5.15/README_handoff.md

@@ -0,0 +1,72 @@
+# pack/5.11 手术室耗材主流程（交接包）
+
+同事解压或拷贝本目录后，配置 Conda/venv、**将 5 个模型权重放入 `weights/`**、把待分析 **MP4 + Excel** 放入 **`input/`**，按需编辑 **`configs/default_config.yaml`**，然后：
+
+```bash
+cd /path/to/5.11
+pip install -r requirements.txt
+pip install -e code/actionformer_release/libs/utils
+python main.py
+```
+
+默认读取 `configs/default_config.yaml`；指定其它配置：
+
+```bash
+python main.py --config configs/my_run.yaml
+```
+
+## 目录说明
+
+| 路径 | 说明 |
+|------|------|
+| `configs/default_config.yaml` | **唯一**业务默认：输入输出路径、5 个权重相对路径、各阶段阈值（勿在 Python 里写死） |
+| `weights/` | 放置 5 个文件（文件名与 yaml 中一致即可，或改 yaml） |
+| `input/` | 投放 `sample.mp4`、`视频中的商品信息表.xlsx`（名称与 yaml 中 `io.*` 一致） |
+| `output/` | 默认 TSV 输出 `output/result.txt` |
+| `code/` | Vendor 源码子树（VideoSwin 提特征、ActionFormer、e2e、YOLO 段内逻辑）；一般不需改 |
+| `src/` | 配置解析与主流程编排（`orchestrator.py`、`config.py`） |
+
+## 输出 TSV（`io.out`）
+
+默认 **12 列**（制表符分隔），**不含**撕膜类名列：`rank`、`start_sec`、`end_sec`、`product_id_top1`、`top1_name`、`top1_conf`、top2 三列、top3 三列。撕膜模型仍在段内用于门控/推理逻辑，仅不写进结果表。
+
+若需要旧版 14 列（含 `tear_top1_name`、`tear_top2_name`），在配置里设 `output.legacy_12_col_only: false`。
+
+## 权重清单（从开发机仓库拷贝到 `weights/`）
+
+将下列文件复制到 `weights/`，并命名为 yaml 中的默认名（或在 yaml 里改成你的文件名）：
+
+| 配置键 | 建议文件名 | 开发仓库中原路径（参考） |
+|--------|------------|---------------------------|
+| `weights.actionformer` | `actionformer_epoch_045.pth.tar` | `code/video_clip_cls/runs/actionformer_ckpt/haocai_main_perspective_videoswin_haocai_main_perspective_videoswin/epoch_045.pth.tar` |
+| `weights.hand` | `hand_detect.pt` | `code/hand_detection/runs/hand_det_y11s_multiframe-better/weights/best.pt` |
+| `weights.goodbad` | `goodbad_frame.pt` | `code/goodORbad_frame/runs/goodbad_frame_y11m_e50/weights/best.pt` |
+| `weights.haocai` | `haocai_classify.pt` | `code/haocai_classify/runs/haocai_cls_41cls_goodframe_721_e50_p8-0.96/weights/best.pt` |
+| `weights.tear` | `tear_classify.pt` | `code/tear_classify/runs/tear_cls_bicls_y11m_e50_ds0511/weights/best.pt` |
+
+**VideoSwin** 使用 `torchvision` 预训练 Swin3D-T，无需额外权重文件。
+
+## ActionFormer NMS 扩展
+
+若 `eval.py` 报与 `nms` 相关错误，在 **本包根目录** 执行：
+
+```bash
+pip install -e code/actionformer_release/libs/utils
+```
+
+需已安装好 `torch`（会先 import torch）。
+
+## 环境与设备
+
+- 推荐 **Python 3.10+**，**CUDA** 与 PyTorch 版本匹配。
+- `configs/default_config.yaml` 中 `device.type` 可改为 `cpu`（极慢，仅调试）。
+- `device.half: true` 可降低显存占用。
+
+## 白名单
+
+- `io.whitelist_json: null` 时：从 Excel **第 1 张表 C 列**读取商品名称作为耗材白名单（与线上一致）。
+- 若设为路径如 `input/whitelist.json`，格式为 `{"allowed_names":["名称",...]}`。
+
+## 与开发仓库的关系
+
+本包内 `code/` 为导出子树，主入口逻辑在 `src/orchestrator.py`；若需修复推理 bug，可对比仓库 `code/video_clip_cls/scripts/main_pipeline.py`。