Class OcrService

app/services/ocr_service.py:104–418

Run the vendored TenVision captcha OCR pipeline in this project.

                details={"missing_dependencies": missing},
            )
        self._bootstrap_engine_once()
        executor = self._ensure_executor()
        timeout = max(self.settings.tencent_ocr_timeout_seconds, 1)
        # 首次启动先保证模型在主进程完整落地，再做单 worker 预热，
        # 避免 Windows 下多个进程同时下载/加载同一个 onnx 文件导致文件占用和损坏竞争。
        future = executor.submit(_warmup_worker, 0)
        future.result(timeout=timeout)

    def shutdown(self) -> None:
        with self._executor_lock:
            if self._executor is None:
                return
            self._executor.shutdown(wait=False, cancel_futures=True)
            self._executor = None

    def analyze_captcha_image(self, image_bytes: bytes, *, prompt_text: str) -> dict[str, Any]:
        if not self.settings.tencent_ocr_enabled:
            raise BadRequestError("本地 OCR 已关闭，请设置 TENCENT_OCR_ENABLED=1")

        missing = self._missing_dependencies()
        if missing:
            raise BadRequestError(
                "本地 OCR 依赖没装全，先运行 pip install -r requirements.txt，别让发动机缺缸还硬跑。",
                details={"missing_dependencies": missing},
            )

        try:
            result = self._run_worker(image_bytes, prompt_text)
        except FuturesTimeoutError as exc:
            raise BadRequestError(
                "验证码 OCR 识别超时",
                details={"timeout_seconds": self.settings.tencent_ocr_timeout_seconds},
            ) from exc
        except Exception as exc:
            raise BadRequestError("验证码 OCR 识别失败", details={"reason": str(exc)}) from exc

        return self._normalize_result(result)

    def _run_worker(self, image_bytes: bytes, prompt_text: str) -> dict[str, Any]:
        timeout = max(self.settings.tencent_ocr_timeout_seconds, 1)
        payload_prompt = prompt_text or ""
        self._bootstrap_engine_once()
        for attempt in range(1, 3):
            executor = self._ensure_executor()
            future = executor.submit(
                _worker_analyze,
                image_bytes,
                payload_prompt,
                self.settings.tencent_ocr_include_debug,
            )
            try:
                return future.result(timeout=timeout)
            except FuturesTimeoutError:
                future.cancel()
                raise
            except BrokenProcessPool:
                self.shutdown()
                if attempt >= 2: