557fcee803
- Refine effective candidate consumables and classifier labels - Adjust vision algorithm, TSV logging, and video session wiring - Refresh client surgery HTTP contract doc and staging/video docs - Update settings, docker-compose prod, tests, and uv.lock Made-with: Cursor
45 lines
3.6 KiB
Markdown
45 lines
3.6 KiB
Markdown
# 视频双后端说明（RTSP / 海康 HCNetSDK）
|
||
|
||
## 目标容器
|
||
|
||
- **推荐**：`Linux x86_64` + **glibc**（与当前 `python:3.13-slim-bookworm` 一致）。
|
||
- **不推荐**：Alpine（musl）加载海康预编译 `.so` 往往失败。
|
||
- 镜像已安装 **ffmpeg** 与 OpenCV 常用系统库，便于 `cv2.VideoCapture(..., cv2.CAP_FFMPEG)` 拉 RTSP。
|
||
|
||
## RTSP 模式（默认）
|
||
|
||
1. 配置 `**camera_id` → RTSP URL** 映射，任选其一或组合使用：
|
||
- `**VIDEO_RTSP_URLS_JSON_FILE`**：指向 UTF-8 JSON 文件（对象键为与请求一致的 `camera_id`）。仓库示例：`[app/resources/camera_rtsp_urls.sample.json](../app/resources/camera_rtsp_urls.sample.json)`（示例 ID：`or-cam-01`、`or-cam-02`）。
|
||
- `**VIDEO_RTSP_URLS_JSON**`：内联 JSON 字符串；与文件合并时**覆盖同键**。
|
||
- `**VIDEO_RTSP_URL_TEMPLATE`**：单模板，可用 `{camera_id}`。
|
||
2. 调用 `POST /client/surgeries/start` 时，`camera_ids` 必须能在上述配置中解析出 RTSP 地址。
|
||
3. **开录确认**：每路摄像头在超时内成功打开并读到**首帧**后，才认为该路已开录。
|
||
|
||
## 海康官方 SDK 模式（可选）
|
||
|
||
SDK **不作为构建期依赖**：将厂商提供的 Linux x86_64 动态库挂载到容器内（例如 `/opt/hikvision/lib/libhcnetsdk.so`），并设置：
|
||
|
||
- `HIKVISION_SDK_ENABLED=true`
|
||
- `HIKVISION_DEVICE_IP` / `HIKVISION_USER` / `HIKVISION_PASSWORD`（以及可选端口）
|
||
- `HIKVISION_PREVIEW_RTSP_TEMPLATE` 或 `HIKVISION_CAMERA_RTSP_URLS_JSON`：登录成功后仍通过 **RTSP** 取帧送模型（与常见部署一致：SDK 负责设备会话，码流仍走 RTSP）。
|
||
|
||
行为概要：
|
||
|
||
1. 进程内对 `NET_DVR_Init` 使用引用计数；每路使用 SDK 的工作线程在登录后 `NET_DVR_Logout`，线程结束时配对 `NET_DVR_Cleanup`。
|
||
2. 若 `HIKVISION_SDK_FALLBACK_TO_RTSP=true`（默认），在**无法加载动态库**、**登录失败**或**未配置凭据**时，自动回退到 `VIDEO_RTSP_`* 映射拉流。
|
||
|
||
**注意**：`NET_DVR_Login_V30` 的设备信息结构体在不同 SDK 版本上可能存在差异；若登录异常，请优先使用 RTSP 回退或按厂商文档校对 ctypes 绑定。
|
||
|
||
## 推理与结果查询
|
||
|
||
- 开录后按 `VIDEO_INFERENCE_INTERVAL_SEC` 抽帧，依次调用耗材分类与撕扯动作模型。
|
||
- **候选耗材清单**（`candidate_consumables`）：非空时**仅**清单内名称参与自动记账与待确认；**缺省或 `[]`** 时，用 `consumable_classifier_labels.yaml` 的 **全部类名**作为候选；yaml 无有效 `names` 时用分类模型**全部类名**。
|
||
- 当分类 Top1 置信度 **≥** `VIDEO_AUTO_CONFIRM_CONFIDENCE`（**默认 0.9**）且标签在候选清单内时，自动写入一条 `source=vision` 的消耗明细；**低于**该线的识别需人工确认（在语音下沿之上且能展示候选项时入队）。
|
||
- 置信度在 `VIDEO_VOICE_CONFIRM_MIN_CONFIDENCE`, `VIDEO_AUTO_CONFIRM_CONFIDENCE` 等区间且存在可向医生展示的候选时，会生成**待确认**任务；客户端 `GET /client/surgeries/{surgery_id}/pending-confirmation`，确认后 `POST .../pending-confirmation/{id}/resolve` 等。
|
||
- `GET /client/surgeries/{surgery_id}/result` 仅在存在**至少一条**消耗明细时返回 200；无明细（已开录但尚未记账、已结束但零消耗、或尚无归档等）返回 503 `RESULT_NOT_READY`。
|
||
- 同类物品写入受 `VIDEO_DETAIL_COOLDOWN_SEC` 节流。
|
||
- RTSP 读帧连续失败达到 `VIDEO_READ_FAILURE_RECONNECT_THRESHOLD` 时会 `release` 并尝试重连，间隔 `VIDEO_RECONNECT_BACKOFF_SECONDS`。
|
||
|
||
## 相关环境变量
|
||
|
||
详见仓库根目录 `.env.example` 中「视频：RTSP + 可选海康 HCNetSDK」一节。 |