stt_lease.py 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. """Local-STT lifecycle for the desktop voice-input path: warm-up leases.
  2. Desktop voice transcription (``POST /api/audio/transcribe``) blocks until the
  3. configured STT engine answers inside the renderer's timeout floor (180s for a
  4. short clip). With the ``local`` provider that floor also covers the cold cost:
  5. first-use faster-whisper download + model load, or a reload after
  6. ``stt.local.unload_after_idle_seconds`` evicted the cache — on CPU-bound hosts
  7. that alone can exceed the floor, so every attempt times out while the engine
  8. itself is healthy (issue #105955).
  9. Every surface that is about to need speech-to-text holds a *lease* here while
  10. it does (the desktop acquires when the mic opens, releases after the
  11. transcript settles). Acquiring pre-loads the configured local model into the
  12. exact singleton slot transcription reads, so the bill is paid while the user
  13. is still speaking instead of inside the transcription request's timeout.
  14. Mirrors :mod:`tools.tts_tool_lifecycle` with one deliberate divergence:
  15. releasing the last lease does NOT unload the model. The cached local model is
  16. shared with the gateway/CLI/Telegram surfaces in the same backend process —
  17. one surface's "mic closed" must not evict an engine another surface is about
  18. to use. Eviction stays governed by ``stt.local.unload_after_idle_seconds``,
  19. and warming touches the idle timer so a just-warmed model is never
  20. instantly eligible for unload.
  21. """
  22. from __future__ import annotations
  23. import logging
  24. import threading
  25. import time
  26. from typing import Any, Dict, List, Optional
  27. logger = logging.getLogger("tools.stt_lease")
  28. _stt_lease_lock = threading.Lock()
  29. _stt_leases: set = set()
  30. def warm_stt_provider(
  31. stt_config: Optional[dict[str, Any]] = None, provider: Optional[str] = None
  32. ) -> dict[str, Any]:
  33. """Pre-load the configured STT engine so the next transcription starts hot.
  34. Blocking; never raises. Only the ``local`` (faster-whisper) provider has
  35. anything resident: it fills the same cache slot ``_transcribe_local``
  36. reads (including first-use download and lazy install). ``local_command``
  37. shells out to an external binary and cloud providers are remote, so both
  38. are ``action: "noop"``. The result carries ``provider`` / ``warmed`` /
  39. ``action`` / ``error``.
  40. """
  41. from tools import transcription_tools
  42. from tools.transcription_local import _normalize_local_model
  43. if stt_config is None:
  44. stt_config = transcription_tools._load_stt_config()
  45. name = (provider or transcription_tools._get_provider(stt_config) or "").lower().strip()
  46. result: dict[str, Any] = {"provider": name, "warmed": False, "action": "noop"}
  47. if name not in {"local", "local_command"}:
  48. return result
  49. if name == "local_command":
  50. result.update(warmed=True)
  51. return result
  52. if not transcription_tools._HAS_FASTER_WHISPER and not transcription_tools._try_lazy_install_stt():
  53. result.update(action="error", error="faster-whisper not installed")
  54. return result
  55. local_cfg = stt_config.get("local") or {}
  56. # Same name transcription itself resolves (config > default, cloud-only
  57. # names normalized) so warm-up fills the slot the next request reads.
  58. model_name = _normalize_local_model(local_cfg.get("model"))
  59. hot_before = (
  60. transcription_tools._local_model is not None
  61. and transcription_tools._local_model_name == model_name
  62. )
  63. started = time.monotonic()
  64. try:
  65. model = transcription_tools._get_or_load_local_model(model_name, local_cfg)
  66. if model is None: # defensive: load failed without raising
  67. result.update(action="error", error="Local whisper model failed to load")
  68. return result
  69. # A just-warmed model counts as activity: the idle-unload watcher must
  70. # not treat the load itself as idle time and evict it immediately.
  71. transcription_tools._touch_transcription_time()
  72. # Register with the idle-lifetime mechanism: a model loaded ONLY by
  73. # warm-up (mic open → cancel, no transcription) would otherwise sit
  74. # resident with no watcher, silently ignoring
  75. # stt.local.unload_after_idle_seconds until some later successful
  76. # transcription starts one. Also covers the reload-after-prior-eviction
  77. # case (the previous watcher exited after unloading).
  78. idle_timeout = transcription_tools._get_idle_unload_seconds(local_cfg)
  79. if idle_timeout > 0:
  80. transcription_tools._start_idle_unload_watcher(idle_timeout)
  81. except Exception as exc: # engine missing, download failed, bad device…
  82. logger.warning("[STT] warm-up for local model '%s' failed: %s", model_name, exc)
  83. result.update(action="error", error=str(exc))
  84. return result
  85. elapsed_ms = int((time.monotonic() - started) * 1000)
  86. result.update(warmed=True, action="cached" if hot_before else "loaded", elapsed_ms=elapsed_ms)
  87. logger.info("[STT] warm-up local model '%s': %s in %dms", model_name, result["action"], elapsed_ms)
  88. return result
  89. def acquire_stt_lease(lease: str, stt_config: Optional[dict[str, Any]] = None) -> dict[str, Any]:
  90. """Register ``lease`` (e.g. ``"desktop:voice-input:abcd1234"``) and warm the engine.
  91. Re-acquiring is idempotent but still re-warms (cheap on a cache hit; heals
  92. a cache the idle-unload watcher cleared meanwhile).
  93. """
  94. with _stt_lease_lock:
  95. _stt_leases.add(lease)
  96. holders = len(_stt_leases)
  97. return {**warm_stt_provider(stt_config), "leases": holders}
  98. def release_stt_lease(lease: str) -> dict[str, Any]:
  99. """Drop ``lease``. A never-acquired lease is a no-op (still reports the
  100. holder count) so surfaces can call this unconditionally. Never unloads the
  101. model — see the module docstring for why this diverges from TTS leases."""
  102. with _stt_lease_lock:
  103. _stt_leases.discard(lease)
  104. holders = len(_stt_leases)
  105. return {"leases": holders}
  106. def stt_lease_holders() -> list[str]:
  107. """Snapshot of live lease names (diagnostics / tests)."""
  108. with _stt_lease_lock:
  109. return sorted(_stt_leases)
  110. def _reset_stt_leases_for_tests() -> None:
  111. with _stt_lease_lock:
  112. _stt_leases.clear()