Implementation:Hiyouga LLaMA Factory WebUI Control
| Knowledge Sources | |
|---|---|
| Domains | WebUI, Controller, State Management |
| Last Updated | 2026-02-06 19:00 GMT |
Overview
Controller module providing callback functions that Gradio UI components invoke on change events to perform dynamic state transitions in the WebUI.
Description
The control.py module acts as the controller layer between the Gradio UI components and the underlying data and configuration. It provides functions for switching model hubs by setting environment variables (switch_hub), checking quantization compatibility based on finetuning type and method (can_quantize, can_quantize_to), changing training stages (change_stage), retrieving model info including path and template (get_model_info), validating template selection (check_template), reading trainer logs for progress monitoring with loss plotting and SwanLab experiment link extraction (get_trainer_info), listing available checkpoints from save directories (list_checkpoints), listing saved configuration files (list_config_paths), listing available datasets filtered by training stage (list_datasets), and listing resumable output directories (list_output_dirs).
Usage
Use this module's functions as Gradio event callbacks. They are wired to UI component change/click/focus events in the top panel, training tab, and evaluation tab components. The functions handle all dynamic UI updates that respond to user interactions.
Code Reference
Source Location
- Repository: Hiyouga_LLaMA_Factory
- File: src/llamafactory/webui/control.py
- Lines: 1-224
Signature
def switch_hub(hub_name: str) -> None: ...
def can_quantize(finetuning_type: str) -> "gr.Dropdown": ...
def can_quantize_to(quantization_method: str) -> "gr.Dropdown": ...
def change_stage(training_stage: str = list(TRAINING_STAGES.keys())[0]) -> tuple[list[str], bool]: ...
def get_model_info(model_name: str) -> tuple[str, str]: ...
def check_template(lang: str, template: str) -> None: ...
def get_trainer_info(
lang: str, output_path: os.PathLike, do_train: bool
) -> tuple[str, "gr.Slider", dict[str, Any]]: ...
def list_checkpoints(model_name: str, finetuning_type: str) -> "gr.Dropdown": ...
def list_config_paths(current_time: str) -> "gr.Dropdown": ...
def list_datasets(
dataset_dir: str = None, training_stage: str = list(TRAINING_STAGES.keys())[0]
) -> "gr.Dropdown": ...
def list_output_dirs(
model_name: str | None, finetuning_type: str, current_time: str
) -> "gr.Dropdown": ...
Import
from llamafactory.webui.control import (
switch_hub, can_quantize, can_quantize_to, change_stage,
get_model_info, check_template, get_trainer_info,
list_checkpoints, list_config_paths, list_datasets, list_output_dirs,
)
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| hub_name | str | Yes (switch_hub) | Hub to activate: "huggingface", "modelscope", or "openmind" |
| finetuning_type | str | Yes (can_quantize) | Finetuning method to check quantization compatibility |
| quantization_method | str | Yes (can_quantize_to) | Quantization method ("bnb", "hqq", "eetq") for available bit options |
| training_stage | str | No (change_stage) | Training stage key from TRAINING_STAGES |
| model_name | str | Yes (get_model_info, list_checkpoints) | Model name for path/template lookup or checkpoint directory listing |
| lang | str | Yes (check_template, get_trainer_info) | UI language code for localized warnings |
| output_path | os.PathLike | Yes (get_trainer_info) | Path to training output directory containing logs |
| do_train | bool | Yes (get_trainer_info) | Whether to include training-specific info (loss plot, SwanLab link) |
| dataset_dir | str | No (list_datasets) | Dataset directory path (defaults to DEFAULT_DATA_DIR) |
| current_time | str | Yes (list_config_paths, list_output_dirs) | Current timestamp for generating default filenames |
Outputs
| Name | Type | Description |
|---|---|---|
| (switch_hub) | None | Sets USE_MODELSCOPE_HUB and USE_OPENMIND_HUB environment variables |
| (can_quantize) | gr.Dropdown | Updated quantization_bit dropdown with interactive state |
| (can_quantize_to) | gr.Dropdown | Updated quantization_bit dropdown with available bit choices |
| (change_stage) | tuple[list, bool] | Empty dataset list and packing boolean (True for pretrain stage) |
| (get_model_info) | tuple[str, str] | Model path and template name |
| (get_trainer_info) | tuple[str, gr.Slider, dict] | Running log text, progress slider, and optional dict with loss_viewer and swanlab_link |
| (list_checkpoints) | gr.Dropdown | Dropdown with available checkpoint directories |
| (list_datasets) | gr.Dropdown | Dropdown with available dataset names filtered by ranking type |
| (list_output_dirs) | gr.Dropdown | Dropdown with resumable output directories |
Usage Examples
# Wiring hub switch to a Gradio dropdown
from llamafactory.webui.control import switch_hub, get_model_info, list_checkpoints
hub_name.change(switch_hub, inputs=[hub_name], queue=False).then(
get_model_info, [model_name], [model_path, template], queue=False
).then(
list_checkpoints, [model_name, finetuning_type], [checkpoint_path], queue=False
)
# Listing datasets for a specific training stage
from llamafactory.webui.control import list_datasets
dataset_dropdown = list_datasets(dataset_dir="data", training_stage="Supervised Fine-Tuning")
Related Pages
- Hiyouga_LLaMA_Factory_WebUI_Top_Component - Top panel that wires most control callbacks
- Hiyouga_LLaMA_Factory_WebUI_Common - Provides utility functions used by control callbacks
- Hiyouga_LLaMA_Factory_WebUI_Eval_Component - Eval tab that uses list_datasets
- Hiyouga_LLaMA_Factory_WebUI_Engine - Engine whose runner monitor calls get_trainer_info