04866559db
- Add FastAPI routes for surgery start/end, results, pending confirmation (WAV upload), and health checks. - Implement RTSP/Hikvision capture, consumable classification, session manager, MinIO/Baidu voice resolution, and DB persistence. - Add documentation (client API, video backends, staging checklist) and sample camera/RTSP config. - Add pytest suite (API contract, session manager, voice, repositories, pipeline persistence) and httpx dev dependency. - Replace deprecated HTTP_422_UNPROCESSABLE_ENTITY with HTTP_422_UNPROCESSABLE_CONTENT. - Fix SurgeryPipeline DB reads to use an explicit transaction with autobegin disabled. Made-with: Cursor
46 lines
3.5 KiB
Markdown
46 lines
3.5 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`）为**硬约束**：若为空，服务端**不会**写入任何消耗明细（仅拉流推理）；非空时仅允许清单内标签自动记账。
|
||
- 当分类 Top1 置信度 ≥ `VIDEO_AUTO_CONFIRM_CONFIDENCE` 且标签在候选清单内时，自动写入一条 `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」一节。
|