Implementation:Hiyouga LLaMA Factory V1 Plugin System

Knowledge Sources	Hiyouga_LLaMA_Factory
Domains	Software Architecture, Plugin Systems
Last Updated	2026-02-06 19:00 GMT

Overview

BasePlugin is the core extensibility mechanism for the LLaMA-Factory v1 architecture, providing a name-based registration and dispatch system for pluggable functions.

Description

BasePlugin uses a class-level _registry (a defaultdict of dictionaries) to map plugin names to their registered method callables. Plugins are created by instantiating a subclass with a name, then using the register decorator to associate functions with that name under a specific method key (defaulting to __call__). The __call__ method dispatches to the __call__ entry in the registry, while __getattr__ and __getitem__ allow accessing any registered method by name. This enables a pattern where configuration strings can dynamically select plugin implementations at runtime. Subclasses share the same registry namespace, allowing different plugin families (rendering, data conversion, model initialization, etc.) to coexist.

Usage

Use BasePlugin as a base class for any component that needs pluggable, name-dispatched behavior. Define a subclass, register functions with @MyPlugin("name").register("method_name"), and invoke them with MyPlugin("name").method_name() or MyPlugin("name")() for the default callable. This is used throughout v1 for rendering plugins, data converter plugins, model initialization plugins, and more.

Code Reference

Source Location

• Repository: Hiyouga_LLaMA_Factory
• File: src/llamafactory/v1/utils/plugin.py
• Lines: 1-107

Signature

class BasePlugin:
    _registry: dict[str, dict[str, Callable]] = defaultdict(dict)

    def __init__(self, name: str | None = None) -> None: ...

    def register(self, method_name: str = "__call__") -> Callable: ...

    def __call__(self, *args, **kwargs) -> Any: ...

    def __getattr__(self, method_name: str) -> Callable: ...

    def __getitem__(self, method_name: str) -> Callable: ...

Import

from llamafactory.v1.utils.plugin import BasePlugin

I/O Contract

Inputs

Name	Type	Required	Description
name	str or None	Yes (for registration)	The plugin name used as the registry key; None raises ValueError on register
method_name (register)	str	No	The method key to register under; defaults to "__call__"
*args, **kwargs (__call__)	Any	Varies	Arguments passed through to the registered function

Outputs

Name	Type	Description
register	Callable	Decorator that returns the original function after registering it
__call__	Any	Return value of the registered "__call__" function
__getattr__ / __getitem__	Callable	The registered function for the given method name

Usage Examples

from llamafactory.v1.utils.plugin import BasePlugin

# Define a plugin subclass
class PrintPlugin(BasePlugin):
    def again(self):  # optional typed accessor
        self["again"]()

# Register functions under the "hello" plugin name
@PrintPlugin("hello").register()
def print_hello():
    print("Hello world!")

@PrintPlugin("hello").register("again")
def print_hello_again():
    print("Hello world! Again.")

# Invoke via the default callable
PrintPlugin("hello")()        # prints: "Hello world!"

# Invoke a named method
PrintPlugin("hello").again()   # prints: "Hello world! Again."

Related Pages

• Implementation:Hiyouga_LLaMA_Factory_V1_Rendering_Plugin - Concrete plugin subclass for message rendering
• Implementation:Hiyouga_LLaMA_Factory_V1_Logging - Logging module used for duplicate registration warnings