{"record":{"id":"c1a5f08658dd0c48","repo":"mudler/LocalAI","slug":"unknown-whisper-model-ref-model-ref-r-expected","errorCode":null,"errorMessage":"Unknown Whisper model_ref={model_ref!r}; expected one of {list(MODEL_URLS)} or an openai/whisper-* HF id","messagePattern":"Unknown Whisper model_ref=(.+?); expected one of (.+?) or an openai/whisper-\\* HF id","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/python/tinygrad/backend.py","lineNumber":428,"sourceCode":"        Accepts a model-size alias (tiny / tiny.en / base / base.en / small /\n        small.en) OR an explicit `.pt` file path OR the HF repo id naming\n        convention `openai/whisper-*` (mapped to the matching OpenAI alias).\n        \"\"\"\n        from vendor.whisper import init_whisper, MODEL_URLS\n\n        alias = model_ref\n        if \"/\" in alias and alias.startswith(\"openai/whisper-\"):\n            alias = alias.removeprefix(\"openai/whisper-\")\n        if alias not in MODEL_URLS:\n            # Explicit path to a .pt checkpoint — fall back to size heuristic\n            # via filename.\n            basename = Path(alias).name.lower()\n            for name in MODEL_URLS:\n                if name in basename:\n                    alias = name\n                    break\n            else:\n                raise ValueError(\n                    f\"Unknown Whisper model_ref={model_ref!r}; expected one of {list(MODEL_URLS)} \"\n                    f\"or an openai/whisper-* HF id\"\n                )\n\n        model, enc = init_whisper(alias, batch_size=1)\n        self.whisper_model = model\n        self.whisper_tokenizer = enc\n\n    # --------------------- LLM generation -------------------------------\n\n    def _encode_prompt(self, prompt: str) -> list[int]:\n        \"\"\"Normalize tokenizer output: HF `tokenizers.Tokenizer.encode()`\n        returns an `Encoding` with `.ids`; apps.llm's `SimpleTokenizer.encode()`\n        returns `list[int]` directly.\"\"\"\n        encoded = self.llm_tokenizer.encode(prompt)\n        return list(getattr(encoded, \"ids\", encoded))\n\n    def _decode_tokens(self, ids: list[int]) -> str:","sourceCodeStart":410,"sourceCodeEnd":446,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/tinygrad/backend.py#L410-L446","documentation":"The tinygrad Whisper wrapper recognizes aliases from the MODEL_URLS table (tiny..large style size names) or 'openai/whisper-*' HF ids; it also strips the 'openai/whisper-' prefix and tries a substring match of a known size name in the file basename as a fallback. Only when no known size matches does it raise ValueError listing the accepted aliases.","triggerScenarios":"Calling Whisper with model_ref like 'whisper-turbo-neo', 'facebook/wav2vec2', or a .pt checkpoint whose filename contains no recognized size token (e.g. 'my_finetune.pt'); typo in the size name.","commonSituations":"Passing a non-OpenAI speech model id expecting generic HF support; custom fine-tuned checkpoints with arbitrary names; using 'whisper-large-v3-turbo' when the MODEL_URLS table predates that alias — filename fallback only works if a base alias like 'large' is a substring.","solutions":["Use one of the aliases listed in the error message (e.g. 'tiny', 'base', 'small', 'medium', 'large') or the 'openai/whisper-<size>' HF id form.","For a custom checkpoint, rename the file so it contains a recognized size token (e.g. mymodel-large.pt) so the filename heuristic matches.","Update the backend if the alias table is stale relative to the Whisper release you need."],"exampleFix":"# before\nmodel_ref = \"whisper-turbo-neo\"\n# after\nmodel_ref = \"openai/whisper-large-v3\"  # or a bare alias: \"large\"","handlingStrategy":"validation","validationCode":"KNOWN = {\"tiny\", \"base\", \"small\", \"medium\", \"large\"}  # keep in sync with MODEL_URLS\n\ndef whisper_ref_ok(ref: str) -> bool:\n    a = ref.removeprefix(\"openai/whisper-\")\n    return a in KNOWN or any(k in Path(a).name.lower() for k in KNOWN)","typeGuard":null,"tryCatchPattern":"try:\n    self._load_whisper(ref)\nexcept ValueError as e:\n    if \"Unknown Whisper\" in str(e):\n        raise ConfigError(f\"bad whisper ref {ref!r}: use tiny|base|small|medium|large\") from e\n    raise","preventionTips":["Constrain the whisper model dropdown in clients to the known aliases.","Name custom .pt checkpoints with a size token so the fallback matches.","Pin the backend version whose alias table matches the sizes you use."],"tags":["tinygrad","whisper","model-alias","validation","localai"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}