# File format matching the runtime: common mistakes and fixes

# What “File format matching the runtime” is really about

Wrong format wastes a day. Local LLM runtimes such as Ollama, LM Studio and llama.cpp are easy to install and surprisingly easy to misconfigure. Most problems that look like “the model is bad” are actually environment problems: the wrong file format, a quantisation that does not suit the language you use, a context window set too small, or a proxy silently breaking downloads.

# Get the basics right

• Pin versions. Record the runtime version and the exact model file (name, quantisation, checksum) that passed your tests.
• Match the file format to the runtime: GGUF for llama.cpp-based tools, MLX builds for MLX on Apple Silicon, safetensors for frameworks that expect them.
• Keep models in one directory or warehouse and point each tool at it, instead of downloading the same weights three times.
• Set the context length deliberately; larger contexts cost memory for every concurrent session.

# Troubleshooting order

When a pull fails or a model refuses to load, work through the layers in a fixed order: network and certificates, proxy settings, mirror or registry availability, disk space, then the checksum of the file. When the model loads but answers poorly, check the prompt template, temperature, and whether the quantisation is too aggressive for your language. Change one thing at a time and write down the result.

# Serving to a team

A single workstation can serve a small group if you are honest about limits. Put an OpenAI-compatible endpoint in front, require keys, cap concurrent requests, and show users when the queue is busy. Log the model name and version with every request so that you can explain changes in answer quality later. Keep a rollback path: the previous model file and the previous runtime version should be one command away.

# Upgrading safely

New releases arrive often. Before switching, run your small evaluation set on the new version side by side with the old one. If quality or stability drops, roll back and wait. Do not trust a single public chart; methodology, hardware and prompts differ too much.

# A small troubleshooting story

A team reported that their local model suddenly “forgot Chinese” after an update. The cause was not the model at all: the new runtime used a different default prompt template, and the quantised file they had pulled was a different variant from the one they had tested. Rolling back the runtime confirmed the diagnosis. They then pinned both the runtime version and the model checksum, added the template to their configuration file, and re-ran their evaluation prompts before upgrading again. The fix took an afternoon; the lesson was to treat runtimes and model files like any other dependency that needs versioning.

More on this topic: Dify + Ollama on Windows. See also MicroAI One software.

# Bottom line

Local AI rewards patience and record keeping more than raw spending. Decide what the system must do, measure it on your own hardware and documents, write down every change with a date and an owner, and review the setup after each significant upgrade. Small, documented steps are easier to debug, easier to hand over and easier to defend when someone asks why a particular choice was made. When in doubt, test on a smaller scale first and expand only when the evidence supports it.

# Quick reminders

• Publish what the assistant will refuse to do.
• Use one models directory shared by every runtime.
• Keep the previous model file until the new one passes your eval set.
• Cap concurrent sessions before lowering quantisation.

Published by MicroAI One (本地AI 1号网), a Shenzhen team working on local LLM hardware, software and deployment.