mudler/LocalAI · error · NotImplementedError

analyze head failed to load — install transformers + torch o

Error message

analyze head failed to load — install transformers + torch or pass age_gender_model/emotion_model options

What it means

Raised by the speaker-recognition backend's analyze() when the AnalysisHead (age/gender/emotion models) failed to initialize and returns no attributes for the requested actions. ECAPA-TDNN itself does not produce these outputs, so they are delegated to a separate head that requires transformers + torch and explicit model options.

Source

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

    def embed(self, audio_path: str) -> list[float]:
        waveform = self._load_waveform(audio_path)
        vec = self._model.encode_batch(waveform).squeeze().detach().cpu().numpy()
        return [float(x) for x in vec]

    def compare(self, audio1: str, audio2: str) -> float:
        return _cosine_distance(self.embed(audio1), self.embed(audio2))

    def analyze(self, audio_path: str, actions):
        # Age / gender / emotion aren't produced by ECAPA-TDNN itself;
        # delegate to AnalysisHead which wraps separate Apache-2.0
        # checkpoints. Returns a single segment spanning the clip —
        # segmentation / diarisation is a future enhancement.
        waveform = self._load_waveform(audio_path)
        mono = waveform.squeeze().detach().cpu().numpy()
        attrs = self._analysis.analyze(audio_path, mono, actions)
        if not attrs:
            raise NotImplementedError(
                "analyze head failed to load — install transformers + torch or pass age_gender_model/emotion_model options"
            )
        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")

View on GitHub (pinned to 44413a9d06)

Solutions

1. pip install transformers torch into the backend environment (or rebuild the backend image with them)
2. Set age_gender_model and emotion_model options in the model config pointing at the analysis checkpoints
3. If you only need speaker embeddings, drop age/gender/emotion from the requested actions

Example fix

# before
result = engine.analyze('/tmp/a.wav', ['age', 'emotion'])  # NotImplementedError

# after (install deps + configure models)
# pip install transformers torch
engine = EcapaTdnnEngine(name, {'age_gender_model': '/models/ag.onnx', 'emotion_model': '/models/em.onnx', ...})

def can_analyze(engine, actions) -> bool:
    if not {'age', 'gender', 'emotion'} & set(actions):
        return True  # embedding-only path is fine
    return getattr(engine, '_analysis', None) is not None and engine._analysis.loaded

def analysis_ready(engine) -> bool:
    head = getattr(engine, '_analysis', None)
    return head is not None and getattr(head, 'loaded', False)

try:
    segments = engine.analyze(path, actions)
except NotImplementedError as err:
    # capability gap: install transformers+torch and configure analysis models
    return error_response(str(err), hint='analysis requires extra models/deps')

When it happens

Trigger: Calling analyze with actions like ['age','gender','emotion'] when transformers or torch is not installed in the backend environment, or when neither age_gender_model nor emotion_model options were provided so self._analysis has no loaded head.

Common situations: Minimal installs of the speaker-recognition backend without the extra analysis dependencies, or gallery configs that only specify the speaker-embedding model but request analysis actions.

Related errors

• audio is required for LongCat-Video-Avatar-1.5
• audio input is not a readable staged file
• audio contains no samples
• audio encoder returned non-finite values
• request needs {segments} avatar segments, but max_segments i

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