Implementation:Mlc ai Web llm Prebuilt App Config

Overview

prebuiltAppConfig is the built-in model registry constant provided by @mlc-ai/web-llm. It is an AppConfig object containing a curated list of ModelRecord entries, each mapping a model_id to its HuggingFace weight URL, compiled WASM library URL, VRAM requirements, and default configuration overrides. The findModelRecord utility function looks up a model by its ID within the registry.

Description

The prebuiltAppConfig constant is the single source of truth for which pre-compiled model libraries are compatible with the current WebLLM npm version. Each entry is a ModelRecord that fully specifies how to locate and load a model.

The AppConfig interface contains:

model_list -- an array of ModelRecord entries
useIndexedDBCache -- optional boolean controlling whether to use IndexedDB or the Cache API for model caching (defaults to false, meaning Cache API is used)

Each ModelRecord contains:

model -- HuggingFace URL for downloading weights (supports branch specification via /resolve/{BRANCH}/)
model_id -- unique string identifier (e.g., "Llama-3.2-1B-Instruct-q4f16_1-MLC")
model_lib -- URL to the compiled WebGPU WASM library
overrides -- optional ChatOptions to override mlc-chat-config.json defaults
vram_required_MB -- estimated VRAM required in megabytes
low_resource_required -- boolean flag for models suitable for constrained devices
buffer_size_required_bytes -- required maxStorageBufferBindingSize limit
required_features -- array of WebGPU features needed (e.g., ["shader-f16"])
model_type -- enum value: ModelType.LLM, ModelType.embedding, or ModelType.VLM

The findModelRecord function in src/support.ts performs a linear search through appConfig.model_list to find a matching model_id, throwing ModelNotFoundError if no match is found.

Code Reference

Repository: https://github.com/mlc-ai/web-llm
File: src/config.ts (interfaces and prebuiltAppConfig constant, lines 255-2321)
File: src/support.ts (findModelRecord function, lines 206-215)

Type Signatures

export interface ModelRecord {
  model: string;
  model_id: string;
  model_lib: string;
  overrides?: ChatOptions;
  vram_required_MB?: number;
  low_resource_required?: boolean;
  buffer_size_required_bytes?: number;
  required_features?: Array<string>;
  model_type?: ModelType;
}

export interface AppConfig {
  model_list: Array<ModelRecord>;
  useIndexedDBCache?: boolean;
}

export const prebuiltAppConfig: AppConfig;

// In src/support.ts
export function findModelRecord(modelId: string, appConfig: AppConfig): ModelRecord;

Import

import { prebuiltAppConfig, ModelRecord, AppConfig } from "@mlc-ai/web-llm";

I/O Contract

Direction	Name	Type	Required	Description
Input	model_id	`string`	Yes	Unique identifier for the model to look up
Output	ModelRecord	`ModelRecord`	--	Object containing model URL, model_lib URL, VRAM requirements, and configuration overrides

If the model_id is not found in the registry, findModelRecord throws a ModelNotFoundError.

Usage Example

import { prebuiltAppConfig } from "@mlc-ai/web-llm";

// List all available model IDs
const availableModels = prebuiltAppConfig.model_list.map(
  (record) => record.model_id
);
console.log("Available models:", availableModels);

// Filter models by VRAM budget (e.g., under 2GB)
const lowVramModels = prebuiltAppConfig.model_list.filter(
  (record) => record.vram_required_MB !== undefined && record.vram_required_MB < 2000
);
console.log("Models under 2GB VRAM:", lowVramModels.map((m) => m.model_id));

// Filter for low-resource models suitable for mobile devices
const mobileModels = prebuiltAppConfig.model_list.filter(
  (record) => record.low_resource_required === true
);

// Filter for embedding models
import { ModelType } from "@mlc-ai/web-llm";
const embeddingModels = prebuiltAppConfig.model_list.filter(
  (record) => record.model_type === ModelType.embedding
);
console.log("Embedding models:", embeddingModels.map((m) => m.model_id));

// Look up a specific model record
import { findModelRecord } from "@mlc-ai/web-llm";
const record = findModelRecord("Llama-3.2-1B-Instruct-q4f16_1-MLC", prebuiltAppConfig);
console.log("Model URL:", record.model);
console.log("WASM library:", record.model_lib);
console.log("VRAM required:", record.vram_required_MB, "MB");

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment