Skip to content

Commit 702e8d4

Browse files
committed
Harden ML inference load and decode paths
1 parent 87ad25e commit 702e8d4

12 files changed

Lines changed: 548 additions & 17 deletions

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22

33
All notable changes to the `unplug-ai` SDK.
44

5+
## [Unreleased]
6+
7+
### Fixed
8+
9+
- ML inference hardening: BIOES decode no longer crashes on checkpoints without `*-INJ` labels; label maps are validated at load with a clear `ModelError`; forced torch devices are validated (`ConfigError`); `ModelProvider`/`SpanInferenceModel` load is thread-safe; ML modules log device/tokenizer fallbacks and import torch via `unplug.optional.ml` helpers
10+
11+
### Added
12+
13+
- Offline synthetic BIOES checkpoint fixture for ML unit tests (no real weights required)
14+
515
## [0.5.1] — 2026-07-20
616

717
### Fixed

‎sdk/src/unplug/ml/bioes.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,13 @@ def decode_bioes_spans(
1717
1818
Handles B/I and, when present in the label map, E (explicit end) and
1919
S (single token). Falls back to plain BIO behavior for BIO-only checkpoints.
20+
21+
Returns an empty list when the label map has no ``*-INJ`` columns (callers
22+
should reject such checkpoints at load time).
2023
"""
2124
inj_cols = [label2id[t] for t in ("B-INJ", "I-INJ", "E-INJ", "S-INJ") if t in label2id]
25+
if not inj_cols:
26+
return []
2227
inj_label_ids = set(inj_cols)
2328
current: CharSpan | None = None
2429
spans: list[CharSpan] = []

‎sdk/src/unplug/ml/device.py‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,49 @@
22

33
from __future__ import annotations
44

5+
from unplug.exceptions import ConfigError
6+
57

68
def resolve_torch_device(preferred: str | None = None) -> str:
7-
if preferred and preferred not in ("auto", ""):
8-
return preferred
9-
import torch
9+
"""Resolve a torch device string, validating forced preferences.
1010
11+
Raises:
12+
ConfigError: when ``preferred`` names a device torch cannot use.
13+
"""
14+
from unplug.optional.ml import get_torch
15+
16+
torch = get_torch()
17+
available: list[str] = ["cpu"]
1118
if torch.cuda.is_available():
19+
available.append("cuda")
20+
mps_backend = getattr(torch.backends, "mps", None)
21+
if mps_backend is not None and mps_backend.is_available():
22+
available.append("mps")
23+
24+
if preferred and preferred not in ("auto", ""):
25+
device = preferred.strip()
26+
if not _device_available(device, torch=torch, mps_backend=mps_backend):
27+
msg = f"Torch device '{device}' is not available. Available: {', '.join(available)}"
28+
raise ConfigError(msg)
29+
return device
30+
31+
if "cuda" in available:
1232
return "cuda"
13-
if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
33+
if "mps" in available:
1434
return "mps"
1535
return "cpu"
36+
37+
38+
def _device_available(
39+
device: str,
40+
*,
41+
torch: object,
42+
mps_backend: object | None,
43+
) -> bool:
44+
if device == "cpu":
45+
return True
46+
if device == "cuda" or device.startswith("cuda:"):
47+
return bool(torch.cuda.is_available()) # type: ignore[attr-defined]
48+
if device == "mps":
49+
return mps_backend is not None and bool(mps_backend.is_available()) # type: ignore[attr-defined]
50+
return False

‎sdk/src/unplug/ml/models.py‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ class ModelProvider(ABC):
2929
def __init__(self, spec: ModelSpec) -> None:
3030
self._spec = spec
3131
self._loaded = False
32+
self._load_lock = threading.Lock()
3233

3334
@property
3435
def spec(self) -> ModelSpec:
@@ -39,14 +40,19 @@ def loaded(self) -> bool:
3940
return self._loaded
4041

4142
def load(self) -> None:
42-
if not self._loaded:
43-
self._do_load()
44-
self._loaded = True
43+
# Fast path: avoid lock when already loaded (predict stays lock-free).
44+
if self._loaded:
45+
return
46+
with self._load_lock:
47+
if not self._loaded:
48+
self._do_load()
49+
self._loaded = True
4550

4651
def unload(self) -> None:
47-
if self._loaded:
48-
self._do_unload()
49-
self._loaded = False
52+
with self._load_lock:
53+
if self._loaded:
54+
self._do_unload()
55+
self._loaded = False
5056

5157
@abstractmethod
5258
def _do_load(self) -> None: ...

‎sdk/src/unplug/ml/providers.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,15 @@
22

33
from __future__ import annotations
44

5+
import logging
56
from typing import Any
67

78
from unplug.ml.models import ModelProvider, ModelSpec
89
from unplug.ml.span_model import SpanInferenceModel
910
from unplug.ml.types import SpanPrediction
1011

12+
logger = logging.getLogger("unplug.ml.providers")
13+
1114

1215
class TransformersSpanProvider(ModelProvider):
1316
"""HuggingFace token-classification checkpoint for BIOES span detection."""
@@ -30,6 +33,7 @@ def __init__(self, spec: ModelSpec) -> None:
3033
)
3134

3235
def _do_load(self) -> None:
36+
logger.info("loading transformers span provider %s", self._spec.name)
3337
self._engine.load()
3438

3539
def _do_unload(self) -> None:

‎sdk/src/unplug/ml/span_model.py‎

Lines changed: 45 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,25 @@
22

33
from __future__ import annotations
44

5+
import logging
6+
import threading
57
from pathlib import Path
68
from typing import TYPE_CHECKING
79

10+
from unplug.exceptions import ModelError
811
from unplug.ml.bioes import decode_bioes_spans
912
from unplug.ml.device import resolve_torch_device
1013
from unplug.ml.spans_merge import merge_char_spans
1114
from unplug.ml.types import CharSpan, SpanPrediction
15+
from unplug.optional.ml import get_torch, get_transformers
1216

1317
if TYPE_CHECKING:
1418
from transformers import PreTrainedModel, PreTrainedTokenizerBase
1519

20+
logger = logging.getLogger("unplug.ml.span_model")
21+
22+
_INJ_LABELS = ("B-INJ", "I-INJ", "E-INJ", "S-INJ")
23+
1624

1725
class SpanInferenceModel:
1826
"""Token-classification head → injection character spans on normalized text."""
@@ -44,6 +52,7 @@ def __init__(
4452
self._max_length = max_length or 256
4553
self._has_disposition = False
4654
self._id2disposition: dict[int, str] = {}
55+
self._load_lock = threading.Lock()
4756

4857
@property
4958
def checkpoint(self) -> Path:
@@ -68,7 +77,14 @@ def doc_threshold(self) -> float:
6877
def load(self) -> None:
6978
if self._model is not None:
7079
return
71-
import torch
80+
with self._load_lock:
81+
if self._model is not None:
82+
return
83+
self._load_unlocked()
84+
85+
def _load_unlocked(self) -> None:
86+
torch = get_torch()
87+
get_transformers()
7288
from transformers import AutoConfig, AutoModelForTokenClassification, AutoTokenizer
7389

7490
if not self._checkpoint.is_dir():
@@ -83,7 +99,12 @@ def load(self) -> None:
8399
use_fast=True,
84100
clean_up_tokenization_spaces=False,
85101
)
86-
except Exception:
102+
except Exception as exc:
103+
logger.warning(
104+
"fast tokenizer load failed for %s, falling back: %s",
105+
self._checkpoint,
106+
exc,
107+
)
87108
if tok_json.is_file():
88109
from transformers import PreTrainedTokenizerFast
89110

@@ -137,8 +158,25 @@ def load(self) -> None:
137158
self._model.eval()
138159
self._label2id = dict(self._model.config.label2id)
139160
self._id2label = {int(k): v for k, v in self._model.config.id2label.items()}
161+
self._validate_inj_labels()
162+
logger.info("injection model loaded on %s", self._device)
163+
164+
def _validate_inj_labels(self) -> None:
165+
if any(label in self._label2id for label in _INJ_LABELS):
166+
return
167+
labels = sorted(self._label2id)
168+
self._clear_state()
169+
raise ModelError(
170+
"Checkpoint label map has no *-INJ labels "
171+
"(expected BIOES scheme: B-INJ/I-INJ/E-INJ/S-INJ). "
172+
f"Got labels: {labels}"
173+
)
140174

141175
def unload(self) -> None:
176+
with self._load_lock:
177+
self._clear_state()
178+
179+
def _clear_state(self) -> None:
142180
self._model = None
143181
self._tokenizer = None
144182
self._label2id = {}
@@ -156,7 +194,7 @@ def predict_batch(
156194
*,
157195
batch_size: int = 32,
158196
) -> list[SpanPrediction]:
159-
import torch
197+
torch = get_torch()
160198

161199
self.load()
162200
assert self._tokenizer is not None
@@ -234,7 +272,7 @@ def _predict_overflowing(
234272
encoding: dict,
235273
bodies: list[str],
236274
) -> list[SpanPrediction]:
237-
import torch
275+
torch = get_torch()
238276

239277
assert self._tokenizer is not None
240278
assert self._model is not None
@@ -313,7 +351,7 @@ def _doc_score(
313351
row_probs: object,
314352
doc_logits: object | None,
315353
) -> tuple[float, str]:
316-
import torch
354+
torch = get_torch()
317355

318356
if self._is_dual_head and doc_logits is not None:
319357
doc_prob = float(torch.softmax(doc_logits, dim=-1)[self._doc_pos_index].item())
@@ -329,7 +367,7 @@ def _disposition(
329367
self, disposition_logits: object | None
330368
) -> tuple[str | None, dict[str, float] | None]:
331369
"""Softmax the ternary head for one row; (None, None) without the head."""
332-
import torch
370+
torch = get_torch()
333371

334372
if not self._has_disposition or disposition_logits is None:
335373
return None, None
@@ -348,7 +386,7 @@ def _token_max_inj_prob(
348386
probs: object,
349387
label2id: dict[str, int],
350388
) -> float:
351-
inj_cols = [label2id[t] for t in ("B-INJ", "I-INJ", "E-INJ", "S-INJ") if t in label2id]
389+
inj_cols = [label2id[t] for t in _INJ_LABELS if t in label2id]
352390
if not inj_cols:
353391
return 0.0
354392
best = 0.0

‎sdk/tests/unit/ml/conftest.py‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
"""ML unit fixtures: offline synthetic checkpoints (no hub downloads)."""
2+
3+
from __future__ import annotations
4+
5+
from pathlib import Path
6+
7+
import pytest
8+
9+
_BIOES_LABELS = ("O", "B-INJ", "I-INJ", "E-INJ", "S-INJ")
10+
_VOCAB_WORDS = (
11+
"ignore",
12+
"all",
13+
"previous",
14+
"instructions",
15+
"and",
16+
"reveal",
17+
"secrets",
18+
"hello",
19+
"world",
20+
"the",
21+
"weather",
22+
"in",
23+
"tokyo",
24+
"please",
25+
"dump",
26+
"a",
27+
"b",
28+
"c",
29+
"test",
30+
"text",
31+
)
32+
33+
34+
def _write_bert_vocab(path: Path, *, vocab_size: int = 1000) -> None:
35+
special = ["[PAD]", "[UNK]", "[CLS]", "[SEP]", "[MASK]"]
36+
words = list(_VOCAB_WORDS)
37+
filler = [f"tok{i}" for i in range(vocab_size - len(special) - len(words))]
38+
vocab = special + words + filler
39+
if len(vocab) != vocab_size:
40+
raise AssertionError(f"vocab size {len(vocab)} != {vocab_size}")
41+
path.write_text("\n".join(vocab) + "\n", encoding="utf-8")
42+
43+
44+
def _build_token_classification_checkpoint(
45+
root: Path,
46+
*,
47+
labels: tuple[str, ...],
48+
vocab_size: int = 1000,
49+
max_position_embeddings: int = 128,
50+
) -> Path:
51+
pytest.importorskip("transformers")
52+
from transformers import BertConfig, BertForTokenClassification, BertTokenizerFast
53+
54+
label2id = {label: idx for idx, label in enumerate(labels)}
55+
id2label = {idx: label for label, idx in label2id.items()}
56+
config = BertConfig(
57+
vocab_size=vocab_size,
58+
hidden_size=32,
59+
num_hidden_layers=1,
60+
num_attention_heads=2,
61+
intermediate_size=64,
62+
max_position_embeddings=max_position_embeddings,
63+
num_labels=len(labels),
64+
id2label=id2label,
65+
label2id=label2id,
66+
)
67+
model = BertForTokenClassification(config)
68+
root.mkdir(parents=True, exist_ok=True)
69+
vocab_path = root / "vocab.txt"
70+
_write_bert_vocab(vocab_path, vocab_size=vocab_size)
71+
tokenizer = BertTokenizerFast(vocab_file=str(vocab_path), do_lower_case=True)
72+
model.save_pretrained(root, safe_serialization=True)
73+
tokenizer.save_pretrained(root)
74+
return root
75+
76+
77+
@pytest.fixture(scope="session")
78+
def synthetic_ml_checkpoint(tmp_path_factory: pytest.TempPathFactory) -> Path:
79+
"""Tiny random BIOES token-classification checkpoint (~200KB, offline)."""
80+
pytest.importorskip("torch")
81+
root = tmp_path_factory.mktemp("synthetic_ml_ckpt")
82+
return _build_token_classification_checkpoint(root, labels=_BIOES_LABELS)
83+
84+
85+
@pytest.fixture(scope="session")
86+
def synthetic_non_inj_checkpoint(tmp_path_factory: pytest.TempPathFactory) -> Path:
87+
"""Checkpoint whose label map has no *-INJ labels (load must raise ModelError)."""
88+
pytest.importorskip("torch")
89+
root = tmp_path_factory.mktemp("synthetic_non_inj_ckpt")
90+
return _build_token_classification_checkpoint(
91+
root,
92+
labels=("O", "B-PER", "I-PER"),
93+
vocab_size=100,
94+
max_position_embeddings=64,
95+
)

0 commit comments

Comments
 (0)