Files

Kevin 557fcee803 Update consumable pipeline, client API docs, and deployment config

- 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

2026-04-24 11:05:17 +08:00

3.6 KiB

Raw Blame History

视频双后端说明（RTSP / 海康 HCNetSDK）

目标容器

推荐：Linux x86_64 + glibc（与当前 python:3.13-slim-bookworm 一致）。
不推荐：Alpine（musl）加载海康预编译 .so 往往失败。
镜像已安装 ffmpeg 与 OpenCV 常用系统库，便于 cv2.VideoCapture(..., cv2.CAP_FFMPEG) 拉 RTSP。

RTSP 模式（默认）

配置 **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}。

调用 POST /client/surgeries/start 时，camera_ids 必须能在上述配置中解析出 RTSP 地址。
开录确认：每路摄像头在超时内成功打开并读到首帧后，才认为该路已开录。

海康官方 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）。

行为概要：

进程内对 NET_DVR_Init 使用引用计数；每路使用 SDK 的工作线程在登录后 NET_DVR_Logout，线程结束时配对 NET_DVR_Cleanup。
若 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。

3.6 KiB Raw Blame History Unescape Escape