mudler/LocalAI · error · ValueError

OnnxDirectEngine requires `model_path: <file.onnx>` in optio

Error message

OnnxDirectEngine requires `model_path: <file.onnx>` in options

What it means

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.

Source

Thrown at backend/python/speaker-recognition/engines.py:308

            )
        duration = float(mono.shape[-1]) / 16000.0 if mono.size else 0.0
        return [dict(start=0.0, end=duration, **attrs)]


class OnnxDirectEngine:
    """Run a pre-exported ONNX speaker encoder (WeSpeaker / 3D-Speaker)."""

    name = "onnx-direct"

    def __init__(self, model_name: str, options: dict[str, str]):
        import onnxruntime as ort  # type: ignore

        # The gallery is expected to have dropped the ONNX file under
        # the models directory; accept either an absolute path or a
        # filename relative to _model_path.
        onnx_path = options.get("model_path") or options.get("onnx")
        if not onnx_path:
            raise ValueError("OnnxDirectEngine requires `model_path: <file.onnx>` in options")
        if not os.path.isabs(onnx_path):
            onnx_path = os.path.join(options.get("_model_path", ""), onnx_path)
        if not os.path.isfile(onnx_path):
            raise FileNotFoundError(f"ONNX model not found: {onnx_path}")

        providers = options.get("providers")
        if providers:
            provider_list = [p.strip() for p in providers.split(",") if p.strip()]
        else:
            provider_list = ["CPUExecutionProvider"]
        self._session = ort.InferenceSession(onnx_path, providers=provider_list)
        input_meta = self._session.get_inputs()[0]
        self._input_name = input_meta.name
        # Pre-exported speaker encoders come in two shapes:
        #   rank-2  [batch, samples]          — some 3D-Speaker exports feed raw waveform.
        #   rank-3  [batch, frames, n_mels]   — WeSpeaker and most Kaldi-lineage encoders
        #                                        expect pre-computed Kaldi FBank features.
        # We detect this at load time and branch in embed(), because feeding raw audio

View on GitHub (pinned to 44413a9d06)

Solutions

  1. Add model_path: /path/to/encoder.onnx (absolute) or model_path: encoder.onnx relative to the models directory, to the engine options
  2. If you meant to use a downloaded checkpoint instead of a raw ONNX file, pick the regular ECAPA/WeSpeaker engine rather than onnx-direct
  3. Verify the file exists once configured — the next check raises FileNotFoundError with the resolved path

Example fix

# before (YAML)
engine: onnx-direct
options:
  backend: onnx

# after (YAML)
engine: onnx-direct
options:
  model_path: wespeaker_resnet34.onnx
Defensive patterns

Strategy: validation

Validate before calling

opts = model_config.get('options', {})
onnx_path = opts.get('model_path') or opts.get('onnx')
if not onnx_path:
    raise ValueError('onnx-direct engine requires options.model_path pointing at a .onnx file')
if not os.path.isfile(onnx_path if os.path.isabs(onnx_path) else os.path.join(model_dir, onnx_path)):
    raise FileNotFoundError(onnx_path)

Type guard

def has_onnx_path(options: dict) -> bool:
    return bool(options.get('model_path') or options.get('onnx'))

Try / catch

try:
    engine = OnnxDirectEngine(name, options)
except (ValueError, FileNotFoundError) as err:
    fail_config(f'cannot start onnx-direct engine: {err}')

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/9f01649e694a3a9b. Report an issue: GitHub.