Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python
5.6 KB
Raw Blame
"""How whisperx-asr-service chooses the model for a request, vendored for tests.

Speakr's fake ASR server (tests/contract/fake_asr_server.py) answers with these
rules, so Speakr's tests fail when Speakr sends a request the real service
would reject. test_whisperx_contract.py checks this copy against the service's
own code (WHISPERX_REPO) so the two cannot drift apart unnoticed.

Two service generations are modelled:

- ``fixed`` (0.4.2 onward): an empty or whitespace request model uses
  DEFAULT_MODEL, which is DEFAULT_MODEL / PRELOAD_MODEL / large-v3 and never
  empty; unknown names are rejected with HTTP 400.
- ``legacy`` (0.2.0 to 0.4.1): the default is PRELOAD_MODEL as compose passes
  it, which is an empty string when .env does not set it (Speakr #409), and an
  unknown name reaches faster-whisper, which fails with HTTP 500.
"""

import os

BUILTIN_DEFAULT_MODEL = "large-v3"

# faster_whisper.available_models() in the service image (faster-whisper 1.2.1).
CANONICAL_MODELS = (
    "tiny.en", "tiny", "base.en", "base", "small.en", "small",
    "medium.en", "medium", "large-v1", "large-v2", "large-v3", "large",
    "distil-large-v2", "distil-medium.en", "distil-small.en",
    "distil-large-v3", "distil-large-v3.5", "large-v3-turbo", "turbo",
)

STATIC_ALIASES = {
    "whisper-large-v3": "large-v3",
    "whisper-large-v2": "large-v2",
    "whisper-medium": "medium",
    "whisper-small": "small",
    "whisper-base": "base",
    "whisper-tiny": "tiny",
}

_HF_REPO_CHARS = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.")


class ModelRejected(Exception):
    """The service would refuse this request; ``status`` is its HTTP code."""

    def __init__(self, status, detail):
        super().__init__(detail)
        self.status = status
        self.detail = detail


def _env_or_none(value):
    if value is None:
        return None
    value = value.strip()
    return value or None


def is_hf_repo_id(name):
    parts = name.split("/")
    return len(parts) == 2 and all(parts) and all(set(p) <= _HF_REPO_CHARS for p in parts)


def is_loadable_model(name):
    return bool(name) and (name in CANONICAL_MODELS or is_hf_repo_id(name) or os.path.isdir(name))


def _strip_whisper_prefix(name):
    if name.startswith("whisper-") and name[len("whisper-"):] in CANONICAL_MODELS:
        return name[len("whisper-"):]
    return name


def resolve_default(raw, openai_whisper1=None):
    """The fixed service's DEFAULT_MODEL for a configured value (never empty)."""
    name = (raw or "").strip()
    if name == "whisper-1":
        name = _env_or_none(openai_whisper1) or BUILTIN_DEFAULT_MODEL
    name = STATIC_ALIASES.get(name, name)
    name = _strip_whisper_prefix(name)
    return name if is_loadable_model(name) else BUILTIN_DEFAULT_MODEL


class ServiceModelRules:
    """The model decision the service makes for one /asr request.

    ``env`` holds the service's container environment as compose delivers it:
    a key present with value "" is how compose forwards a variable that the
    .env file does not set.
    """

    def __init__(self, env=None, generation="fixed"):
        env = dict(env or {})
        self.generation = generation
        if generation == "fixed":
            preload = _env_or_none(env.get("PRELOAD_MODEL"))
            configured = _env_or_none(env.get("DEFAULT_MODEL")) or preload or BUILTIN_DEFAULT_MODEL
            whisper1 = _env_or_none(env.get("OPENAI_WHISPER1_MODEL"))
            self.default_model = resolve_default(configured, whisper1)
            self.whisper1 = resolve_default(whisper1) if whisper1 else self.default_model
            allowed = []
            for entry in (_env_or_none(env.get("ALLOWED_MODELS")) or "").split(","):
                entry = entry.strip()
                if entry:
                    mapped = self._map_alias(entry)
                    if mapped not in allowed:
                        allowed.append(mapped)
            self.allowed = allowed
        elif generation == "legacy":
            # os.getenv("PRELOAD_MODEL", "large-v3"): the fallback only applies
            # when the variable is absent, not when compose forwards it empty.
            self.default_model = env["PRELOAD_MODEL"] if "PRELOAD_MODEL" in env else BUILTIN_DEFAULT_MODEL
            self.whisper1 = env.get("OPENAI_WHISPER1_MODEL", self.default_model)
            self.allowed = []
        else:
            raise ValueError(f"unknown service generation {generation!r}")

    def _map_alias(self, name):
        if name == "whisper-1":
            return self.whisper1
        if name in STATIC_ALIASES:
            return STATIC_ALIASES[name]
        return _strip_whisper_prefix(name)

    def resolve(self, model):
        """Name the service loads for a request's ``model``; raises ModelRejected."""
        if self.generation == "legacy":
            # No stripping; an empty model returns DEFAULT_MODEL unmapped.
            name = self._map_alias(model) if model else self.default_model
            if not is_loadable_model(name):
                raise ModelRejected(
                    500,
                    f"Invalid model size {name!r}, expected one of: {', '.join(CANONICAL_MODELS)}",
                )
            return name
        name = (model or "").strip()
        if not name:
            return self.default_model
        resolved = self._map_alias(name)
        if not is_loadable_model(resolved):
            raise ModelRejected(400, f"Unknown model {name!r}.")
        if self.allowed and resolved not in self.allowed and resolved != self.default_model:
            raise ModelRejected(400, f"Model {name!r} is not allowed on this server.")
        return resolved