mirror of
https://github.com/nomadkaraoke/karaoke-gen.git
synced 2026-11-20 13:07:57 +09:00
Compare commits
4
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
e8b3c6a28b | ||
|
|
666ee965a9 | ||
|
|
1600641b5b | ||
|
|
4f8dac0161 |
No files matched your search
+9
-1
@@ -10,6 +10,7 @@ from backend.config import settings
|
||||
from backend.api.routes import health, jobs, internal, file_upload, review, auth, audio_search, themes, users, admin
|
||||
from backend.services.tracing import setup_tracing, instrument_app, get_current_trace_id
|
||||
from backend.services.structured_logging import setup_structured_logging
|
||||
from backend.services.spacy_preloader import preload_spacy_model
|
||||
from backend.middleware.audit_logging import AuditLoggingMiddleware
|
||||
|
||||
|
||||
@@ -67,7 +68,14 @@ async def lifespan(app: FastAPI):
|
||||
logger.info(f"Environment: {settings.environment}")
|
||||
logger.info(f"GCS Bucket: {settings.gcs_bucket_name}")
|
||||
logger.info(f"Tracing enabled: {tracing_enabled}")
|
||||
|
||||
|
||||
# Preload SpaCy model to avoid 60+ second delay on first request
|
||||
# See docs/archive/2026-01-08-spacy-preload-plan.md for background
|
||||
try:
|
||||
preload_spacy_model("en_core_web_sm")
|
||||
except Exception as e:
|
||||
logger.warning(f"SpaCy preload failed (will load lazily): {e}")
|
||||
|
||||
# Validate OAuth credentials (non-blocking)
|
||||
try:
|
||||
await validate_credentials_on_startup()
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
"""SpaCy model preloader for container startup.
|
||||
|
||||
Loads SpaCy models at container startup to avoid slow loading during request processing.
|
||||
Cloud Run filesystem I/O can cause 60+ second delays when loading SpaCy models lazily.
|
||||
"""
|
||||
|
||||
import logging
|
||||
import time
|
||||
from typing import Optional
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Singleton storage for preloaded models
|
||||
_preloaded_models: dict = {}
|
||||
|
||||
|
||||
def preload_spacy_model(model_name: str = "en_core_web_sm") -> None:
|
||||
"""Preload a SpaCy model at startup.
|
||||
|
||||
Args:
|
||||
model_name: The SpaCy model to load (default: en_core_web_sm)
|
||||
"""
|
||||
global _preloaded_models
|
||||
|
||||
if model_name in _preloaded_models:
|
||||
logger.info(f"SpaCy model '{model_name}' already preloaded")
|
||||
return
|
||||
|
||||
logger.info(f"Preloading SpaCy model '{model_name}'...")
|
||||
start_time = time.time()
|
||||
|
||||
try:
|
||||
import spacy
|
||||
|
||||
nlp = spacy.load(model_name)
|
||||
_preloaded_models[model_name] = nlp
|
||||
|
||||
elapsed = time.time() - start_time
|
||||
logger.info(f"SpaCy model '{model_name}' preloaded in {elapsed:.2f}s")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to preload SpaCy model '{model_name}': {e}")
|
||||
raise
|
||||
|
||||
|
||||
def get_preloaded_model(model_name: str = "en_core_web_sm") -> Optional[object]:
|
||||
"""Get a preloaded SpaCy model if available.
|
||||
|
||||
Args:
|
||||
model_name: The SpaCy model name
|
||||
|
||||
Returns:
|
||||
The preloaded SpaCy Language object, or None if not preloaded
|
||||
"""
|
||||
return _preloaded_models.get(model_name)
|
||||
|
||||
|
||||
def is_model_preloaded(model_name: str = "en_core_web_sm") -> bool:
|
||||
"""Check if a SpaCy model has been preloaded."""
|
||||
return model_name in _preloaded_models
|
||||
|
||||
|
||||
def clear_preloaded_models() -> None:
|
||||
"""Clear all preloaded models. Useful for testing."""
|
||||
global _preloaded_models
|
||||
_preloaded_models.clear()
|
||||
@@ -0,0 +1,119 @@
|
||||
"""Tests for SpaCy preloader service."""
|
||||
|
||||
import pytest
|
||||
from unittest.mock import patch, MagicMock
|
||||
|
||||
from backend.services.spacy_preloader import (
|
||||
preload_spacy_model,
|
||||
get_preloaded_model,
|
||||
is_model_preloaded,
|
||||
clear_preloaded_models,
|
||||
)
|
||||
|
||||
|
||||
class TestSpacyPreloader:
|
||||
"""Tests for SpaCy preloading functionality."""
|
||||
|
||||
def setup_method(self):
|
||||
"""Clear preloaded models before each test."""
|
||||
clear_preloaded_models()
|
||||
|
||||
def teardown_method(self):
|
||||
"""Clear preloaded models after each test."""
|
||||
clear_preloaded_models()
|
||||
|
||||
def test_preload_spacy_model_loads_and_stores(self):
|
||||
"""GIVEN no preloaded models
|
||||
WHEN preload_spacy_model is called
|
||||
THEN model should be loaded and stored in singleton."""
|
||||
mock_nlp = MagicMock()
|
||||
|
||||
with patch("spacy.load", return_value=mock_nlp) as mock_load:
|
||||
preload_spacy_model("en_core_web_sm")
|
||||
|
||||
mock_load.assert_called_once_with("en_core_web_sm")
|
||||
assert is_model_preloaded("en_core_web_sm")
|
||||
assert get_preloaded_model("en_core_web_sm") is mock_nlp
|
||||
|
||||
def test_preload_is_idempotent(self):
|
||||
"""GIVEN a model already preloaded
|
||||
WHEN preload_spacy_model is called again
|
||||
THEN model should not be reloaded."""
|
||||
mock_nlp = MagicMock()
|
||||
|
||||
with patch("spacy.load", return_value=mock_nlp) as mock_load:
|
||||
preload_spacy_model("en_core_web_sm")
|
||||
preload_spacy_model("en_core_web_sm") # Second call
|
||||
|
||||
# Should only load once
|
||||
assert mock_load.call_count == 1
|
||||
|
||||
def test_get_preloaded_model_returns_none_if_not_loaded(self):
|
||||
"""GIVEN no preloaded models
|
||||
WHEN get_preloaded_model is called
|
||||
THEN should return None."""
|
||||
assert get_preloaded_model("en_core_web_sm") is None
|
||||
assert not is_model_preloaded("en_core_web_sm")
|
||||
|
||||
def test_preload_different_models(self):
|
||||
"""GIVEN no preloaded models
|
||||
WHEN preload_spacy_model is called with different model names
|
||||
THEN each model should be loaded and stored separately."""
|
||||
mock_nlp_sm = MagicMock(name="en_core_web_sm")
|
||||
mock_nlp_md = MagicMock(name="en_core_web_md")
|
||||
|
||||
def mock_load(model_name):
|
||||
if model_name == "en_core_web_sm":
|
||||
return mock_nlp_sm
|
||||
elif model_name == "en_core_web_md":
|
||||
return mock_nlp_md
|
||||
raise ValueError(f"Unknown model: {model_name}")
|
||||
|
||||
with patch("spacy.load", side_effect=mock_load):
|
||||
preload_spacy_model("en_core_web_sm")
|
||||
preload_spacy_model("en_core_web_md")
|
||||
|
||||
assert is_model_preloaded("en_core_web_sm")
|
||||
assert is_model_preloaded("en_core_web_md")
|
||||
assert get_preloaded_model("en_core_web_sm") is mock_nlp_sm
|
||||
assert get_preloaded_model("en_core_web_md") is mock_nlp_md
|
||||
|
||||
def test_clear_preloaded_models(self):
|
||||
"""GIVEN preloaded models
|
||||
WHEN clear_preloaded_models is called
|
||||
THEN all models should be removed."""
|
||||
mock_nlp = MagicMock()
|
||||
|
||||
with patch("spacy.load", return_value=mock_nlp):
|
||||
preload_spacy_model("en_core_web_sm")
|
||||
assert is_model_preloaded("en_core_web_sm")
|
||||
|
||||
clear_preloaded_models()
|
||||
assert not is_model_preloaded("en_core_web_sm")
|
||||
assert get_preloaded_model("en_core_web_sm") is None
|
||||
|
||||
def test_preload_failure_raises_exception(self):
|
||||
"""GIVEN spacy.load raises an exception
|
||||
WHEN preload_spacy_model is called
|
||||
THEN exception should be propagated."""
|
||||
with patch(
|
||||
"spacy.load",
|
||||
side_effect=OSError("Model not found"),
|
||||
):
|
||||
with pytest.raises(OSError, match="Model not found"):
|
||||
preload_spacy_model("nonexistent_model")
|
||||
|
||||
# Model should not be marked as preloaded
|
||||
assert not is_model_preloaded("nonexistent_model")
|
||||
|
||||
def test_preload_uses_default_model_name(self):
|
||||
"""GIVEN no model name specified
|
||||
WHEN preload_spacy_model is called without arguments
|
||||
THEN should use en_core_web_sm as default."""
|
||||
mock_nlp = MagicMock()
|
||||
|
||||
with patch("spacy.load", return_value=mock_nlp) as mock_load:
|
||||
preload_spacy_model()
|
||||
|
||||
mock_load.assert_called_once_with("en_core_web_sm")
|
||||
assert is_model_preloaded("en_core_web_sm")
|
||||
@@ -993,6 +993,70 @@ class LangChainBridge:
|
||||
|
||||
**Testing**: Write tests that use `threading.Barrier` to ensure multiple threads hit the initialization check simultaneously, then assert the initialization function was called exactly once.
|
||||
|
||||
### Preloading Heavy Resources at Container Startup
|
||||
|
||||
**Problem**: Lazy-loading heavy resources (like SpaCy NLP models) during request processing can cause 60+ second delays on Cloud Run due to slow filesystem I/O during cold starts. The first request after deployment/scaling pays the full load penalty.
|
||||
|
||||
**Example bug**: `PhraseAnalyzer` loaded SpaCy's `en_core_web_sm` model lazily on first use during agentic lyrics correction. On Cloud Run, this took 63 seconds due to container filesystem being slower than local SSD. Job `2ccbdf6b` showed 73-second gap between "Initializing PhraseAnalyzer" and "Initialized AnchorSequenceFinder" logs.
|
||||
|
||||
**Symptoms**:
|
||||
- First job after deployment is extremely slow
|
||||
- Large time gaps in logs between "loading X" and "using X"
|
||||
- Same code runs much faster locally (where filesystem is faster)
|
||||
- Subsequent requests (warm container) are fast
|
||||
|
||||
**Solution**: Preload heavy resources at container startup using FastAPI's lifespan handler:
|
||||
|
||||
```python
|
||||
# backend/services/spacy_preloader.py - singleton storage
|
||||
_preloaded_models: dict = {}
|
||||
|
||||
def preload_spacy_model(model_name: str = "en_core_web_sm") -> None:
|
||||
if model_name not in _preloaded_models:
|
||||
_preloaded_models[model_name] = spacy.load(model_name)
|
||||
|
||||
def get_preloaded_model(model_name: str) -> Optional[object]:
|
||||
return _preloaded_models.get(model_name)
|
||||
|
||||
# backend/main.py - load at startup
|
||||
@asynccontextmanager
|
||||
async def lifespan(app: FastAPI):
|
||||
preload_spacy_model("en_core_web_sm") # Pay cost once at startup
|
||||
yield
|
||||
```
|
||||
|
||||
Then modify consumers to check for preloaded model:
|
||||
```python
|
||||
class PhraseAnalyzer:
|
||||
def __init__(self):
|
||||
preloaded = get_preloaded_model("en_core_web_sm")
|
||||
if preloaded:
|
||||
self.nlp = preloaded # Fast path
|
||||
else:
|
||||
self.nlp = spacy.load("en_core_web_sm") # Fallback
|
||||
```
|
||||
|
||||
**Key insight**: On Cloud Run, container startup time doesn't directly impact users (they don't see the startup delay), but request processing time does. Moving heavy initialization from request-time to startup-time improves user experience even if total work is the same.
|
||||
|
||||
**Good candidates for preloading**:
|
||||
- ML model files (SpaCy, transformers, etc.)
|
||||
- Large data files
|
||||
- Expensive-to-initialize clients
|
||||
- Anything that touches the filesystem heavily
|
||||
|
||||
**Not worth preloading**:
|
||||
- Fast in-memory operations
|
||||
- Resources that vary per-request
|
||||
- Rarely-used code paths
|
||||
|
||||
**Logging**: Add timing logs to both startup preload and usage paths so you can verify the optimization is working:
|
||||
```
|
||||
# At startup: "SpaCy model 'en_core_web_sm' preloaded in 2.34s"
|
||||
# During request: "Using preloaded SpaCy model: en_core_web_sm"
|
||||
```
|
||||
|
||||
See `docs/archive/2026-01-08-spacy-preload-plan.md` for full implementation details.
|
||||
|
||||
## Performance Observations
|
||||
|
||||
| Operation | Duration |
|
||||
|
||||
@@ -34,8 +34,16 @@
|
||||
|
||||
- CDG format generation requires additional style configuration
|
||||
|
||||
## Pending Work
|
||||
|
||||
(No pending work items)
|
||||
|
||||
## Recent Changes
|
||||
|
||||
- **SpaCy Preloading** (2026-01-08): Implemented SpaCy model preloading at container startup to eliminate 60+ second delay during agentic correction. The `en_core_web_sm` model is now loaded during FastAPI lifespan startup, and `PhraseAnalyzer`/`SyllablesMatchHandler` reuse the preloaded model. Added timing logs to verify performance. See [archive/2026-01-08-spacy-preload-plan.md](archive/2026-01-08-spacy-preload-plan.md).
|
||||
|
||||
- **Thread-Safe LangChain Model Initialization** (2026-01-08): Fixed race condition in `LangChainBridge` where parallel threads could all try to initialize the AI model simultaneously, causing 6+ minute delays. Added double-checked locking with `threading.Lock()`. PR #232. See [LESSONS-LEARNED.md](LESSONS-LEARNED.md#thread-safe-lazy-initialization-in-shared-components).
|
||||
|
||||
- **Brand Consistency & Style Guide** (2026-01-07): Implemented unified brand theming across all Nomad Karaoke frontends. Primary color changed from blue to brand pink (#ff7acc). Added comprehensive [BRAND-STYLE-GUIDE.md](BRAND-STYLE-GUIDE.md) for human and LLM reference. Includes: CSS variables for light/dark mode, MUI theme updates for lyrics transcriber, email template branding, and Playwright visual tests. See [BRAND-STYLE-GUIDE.md](BRAND-STYLE-GUIDE.md).
|
||||
|
||||
- **Audio Search Display Override** (2026-01-06): Added optional "Display As" fields to audio search, allowing users to search for audio by one artist/title (e.g., "Jeremy Kushnier") but display a different artist/title on title screens and filenames (e.g., "Footloose (Broadway Cast)"). Useful for Broadway casts, covers, remixes where tracker metadata differs from desired display. See [API.md](API.md#audio-search).
|
||||
|
||||
@@ -0,0 +1,270 @@
|
||||
# Implementation Plan: SpaCy Preloading at Container Startup
|
||||
|
||||
**Date**: 2026-01-08
|
||||
**Status**: Ready for implementation
|
||||
**Related Issue**: Job `2ccbdf6b` slow execution investigation
|
||||
**Related PR**: #232 (thread-safety fix - already merged)
|
||||
|
||||
## Background
|
||||
|
||||
Job `2ccbdf6b` (ABBA - Waterloo) took 17 minutes instead of ~5 minutes expected. Investigation revealed two issues:
|
||||
|
||||
1. **FIXED (PR #232)**: Race condition in `LangChainBridge` where 5 parallel threads all tried to initialize the AI model simultaneously, causing 6+ minute delays.
|
||||
|
||||
2. **PENDING (this plan)**: SpaCy model loading takes ~63 seconds even on warm Cloud Run instances. This happens when `PhraseAnalyzer` is first instantiated during request processing.
|
||||
|
||||
## Problem Details
|
||||
|
||||
From job `2ccbdf6b` worker logs:
|
||||
|
||||
- `04:10:21` - "Initializing PhraseAnalyzer with language model: en_core_web_sm"
|
||||
- `04:11:24` - "Initialized AnchorSequenceFinder" (63 seconds later)
|
||||
|
||||
Key observations:
|
||||
- **SpaCy model**: `en_core_web_sm` (~14MB) is already pre-downloaded in `backend/Dockerfile.base` line 64
|
||||
- **Cloud Run config**: `min-instances: 4` configured - instances are warm
|
||||
- **Root cause**: SpaCy loads lazily when first needed during request processing, not at container startup
|
||||
- **Cloud Run I/O**: Filesystem access on Cloud Run can be slow, causing extended load times
|
||||
|
||||
## Solution: Preload SpaCy at Container Startup
|
||||
|
||||
Load SpaCy during FastAPI lifespan handler (before accepting requests) and make it available as a singleton for reuse.
|
||||
|
||||
## Files to Create/Modify
|
||||
|
||||
### 1. NEW: `backend/services/spacy_preloader.py`
|
||||
|
||||
Create a new module to handle SpaCy preloading:
|
||||
|
||||
```python
|
||||
"""SpaCy model preloader for container startup.
|
||||
|
||||
Loads SpaCy models at container startup to avoid slow loading during request processing.
|
||||
Cloud Run filesystem I/O can cause 60+ second delays when loading SpaCy models lazily.
|
||||
"""
|
||||
import logging
|
||||
import time
|
||||
from typing import Optional
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Singleton storage for preloaded models
|
||||
_preloaded_models: dict = {}
|
||||
|
||||
|
||||
def preload_spacy_model(model_name: str = "en_core_web_sm") -> None:
|
||||
"""Preload a SpaCy model at startup.
|
||||
|
||||
Args:
|
||||
model_name: The SpaCy model to load (default: en_core_web_sm)
|
||||
"""
|
||||
global _preloaded_models
|
||||
|
||||
if model_name in _preloaded_models:
|
||||
logger.info(f"SpaCy model '{model_name}' already preloaded")
|
||||
return
|
||||
|
||||
logger.info(f"Preloading SpaCy model '{model_name}'...")
|
||||
start_time = time.time()
|
||||
|
||||
try:
|
||||
import spacy
|
||||
nlp = spacy.load(model_name)
|
||||
_preloaded_models[model_name] = nlp
|
||||
|
||||
elapsed = time.time() - start_time
|
||||
logger.info(f"SpaCy model '{model_name}' preloaded in {elapsed:.2f}s")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to preload SpaCy model '{model_name}': {e}")
|
||||
raise
|
||||
|
||||
|
||||
def get_preloaded_model(model_name: str = "en_core_web_sm") -> Optional[object]:
|
||||
"""Get a preloaded SpaCy model if available.
|
||||
|
||||
Args:
|
||||
model_name: The SpaCy model name
|
||||
|
||||
Returns:
|
||||
The preloaded SpaCy Language object, or None if not preloaded
|
||||
"""
|
||||
return _preloaded_models.get(model_name)
|
||||
|
||||
|
||||
def is_model_preloaded(model_name: str = "en_core_web_sm") -> bool:
|
||||
"""Check if a SpaCy model has been preloaded."""
|
||||
return model_name in _preloaded_models
|
||||
```
|
||||
|
||||
### 2. MODIFY: `backend/main.py`
|
||||
|
||||
Add SpaCy preloading to the lifespan handler. Current code is at lines 62-80.
|
||||
|
||||
**Add import at top of file:**
|
||||
```python
|
||||
from backend.services.spacy_preloader import preload_spacy_model
|
||||
```
|
||||
|
||||
**Modify lifespan function (around line 62):**
|
||||
```python
|
||||
@asynccontextmanager
|
||||
async def lifespan(app: FastAPI):
|
||||
"""Lifespan event handler for startup and shutdown."""
|
||||
# Startup
|
||||
logger.info("Starting karaoke generation backend")
|
||||
logger.info(f"Environment: {settings.environment}")
|
||||
logger.info(f"GCS Bucket: {settings.gcs_bucket_name}")
|
||||
logger.info(f"Tracing enabled: {tracing_enabled}")
|
||||
|
||||
# Preload SpaCy model to avoid 60+ second delay on first request
|
||||
try:
|
||||
preload_spacy_model("en_core_web_sm")
|
||||
except Exception as e:
|
||||
logger.warning(f"SpaCy preload failed (will load lazily): {e}")
|
||||
|
||||
# Validate OAuth credentials (non-blocking)
|
||||
try:
|
||||
await validate_credentials_on_startup()
|
||||
except Exception as e:
|
||||
logger.error(f"Credential validation failed: {e}")
|
||||
|
||||
yield
|
||||
|
||||
# Shutdown
|
||||
logger.info("Shutting down karaoke generation backend")
|
||||
```
|
||||
|
||||
### 3. MODIFY: `lyrics_transcriber_temp/lyrics_transcriber/correction/phrase_analyzer.py`
|
||||
|
||||
The `PhraseAnalyzer` class loads SpaCy in its `__init__` method. Modify to use preloaded model if available.
|
||||
|
||||
**Add imports at top:**
|
||||
```python
|
||||
# Try to import preloader (may not exist in standalone library usage)
|
||||
try:
|
||||
from backend.services.spacy_preloader import get_preloaded_model
|
||||
_HAS_PRELOADER = True
|
||||
except ImportError:
|
||||
_HAS_PRELOADER = False
|
||||
```
|
||||
|
||||
**Modify `__init__` method:**
|
||||
```python
|
||||
def __init__(self, logger: logging.Logger, language_code: str = "en_core_web_sm"):
|
||||
self.logger = logger
|
||||
|
||||
# Try to use preloaded model first (avoids 60+ second load on Cloud Run)
|
||||
if _HAS_PRELOADER:
|
||||
preloaded = get_preloaded_model(language_code)
|
||||
if preloaded is not None:
|
||||
self.logger.info(f"Using preloaded SpaCy model: {language_code}")
|
||||
self.nlp = preloaded
|
||||
return
|
||||
|
||||
# Fall back to loading model directly
|
||||
self.logger.info(f"Initializing PhraseAnalyzer with language model: {language_code}")
|
||||
try:
|
||||
self.nlp = spacy.load(language_code)
|
||||
except OSError:
|
||||
# ... keep existing download fallback code ...
|
||||
```
|
||||
|
||||
### 4. MODIFY: `lyrics_transcriber_temp/lyrics_transcriber/correction/handlers/syllables_match.py`
|
||||
|
||||
This file also loads SpaCy. Apply the same pattern.
|
||||
|
||||
**Add imports at top:**
|
||||
```python
|
||||
try:
|
||||
from backend.services.spacy_preloader import get_preloaded_model
|
||||
_HAS_PRELOADER = True
|
||||
except ImportError:
|
||||
_HAS_PRELOADER = False
|
||||
```
|
||||
|
||||
**Modify the SpaCy loading section in `__init__`:**
|
||||
```python
|
||||
# Try to use preloaded model first
|
||||
if _HAS_PRELOADER:
|
||||
preloaded = get_preloaded_model("en_core_web_sm")
|
||||
if preloaded is not None:
|
||||
self.logger.info("Using preloaded SpaCy model for syllable analysis")
|
||||
self.nlp = preloaded
|
||||
# Still need to add syllables component if not present
|
||||
if "syllables" not in self.nlp.pipe_names:
|
||||
self.nlp.add_pipe("syllables", after="tagger")
|
||||
return
|
||||
|
||||
# ... existing loading code as fallback ...
|
||||
```
|
||||
|
||||
## Testing Approach
|
||||
|
||||
### Unit Tests for Preloader
|
||||
|
||||
See `backend/tests/test_spacy_preloader.py` for the actual implementation. Key tests:
|
||||
|
||||
- `test_preload_spacy_model_loads_and_stores` - Verifies model is loaded and stored
|
||||
- `test_preload_is_idempotent` - Verifies repeated calls don't reload
|
||||
- `test_get_preloaded_model_returns_none_if_not_loaded` - Verifies None returned when not preloaded
|
||||
- `test_preload_different_models` - Verifies multiple models can be preloaded
|
||||
- `test_clear_preloaded_models` - Verifies clearing works
|
||||
- `test_preload_failure_raises_exception` - Verifies errors propagate
|
||||
- `test_preload_uses_default_model_name` - Verifies default is en_core_web_sm
|
||||
|
||||
All tests use `clear_preloaded_models()` in setup/teardown for isolation.
|
||||
|
||||
### Integration Verification
|
||||
|
||||
After deployment, check Cloud Run logs:
|
||||
|
||||
1. **At startup**: Look for "SpaCy model 'en_core_web_sm' preloaded in X.XXs"
|
||||
2. **During job processing**: Look for "Using preloaded SpaCy model: en_core_web_sm"
|
||||
3. **Timing**: Verify no 60+ second gaps in agentic correction phase
|
||||
|
||||
## Expected Outcomes
|
||||
|
||||
1. **Startup time**: SpaCy load time (~60s) moves from request processing to container startup
|
||||
2. **Request latency**: First agentic correction request no longer has 60+ second SpaCy delay
|
||||
3. **Visibility**: Clear logs showing preload time at startup
|
||||
4. **Total job time**: Agentic correction phase should complete in ~5 minutes instead of ~17 minutes
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Create new worktree:
|
||||
```bash
|
||||
cd /Users/andrew/Projects/karaoke-gen-multiagent/karaoke-gen
|
||||
git worktree add -b feat/spacy-preload ../karaoke-gen-spacy-preload origin/main
|
||||
cd ../karaoke-gen-spacy-preload
|
||||
```
|
||||
|
||||
2. Create `backend/services/spacy_preloader.py`
|
||||
|
||||
3. Modify `backend/main.py` to add preloading in lifespan
|
||||
|
||||
4. Modify `lyrics_transcriber_temp/lyrics_transcriber/correction/phrase_analyzer.py`
|
||||
|
||||
5. Modify `lyrics_transcriber_temp/lyrics_transcriber/correction/handlers/syllables_match.py`
|
||||
|
||||
6. Create unit tests for the preloader
|
||||
|
||||
7. Run tests:
|
||||
```bash
|
||||
make test 2>&1 | tail -n 500
|
||||
```
|
||||
|
||||
8. Bump version in `pyproject.toml`
|
||||
|
||||
9. Follow standard PR workflow: `/docs-review` -> `/coderabbit` -> `/pr`
|
||||
|
||||
## Risk Considerations
|
||||
|
||||
- **Startup time increase**: Container startup will take ~60s longer, but this happens once per container lifecycle, not per request
|
||||
- **Memory usage**: SpaCy model (~50MB in memory) will persist for container lifetime - acceptable tradeoff
|
||||
- **Import error handling**: Graceful fallback if preloader module unavailable (library standalone use case)
|
||||
|
||||
## Related Files Reference
|
||||
|
||||
- `backend/Dockerfile.base:64` - SpaCy model download at build time
|
||||
- `infrastructure/cloudrun.ts` - Cloud Run configuration (min-instances: 4)
|
||||
- `docs/LESSONS-LEARNED.md` - Contains thread-safety lesson from related fix
|
||||
@@ -32,19 +32,24 @@ class AnchorSequenceFinder:
|
||||
progress_check_interval: int = 50, # Check progress every N iterations
|
||||
logger: Optional[logging.Logger] = None,
|
||||
):
|
||||
init_start = time.time()
|
||||
self.min_sequence_length = min_sequence_length
|
||||
self.min_sources = min_sources
|
||||
self.timeout_seconds = timeout_seconds
|
||||
self.max_iterations_per_ngram = max_iterations_per_ngram
|
||||
self.progress_check_interval = progress_check_interval
|
||||
self.logger = logger or logging.getLogger(__name__)
|
||||
|
||||
self.logger.info("Initializing AnchorSequenceFinder...")
|
||||
self.phrase_analyzer = PhraseAnalyzer(logger=self.logger)
|
||||
self.used_positions = {}
|
||||
|
||||
# Initialize cache directory
|
||||
self.cache_dir = Path(cache_dir)
|
||||
self.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
self.logger.info(f"Initialized AnchorSequenceFinder with cache dir: {self.cache_dir}, timeout: {timeout_seconds}s")
|
||||
|
||||
init_elapsed = time.time() - init_start
|
||||
self.logger.info(f"Initialized AnchorSequenceFinder in {init_elapsed:.2f}s (cache: {self.cache_dir}, timeout: {timeout_seconds}s)")
|
||||
|
||||
def _check_timeout(self, start_time: float, operation_name: str = "operation"):
|
||||
"""Check if timeout has occurred and raise exception if so."""
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
from typing import List, Tuple, Dict, Any, Optional
|
||||
import spacy
|
||||
import logging
|
||||
import time
|
||||
import pyphen
|
||||
import nltk
|
||||
from nltk.corpus import cmudict
|
||||
@@ -11,6 +12,14 @@ from lyrics_transcriber.types import GapSequence, WordCorrection
|
||||
from lyrics_transcriber.correction.handlers.base import GapCorrectionHandler
|
||||
from lyrics_transcriber.correction.handlers.word_operations import WordOperations
|
||||
|
||||
# Try to import preloader (may not exist in standalone library usage)
|
||||
try:
|
||||
from backend.services.spacy_preloader import get_preloaded_model
|
||||
|
||||
_HAS_PRELOADER = True
|
||||
except ImportError:
|
||||
_HAS_PRELOADER = False
|
||||
|
||||
|
||||
class SyllablesMatchHandler(GapCorrectionHandler):
|
||||
"""Handles gaps where number of syllables in reference text matches number of syllables in transcription."""
|
||||
@@ -18,11 +27,27 @@ class SyllablesMatchHandler(GapCorrectionHandler):
|
||||
def __init__(self, logger: Optional[logging.Logger] = None):
|
||||
super().__init__(logger)
|
||||
self.logger = logger or logging.getLogger(__name__)
|
||||
init_start = time.time()
|
||||
|
||||
# Marking SpacySyllables as used to prevent unused import warning
|
||||
_ = SpacySyllables
|
||||
|
||||
# Load spacy model with syllables pipeline
|
||||
# Try to use preloaded model first (avoids 60+ second load on Cloud Run)
|
||||
if _HAS_PRELOADER:
|
||||
preloaded = get_preloaded_model("en_core_web_sm")
|
||||
if preloaded is not None:
|
||||
self.logger.info("Using preloaded SpaCy model for syllable analysis")
|
||||
self.nlp = preloaded
|
||||
# Add syllables component if not already present
|
||||
if "syllables" not in self.nlp.pipe_names:
|
||||
self.nlp.add_pipe("syllables", after="tagger")
|
||||
self._init_nltk_resources()
|
||||
init_elapsed = time.time() - init_start
|
||||
self.logger.info(f"Initialized SyllablesMatchHandler in {init_elapsed:.2f}s (preloaded)")
|
||||
return
|
||||
|
||||
# Fall back to loading model directly
|
||||
self.logger.info("Loading SpaCy model for syllable analysis (not preloaded)...")
|
||||
try:
|
||||
self.nlp = spacy.load("en_core_web_sm")
|
||||
except OSError:
|
||||
@@ -43,6 +68,13 @@ class SyllablesMatchHandler(GapCorrectionHandler):
|
||||
if "syllables" not in self.nlp.pipe_names:
|
||||
self.nlp.add_pipe("syllables", after="tagger")
|
||||
|
||||
self._init_nltk_resources()
|
||||
init_elapsed = time.time() - init_start
|
||||
self.logger.info(f"Initialized SyllablesMatchHandler in {init_elapsed:.2f}s (lazy loaded)")
|
||||
|
||||
def _init_nltk_resources(self):
|
||||
"""Initialize NLTK resources (Pyphen and CMU dictionary)."""
|
||||
|
||||
# Initialize Pyphen for English
|
||||
self.dic = pyphen.Pyphen(lang="en_US")
|
||||
|
||||
|
||||
@@ -5,6 +5,14 @@ import logging
|
||||
from lyrics_transcriber.correction.text_utils import clean_text
|
||||
from lyrics_transcriber.types import PhraseType, PhraseScore
|
||||
|
||||
# Try to import preloader (may not exist in standalone library usage)
|
||||
try:
|
||||
from backend.services.spacy_preloader import get_preloaded_model
|
||||
|
||||
_HAS_PRELOADER = True
|
||||
except ImportError:
|
||||
_HAS_PRELOADER = False
|
||||
|
||||
|
||||
class PhraseAnalyzer:
|
||||
"""Language-agnostic phrase analyzer using spaCy"""
|
||||
@@ -17,6 +25,16 @@ class PhraseAnalyzer:
|
||||
language_code: spaCy language model to use
|
||||
"""
|
||||
self.logger = logger
|
||||
|
||||
# Try to use preloaded model first (avoids 60+ second load on Cloud Run)
|
||||
if _HAS_PRELOADER:
|
||||
preloaded = get_preloaded_model(language_code)
|
||||
if preloaded is not None:
|
||||
self.logger.info(f"Using preloaded SpaCy model: {language_code}")
|
||||
self.nlp = preloaded
|
||||
return
|
||||
|
||||
# Fall back to loading model directly
|
||||
self.logger.info(f"Initializing PhraseAnalyzer with language model: {language_code}")
|
||||
try:
|
||||
self.nlp = spacy.load(language_code)
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[tool.poetry]
|
||||
name = "karaoke-gen"
|
||||
version = "0.96.0"
|
||||
version = "0.97.0"
|
||||
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
|
||||
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
|
||||
license = "MIT"
|
||||
|
||||
Reference in new issue
Block a user