Implementation:Hiyouga LLaMA Factory V1 Model Engine

Knowledge Sources	Hiyouga_LLaMA_Factory
Domains	Machine Learning, Model Loading
Last Updated	2026-02-06 19:00 GMT

Overview

ModelEngine is the core model factory that orchestrates the complete model initialization pipeline including processor loading, model configuration, model instantiation, PEFT adapter application, and kernel optimization.

Description

The ModelEngine class provides a unified model setup pipeline for the LLaMA-Factory v1 system. It sequentially initializes the HuggingFace processor/tokenizer via AutoProcessor, the model configuration via AutoConfig, and the model itself by selecting the appropriate AutoClass (AutoModelForCausalLM, AutoModelForImageTextToText, AutoModelForTokenClassification, or AutoModel) based on the model_class configuration. The engine supports meta-device initialization through init plugins for deferred weight materialization, applies PEFT adapters (such as LoRA) through the PeftPlugin system, and enables custom kernel optimizations through the KernelPlugin system.

Usage

Use ModelEngine to initialize a model for training or inference. Instantiate it with ModelArguments and optionally set is_train=True for training mode (which casts the model to float32 for full-precision fine-tuning when no PEFT config is provided). The resulting model, processor, and renderer attributes are then passed to trainers or samplers.

Code Reference

Source Location

• Repository: Hiyouga_LLaMA_Factory
• File: src/llamafactory/v1/core/model_engine.py
• Lines: 1-160

Signature

class ModelEngine:
    def __init__(self, model_args: ModelArguments, is_train: bool = False) -> None: ...

    def _init_processor(self) -> Processor: ...
    def _init_model_config(self) -> HFConfig: ...
    def _init_model(self) -> HFModel: ...

Import

from llamafactory.v1.core.model_engine import ModelEngine

I/O Contract

Inputs

Name	Type	Required	Description
model_args	ModelArguments	Yes	Model configuration including model name/path, model_class, template, trust_remote_code, init_config, peft_config, and kernel_config.
is_train	bool	No	Whether the model is being initialized for training (default: False). When True and no PEFT config is set, casts model to float32.

Outputs

Name	Type	Description
processor	Processor	The HuggingFace processor/tokenizer loaded from the model path.
renderer	Renderer	A Renderer instance initialized with the template and processor.
model_config	HFConfig	The HuggingFace model configuration.
model	HFModel	The fully initialized model with optional PEFT adapters and kernel optimizations applied.

Usage Examples

from llamafactory.v1.core.model_engine import ModelEngine

# Initialize for inference
model_engine = ModelEngine(model_args=model_args)
print(model_engine.processor)
print(model_engine.model)

# Initialize for training
model_engine = ModelEngine(model_args=model_args, is_train=True)

# Access components
model = model_engine.model
renderer = model_engine.renderer
processor = model_engine.processor

# CLI usage
# python -m llamafactory.v1.core.model_engine --model llamafactory/tiny-random-qwen2.5

Related Pages

• Hiyouga_LLaMA_Factory_V1_Rendering - The Renderer created by ModelEngine for template application.
• Hiyouga_LLaMA_Factory_V1_Base_Trainer - Consumes the model and renderer from ModelEngine.
• Hiyouga_LLaMA_Factory_V1_Base_Sampler - Consumes the model and renderer for inference.
• Hiyouga_LLaMA_Factory_V1_Launcher - Top-level entry point that triggers ModelEngine initialization.