native-mlx-vlm-repro

Reproduce mlx-vlm inference failures natively to isolate upstream defects from harness behavior.

1|1|Updated Apr 21, 2025
One-click install
npx skills add https://github.com/jrp2014/check_models --skill native-mlx-vlm-repro-jrp2014
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: native-mlx-vlm-repro
Source: https://github.com/jrp2014/check_models/tree/main/.agents/skills/native-mlx-vlm-repro
Command: npx skills add https://github.com/jrp2014/check_models --skill native-mlx-vlm-repro-jrp2014

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a Vision-Language Model fails inside the check_models harness, it is hard to tell whether the bug lives in the harness or in upstream mlx-vlm. This Skill provides a disciplined workflow for building minimal native reproductions using python -m mlx_vlm.generate or the load/apply_chat_template/stream_generate Python path, so failures can be attributed correctly and reported upstream. ## Core Features & Use Cases - Native CLI and Python repro patterns: Canonical commands for text-only and image inference, including revision pinning, trust-remote-code, and deterministic settings (temperature 0.0, bounded max-tokens). - Harness-aware starting points: Reuses existing artifacts such as issue drafts, diagnostics reproduction blocks, and results.jsonl metadata instead of inventing new commands. - Failure routing and thinking-output checks: A symptom-to-cause table (unsupported model_type, missing weights, processor errors, media shape errors) plus rules for judging thinking-block output. - Use Case: A model crashes in check_models with a chat-template error. You pull the native CLI command from the issue draft, confirm flags with --help, run one model per process, and confirm the failure is upstream before filing an issue. ## Quick Start Ask the assistant to reproduce a failing model natively with mlx-vlm using the conda mlx-vlm environment, starting from the diagnostics or issue-draft command for that model.

Frequently Asked Questions about native-mlx-vlm-repro

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I reproduce an mlx-vlm failure outside the check_models harness?▼

Run python -m mlx_vlm.generate with the same model, image, and prompt, using temperature 0.0 and a bounded max-tokens. Start from the native command recorded in the harness issue draft or diagnostics reproduction block rather than inventing new flags.

How do I tell if a bug is in mlx-vlm or in my harness code?▼

Reproduce the failure with the native mlx-vlm CLI or the load/apply_chat_template/stream_generate loop. If it fails natively the same way, it is an upstream issue; if it only fails in the harness, inspect preflight, prompt construction, and kwarg mapping.

Can I use uv to run mlx-vlm reproduction commands?▼

No. This repository uses the conda mlx-vlm environment with pip installs only. Never document or run uv commands; prefer python -m mlx_vlm.generate over bare entry-point scripts.

Why does mlx-vlm fail with an unsupported model_type error?▼

The model's config.json declares a model_type that mlx-vlm does not implement. Check the mlx_vlm/models/ directory for supported families and read the model-family README when debugging inside an mlx-vlm checkout.

Is thinking-block output from a VLM a failure?▼

Not by itself. A properly closed thinking block followed by substantive final text is valid output. Reproduce natively only when the block is unclosed, consumes the token budget, lacks a final answer, or exposes an undeclared control token.