Implementation:Mlc ai Mlc llm Config Base

Overview

Config Base provides a common base class infrastructure for configuration objects in MLC LLM. It is located at python/mlc_llm/support/config.py (114 lines).

The module defines two base classes -- ConfigBase and ConfigOverrideBase -- that enable configuration objects to be initialized from JSON files, JSON strings, or Python dictionaries. Irrelevant fields encountered during initialization are automatically captured in a kwargs field, making it robust when loading HuggingFace model configuration files that contain extra metadata.

Purpose

Model configurations in HuggingFace repositories (e.g., config.json) typically contain model hyperparameters alongside metadata fields like transformers_version and use_cache. The ConfigBase class allows MLC LLM to load such configurations while cleanly separating known fields from unknown ones. The ConfigOverrideBase class provides a mechanism to selectively override specific configuration fields at runtime.

Classes

ConfigBase

@dataclasses.dataclass
class ConfigBase:

A dataclass-based base class that provides a common interface for loading configurations. Subclasses must be Python dataclasses and must include a kwargs field to capture extra fields.

from_dict

@classmethod
def from_dict(cls: Type[ConfigClass], source: Dict[str, Any]) -> ConfigClass:

Creates a configuration instance from a dictionary. The method introspects the subclass's dataclass fields to determine which keys are recognized. Recognized keys are passed as constructor arguments; unrecognized keys are collected into the kwargs parameter:

field_names = [field.name for field in dataclasses.fields(cls)]
fields = {k: v for k, v in source.items() if k in field_names}
kwargs = {k: v for k, v in source.items() if k not in field_names}
return cls(**fields, kwargs=kwargs)

from_file

@classmethod
def from_file(cls: Type[ConfigClass], source: Path) -> ConfigClass:

Creates a configuration instance from a JSON file. It opens the file, parses the JSON, and delegates to from_dict.

asdict

def asdict(self):

Converts the configuration object back to a dictionary using dataclasses.asdict, removing the kwargs field from the result. This produces a clean dictionary of only the recognized configuration fields.

ConfigOverrideBase

class ConfigOverrideBase:

A base class for creating configuration override objects. Subclasses must be dataclasses whose fields represent overridable configuration values. Fields set to None are skipped (not overridden).

apply

def apply(self, config):

Applies the overrides to a given configuration object. The method:

1. Converts the target config to a dictionary via config.asdict().
2. Iterates over its own dataclass fields.
3. Skips any field whose value is None.
4. Logs a warning (styled in red) if the target config does not contain the field being overridden.
5. Logs an info message showing the old and new values for successfully overridden fields.
6. Reconstructs a new config object from the updated dictionary using type(config).from_dict(updated).

def apply(self, config):
    updated = config.asdict()
    for field in dataclasses.fields(self):
        key = field.name
        value = getattr(self, key)
        if value is None:
            continue
        if key not in updated:
            logger.warning(
                "%s: Cannot override %s, because %s does not have this field",
                red("Warning"),
                bold(key),
                bold(type(config).__name__),
            )
        else:
            logger.info(f"Overriding {bold(key)} from {updated[key]} to {value}")
            updated[key] = value
    return type(config).from_dict(updated)

Type Variable

The module defines a ConfigClass type variable bounded to ConfigBase, enabling proper type inference in the classmethod signatures:

ConfigClass = TypeVar("ConfigClass", bound="ConfigBase")

Usage Pattern

A typical model config subclass would look like:

@dataclasses.dataclass
class LlamaConfig(ConfigBase):
    hidden_size: int = 4096
    num_attention_heads: int = 32
    num_hidden_layers: int = 32
    kwargs: Dict[str, Any] = dataclasses.field(default_factory=dict)

This can then be loaded from a HuggingFace config.json file:

config = LlamaConfig.from_file(Path("config.json"))

Any fields in the JSON not declared in the dataclass (e.g., transformers_version) are silently captured in config.kwargs.

Dependencies

• dataclasses -- Python standard library for dataclass introspection
• json, pathlib.Path -- Standard library for JSON parsing and file paths
• mlc_llm.support.logging -- Internal logging module
• mlc_llm.support.style -- Terminal styling helpers (bold, red)

Exports

__all__ = ["ConfigBase", "ConfigOverrideBase"]

File Location

python/mlc_llm/support/config.py