ml-explore / ml-explore/mlx-examples

whisper/convert.py outputs `model.safetensors` but `mlx_whisper.load_models` expects `weights.safetensors`

Open Beginner friendly
#1,421 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
9k
Forks
1.2k
PR merge metrics
No merged PRs in 30d

Description

The pip-installed mlx-whisper package looks for weights.safetensors or
weights.npz, but the upstream whisper/convert.py script in this repo
writes the converted weights to model.safetensors. After running the
documented conversion command, mlx_whisper.transcribe(path_or_hf_repo=...)
fails to find the weights and crashes.

Repro
python3 whisper/convert.py \
    --torch-name-or-path nectec/Pathumma-whisper-th-large-v3 \
    --mlx-path /tmp/pathumma-mlx \
    --dtype float16

ls /tmp/pathumma-mlx
# config.json
# model.safetensors    <-- written by convert.py
import mlx_whisper
mlx_whisper.transcribe("audio.wav", path_or_hf_repo="/tmp/pathumma-mlx")
# FileNotFoundError / load failure: weights.safetensors not found
Source
  • whisper/convert.py (this repo) writes model.safetensors:
    https://github.com/ml-explore/mlx-examples/blob/main/whisper/convert.py#L385
    mx.save_safetensors(str(mlx_path / "model.safetensors"), weights)

  • mlx_whisper/load_models.py (PyPI mlx-whisper 0.4.3) expects weights.safetensors:

    wf = model_path / "weights.safetensors"
    if not wf.exists():
        wf = model_path / "weights.npz"
    weights = mx.load(str(wf))
    
Workaround

Rename after conversion:

mv /tmp/pathumma-mlx/model.safetensors /tmp/pathumma-mlx/weights.safetensors
Possible fix

Either:

  • convert.py writes to weights.safetensors, or
  • load_models.py also accepts model.safetensors

The latter seems more backwards-compatible since pre-converted models on the Hub
(e.g. mlx-community/whisper-large-v3-mlx) currently ship weights.npz.

Versions: mlx-whisper==0.4.3, mlx==0.31.2, mlx-examples HEAD e52c128.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with whisper/convert.py at the mx.save_safetensors call and compare its output name with the loading behavior described for mlx_whisper/load_models.py. Reproduce the documented conversion and transcription flow, then verify that the converted model is accepted without the manual rename workaround.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
machine-learning
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.