From 60331e609a2caba4bf207595549e0182614684bb Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 02:44:02 +0000 Subject: [PATCH] fix(server): warm BGE-M3 through patchable loaders Resources.startup warmed BGE-M3 through _get_tokenizer and _get_model imported by name from server.query_encoder, which binds the original functions when resources.py is first imported. Tests that mock the model patch server.query_encoder, so the startup warm-up never saw the mock. Every test that boots the server loaded the real 2.3 GB model wherever it was cached, and failed wherever it was not. Startup now calls the loaders through the module, so one patch covers both the warm-up and request-time encoding. The trap was known and routed around rather than fixed: patch_bge_m3_model and one test patched server.resources as well, and three test docstrings described dual-module patching as a rule. Those now patch query_encoder only, and the docstrings say so. The cacheless-boot probe, which patched neither, now mocks the model too. A new test boots the app with recording stand-ins for the two loaders and expects both called. It fails on the old binding, where the real loaders run instead; with the model cached it would see no calls. Measured on Linux with no model available: the full suite goes from 214 failures to 123, all 91 fixed being tests that boot the server, and none new. --- server/resources.py | 11 +++----- tests/_corpus_helpers.py | 19 +++++--------- tests/test_bootstrap_mode.py | 5 ++-- tests/test_corpus_freshness.py | 9 +------ tests/test_corpus_integrity_probes.py | 3 +++ tests/test_server_startup.py | 33 +++++++++++++++--------- tests/test_server_startup_integration.py | 8 +----- 7 files changed, 40 insertions(+), 48 deletions(-) diff --git a/server/resources.py b/server/resources.py index bab8c0f5..7a9c7400 100644 --- a/server/resources.py +++ b/server/resources.py @@ -76,6 +76,7 @@ from pathlib import Path from typing import Any, TypeVar +from server import query_encoder from server.config import Config from server.corpus import ( CorpusVersionInfo, @@ -89,11 +90,7 @@ FreshnessGate, read_marker_off_loop, ) -from server.query_encoder import ( - _get_model, - _get_tokenizer, - shutdown_executor, -) +from server.query_encoder import shutdown_executor logger = logging.getLogger(__name__) @@ -904,8 +901,8 @@ async def startup(cls, config: Config) -> Resources: # 3. Eager BGE-M3 load (forces query_encoder's singletons to # populate; subsequent calls hit cached model + tokenizer). - await loop.run_in_executor(None, _get_tokenizer) - await loop.run_in_executor(None, _get_model) + await loop.run_in_executor(None, query_encoder._get_tokenizer) + await loop.run_in_executor(None, query_encoder._get_model) logger.info("Resources.startup: BGE-M3 embedder warm") # 4. Reranker — only when enabled (synthesis D6: refuse on diff --git a/tests/_corpus_helpers.py b/tests/_corpus_helpers.py index b5a1cae2..dc2b0bf1 100644 --- a/tests/_corpus_helpers.py +++ b/tests/_corpus_helpers.py @@ -149,20 +149,15 @@ def seed_corpus_multi_paper( def patch_bge_m3_model(monkeypatch) -> None: - """Mock the BGE-M3 load in BOTH the query_encoder module and the - resources module. - - Load-bearing per the notebook-retrieval-m2 lesson: ``resources.py`` - binds ``_get_model`` and ``_get_tokenizer`` by name via - ``from server.query_encoder import _get_model``, so patching only - ``query_encoder`` is INSUFFICIENT for any test that exercises - ``Resources.startup``. The patch must target both modules. + """Mock the BGE-M3 load, for any test that runs ``Resources.startup``. + + ``Resources.startup`` reaches the loaders through + ``server.query_encoder``'s module attributes, so patching them there + covers both the startup warm-up and request-time encoding. """ import server.query_encoder as qe_mod # noqa: PLC0415 - import server.resources as res_mod # noqa: PLC0415 fake_model = object() fake_tokenizer = object() - for mod in (qe_mod, res_mod): - monkeypatch.setattr(mod, "_get_model", lambda: fake_model) - monkeypatch.setattr(mod, "_get_tokenizer", lambda: fake_tokenizer) + monkeypatch.setattr(qe_mod, "_get_model", lambda: fake_model) + monkeypatch.setattr(qe_mod, "_get_tokenizer", lambda: fake_tokenizer) diff --git a/tests/test_bootstrap_mode.py b/tests/test_bootstrap_mode.py index 21013305..aec9d16e 100644 --- a/tests/test_bootstrap_mode.py +++ b/tests/test_bootstrap_mode.py @@ -828,13 +828,14 @@ def test_bootstrap_envelope_text_uses_configured_bind(self): def _patch_startup_heavy_io(monkeypatch, lancedb_path: Path) -> None: """Patch the expensive startup steps (BGE-M3, LanceDB, BM25, cache) so Resources.startup can run in a fast offline test.""" + import server.query_encoder as qe_mod import server.resources as res_mod # BGE-M3 model + tokenizer. fake_model = object() fake_tokenizer = object() - monkeypatch.setattr(res_mod, "_get_model", lambda: fake_model) - monkeypatch.setattr(res_mod, "_get_tokenizer", lambda: fake_tokenizer) + monkeypatch.setattr(qe_mod, "_get_model", lambda: fake_model) + monkeypatch.setattr(qe_mod, "_get_tokenizer", lambda: fake_tokenizer) # LanceDB open — return a fake table + no degraded state. fake_table = _make_fake_table() diff --git a/tests/test_corpus_freshness.py b/tests/test_corpus_freshness.py index 6ff9179b..6000de7e 100644 --- a/tests/test_corpus_freshness.py +++ b/tests/test_corpus_freshness.py @@ -683,14 +683,7 @@ def _search(client: TestClient, sid: str, query: str, k: int = 20) -> dict: @pytest.fixture def deterministic_embedder(monkeypatch): - """Mock BGE-M3 in BOTH modules and make ``encode_query`` deterministic. - - Dual-module patching is load-bearing: ``server/resources.py`` binds - ``_get_model`` / ``_get_tokenizer`` by name at import time, so - patching only ``query_encoder`` leaves ``Resources.startup`` loading - real 1.5 GB weights (the notebook-retrieval-m2 lesson, encoded in - ``tests/_corpus_helpers.patch_bge_m3_model``). - """ + """Mock the BGE-M3 load and make ``encode_query`` deterministic.""" patch_bge_m3_model(monkeypatch) async def _fake_encode_query(text): diff --git a/tests/test_corpus_integrity_probes.py b/tests/test_corpus_integrity_probes.py index 74c38971..cc87bf6e 100644 --- a/tests/test_corpus_integrity_probes.py +++ b/tests/test_corpus_integrity_probes.py @@ -320,6 +320,7 @@ def test_a_cacheless_boot_says_cacheless_and_not_warm( import pyarrow as pa import server.cache as cache_mod + import server.query_encoder as qe_mod import server.resources as res_mod from ingest.embedder import EMBEDDER_VERSION from ingest.schema import CHUNKS_SCHEMA_V1 @@ -382,6 +383,8 @@ async def _bm25(**_kw: object) -> object: monkey.setattr(BM25Phase, "startup", staticmethod(_bm25)) monkey.setattr(cache_mod, "set_cache", lambda _c: None) + monkey.setattr(qe_mod, "_get_model", lambda: object()) + monkey.setattr(qe_mod, "_get_tokenizer", lambda: object()) cfg = Config( lancedb_path=lance, diff --git a/tests/test_server_startup.py b/tests/test_server_startup.py index 061d7dd5..67b6b435 100644 --- a/tests/test_server_startup.py +++ b/tests/test_server_startup.py @@ -150,6 +150,26 @@ def warm_app(seeded_lancedb, mocked_bge_m3): yield client +class TestModelWarmupIsPatchable: + def test_startup_warms_through_the_query_encoder_loaders( + self, seeded_lancedb, monkeypatch + ): + """Startup must reach BGE-M3 through ``server.query_encoder``'s + module attributes, so a test that patches them keeps the model + out. A name bound at import would load the real model instead, and + every mocked test would still pass wherever the model is cached.""" + import server.query_encoder as qe_mod + + calls: list[str] = [] + monkeypatch.setattr(qe_mod, "_get_tokenizer", lambda: calls.append("tokenizer")) + monkeypatch.setattr(qe_mod, "_get_model", lambda: calls.append("model")) + + with TestClient(create_app(Config(lancedb_path=seeded_lancedb))): + pass + + assert calls == ["tokenizer", "model"] + + # =========================================================================== # AC: GET /healthz returns 200 before readiness # =========================================================================== @@ -660,7 +680,7 @@ def test_two_notebooks_derive_distinct_bm25_index_roots( ) def test_resources_startup_boots_notebook_corpus( - self, notebooks_base, mocked_bge_m3, monkeypatch + self, notebooks_base, mocked_bge_m3 ): """F2 rectification: prove Resources.startup actually BOOTS against the notebook-derived lancedb path — not merely that the path @@ -670,17 +690,6 @@ def test_resources_startup_boots_notebook_corpus( pinned and the notebook's table opened. If routing were broken (read the empty shared default), startup would raise CorpusNotIngestedError and /readyz would be 503.""" - # resources.py imports _get_model/_get_tokenizer as direct module - # names (resources.py:77-79), so the mocked_bge_m3 fixture (which - # patches server.query_encoder for the request-time encode path) - # does NOT intercept the STARTUP warmup at resources.py:357-358. - # Patch the resources-level names too so this boot test is - # hermetic — no real BGE-M3 download, no HF Hub network dependency. - import server.resources as res_mod - - monkeypatch.setattr(res_mod, "_get_model", lambda: object()) - monkeypatch.setattr(res_mod, "_get_tokenizer", lambda: object()) - nb_lancedb = notebooks_base / "demo-nb" / "lancedb" nb_version = _seed_corpus(nb_lancedb) cfg = Config(notebook="demo-nb") diff --git a/tests/test_server_startup_integration.py b/tests/test_server_startup_integration.py index f40388c9..1bca6aee 100644 --- a/tests/test_server_startup_integration.py +++ b/tests/test_server_startup_integration.py @@ -52,13 +52,7 @@ ``seed_corpus_multi_paper`` is the load-bearing multi-call fixture that exercises the bug class. The single-call ``seed_corpus`` is NOT used here — see rect F1. - - Dual-module BGE-M3 mock via ``patch_bge_m3_model``. The simple - single-module ``mocked_bge_m3`` fixture in - ``test_server_startup.py`` is INSUFFICIENT because - ``server/resources.py:78-82`` binds ``_get_model`` / - ``_get_tokenizer`` by name at module load time. This is the FM-1 - top-risk per the research and the ``notebook-retrieval-m2`` - lesson encoded in the shared helper's docstring. + - BGE-M3 is mocked via ``patch_bge_m3_model``. - Monkeypatch target for the mutation test: ``ingest.store.write_corpus_version_marker`` — the module's own namespace (since ``write_chunks`` calls it by bare name at module