Model Family & Matching

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/recipeModelMatch.ts
• src/components/features/InputEnvironmentPanel.tsx
• src/lib/oliveRecipeSchema.ts
• src/lib/recipePipeline.ts
• src/lib/tests/recipePipeline.test.ts
• README.md

Introduction

The Model Family & Matching system in Olive Studio is a critical intelligence layer designed to bridge the gap between a user's uploaded local model assets and the curated library of Microsoft Olive optimization recipes. Its primary purpose is to automatically identify which optimization "presets" (e.g., Llama-3 quantization for TensorRT) are compatible with the specific architecture and files provided by the user.

By parsing model configuration files and analyzing file naming conventions, the system generates "Local Model Hints" that are then scored against the olive-recipes catalog. This ensures that users are presented with the most relevant optimization paths, reducing the manual effort required to find a matching recipe for complex Large Language Models (LLMs) or Vision models.

Sources: src/lib/recipeModelMatch.ts, src/components/features/InputEnvironmentPanel.tsx:185-225, README.md:120-130

Architecture and Data Flow

The matching logic follows a structured pipeline: extracting metadata from user-provided files, normalizing that data into a hint structure, and executing a scoring algorithm against the recipe catalog.

Metadata Extraction

The system prioritizes information from config.json if available in the local file list. It specifically looks for Hugging Face model IDs and architecture labels. If no config file exists, it falls back to parsing filenames (e.g., extracting "llama" from llama-weights.bin).

The diagram above shows the process of deriving model identity from disparate local file inputs.
Sources: src/lib/recipeModelMatch.ts:58-100, src/components/features/InputEnvironmentPanel.tsx:189-215

Key Data Structures

LocalModelHints

This interface serves as the normalized representation of a user's uploaded model for matching purposes.

Field	Type	Description
fileNames	string[]	List of original filenames uploaded.
displayName	string	Best-effort UI label (e.g., "Llama-3-8B").
hfModelIds	string[]	Extracted IDs like meta-llama/Meta-Llama-3-8B.
architectureHints	string[]	Normalized architecture strings (e.g., "LlamaForCausalLM").
slugCandidates	string[]	Normalized strings used for direct string matching.

Sources: src/lib/recipeModelMatch.ts:5-12

RecipeMatchResult

The output of the scoring engine for a single recipe in the catalog.

Field	Type	Description
score	number	0-100 score indicating match confidence.
tier	match | possible | none	Categorical classification of the match.
reason	string	Human-readable explanation of why the match was made.

Sources: src/lib/recipeModelMatch.ts:14-18

Scoring Logic and Algorithm

The scoring engine employs a multi-tiered strategy to determine the relevance of a recipe:

1. Direct Folder Match (Score: 100): If a slug derived from the model ID exactly matches the top-level folder of a recipe in the microsoft/olive-recipes repo (e.g., Qwen-Qwen2.5-1.5B-Instruct).
2. String Inclusion (Score: 85): If the catalog slug contains the candidate string or vice-versa.
3. Token Overlap (Score: 70-90): The system splits strings into tokens (words separated by dashes/underscores) and calculates an overlap ratio. An overlap $\ge 0.55$ results in a score of $70 + (\text{overlap} \times 20)$.
4. Architecture Fallback (Score: 42): If no name matches are found, but the model architecture (e.g., "Llama") matches the recipe's metadata.

The sequence above illustrates how the UI coordinates the matching of a single upload against the entire static recipe catalog.
Sources: src/lib/recipeModelMatch.ts:117-160, src/components/features/InputEnvironmentPanel.tsx:227-250

Implementation Details

Normalization and Tokenization

The system relies on the normalizeToken and tokenSet functions to ensure that variations in casing and punctuation (e.g., "Llama-3" vs "llama_3") do not prevent matches.

• Normalization: Converts to lowercase and strips non-alphanumeric characters.
• Tokenization: Splits strings into parts, filtering out tokens shorter than 2 characters.

function tokenSet(value: string): Set<string> {
  return new Set(
    value
      .toLowerCase()
      .split(/[-_./\s]+/)
      .map((t) => t.replace(/[^a-z0-9]/g, ""))
      .filter((t) => t.length >= 2),
  );
}

Sources: src/lib/recipeModelMatch.ts:25-42

Integration in InputEnvironmentPanel

The InputEnvironmentPanel uses a useMemo hook to recalculate matches whenever localModelHints or the SUGGESTED_RECIPES catalog changes. This allows for real-time UI updates, such as showing a "Matches only" toggle or displaying green badges for "Compatible" recipes.

Sources: src/components/features/InputEnvironmentPanel.tsx:227-255, src/lib/tests/recipePipeline.test.ts:35-50

Summary

Model Family & Matching provides a heuristic-based discovery mechanism that connects local model assets to optimized execution paths. By combining strict metadata parsing (from config.json) with flexible token overlap analysis of filenames, it identifies compatibility across the microsoft/olive-recipes ecosystem, ensuring users find the most performant quantization and conversion recipes for their hardware.