Table of Contents

How Do I Switch to a Newer Model Version Without Breaking My Application?


TL;DR

LM-Kit.NET's model catalog provides a replacement model system that flags deprecated models and points to their recommended successors. To safely update, load the new model in a test environment, verify output quality on your specific tasks, then swap the model ID or URI in your configuration. For maximum stability, pin a specific model file by URI rather than relying on the resolve/main endpoint.


How Model Versions Work

Models in the LM-Kit.NET catalog are referenced by model ID (e.g., qwen3.5:9b) or by direct URI to a specific file on HuggingFace.

Method Behavior Stability
LM.LoadFromModelID("qwen3.5:9b") Resolves to the catalog's current default for that ID. Stable within an SDK version. Updates when you update the SDK.
new LM(new Uri("https://huggingface.co/.../resolve/main/file.lmk")) Resolves to the latest file on the main branch. May change if the repo maintainer updates the file.
new LM(new Uri("https://huggingface.co/.../resolve/{commit-hash}/file.lmk")) Resolves to a specific commit. Fully pinned. Never changes.
new LM("/local/path/to/model.lmk") Loads an exact local file. Fully pinned. You control updates.

The Replacement Model System

When a model family releases a new generation, the catalog marks the older version with a ReplacementModel pointer. This helps you discover recommended upgrades:

Deprecated Model Replacement Notes
qwen2.5:0.5b qwen3.5:0.8b Newer architecture, similar size
qwen2.5:3b qwen3.5:4b Better quality at similar hardware requirements
qwen2.5:7b qwen3.5:9b Improved instruction following
gemma2:2b gemma4:e4b Smaller file, comparable quality
gemma2:9b gemma4:e4b Better reasoning and vision

Deprecated models continue to work. The replacement is a recommendation, not a forced migration.


Safe Migration Workflow

Follow these steps to update a model in a production application:

1. Identify the new model

Check the catalog for replacement recommendations, or browse the Model Catalog for newer options in the same size class.

2. Test in isolation

Load the new model in a test environment and run it against your existing prompts, system prompts, and expected outputs:

using LMKit.Model;

// Load the candidate model
using LM newModel = LM.LoadFromModelID("qwen3.5:9b");

// Run your existing prompts
var chat = new MultiTurnConversation(newModel);
chat.SystemPrompt = existingSystemPrompt;
string result = chat.Submit("Your typical test prompt here");

// Compare output quality against the old model's results

3. Verify capabilities

Ensure the new model supports all capabilities your application depends on:

Console.WriteLine($"Chat: {newModel.Capabilities.HasFlag(ModelCapabilities.Chat)}");
Console.WriteLine($"Tools: {newModel.Capabilities.HasFlag(ModelCapabilities.ToolsCall)}");
Console.WriteLine($"Vision: {newModel.Capabilities.HasFlag(ModelCapabilities.Vision)}");
Console.WriteLine($"Context: {newModel.ContextLength}");

4. Swap the model reference

Update the model ID or URI in your application configuration. If you use a configuration file:

{
  "ModelId": "qwen3.5:9b"
}

string modelId = configuration["ModelId"];
using LM model = LM.LoadFromModelID(modelId);

This lets you change models without recompiling.


Version Pinning for Maximum Stability

For production applications where reproducibility matters, pin to a specific file rather than a mutable reference:

// Pinned to a specific commit on HuggingFace (never changes)
using LM model = new LM(new Uri(
    "https://huggingface.co/lm-kit/qwen-3.5-9b-instruct-lmk/resolve/abc123def/Qwen3.5-9B-Q4_K_M.lmk"
));

Or distribute a specific model file with your application and load from the local path.


What Happens When You Update the SDK

When you update the LM-Kit.NET NuGet package to a new version:

  • Model IDs may point to newer model files (if the catalog was updated).
  • Already-downloaded model files remain in the local cache and continue to work.
  • Direct URIs and local file paths are unaffected by SDK updates.

To avoid surprises, test your application after any SDK update, especially if you rely on LoadFromModelID without version pinning.


📚 Related Content

Share