flowocr 0.1.0__py3-none-any.whl

flowocr/extract/ortclient.py

@@ -0,0 +1,363 @@
+"""ONNX Runtime 常驻 worker 的**客户端**：起进程、管共享内存、一次调用一次往返。
+
+服务端是同目录的 `ort_server.py`（独立进程；用哪个解释器起见 `server_python()`，为什么隔离见那份文件头）。
+一个客户端可以带多个模型（det 和 rec 共用一个进程）。
+
+用法：
+
+    cli = OrtClient({"det": "models/PP-OCRv6_medium_det_onnx/inference.onnx",
+                     "rec": "models/PP-OCRv6_medium_rec_onnx/inference_argmax.onnx"})
+    outs = cli.run("rec", x)          # x 是 float32 的 C 序数组；outs 是 list[np.ndarray]
+    cli.close()
+
+⚠ **形状要收敛**：服务端每个形状开一个 session（ORT 每次形状变化都重规划）。
+调用方自己负责把形状取整到少数几个，否则显存会被 session 吃光。
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+from multiprocessing import shared_memory
+from pathlib import Path
+
+import numpy as np
+
+from flowocr import paths
+
+SERVER = Path(__file__).resolve().parent / "ort_server.py"
+"""worker 脚本和这个文件同目录（2026-09-22 起在包里）；venv / 模型仍跟着**产物根**走（`flowocr.paths` 那条）。"""
+
+
+
+def _has_onnxruntime() -> bool:
+    return importlib.util.find_spec("onnxruntime") is not None
+
+
+def server_python() -> str:
+    """起 ORT worker 用哪个解释器：`FLOWOCR_ORT_PYTHON` 设了就是它；否则**当前解释器**（要装了 onnxruntime——
+    `[nvidia]` / `[cpu]` extras 都带）。原来还有第三条：退回 旧的 onnxrt 实验 venv（双 venv 时代的布局），
+    发布前删了（release-plan F7：生产代码不依赖可整目录删的 `explore/`）；要用别的解释器就设 `FLOWOCR_ORT_PYTHON`。"""
+    configured = os.environ.get("FLOWOCR_ORT_PYTHON", "").strip()
+    if configured:                        # 显式指定（A/B 换 ORT 版本、或发行时把 worker 放在另一个解释器里）
+        return configured
+    if _has_onnxruntime():
+        return sys.executable
+    raise SystemExit(f"这个解释器（{sys.executable}）没装 onnxruntime：装 flowocr 的 [nvidia] 或 [cpu] extras"
+                     f"（uv sync --extra nvidia|cpu），或用 FLOWOCR_ORT_PYTHON 指一个装了的解释器")
+
+
+def pick_addr(env: str, models) -> str:
+    """`FLOWOCR_ORT_ADDR` 里挑出**这个 client 该连哪个服务**。
+
+    两种写法：
+
+    * `host:port` —— 不分引擎的老写法，连上去由握手核能力；
+    * `rec=host:port,det=host:port` —— **一个引擎一个服务**（2026-09-20 接 det 那半时改的）。
+      服务端推理是一把全局锁，两个引擎塞进同一个服务就把 det 和 rec 串回去了，
+      而 `run_ocr2` 早有实测："共用一个 worker 就串行了，det 段 24.8 → 26.1 s"。
+
+    要的模型分散在不同服务里就返回空串——这个 client 自己 spawn 一个带全套的 worker，
+    正确性比共享重要（一个 client 一根管子一块共享内存，连不了两个服务）。
+    """
+    env = (env or "").strip()
+    if not env:
+        return ""
+    if "=" not in env:
+        return env
+    table = dict(part.split("=", 1) for part in env.split(",") if "=" in part)
+    hit = {table.get(m, "") for m in models}
+    return hit.pop() if len(hit) == 1 and all(hit) else ""
+
+
+class OrtClient:
+    def __init__(self, models: dict[str, str], in_mb: int = 64, out_mb: int = 32,
+                 python: str | None = None, gpu_mem_mb: int = 6144, max_sessions: int = 12,
+                 device: str = "gpu:0", extra_args: list[str] | None = None, attach: str = "") -> None:
+        """`gpu_mem_mb` / `max_sessions`：**显存配额**（owner 2026-09-19 定整机 8 GB）。
+        CUDA EP 的 arena 上限 + per-shape 池子的条数上限——超了 ORT 当场报 OOM、池子按 LRU 淘汰，
+        而不是把卡吃光（实测一条扫宽 × 批的探针同时活着 24 个 session、吃到 15 GB）。
+        `python` 不给就按 `server_python()`；模型路径经 `paths.resolve_model`（相对当前目录找不到就到模型根找）。
+        `device`：`gpu:N` / `cpu`（`gpu` 当 `gpu:0`），原样交给 worker（`ort_server --device`）；调用方按自己的 `--device` 传，
+        **别让 worker 自己挑**（NVIDIA 包里 `--device cpu` 时 rec 曾经照样上 GPU，Codex 审计 P1；卡号曾经丢在半路，复审 P2）。
+        实际用上的 provider 在 `self.provider`，`stats()` 带出去。
+        `extra_args`：原样追加给 `ort_server` 的参数（比如 `--share-mem 1`；管线由 `run_ocr2.ort_server_args` 给）。
+        `attach`：**只接**这个地址上的现成服务（`side_channel` 用）——接不上就抛，不自己起（那会多出一整份模型和显存）。"""
+        from flowocr.extract.ocr_args import ort_device   # ort_server 顶层 import onnxruntime，别为一个字符串归一去拉它
+        try:
+            self.device = ort_device(device)
+        except SystemExit as exc:
+            raise ValueError(str(exc)) from None
+        self.cap_in, self.mb = in_mb * 2 ** 20, (in_mb, out_mb)
+        self.shm = shared_memory.SharedMemory(create=True, size=self.cap_in + out_mb * 2 ** 20)
+        if attach:
+            if not self._attach(attach, models):
+                self.shm.close()
+                self.shm.unlink()
+                raise RuntimeError(f"接不上 ORT 服务 {attach}")
+            return
+        python = python or server_python()
+        models = {n: paths.resolve_model(p) for n, p in models.items()}
+        # **有现成的服务就接上去**（`FLOWOCR_ORT_ADDR=host:port`）：N 个 worker 共用一份模型
+        # = **显存只有一份**。owner 2026-09-19 把 `--workers` 默认压回 1 的理由就是显存，
+        # 共享是重新放宽的前提。自己的共享内存还是自己建——张量不走 socket。
+        addr = pick_addr(os.environ.get("FLOWOCR_ORT_ADDR", ""), models)
+        if addr and self._attach(addr, models):
+            return
+        self.shared = False
+        args = [os.path.abspath(python), str(SERVER), "--shm", self.shm.name,
+                "--in-bytes", str(self.cap_in), "--gpu-mem-mb", str(gpu_mem_mb),
+                "--max-sessions", str(max_sessions), "--device", device]
+        for name, path in models.items():
+            args += ["--model", f"{name}={path}"]
+        args += list(extra_args or ())
+        # ⚠ Windows 的 CreateProcess 不吃"相对路径 + 正斜杠"的可执行文件（WinError 2，实测）
+        # worker 的 stderr 落一个临时文件：它建 session 就死的时候（2026-09-22 nightly：ORT 1.26 的 CPU EP 打不开 fp16 模型），
+        # 原来 DEVNULL 只剩客户端一行 JSONDecodeError，病因要另起进程才看得到
+        import tempfile
+        self._err = tempfile.NamedTemporaryFile(prefix="flowocr-ort-", suffix=".log", delete=False)
+        self.proc = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                     stderr=self._err, text=True, encoding="utf-8",
+                                     bufsize=1)
+        line = self.proc.stdout.readline()
+        try:
+            hello = json.loads(line) if line.strip() else {}
+        except json.JSONDecodeError:
+            hello = {"line": line[:300]}
+        if "ready" not in hello:
+            tail = self._stderr_tail()                # 先取，close() 会把那个临时文件删掉
+            self.close()
+            raise RuntimeError(f"ORT worker 起不来：{hello}；它的 stderr 尾部：{tail}")
+        self.provider, self.ort_version = hello.get("provider", ""), hello.get("ort_version", "")
+        self.side_addr = f"127.0.0.1:{hello['port']}" if hello.get("port") else ""
+        """服务开了旁路端口（`extra_args` 里有 `--side-listen`）时，`side_channel()` 从这里再接连接进去。"""
+        self.pre = bool(hello.get("pre"))
+        """服务端会做 rec 前处理（能收原样的 uint8 裁剪，`run_crops`）。"""
+        self.models = list(models)
+        self.t = {"send": 0.0, "wait": 0.0, "infer": 0.0, "pre": 0.0, "calls": 0}
+        """分段计时（**别猜，量**）：调用方自己决定什么时候打出来。"""
+        self.lock = threading.Lock()
+        """⚠ **一个 client 同时只能有一个调用在飞**：一根管道 + 一块共享内存，
+        两个线程各写各的请求会串线——回信认不出是谁的，输入区也会互相盖。
+        管线里 det 在预取线程、rec 在主线程，**真会同时调**（2026-09-18 接 det 后端时差点栽）。
+        锁只保证不坏；要并行就给两个引擎各起一个 worker（`run_ocr2` 就是这么做的）。"""
+        self.shapes: dict = {}
+
+    def _attach(self, addr: str, models: dict[str, str]) -> bool:
+        """接上现成的共享服务。**接不上就返回 False，由调用方自己 spawn**。
+
+    ⚠ `FLOWOCR_ORT_ADDR` 是**进程级**的，而一个 run_ocr2 进程里 det 和 rec 是**两个 client**
+    （det 在预取线程、rec 在主线程，共用一个 worker 会串行——实测 det 段 24.8 → 26.1 s）。
+    共享服务现在只加载 rec，所以握手必须报出**自己要哪几个模型**（`want`）让服务端核：
+    核不过就退回自己 spawn。不核的话 `--workers N`
+    会把 det 请求打进只服 rec 的服务里、在服务端 `models["det"]` 上炸（审计七）。
+        """
+        import socket
+        try:
+            host, _, port = addr.rpartition(":")
+            sock = socket.create_connection((host or "127.0.0.1", int(port)), timeout=10)
+            sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)   # 关 Nagle，同 ort_server 那一侧（decode-buffer）
+            f = sock.makefile("rwb")
+            f.write((json.dumps({"hello": {"shm": self.shm.name, "in_bytes": self.cap_in,
+                                           "want": sorted(models), "device": self.device}}) + "\n").encode())
+            f.flush()
+            ok = json.loads(f.readline() or "{}")
+        except Exception as e:                       # 服务没了 / 连不上：自己起一个就是
+            print(f"[ort] 接不上共享服务 {addr}（{e!r}），自己起一个 worker", flush=True)
+            return False
+        if not ok.get("ok"):
+            f.close()
+            sock.close()
+            print(f"[ort] 共享服务 {addr} 不提供 {ok.get('missing')} / 设备是 {ok.get('device')}"
+                  f"（它有 {ok.get('models')}，这个 client 要 {self.device}），自己起一个 worker", flush=True)
+            return False
+        sock.settimeout(None)
+        self.provider, self.ort_version = ok.get("provider", ""), ok.get("ort_version", "")
+        self.side_addr = addr
+        self.pre = bool(ok.get("pre"))
+        self.sock, self.f, self.proc = sock, f, None
+        self.models = list(models)
+        self.t = {"send": 0.0, "wait": 0.0, "infer": 0.0, "pre": 0.0, "calls": 0}
+        self.lock = threading.Lock()
+        self.shapes = {}
+        self.shared = True
+        return True
+
+    def side_channel(self) -> "OrtClient":
+        """再接一条到**同一个服务进程**的连接（自己的共享内存、自己的锁），给同时在途的第 2..N 个请求用
+        （`run_ocr2 --rec-inflight`，decode-buffer）：模型和显存仍只有一份。
+        管道模式起服务时要带 `--side-listen`；接的是共享服务就连同一个地址。
+        **接不上就抛**——这里不退回自己 spawn（那会多出一整份模型和显存）。"""
+        if not self.side_addr:
+            raise RuntimeError("这个 ORT 服务没开旁路端口（起它时要给 --side-listen）")
+        return OrtClient(dict.fromkeys(self.models, ""), in_mb=self.mb[0], out_mb=self.mb[1],
+                         device=self.device, attach=self.side_addr)
+
+    def run(self, model: str, x: np.ndarray) -> list[np.ndarray]:
+        if x.dtype != np.float32 or not x.flags["C_CONTIGUOUS"]:
+            x = np.ascontiguousarray(x, dtype=np.float32)
+        if x.nbytes > self.cap_in:
+            raise ValueError(f"输入 {x.nbytes / 2**20:.0f} MB 超过共享内存的输入区 "
+                             f"{self.cap_in / 2**20:.0f} MB")
+        with self.lock:
+            t0 = time.perf_counter()
+            np.ndarray(x.shape, dtype=np.float32, buffer=self.shm.buf[: x.nbytes])[...] = x
+            return self._roundtrip(model, {"model": model, "shape": list(x.shape)}, t0)
+
+    def run_crops(self, model: str, crops: list[np.ndarray], grid: int, batch: int) -> list[np.ndarray]:
+        """rec：送**原样的 uint8 裁剪**（依次紧排进共享内存），前处理在服务进程里做（`recprep.batch`，要 `self.pre`）。
+        为什么（2026-09-23，decode-buffer）：前处理在管线进程里抢 GIL，6,400 个裁剪要 5~9 s（单独跑约 1 s）。"""
+        crops = [np.ascontiguousarray(c, dtype=np.uint8) for c in crops]
+        total = sum(c.nbytes for c in crops)
+        if total > self.cap_in:
+            raise ValueError(f"裁剪共 {total / 2**20:.0f} MB 超过共享内存的输入区 {self.cap_in / 2**20:.0f} MB")
+        with self.lock:
+            t0 = time.perf_counter()
+            off = 0
+            for c in crops:
+                self.shm.buf[off: off + c.nbytes] = c.reshape(-1).data
+                off += c.nbytes
+            return self._roundtrip(model, {"model": model, "crops": [list(c.shape) for c in crops],
+                                           "grid": grid, "batch": batch}, t0)
+
+    def _roundtrip(self, model: str, req_d: dict, t0: float) -> list[np.ndarray]:
+        """输入已经写进共享内存：发一行请求、等一行回信、按回信切输出。**两种请求共用这一份**。"""
+        req = json.dumps(req_d) + "\n"
+        if self.shared:                      # 共用一个服务进程：走 socket
+            self.f.write(req.encode())
+            self.f.flush()
+            t1 = time.perf_counter()
+            line = self.f.readline().decode()
+        else:
+            self.proc.stdin.write(req)
+            self.proc.stdin.flush()
+            t1 = time.perf_counter()
+            line = self.proc.stdout.readline()
+        t2 = time.perf_counter()
+        if not line:
+            raise RuntimeError("ORT worker 没了（连接断了）")
+        rep = json.loads(line)
+        if "outs" not in rep:
+            raise RuntimeError(f"ORT worker 报错：{rep}")
+        out, off = [], self.cap_in
+        for dtype, shape in rep["outs"]:
+            arr = np.ndarray(tuple(shape), dtype=np.dtype(dtype),
+                             buffer=self.shm.buf[off: off + int(np.prod(shape)) * np.dtype(dtype).itemsize])
+            out.append(arr.copy())
+            off += arr.nbytes
+        self.t["send"] += t1 - t0
+        self.t["wait"] += t2 - t1
+        self.t["infer"] += rep.get("infer_ms", 0.0) / 1000.0
+        self.t["pre"] += rep.get("pre_ms", 0.0) / 1000.0     # 服务端做的前处理（只有 run_crops 有）
+        self.t["built"] = rep.get("built", 0)          # 服务端自报的累计数（不是增量）
+        self.t["evicted"] = rep.get("evicted", 0)
+        self.t["warmed"] = rep.get("warmed", 0)        # 服务端起动后后台预热进池子的形状数（--warm）
+        self.t["build"] = rep.get("build_ms", 0.0) / 1000.0
+        self.t["calls"] += 1
+        key = (model, tuple(rep.get("shape") or req_d.get("shape") or ()))
+        self.shapes[key] = self.shapes.get(key, 0) + 1
+        return out
+
+    def stats(self) -> dict:
+        """给 `_meta` 的分因数据（2026-09-19 两轮审计）。
+
+        * `wait_sec − infer_sec` 是**客户端这一侧**看到的"推理之外的钱"：建 session + IPC + 输出拷贝。
+          IPC 实测每次调用 0.12~0.33 ms，量级小，但**它确实混在里面**，别把这个差整个当成建 session。
+        ⚠ **共享服务下 `built` / `evicted` / `build_sec` 是跨客户端的全局累计值**
+          （服务端一份计数器、逐次回给每个客户端），所以多 worker 时**别把它当这一个 worker 的账**。
+          那组证据是单进程量的、不受影响（审计七第三条）。
+
+        * `built` / `evicted` / `build_sec` 是**服务端自报的**：建了几个 session、LRU 淘汰了几次、
+          建它们花了多久。**只有 `build_sec` 分不开**"每个新形状一次性的规划"（整片上摊薄）和
+          "反复淘汰重建"（整片上持续付）——而这两种对整片的预测相反。`evicted > 0` 就是后者在发生。
+        """
+        return {"calls": self.t["calls"], "send_sec": round(self.t["send"], 2),
+                "wait_sec": round(self.t["wait"], 2), "infer_sec": round(self.t["infer"], 2),
+                "overhead_sec": round(self.t["wait"] - self.t["infer"] - self.t["pre"], 2),
+                "server_pre_sec": round(self.t["pre"], 2), "pre_on_server": self.pre,
+                "built": self.t.get("built", 0), "evicted": self.t.get("evicted", 0), "warmed": self.t.get("warmed", 0),
+                "build_sec": round(self.t.get("build", 0.0), 2),
+                "shapes": len(self.shapes), "device": self.device, "provider": self.provider,
+                "ort_version": self.ort_version}
+
+    def report(self, tag: str = "") -> None:
+        if not self.t["calls"]:
+            return
+        print(f"[ort{tag}] {self.t['calls']} 次调用：送 {self.t['send']:.1f}s、等回信 "
+              f"{self.t['wait']:.1f}s（worker 自报推理 {self.t['infer']:.1f}s）；"
+              f"{len(self.shapes)} 种形状", flush=True)
+
+    def close(self) -> None:
+        if getattr(self, "shared", False):
+            # 接上去的那条：**只关自己这一端**，服务进程是别人的
+            try:
+                self.f.write(b'{"bye":1}\n')
+                self.f.flush()
+                self.f.close()
+                self.sock.close()
+            except Exception:
+                pass
+            if getattr(self, "shm", None):
+                self.shm.close()
+                try:
+                    self.shm.unlink()
+                except FileNotFoundError:
+                    pass
+            self.shm = None
+            return
+        try:
+            if getattr(self, "proc", None) and self.proc.poll() is None:
+                self.proc.stdin.write(json.dumps({"bye": 1}) + "\n")
+                self.proc.stdin.flush()
+                self.proc.wait(timeout=5)
+        except Exception:
+            if getattr(self, "proc", None):
+                self.proc.kill()
+        finally:
+            if getattr(self, "shm", None):
+                self.shm.close()
+                try:
+                    self.shm.unlink()
+                except FileNotFoundError:
+                    pass
+            err = getattr(self, "_err", None)
+            if err is not None:                       # worker 的 stderr 临时文件：正常退出就删掉
+                self._err = None
+                try:
+                    err.close()
+                    os.unlink(err.name)
+                except OSError:
+                    pass
+
+    def _stderr_tail(self, n: int = 1500) -> str:
+        err = getattr(self, "_err", None)
+        if err is None:
+            return ""
+        try:
+            err.flush()
+            return Path(err.name).read_text(encoding="utf-8", errors="replace")[-n:].strip()
+        except OSError:
+            return ""
+
+    def __del__(self) -> None:
+        self.close()
+
+
+def make_det_runner(client: OrtClient, model: str = "det"):
+    """给 `FastDet` 换 runner：它只要一个 `runner([blob]) -> preds` 的可调用对象。
+
+    所以 det 的**前处理（`FastDet.preprocess`）和后处理（`post_op`）一个字都不用动**，
+    换掉的只是中间那一下推理。det 的输入是定尺（按 `--det-batch` 有一两种形状），
+    没有 rec 那个动态宽的坑。
+
+    ⚠ **只用 fp32 那份**：实测 fp16 的 det 会多出 10% 的框（IoU≥0.5 只有 94.4%、24 帧没有一帧
+    多边形完全相同），fp32 则 21/24 帧完全相同、108 vs 107 框（一次性探针 `probe_ort_det.py`）。
+    """
+    def runner(blobs):
+        x = blobs[0]
+        return client.run(model, x)
+    return runner

flowocr/extract/ptsclock.py

@@ -0,0 +1,150 @@
+"""采样帧时间戳的唯一判据：只认解码器给的真实 PTS，且必须严格递增。
+
+**单独放一个文件是为了让守卫够得着**——和 `flowocr.extract.ocr_complete` 同一个理由
+（audit-4 C8）：判据写在 `run_ocr2.py`（当时在 paddleocr 实验目录）里的话，那个文件
+import cv2 和 paddleocr，共享层的自检够不着，够不着就等于测不了。
+而这条判据恰好属于**错了不会报错**的一类：一条坏时间轴不会让任何下游抛异常，
+只会让所有时间都错一点。
+
+## 为什么不能再用 `idx / src_fps`
+
+`src_fps` 是 `CAP_PROP_FPS`，即**容器的平均帧率**。直播录像有丢帧缺口时它低于
+标称的 60，于是帧计数 × (1/59.978) 在缺口**之前**就已经比真实 pts 慢，
+缺口之后还要再跳一次。实测（fps-and-rec-budget 报告）：
+
+| 素材 | `src_fps` | pts 缺口 | 管线比真实 pts 晚 |
+| --- | ---: | --- | --- |
+| f1 / f2 / f5 | 60.000 | 无 | 0 |
+| f3 | 59.978 | 两处（5.2 s + 7.0 s） | 7.2 h 处 **9.5 s** |
+| f4 | 59.987 | 一处（6.0 s） | 6.4 h 处 **5.0 s** |
+
+旧产物**不能**乘 `src_fps / round(src_fps)` 修回来：那只消掉伸缩，
+缺口之后仍缺累计丢帧时长。
+
+## `CAP_PROP_POS_MSEC` 的语义（2026-09-09 实测）
+
+`read()` 之后 `cap.get(CAP_PROP_POS_MSEC)` 给的是**刚读到那一帧**的 pts，
+逐帧对齐 ffprobe 的 `frame=pts_time`（从 0.0 起，不是下一帧）。
+"""
+from __future__ import annotations
+
+import bisect
+import json
+import math
+
+
+class BadPts(ValueError):
+    """解码器给的时间戳不可信。**不要吞掉它**——产物必须判为未完成。"""
+
+
+class PtsClock:
+    """按顺序喂进每个采样帧的 pts（秒），换出 `t_us`（微秒整数）。
+
+    三道门，任何一道不过就抛 `BadPts`：非有限、为负、不严格递增。
+
+    严格递增而不是非递减：两个采样帧拿到同一个 `t_us`，下游会把两次观测
+    叠成一个时刻——这既不会报错，也数不出来。
+    """
+
+    def __init__(self) -> None:
+        self.first_us: int | None = None
+        self.last_us: int | None = None
+        self.n: int = 0
+
+    def push(self, t_sec: float, *, where: str = "") -> int:
+        tag = f"{where}：" if where else ""
+        if not math.isfinite(t_sec) or t_sec < 0:
+            raise BadPts(f"{tag}解码器给的 PTS 无效（{t_sec!r}）")
+        t_us = int(round(t_sec * 1_000_000))
+        if self.last_us is not None and t_us <= self.last_us:
+            raise BadPts(f"{tag}PTS 没有严格递增"
+                         f"（{self.last_us / 1e6:.6f}s -> {t_sec:.6f}s）")
+        if self.first_us is None:
+            self.first_us = t_us
+        self.last_us = t_us
+        self.n += 1
+        return t_us
+
+    @property
+    def span_sec(self) -> float:
+        """覆盖到的 pts 跨度（秒）。一帧都没有时是 0。"""
+        if self.first_us is None or self.last_us is None:
+            return 0.0
+        return (self.last_us - self.first_us) / 1e6
+
+    def meta(self) -> dict:
+        """写进 `_meta` 的那几个键。`timebase` 是下游认时间轴的唯一凭据。"""
+        return {"timebase": "pts",
+                "pts_first_sec": self.first_us / 1e6 if self.first_us is not None else None,
+                "pts_last_sec": self.last_us / 1e6 if self.last_us is not None else None}
+
+
+class IndexClock:
+    """**帧号 ↔ 真实时间**的双向映射（回抠这一级用）。
+
+    为什么需要它（2026-09-17，reuse-budget 计划第 1 条）：回抠拿 run 的时间（**真实 pts**）
+    换算成帧号去开解码窗，再把窗内的帧号换算回时间写进产物——两头都用 `us_per_frame = 1e6 / src_fps`，
+    而 `src_fps` 是**容器的平均帧率**。于是在丢帧缺口的素材上，窗口位置和输出时刻都带着那份偏差：
+    实测 yuka f4 一个 20 分钟窗口里**一处缺口都没有**，光是"平均帧率 59.9870 vs 窗内真实 60.000"这一项，
+    从头到尾就漂 **−260 ms**（≈ 15 帧）；f3 在 7.2 h 处是 **9.5 s**（本文件开头那张表）。
+
+    做法：拿 obs 里逐采样点的 `(帧号, t_us)` 当锚点做**分段线性**插值——采样点本身就是解码器给的真实 pts，
+    不用再解一遍视频；锚点之间只剩局部帧率的抖动。锚点之外（窗口首尾探出去的几十帧）退回名义帧率。
+
+    **不给锚点时它就是原来的常量换算**（`t_of(i) = i × us_per_frame`，逐位相同），所以 CFR 素材上产物不变。
+    """
+
+    __slots__ = ("us", "f", "t", "rate")
+
+    def __init__(self, us_per_frame: float, pairs=()) -> None:
+        self.us = float(us_per_frame)
+        pairs = sorted(pairs)
+        self.f = [int(p[0]) for p in pairs]
+        self.t = [float(p[1]) for p in pairs]
+        # 每段的局部帧率（µs/帧）；只有一个锚点时全程退回名义值
+        self.rate = [((self.t[i + 1] - self.t[i]) / (self.f[i + 1] - self.f[i]))
+                     for i in range(len(self.f) - 1)]
+
+    def __len__(self) -> int:
+        return len(self.f)
+
+    def t_of(self, idx: float) -> float:
+        """帧号 -> 时间（µs，**浮点**：调用方按原来的口径自己 `int(round(...))`）。"""
+        if not self.f:
+            return idx * self.us
+        k = bisect.bisect_right(self.f, idx) - 1
+        if k < 0:
+            return self.t[0] - (self.f[0] - idx) * self.us
+        if k >= len(self.f) - 1:
+            return self.t[-1] + (idx - self.f[-1]) * self.us
+        return self.t[k] + (idx - self.f[k]) * self.rate[k]
+
+    def idx_of(self, t_us: float) -> float:
+        """时间（µs）-> 帧号（浮点，同上）。和 `t_of` 严格互逆。"""
+        if not self.t:
+            return t_us / self.us
+        k = bisect.bisect_right(self.t, t_us) - 1
+        if k < 0:
+            return self.f[0] - (self.t[0] - t_us) / self.us
+        if k >= len(self.t) - 1:
+            return self.f[-1] + (t_us - self.t[-1]) / self.us
+        return self.f[k] + (t_us - self.t[k]) / self.rate[k]
+
+
+def index_clock_from_obs(obs_path, us_per_frame: float) -> IndexClock:
+    """从 obs 的逐采样点 `(frame, t_us)` 建 `IndexClock`。只流式扫一遍、按帧号去重；
+    `timebase` 不是 pts 的旧产物一律退回常量换算（那种时间轴本身就不可信，拿来归因的工具一律只认 pts 时间轴）。"""
+    pairs: dict[int, int] = {}
+    with open(obs_path, encoding="utf-8") as fh:
+        meta = json.loads(fh.readline()).get("_meta", {})
+        if meta.get("timebase") != "pts":
+            return IndexClock(us_per_frame)
+        for line in fh:
+            i = line.find('"frame": ')
+            j = line.find('"t_us": ')
+            if i < 0 or j < 0:
+                continue
+            f = int(line[i + 9:line.find(",", i)])
+            if f not in pairs:
+                pairs[f] = int(line[j + 8:line.find(",", j)])
+    return IndexClock(us_per_frame, pairs.items())

flowocr/extract/recdecode.py

@@ -0,0 +1,78 @@
+"""rec 的**前处理 + CTC 贪心解码**：换推理后端时两边共用这一份。
+
+为什么单独一个模块（"判据只有一份"，同 `srtio` / `recpack` 的思路）：
+要把 rec 换到别的运行时（inference-runtime 计划第 2 条），**PaddleX 内部那两段**
+——`RecResizeImg` 的前处理和 `CTCLabelDecode` 的后处理——就必须在我们这边有一份等价实现。
+一旦这份和 PaddleX 对不上，换后端就会静默改文本，而"文本不一样"在下游看起来和"模型不一样"没区别。
+所以：**这份实现先拿 一次性探针 `probe_rec_decode.py` 对着 PaddleX 逐条验，验过了再给后端用。**
+
+口径来自模型自己的 `inference.yml`（不是抄网上的）：
+* `PreProcess.RecResizeImg.image_shape = [3, 48, 320]`、`DecodeImage.img_mode = BGR`
+  （cv2 读出来就是 BGR，**不做通道交换**）；
+* 张量宽用 `recpack.rec_target_w`——**和管线分桶键同一份代码**；
+* `PostProcess.name = CTCLabelDecode`、字表在 `PostProcess.character_dict` 里。
+  标签表 = `['blank'] + 字表 + [' ']`（PaddleOCR 的 `use_space_char`），共 18,710 类。
+"""
+from __future__ import annotations
+
+import functools
+from pathlib import Path
+
+import numpy as np
+
+from flowocr.extract import recpack  # noqa: F401
+# 前处理（裁剪 -> 张量）搬进了 recprep：ORT 服务进程要按文件路径加载它（2026-09-23，decode-buffer）。这里照旧导出
+from flowocr.extract.recprep import REC_H, grid_w, preprocess  # noqa: F401
+
+ITEM = "  - "
+"""`character_dict` 那一段每一项的固定前缀（缩进两格）。"""
+
+
+@functools.lru_cache(maxsize=4)
+def load_labels(model_dir: str) -> tuple[str, ...]:
+    """从模型目录的 `inference.yml` 里读标签表：`['blank'] + character_dict + [' ']`。
+
+    ⚠ 不用 yaml 解析器（生产 venv 里不一定有）：这一段的结构是固定的
+    `PostProcess:` -> `character_dict:` -> 一行一个 `  - <字符>`，直到下一个键。
+
+    ⚠⚠ **不能对整行 `strip()`**：字表里**有空白字符本身**（全角空格 U+3000、` ` 这类），
+    `str.strip()` 认 Unicode 空白，于是 `"  - 　"` 被 strip 成 `"-"`、判成"列表结束"——
+    第一版就这么写的，解析在第 1,750 类上提前收工，解码时 `labels[i]` 直接 IndexError（2026-09-18 实测）。
+    所以按**固定前缀** `ITEM` 切，剩下的部分原样留着。
+
+    读出来的条数**必须**和模型输出的类别数对账（调用方拿 `len(labels)` 比）——18,710 类。
+    """
+    txt = (Path(model_dir) / "inference.yml").read_text(encoding="utf-8").splitlines()
+    try:
+        i = next(k for k, ln in enumerate(txt) if ln.strip() == "character_dict:")
+    except StopIteration:
+        raise ValueError(f"{model_dir}/inference.yml 里没有 PostProcess.character_dict")
+    chars: list[str] = []
+    for ln in txt[i + 1:]:
+        if not ln.startswith(ITEM):
+            break
+        v = ln[len(ITEM):]
+        if len(v) >= 2 and v[0] == v[-1] and v[0] in "'\"":
+            v = v[1:-1].replace("''", "'")
+        chars.append(v)
+    return ("blank", *chars, " ")
+
+
+def ctc_greedy(cls: np.ndarray, prob: np.ndarray, labels: tuple[str, ...]) -> list[tuple[str, float]]:
+    """CTC 贪心解码：逐样本**先并相邻重复、再去 blank**，分数 = 留下那些位置的概率均值。
+
+    `cls` / `prob` 形状都是 [batch, T]（`cls` 是 argmax 的类别，`prob` 是那一位的概率）——
+    正是 argmax 融合过的 ONNX 直接给的两个小张量，也等价于对 logits 自己取 argmax / max。
+    顺序要紧：**先并重复再去 blank**（反过来会把 `ll` 这种叠字并成一个）。
+    """
+    out: list[tuple[str, float]] = []
+    for k in range(cls.shape[0]):
+        ids, ps = cls[k], prob[k]
+        keep = np.ones(len(ids), dtype=bool)
+        keep[1:] = ids[1:] != ids[:-1]
+        keep &= ids != 0
+        sel = np.nonzero(keep)[0]
+        text = "".join(labels[i] for i in ids[sel]) if len(sel) else ""
+        score = float(ps[sel].mean()) if len(sel) else 0.0
+        out.append((text, score))
+    return out