{"record":{"id":"9f01649e694a3a9b","repo":"mudler/LocalAI","slug":"onnxdirectengine-requires-model-path-file-onnx","errorCode":null,"errorMessage":"OnnxDirectEngine requires `model_path: <file.onnx>` in options","messagePattern":"OnnxDirectEngine requires `model_path: <file\\.onnx>` in options","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/python/speaker-recognition/engines.py","lineNumber":308,"sourceCode":"            )\n        duration = float(mono.shape[-1]) / 16000.0 if mono.size else 0.0\n        return [dict(start=0.0, end=duration, **attrs)]\n\n\nclass OnnxDirectEngine:\n    \"\"\"Run a pre-exported ONNX speaker encoder (WeSpeaker / 3D-Speaker).\"\"\"\n\n    name = \"onnx-direct\"\n\n    def __init__(self, model_name: str, options: dict[str, str]):\n        import onnxruntime as ort  # type: ignore\n\n        # The gallery is expected to have dropped the ONNX file under\n        # the models directory; accept either an absolute path or a\n        # filename relative to _model_path.\n        onnx_path = options.get(\"model_path\") or options.get(\"onnx\")\n        if not onnx_path:\n            raise ValueError(\"OnnxDirectEngine requires `model_path: <file.onnx>` in options\")\n        if not os.path.isabs(onnx_path):\n            onnx_path = os.path.join(options.get(\"_model_path\", \"\"), onnx_path)\n        if not os.path.isfile(onnx_path):\n            raise FileNotFoundError(f\"ONNX model not found: {onnx_path}\")\n\n        providers = options.get(\"providers\")\n        if providers:\n            provider_list = [p.strip() for p in providers.split(\",\") if p.strip()]\n        else:\n            provider_list = [\"CPUExecutionProvider\"]\n        self._session = ort.InferenceSession(onnx_path, providers=provider_list)\n        input_meta = self._session.get_inputs()[0]\n        self._input_name = input_meta.name\n        # Pre-exported speaker encoders come in two shapes:\n        #   rank-2  [batch, samples]          — some 3D-Speaker exports feed raw waveform.\n        #   rank-3  [batch, frames, n_mels]   — WeSpeaker and most Kaldi-lineage encoders\n        #                                        expect pre-computed Kaldi FBank features.\n        # We detect this at load time and branch in embed(), because feeding raw audio","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/speaker-recognition/engines.py#L290-L326","documentation":"Raised by OnnxDirectEngine.__init__ in the speaker-recognition backend when options contain neither 'model_path' nor 'onnx' (the fallback alias). This engine runs a pre-exported ONNX speaker encoder, so the path to the .onnx file is mandatory; the error is raised before any ONNX runtime work begins.","triggerScenarios":"Selecting the onnx-direct engine in the model config without a model_path option, or misspelling the key ('modelpath', 'path', 'onnx_path') so both lookups return None.","commonSituations":"Gallery configs missing the option, users assuming the engine downloads a default model like other engines do, or copy-paste configs from WeSpeaker CLI docs using different key names.","solutions":["Add model_path: /path/to/encoder.onnx (absolute) or model_path: encoder.onnx relative to the models directory, to the engine options","If you meant to use a downloaded checkpoint instead of a raw ONNX file, pick the regular ECAPA/WeSpeaker engine rather than onnx-direct","Verify the file exists once configured — the next check raises FileNotFoundError with the resolved path"],"exampleFix":"# before (YAML)\nengine: onnx-direct\noptions:\n  backend: onnx\n\n# after (YAML)\nengine: onnx-direct\noptions:\n  model_path: wespeaker_resnet34.onnx","handlingStrategy":"validation","validationCode":"opts = model_config.get('options', {})\nonnx_path = opts.get('model_path') or opts.get('onnx')\nif not onnx_path:\n    raise ValueError('onnx-direct engine requires options.model_path pointing at a .onnx file')\nif not os.path.isfile(onnx_path if os.path.isabs(onnx_path) else os.path.join(model_dir, onnx_path)):\n    raise FileNotFoundError(onnx_path)","typeGuard":"def has_onnx_path(options: dict) -> bool:\n    return bool(options.get('model_path') or options.get('onnx'))","tryCatchPattern":"try:\n    engine = OnnxDirectEngine(name, options)\nexcept (ValueError, FileNotFoundError) as err:\n    fail_config(f'cannot start onnx-direct engine: {err}')","preventionTips":["Always set model_path for onnx-direct; it downloads nothing","Validate config keys with a preflight schema check","Verify the ONNX file exists before engine startup"],"tags":["python","speaker-recognition","onnx","configuration"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}